# MCPEngine Studio — UX/UI Design Specification

**Version:** 1.0 | **Date:** February 2026 | **Status:** Design-Ready

---

## 1. Design System Foundations

### 1.1 Color System

**Primary Palette (Dark Mode Default)**
```
--surface-0:     #0A0F1E    // App background (deepest)
--surface-1:     #111827    // Card/panel background (gray-900)
--surface-2:     #1F2937    // Elevated surface (gray-800)
--surface-3:     #374151    // Hover/active states (gray-700)
--border:        #374151    // Default border (gray-700)
--border-subtle: #1F2937    // Subtle dividers (gray-800)
```

**Brand Colors**
```
--brand-primary:     #6366F1    // Indigo-500 — primary actions
--brand-primary-hover: #818CF8  // Indigo-400
--brand-accent:      #10B981    // Emerald-500 — success/deploy
--brand-accent-hover: #34D399   // Emerald-400
--brand-glow:        #6366F1/20 // Indigo glow for focus rings
```

**Text Colors**
```
--text-primary:   #F9FAFB    // gray-50 — headings, primary content
--text-secondary: #9CA3AF    // gray-400 — descriptions, labels
--text-tertiary:  #6B7280    // gray-500 — placeholders, disabled
--text-inverse:   #111827    // gray-900 — on light backgrounds
```

**Semantic Colors**
```
--success:   #10B981    // Emerald-500
--warning:   #F59E0B    // Amber-500
--error:     #EF4444    // Red-500
--info:      #3B82F6    // Blue-500
```

**Light Mode Overrides**
```
--surface-0:     #FFFFFF
--surface-1:     #F9FAFB    // gray-50
--surface-2:     #F3F4F6    // gray-100
--surface-3:     #E5E7EB    // gray-200
--border:        #D1D5DB    // gray-300
--text-primary:  #111827    // gray-900
--text-secondary: #6B7280   // gray-500
```

### 1.2 Typography

**Font Stack**
- **UI:** Inter (Variable) — `font-family: 'Inter Variable', system-ui, sans-serif`
- **Code:** JetBrains Mono — `font-family: 'JetBrains Mono', monospace`
- **Marketing/Headlines:** Inter with `font-feature-settings: 'ss01', 'ss02'`

**Scale**
| Token | Size | Line Height | Weight | Usage |
|-------|------|------------|--------|-------|
| `text-xs` | 12px | 16px | 400 | Badges, captions |
| `text-sm` | 14px | 20px | 400 | Labels, secondary text |
| `text-base` | 16px | 24px | 400 | Body text, inputs |
| `text-lg` | 18px | 28px | 500 | Section titles |
| `text-xl` | 20px | 28px | 600 | Page subtitles |
| `text-2xl` | 24px | 32px | 700 | Page titles |
| `text-3xl` | 30px | 36px | 700 | Hero headlines |
| `text-4xl` | 36px | 40px | 800 | Landing hero |
| `text-5xl` | 48px | 48px | 800 | Marketing hero |

### 1.3 Spacing

4px base grid. Tailwind spacing scale:
```
space-0.5:  2px     space-6:  24px    space-16: 64px
space-1:    4px     space-8:  32px    space-20: 80px
space-2:    8px     space-10: 40px    space-24: 96px
space-3:    12px    space-12: 48px    space-32: 128px
space-4:    16px    space-14: 56px
```

**Component Spacing Rules:**
- Card padding: `p-6` (24px)
- Section gaps: `gap-8` (32px)
- Inline element gaps: `gap-2` (8px) or `gap-3` (12px)
- Page margins: `px-6` on desktop, `px-4` on mobile

### 1.4 Elevation / Shadows

```css
--shadow-sm:   0 1px 2px rgba(0,0,0,0.3);
--shadow-md:   0 4px 6px -1px rgba(0,0,0,0.4);
--shadow-lg:   0 10px 15px -3px rgba(0,0,0,0.5);
--shadow-xl:   0 20px 25px -5px rgba(0,0,0,0.5);
--shadow-glow: 0 0 20px rgba(99,102,241,0.15);   /* brand glow */
--shadow-success-glow: 0 0 20px rgba(16,185,129,0.15);
```

### 1.5 Border Radius
```
--radius-sm:   6px     (rounded-md)
--radius-md:   8px     (rounded-lg)
--radius-lg:   12px    (rounded-xl)
--radius-xl:   16px    (rounded-2xl)
--radius-full: 9999px  (rounded-full) — pills, avatars
```

---

## 2. Component Library

### 2.1 Button

```
┌─ Primary ────────────────────────────────────┐
│ bg-indigo-500 hover:bg-indigo-400            │
│ text-white font-semibold                     │
│ Sizes: sm(h-8 px-3 text-sm)                 │
│        md(h-10 px-4 text-sm)                 │
│        lg(h-12 px-6 text-base)               │
│ Rounded: rounded-lg                          │
│ Focus: ring-2 ring-indigo-500/50 ring-offset-2 ring-offset-gray-900 │
└──────────────────────────────────────────────┘

Variants:
- Primary:   bg-indigo-500 text-white
- Secondary: bg-gray-700 text-gray-200 border border-gray-600
- Ghost:     bg-transparent text-gray-400 hover:bg-gray-800
- Danger:    bg-red-500/10 text-red-400 hover:bg-red-500/20
- Success:   bg-emerald-500 text-white (deploy button)
```

### 2.2 Card

```
bg-gray-900 border border-gray-700 rounded-xl p-6
hover: border-gray-600 shadow-md transition-all duration-150

Variants:
- Default: as above
- Interactive: + hover:scale-[1.02] cursor-pointer
- Elevated: + shadow-lg bg-gray-800
- Glowing: + shadow-glow border-indigo-500/30 (featured/active)
```

### 2.3 Input

```
bg-gray-800 border border-gray-600 rounded-lg px-4 h-10
text-gray-100 placeholder:text-gray-500
focus: border-indigo-500 ring-2 ring-indigo-500/20
error: border-red-500 ring-2 ring-red-500/20

Variants:
- Text input (default)
- Textarea: h-auto min-h-[80px] py-3
- Select: + chevron icon right
- Search: + magnifying glass icon left, rounded-full
```

### 2.4 Canvas Node (React Flow Tool Block)

```
┌──────────────────────────────────┐
│ ○ GET  get_contacts              │  ← Handle (connection point)
│                                  │
│ Retrieve contacts from CRM       │  ← Description (text-sm text-gray-400)
│                                  │
│ ┌────────┐ ┌────────┐ ┌──────┐ │
│ │ 3 params│ │ Auth ✓ │ │ Live │ │  ← Badges
│ └────────┘ └────────┘ └──────┘ │
└──────────────────────────────────┘

Style: bg-gray-800 border border-gray-600 rounded-xl p-4 w-[280px]
Selected: border-indigo-500 shadow-glow
Disabled: opacity-50
Group header: bg-gray-700/50 text-xs uppercase text-gray-400 px-3 py-1
```

### 2.5 Toast

```
Position: bottom-right, stack up
Style: bg-gray-800 border border-gray-700 rounded-lg shadow-xl p-4
       max-w-sm flex items-start gap-3

Variants:
- Success: left border-l-4 border-l-emerald-500, emerald icon
- Error: left border-l-4 border-l-red-500, red icon
- Info: left border-l-4 border-l-blue-500, blue icon
- Loading: left border-l-4 border-l-indigo-500, spinner icon

Auto-dismiss: 5s (success/info), manual (error)
Animation: slide in from right (200ms ease-out), fade out
```

### 2.6 Modal

```
Backdrop: bg-black/60 backdrop-blur-sm
Container: bg-gray-900 border border-gray-700 rounded-2xl shadow-2xl
           max-w-lg w-full mx-4 p-6
Header: text-xl font-semibold + close button (top right)
Footer: flex justify-end gap-3 pt-4 border-t border-gray-800
Animation: backdrop fade-in 150ms, modal scale-in from 95% (200ms spring)
```

### 2.7 Nav Rail Item

```
Width: 64px total rail
Item: w-10 h-10 rounded-lg flex items-center justify-center
      text-gray-400 hover:text-gray-200 hover:bg-gray-800
Active: text-indigo-400 bg-indigo-500/10
Tooltip: right side, bg-gray-800 text-sm rounded-md px-2 py-1 (200ms delay)
```

---

## 3. Page Wireframes

### 3.1 Landing Page

```
┌─────────────────────────────────────────────────────────────┐
│  [Logo]  Features  Pricing  Docs  Templates    [Sign In] [CTA] │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│           Build MCP Servers Visually.                       │  ← text-5xl font-extrabold
│           Ship AI Apps Instantly.                           │     gradient text (indigo→emerald)
│                                                             │
│     37 templates. Drag-and-drop. Zero boilerplate.         │  ← text-xl text-gray-400
│     From idea to deployed server in 60 seconds.            │
│                                                             │
│     [Get Started Free]  [Watch Demo ▶]                     │  ← Primary + Ghost buttons
│                                                             │
│     ┌─────────────────────────────────────────┐            │
│     │        Live demo / product video         │            │  ← 16:9 rounded-2xl border
│     │        (auto-playing, muted)             │            │     shadow-2xl
│     └─────────────────────────────────────────┘            │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                 │
│  │ Upload   │  │ Customize│  │ Deploy   │                 │  ← 3 value prop cards
│  │ Any Spec │  │ Visually │  │ Anywhere │                 │     with icons + descriptions
│  └──────────┘  └──────────┘  └──────────┘                 │
├─────────────────────────────────────────────────────────────┤
│  "Trusted by" logos (if applicable) or                      │
│  "Built on" — Anthropic, Cloudflare, MCP Protocol           │
├─────────────────────────────────────────────────────────────┤
│  Template Showcase — grid of 6 featured servers             │
│  [Browse All 37 Templates →]                                │
├─────────────────────────────────────────────────────────────┤
│  Pricing Section (4 tier cards)                             │
├─────────────────────────────────────────────────────────────┤
│  Final CTA: "Ready to build?" + email capture               │
└─────────────────────────────────────────────────────────────┘
```

### 3.2 Dashboard

```
┌────┬──────────────────────────────────────────────────────┐
│    │  My Projects                          [+ New Project] │
│ N  │                                                       │
│ A  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │
│ V  │  │ Trello   │ │ Zendesk  │ │ Custom   │ │  + New │ │
│    │  │ MCP      │ │ MCP      │ │ CRM MCP  │ │        │ │
│ R  │  │ ✅ Live  │ │ 🧪 Test │ │ 📝 Draft│ │        │ │
│ A  │  │ 12 tools │ │ 8 tools  │ │ 0 tools  │ │        │ │
│ I  │  └──────────┘ └──────────┘ └──────────┘ └────────┘ │
│ L  │                                                       │
│    │  Recent Activity                                      │
│    │  · Deployed trello-mcp v1.2         2 hours ago      │
│    │  · Tests passed for zendesk-mcp     5 hours ago      │
│    │  · Created custom-crm project       1 day ago        │
│    │                                                       │
│    │  Quick Actions                                        │
│    │  [Upload Spec]  [Browse Templates]  [View Docs]      │
└────┴──────────────────────────────────────────────────────┘
```

### 3.3 Tool Editor (Core Screen)

```
┌────┬──────────────────────────────────────┬──────────────┐
│    │  trello-mcp  [Analyze] [Test] [Deploy]│              │
│ N  ├──────────────────────────────────────┤  Inspector   │
│ A  │                                      │              │
│ V  │     ┌──────────┐   ┌──────────┐     │  Tool Config │
│    │     │get_boards│──▶│get_cards │     │  ──────────  │
│ R  │     └──────────┘   └──────────┘     │  Name:       │
│ A  │                                      │  [get_boards]│
│ I  │     ┌──────────┐   ┌──────────┐     │              │
│ L  │     │create_   │   │update_   │     │  Description:│
│    │     │card      │   │card      │     │  [Fetch all  │
│    │     └──────────┘   └──────────┘     │   boards...] │
│    │                                      │              │
│    │     ┌──────────┐                     │  Parameters: │
│    │     │delete_   │                     │  ┌─────────┐│
│    │     │card      │                     │  │board_id ││
│    │     └──────────┘                     │  │string   ││
│    │                                      │  │required ││
│    │  [+ Add Tool]  Zoom: [- 100% +]     │  └─────────┘│
│    │                                      │  [+ Add Param]│
└────┴──────────────────────────────────────┴──────────────┘
```

### 3.4 MCP App Designer

```
┌────┬────────────┬──────────────────────┬──────────────┐
│    │ Components │      Preview         │  Properties  │
│ N  │            │                      │              │
│ A  │ ┌────────┐ │  ┌────────────────┐  │  Widget:     │
│ V  │ │ Table  │ │  │  Contact Grid  │  │  Data Grid   │
│    │ ├────────┤ │  │  ┌──┬──┬──┬──┐ │  │              │
│ R  │ │ Chart  │ │  │  │Na│Em│Ph│St│ │  │  Data Source:│
│ A  │ ├────────┤ │  │  ├──┼──┼──┼──┤ │  │  [get_contac]│
│ I  │ │ Form   │ │  │  │  │  │  │  │ │  │              │
│ L  │ ├────────┤ │  │  ├──┼──┼──┼──┤ │  │  Columns:    │
│    │ │ Card   │ │  │  │  │  │  │  │ │  │  ☑ name     │
│    │ ├────────┤ │  │  └──┴──┴──┴──┘ │  │  ☑ email    │
│    │ │ Stats  │ │  │                  │  │  ☑ phone    │
│    │ ├────────┤ │  │  [Refresh Data]  │  │  ☐ address  │
│    │ │ Map    │ │  └────────────────┘  │              │
│    │ └────────┘ │                      │  Pagination:  │
│    │            │  Preview as:         │  [25] per page│
│    │            │  [Claude][ChatGPT]   │              │
└────┴────────────┴──────────────────────┴──────────────┘
```

### 3.5 Deploy Screen

```
┌────┬──────────────────────────────────────────────────────┐
│    │  Deploy trello-mcp                                    │
│ N  │                                                       │
│ A  │  Target: [MCPEngine ▾]  [npm]  [Docker]  [Download]  │
│ V  │                                                       │
│    │  ┌─────────────────────────────────────────────────┐ │
│ R  │  │  Step 1: Build          ████████████████ Done ✓ │ │
│ A  │  │  Step 2: Test           ████████████████ Done ✓ │ │
│ I  │  │  Step 3: Package        ████████░░░░░░░ 60%     │ │
│ L  │  │  Step 4: Deploy         ░░░░░░░░░░░░░░ Waiting  │ │
│    │  │  Step 5: Verify         ░░░░░░░░░░░░░░ Waiting  │ │
│    │  └─────────────────────────────────────────────────┘ │
│    │                                                       │
│    │  Live Logs:                                           │
│    │  ┌─────────────────────────────────────────────────┐ │
│    │  │ ▸ Compiling TypeScript...                       │ │
│    │  │ ▸ Bundling for Cloudflare Workers...            │ │
│    │  │ ▸ Uploading bundle (24KB)...                    │ │
│    │  └─────────────────────────────────────────────────┘ │
│    │                                                       │
│    │  Your server will be live at:                         │
│    │  https://trello.mcpengine.run                        │
└────┴──────────────────────────────────────────────────────┘
```

### 3.6 Marketplace

```
┌────┬──────────────────────────────────────────────────────┐
│    │  Templates                    [Search...        🔍]  │
│ N  │                                                       │
│ A  │  [All] [CRM] [eCommerce] [HR] [Marketing] [Support] │
│ V  │                                                       │
│    │  ┌──────────┐ ┌──────────┐ ┌──────────┐            │
│ R  │  │ ⭐       │ │          │ │          │            │
│ A  │  │ Trello   │ │ Zendesk  │ │ Mailchimp│            │
│ I  │  │ 12 tools │ │ 15 tools │ │ 8 tools  │            │
│ L  │  │ 3 apps   │ │ 4 apps   │ │ 2 apps   │            │
│    │  │ ★★★★★    │ │ ★★★★☆    │ │ ★★★★★    │            │
│    │  │ [Fork]   │ │ [Fork]   │ │ [Fork]   │            │
│    │  └──────────┘ └──────────┘ └──────────┘            │
│    │                                                       │
│    │  ┌──────────┐ ┌──────────┐ ┌──────────┐            │
│    │  │ Stripe   │ │ HubSpot  │ │ Shopify  │            │
│    │  │ ...      │ │ ...      │ │ ...      │            │
│    │  └──────────┘ └──────────┘ └──────────┘            │
└────┴──────────────────────────────────────────────────────┘
```

---

## 4. User Flow: 60-Second First Server

```
[Sign Up / Sign In]
        │
        ▼
┌─────────────────────────────┐
│  "Build your first server"  │  ← Full-screen welcome, no sidebar
│                             │
│  Paste an OpenAPI spec URL  │
│  ┌───────────────────────┐  │
│  │ https://api.trello... │  │  ← Auto-focused input
│  └───────────────────────┘  │
│                             │
│  Or: [Upload File] [Pick a Template] │
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│  Analyzing...               │  ← Animated progress
│  ████████████░░░░ 75%       │     Each tool appears as a card
│                             │     as it's discovered
│  Found: get_boards ✓        │
│  Found: get_cards ✓         │
│  Found: create_card ✓       │
│  Finding more...            │
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│  Found 12 tools!            │  ← Tool editor with tools pre-loaded
│  [Review & Customize]       │     User can toggle, rename, tweak
│  or [Deploy Now →]          │  ← Skip to deploy for speed
└──────────────┬──────────────┘
               │ (click Deploy Now)
               ▼
┌─────────────────────────────┐
│  Deploying to MCPEngine...  │  ← Progress stepper
│  ████████████████████ 100%  │
│                             │
│  🎉 Your server is LIVE!   │  ← CONFETTI BURST
│                             │     Screen shakes slightly
│  https://trello.mcpengine.run │   Glow animation on URL
│                             │
│  [Copy URL] [Open Dashboard]│
│  [Add to Claude Desktop]    │  ← Deep link / config snippet
└─────────────────────────────┘

Total time: ~60 seconds
```

---

## 5. Animation & Micro-Interaction Spec

| Element | Trigger | Animation | Duration | Easing |
|---------|---------|-----------|----------|--------|
| Page transition | Route change | Fade + slide up 8px | 150ms | ease-out |
| Modal open | Click | Backdrop fade + modal scale from 95% | 200ms | spring(1, 80, 10) |
| Modal close | Click/Esc | Reverse of open | 150ms | ease-in |
| Toast enter | Event | Slide in from right | 200ms | ease-out |
| Toast exit | Auto/click | Fade out + slide right | 150ms | ease-in |
| Canvas zoom | Scroll/pinch | Smooth interpolation | 200ms | ease-out |
| Tool node hover | Hover | Scale to 1.02, shadow-md | 150ms | ease-out |
| Tool node select | Click | Border glow (indigo), shadow-glow | 200ms | ease-out |
| Inspector open | Node select | Slide in from right | 200ms | ease-out |
| Inspector close | Deselect | Slide out right | 150ms | ease-in |
| Deploy confetti | Deploy success | Canvas confetti burst (200 particles) | 3s | physics-based |
| Deploy glow | Deploy success | URL pulsing glow | 2s loop | ease-in-out |
| Button press | Click | Scale to 0.97, then back | 100ms | ease-out |
| Input focus | Focus | Border color transition + ring expand | 150ms | ease-out |
| Loading spinner | Async op | Rotate 360° | 1s loop | linear |
| Skeleton pulse | Loading state | Opacity 0.5 → 1 → 0.5 | 1.5s loop | ease-in-out |
| Tool discovered | Analysis | Slide up + fade in from bottom | 300ms | spring |
| Progress bar | Generation | Width transition | 100ms | linear |

### Deploy Confetti Spec
```typescript
// Using canvas-confetti library
confetti({
  particleCount: 200,
  spread: 90,
  origin: { y: 0.6 },
  colors: ['#6366F1', '#10B981', '#F59E0B', '#EF4444', '#3B82F6'],
  gravity: 1.2,
  scalar: 1.1,
  ticks: 150,
});
```

---

## 6. States

### Empty States
| Screen | Illustration | Headline | CTA |
|--------|-------------|----------|-----|
| Dashboard (no projects) | Rocket illustration | "Launch your first MCP server" | [Create Project] or [Browse Templates] |
| Tool Editor (no tools) | Magnifying glass | "Upload a spec to discover tools" | [Upload Spec] |
| App Designer (no apps) | Paint palette | "Design your first app" | [Add Component] |
| Marketplace (no results) | Empty box | "No templates match your search" | [Clear Filters] |
| Test Dashboard (no tests) | Clipboard | "Run tests to see results" | [Run All Tests] |

### Loading States
- **Skeleton screens** for all list/grid views (pulsing gray-700/gray-800 blocks)
- **Inline spinners** for button actions (replace button text with spinner)
- **Progress bars** for multi-step operations (analysis, generation, deploy)
- **Streaming text** for AI generation (typewriter effect, 30ms per character)

### Error States
- **Inline errors:** Red border + error message below input
- **Toast errors:** For async failures (API errors, deploy failures)
- **Full-page errors:** 404, 500 with illustration + retry button
- **Recoverable:** Yellow warning banner with "Retry" action
- **Generation failures:** Show partial results + "Continue from here" option

---

## 7. Accessibility

### Requirements (WCAG 2.1 AA)
- **Color contrast:** 4.5:1 minimum for text, 3:1 for large text and UI components
- **Focus indicators:** 2px indigo ring with 2px offset on all interactive elements
- **Keyboard navigation:** Full tab order through all UI, Escape closes modals/inspectors
- **Screen readers:** All images have alt text, all interactive elements have aria-labels
- **Reduced motion:** `prefers-reduced-motion` disables confetti, reduces transitions to opacity-only
- **Canvas accessibility:** React Flow nodes are tabbable with arrow key navigation
- **Touch targets:** Minimum 44x44px for all interactive elements

### Focus Ring Spec
```css
.focus-visible {
  outline: 2px solid #6366F1;
  outline-offset: 2px;
}
/* On dark surfaces */
.dark .focus-visible {
  outline-color: #818CF8;
}
```

---

## 8. Responsive Strategy

**Desktop-first** (primary target: 1280px+)

| Breakpoint | Layout Change |
|-----------|---------------|
| `≥1280px` (xl) | Full layout: NavRail + Canvas + Inspector |
| `1024-1279px` (lg) | Inspector becomes overlay (toggle) |
| `768-1023px` (md) | NavRail collapses to icons, Inspector is modal |
| `<768px` (sm) | Mobile: bottom tab bar, full-screen views, no canvas editor |

**Mobile (sm):** Dashboard and Marketplace work. Editor and App Designer show "Open on desktop for the full experience" with limited read-only preview.

---

## 9. Icon System

- **Library:** Lucide Icons (consistent, MIT licensed, works with React)
- **Size:** 16px (inline), 20px (buttons/nav), 24px (feature icons), 32px (empty states)
- **Style:** Stroke weight 1.5px, consistent with Inter's visual weight
- **Custom icons:** MCP logo, MCPEngine logo, deploy/rocket, tool/wrench

### Nav Rail Icons
| Icon | Label | Lucide Icon |
|------|-------|-------------|
| Home | Dashboard | `LayoutDashboard` |
| Edit | Editor | `Workflow` |
| Palette | App Designer | `Palette` |
| Flask | Testing | `FlaskConical` |
| Rocket | Deploy | `Rocket` |
| Store | Marketplace | `Store` |
| Settings | Settings | `Settings` |

---

*Document Version: 1.0 | Last Updated: February 6, 2026*