🎨 MCP Awesome Design — Design Token Engine

A Model Context Protocol (MCP) server that gives AI agents structured JSON Design Tokens and platform-specific UX guardrails from the awesome-design-md ecosystem.

Instead of giving the AI a wall of text to interpret, this MCP gives it exact hex values, pixel sizes, font weights, component blueprints, and 54 professional UX rules — so it builds like a senior designer, not a guessing machine.

🚀 Installation

Add this to your MCP client configuration (Cursor, Claude Desktop, Antigravity, etc.):

{
  "mcpServers": {
    "awesome-design": {
      "command": "npx",
      "args": ["-y", "mcp-awesome-design"]
    }
  }
}

No dependencies to install. No API keys. Runs via npx.

🛠️ Tools

list_available_designs

Lists all 59+ available design systems. Indicates which have curated JSON tokens (★) and which use markdown fallback (○).

★ spotify (curated JSON tokens)
★ stripe (curated JSON tokens)
○ bmw (markdown fallback)

set_active_design(projectPath, designName)

Saves a design choice to .design-mcp/config.json in your project. Persists across sessions — set it once, forget it.

get_active_design(projectPath, platform?)

Returns the full design system for the active project. The platform parameter (web | android | ios) determines which UX guardrails are included.

For curated systems (★), returns strict JSON:

{
  "name": "Spotify",
  "theme": "dark",
  "tokens": {
    "colors": {
      "primary": "#1DB954",
      "background": "#121212",
      "surface": "#181818",
      "text": "#FFFFFF",
      "muted": "#B3B3B3"
    },
    "typography": {
      "fontFamily": "'Circular Std', 'Montserrat', sans-serif",
      "weights": { "normal": 400, "medium": 500, "bold": 700 }
    },
    "rounding": { "button": "500px", "card": "8px" },
    "shadows": { "card": "0 8px 24px rgba(0,0,0,0.5)" }
  },
  "rules": [
    "NEVER use borders on cards. Use background elevation instead.",
    "ALWAYS use pill-shaped buttons (border-radius: 500px) for primary CTAs."
  ],
  "components": { ... },
  "platform": "web",
  "guardrails": [
    "NEVER set body font-size below 16px.",
    "NEVER let text lines exceed 75 characters wide.",
    "..."
  ]
}

For non-curated systems, returns the upstream Markdown from VoltAgent's GitHub repo plus the platform guardrails.

export_theme_config(projectPath, format, write?)

Generates a ready-to-use theme file from the active curated design:

| format | output | |---|---| | "tailwind" | tailwind.config.js with theme.extend | | "css" | globals.css with :root { --color-primary: ... } |

Set write: true to save the file directly into the project.

get_component_blueprint(projectPath, componentName, platform?)

Returns the precise blueprint for a specific component — anatomy, tokens, interaction rules — plus platform guardrails.

{
  "designSystem": "Stripe",
  "component": "Card",
  "structure": "White background, subtle shadow, rounded corners.",
  "tokens": { "bg": "#FFFFFF", "shadow": "0 4px 6px rgba(50,50,93,0.11)", "radius": "12px" },
  "brandRules": ["ALWAYS use Weight-600 for headings."],
  "guardrails": ["NEVER make touch targets smaller than 44x44px."]
}

🛡️ UX/UI Guardrails

Every response includes platform-aware UX guardrails — 54 professional rules that prevent the AI from making fundamental usability mistakes:

| Layer | Count | Examples | |---|---|---| | Universal | 12 | Contrast ratios, visual hierarchy, loading states, accessibility | | Web | 14 | Min font 16px, hover/focus states, CLS prevention, aria-labels | | Android | 14 | 48dp touch targets, ripple effects, Material elevation, edge-to-edge | | iOS | 14 | 44pt touch targets, Safe Areas, Dynamic Type, swipe-back, haptics |

★ Curated Design Systems

10 brands with high-fidelity JSON tokens (colors, typography, spacing, shadows, rules, components):

| Brand | Theme | Primary | Components | |---|---|---|---| | Spotify | dark | #1DB954 | Card, PlayButton, Pill, SearchBar | | Stripe | light | #635BFF | Card, Button, Navbar | | Vercel | dark | #000000 | Card, Button, Badge | | Airbnb | light | #FF5A5F | ListingCard, SearchBar, Button | | Apple | light | #0071E3 | HeroSection, LinkButton, NavBar | | Linear | dark | #5E6AD2 | IssueRow, CommandPalette, Button | | Figma | light | #A259FF | FeatureCard, Button | | Notion | light | #000000 | PageBlock, Sidebar, Button | | Supabase | dark | #3ECF8E | DashboardCard, Button, CodeBlock | | Tesla | dark | #E82127 | HeroSection, GhostButton, FilledButton |

All other 49 systems are available via markdown fallback from VoltAgent's GitHub repository.

📁 Architecture

src/
├── index.ts                  Entry point
├── server.ts                 MCP tool definitions + dispatch
├── constants.ts              GitHub API configuration
├── utils.ts                  Config I/O and fetch utilities
├── tools/
│   ├── list-designs.ts       list_available_designs handler
│   ├── set-active-design.ts  set_active_design handler
│   ├── get-active-design.ts  get_active_design handler
│   ├── export-theme.ts       export_theme_config handler
│   └── get-blueprint.ts      get_component_blueprint handler
├── tokens/
│   ├── schema.ts             TypeScript interfaces
│   ├── registry.ts           10 curated design token sets
│   └── guardrails.ts         54 UX/UI rules (web/android/ios)
└── generators/
    ├── tailwind.ts            Tailwind config generator
    └── css.ts                 CSS variables generator

🤝 Credits

• Design Systems Content: VoltAgent/awesome-design-md
• MCP Token Engine: Built by Danless

📜 License

MIT