jake/mcpengine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
mcpengine/studio/docs/UX-DESIGN-SPEC.md
Jake Shore 96e52666c5 MCPEngine full sync — studio scaffold, factory v2, server updates, state.json — 2026-02-12 
=== NEW ===
- studio/ — MCPEngine Studio scaffold (Next.js monorepo, build plan)
- docs/FACTORY-V2.md — Factory v2 architecture doc
- docs/CALENDLY_MCP_BUILD_SUMMARY.md — Calendly MCP build report

=== UPDATED SERVERS ===
- fieldedge: Added jobs-tools, UI build script, main entry update
- lightspeed: Updated main + server entry points
- squarespace: Added collection-browser + page-manager apps
- toast: Added main + server entry points

=== INFRA ===
- infra/command-center/state.json — Updated pipeline state
- infra/command-center/FACTORY-V2.md — Factory v2 operator playbook
2026-02-12 17:58:33 -05:00

572 lines
29 KiB
Markdown
Raw Blame History

# 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*
Reference in New Issue View Git Blame Copy Permalink