29 KiB
29 KiB
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) orgap-3(12px) - Page margins:
px-6on desktop,px-4on mobile
1.4 Elevation / Shadows
--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
// 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-motiondisables 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
.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