mcp-app-design
Design system for MCP App interfaces rendering inside Claude, VS Code, and other MCP hosts. Contains CSS custom properties (colors, typography, spacing, shadows for light/dark themes), component patte
SKILL.mdskills/ui-ux/mcp-app-design/SKILL.md
GitHubMCP App Design System
Build interactive HTML UIs that render inside MCP host conversations (Claude, Claude Desktop, VS Code Copilot, Goose, etc.) as sandboxed iframes.
Feedback Loop
Read FEEDBACK.md before every use to apply lessons from prior builds.
- Detect — After building an MCP App UI, note anything that didn't work: a CSS variable that wasn't injected, a component pattern that needed modification, a host-specific rendering quirk, or a gap in the token system.
- Search — Check
FEEDBACK.mdfor existing entries on the same issue. - Scope — One actionable observation per entry.
- Draft-and-ask — Propose the entry to the user before writing.
- Write-on-approval — Append with date and category tag.
- Compact-at-75 — Merge duplicates, promote patterns to reference files, archive resolved. Reset to ~30 entries.
When to Read References
Read the reference files based on what you're building:
| Reference | When to read |
|---|---|
references/design-tokens.md |
Always — contains the complete CSS custom property system, light/dark theme values, typography scale, spacing, shadows, radii |
references/component-patterns.md |
When building UI with buttons, forms, cards, sliders, notices, or any interactive elements |
references/architecture.md |
When scaffolding a new MCP App project, declaring tools with UI, or setting up the App class communication |
Read design-tokens.md first on every MCP App task — it defines the CSS custom properties that the host injects, and your UI consumes these variables rather than hardcoding colors.
Core Principles
1. Host-Injected Theming
MCP Apps don't control their own theme. The host (Claude, VS Code, etc.) pushes CSS custom properties and a theme value ("light" or "dark") to your app via the host context. Your job is to consume these variables, not define your own color palette.
The light-dark() CSS function is the primary mechanism for automatic theme adaptation. Define fallback values in :root using this function, and the host's variables override them seamlessly via applyHostStyleVariables().
:root {
color-scheme: light dark;
--color-text-primary: light-dark(#1f2937, #f3f4f6);
--color-background-primary: light-dark(#ffffff, #1a1a1a);
}
2. Fallback Values Are Mandatory
Define fallback values for every CSS custom property in :root using light-dark(). Host variable injection may be delayed (race condition on initial load) or absent (unsupported host, local testing without the basic-host harness). Your app should render correctly with only its own fallbacks — host variables are an enhancement, not a requirement.
The Quick Start CSS below demonstrates the correct pattern. When adding new variables, follow the same approach: local fallback first, host override via applyHostStyleVariables() second.
3. Sandboxed Iframe Constraints
Your UI runs in a sandboxed iframe:
- All communication goes through postMessage (the App class handles this)
- External scripts need CSP whitelisting via
_meta.ui.csp - Bundle everything into a single HTML file with
vite-plugin-singlefileto avoid CSP issues - No
localStorage/sessionStorage— use in-memory state or persist data via tool calls - No access to parent window DOM or cookies
4. Compact Layout
MCP App iframes have constrained width inside the conversation column. Design for:
- Basic tools:
max-width: 425px— single-column, focused interaction - Dashboards/complex apps:
max-width: 600px(orwidth: 100%for full-width) - Height: Typically 400-600px; design to avoid scrolling when possible
- Always use
box-sizing: border-boxon everything - Padding: 8-12px for compact apps, 16-24px for spacious layouts
5. Font Inheritance
Use the host's font stack via CSS custom properties rather than hardcoding font families, because each host has its own typography:
body {
font-family: var(--font-sans);
font-size: var(--font-text-md-size);
line-height: var(--font-text-md-line-height);
}
code, pre {
font-family: var(--font-mono);
}
6. Spacing System
Derive spacing from the typography scale to keep proportions consistent:
:root {
--spacing-unit: var(--font-text-md-size); /* 1rem */
--spacing-xs: calc(var(--spacing-unit) * 0.25); /* 4px */
--spacing-sm: calc(var(--spacing-unit) * 0.5); /* 8px */
--spacing-md: var(--spacing-unit); /* 16px */
--spacing-lg: calc(var(--spacing-unit) * 1.5); /* 24px */
}
Quick Start CSS
Minimal :root with proper fallbacks for a new MCP App. See architecture.md → "UI: Host Context and Theming" for the TypeScript theme bridging setup that wires these up to the host.
:root {
color-scheme: light dark;
--color-text-primary: light-dark(#1f2937, #f3f4f6);
--color-text-secondary: light-dark(#6b7280, #9ca3af);
--color-background-primary: light-dark(#ffffff, #1a1a1a);
--color-background-secondary: light-dark(#f5f5f5, #2d2d2d);
--color-border-primary: light-dark(#e5e7eb, #404040);
--color-ring-primary: light-dark(#3b82f6, #60a5fa);
--border-radius-md: 6px;
--border-width-regular: 1px;
--font-sans: system-ui, -apple-system, sans-serif;
--font-mono: ui-monospace, 'SF Mono', Monaco, monospace;
--font-weight-normal: 400;
--font-weight-bold: 700;
--font-text-md-size: 1rem;
--font-text-md-line-height: 1.5;
--spacing-unit: var(--font-text-md-size);
--spacing-xs: calc(var(--spacing-unit) * 0.25);
--spacing-sm: calc(var(--spacing-unit) * 0.5);
--spacing-md: var(--spacing-unit);
--spacing-lg: calc(var(--spacing-unit) * 1.5);
/* App-level accent (not a host token — define per-app) */
--color-accent: #2563eb;
--color-text-on-accent: #ffffff;
}
*, *::before, *::after { box-sizing: border-box; }
html, body {
margin: 0; padding: 0;
font-family: var(--font-sans);
font-size: var(--font-text-md-size);
line-height: var(--font-text-md-line-height);
color: var(--color-text-primary);
background: var(--color-background-primary);
transition: background-color 0.2s, color 0.2s;
}
Note:
--color-accentand--color-text-on-accentare app-level variables you define yourself — they're not part of the host token system. Each MCP App can brand its primary action color independently.
Anti-Patterns
Avoid these patterns because they break in the MCP App sandbox or produce inconsistent rendering across hosts:
- Hardcoded colors — Use
var(--color-text-primary)instead ofcolor: #333, because the host controls the palette and may be in dark mode. - Fixed widths over 600px — The conversation column is narrow. Design mobile-first.
- Separate CSS files without CSP config — Bundle CSS inline or configure CSP. Separate files won't load in the sandbox without whitelisting.
- Using localStorage — Sandboxed iframes can't access storage. Use React state, JS variables, or persist via tool calls.
- Ignoring host theme changes — Wire up
onhostcontextchangedto re-apply theme, because users can switch themes mid-conversation. - Heavy frameworks — The iframe loads fresh each time. Prefer Preact (
3KB) over React (40KB) for MCP Apps, since every KB matters on cold loads. Aim for under 100KB total bundle size.
Accessibility Baseline
All MCP App UIs should meet these minimum standards:
- Interactive elements have appropriate ARIA labels when their purpose isn't clear from visible text
- Color combinations meet WCAG AA contrast ratios (4.5:1 for normal text, 3:1 for large text)
- All interactive elements are keyboard-navigable with visible focus indicators (the
focus-visiblepatterns incomponent-patterns.mdhandle this) - Form inputs have associated
<label>elements oraria-labelattributes