The Designer MCP

Part of the HeLa MCP Ecosystem — This server is HeLa Phenotype (hela-phenotype) — the Design component of the HeLa cellular architecture. See the ecosystem docs for profiles, workflows, and multi-client setup.

A Design-Theory-as-a-Service Model Context Protocol (MCP) server for production-grade UI design. Unlike standard code-retrieval MCPs, designer-mcp codifies subjective design principles—perceptual color math (OKLCH), motion physics, typographic scaling, and accessibility—into executable algorithms with strict anti-slop quality gates.

Featuring 17 design systems, 328+ brand references, motion.dev & anime.js motion integration, WCAG 2.1 accessibility auditing, React/Vue component output, and framework-agnostic CSS generation.

Table of Contents

• Features
• Tools
• Motion Design
• Examples
• Installation
• Usage
• Architecture
• Anti-Slop Design Philosophy
• Configuration
• Configuring with AI Assistants
• License

Features

• Anti-Slop Quality Gates — 31-gate slop test + 6-axis self-critique (P-H-E-S-R-V). Rejects anything < 3.
• OKLCH Token System — 16 curated themes with auto dark-mode derivation (full_css field ships both :root and @media (prefers-color-scheme: dark) + [data-theme="dark"] overrides).
• Design Rules Generator — 17 design systems + 4 palettes + 5 archetypes + hybrid combos.
• Pre-Flight Scan — Detect existing project context: framework, font stack, palette tokens, motion libraries.
• Framework-Native Components — Every component (button, card, navbar, hero, etc.) outputs HTML/Tailwind, React TSX (typed FC with prop interface), or Vue 3 SFC (script setup) via the framework param.
• CSS Output Engine — Generate vanilla CSS, CSS Modules (Button/Card/Input with all 8 states), SCSS (variables + mixins + BEM), or a single tokens.css with auto dark-mode overrides.
• WCAG 2.1 Accessibility Audit — 25-check static auditor: alt text, unlabeled inputs, empty buttons/links, heading order, focus-visible removal, skip links, landmark regions, viewport scale lock, and more. Returns 0-100 score + A–F grade + actionable fixes.
• SOTA Motion System (motion.dev & anime.js) — Style-aware animation presets baked into components. generate_motion_snippet for on-demand snippets with React <motion.div> and vanilla physics support (8 categories, all reduced-motion guarded).
• Color Palette Hunter — Live palettes from Color Hunt with format conversion.
• Brand Design References — 328+ real-world brands (Stripe, Vercel, Notion, Claude, Tesla, etc.).

Tools

Core Design Flow

Theme & Token System

Quality Gates

Component & Template

CSS Output

Motion (motion.dev & anime.js)

Color & Palette

Brand References

Utility

Motion Design

The MCP provides a dual-engine motion system: motion.dev (modern, physics-based, React-native) and anime.js v3 (lightweight vanilla JS).

When calling generate_motion_snippet or get_component (for React), the output is automatically calibrated to the design system's character:

Use generate_motion_snippet for standalone snippets targeting specific use cases across React, Vue, and HTML:

{
  "tool": "generate_motion_snippet",
  "arguments": {
    "category": "entrance",
    "style": "glass",
    "engine": "motion.dev",
    "framework": "react"
  }
}

Returns { cdn, snippet, easing, duration, usage_hint, reduced_motion_note }.

All snippets respect prefers-reduced-motion — animations are skipped entirely when the user has enabled reduced motion.

Examples

🔥 Live Demo: Ellis UI Collection

Ellis UI (examples/ellis-ui)
A comprehensive, anti-slop component library demonstrating the extreme versatility of designer-mcp's ruleset. The project takes a single romantic letter and renders it across 24 radically different, strictly enforced aesthetic systems (e.g., Swiss Archival, Vintage Airmail, Brutalist, UNIX Phosphor, 8-Bit Game Boy).

Each design acts as a fully standalone, reusable UI kit utilizing zero JS dependencies—relying entirely on strict structural typography, CSS geometry, and advanced CSS rendering techniques (clip-paths, custom filters, OKLCH gradients). Each of the 24 folders includes a design.md detailing the tokens and layout strategy, acting as an advanced template reference for designer-mcp.

Installation

git clone https://github.com/1999AZZAR/designer-mcp.git
cd designer-mcp
npm install
npm run build

Requirements: Node.js >= 18

Usage

npm start

npx @modelcontextprotocol/inspector node dist/index.js

Architecture

designer-mcp operates on a multi-tier architecture. An MCP server on its own is just an API; by pairing the MCP with three companion AI skills, the AI gets both the tools (the MCP) and the instruction manual (the skills).

• ui-designer skill: Provides the design intelligence, heuristics, and brand context so the AI knows what to ask the MCP to generate.
• color-palette-hunter skill: Handles external palette sourcing and feeds them into the OKLCH token engine.
• motion-designer skill: Defines SOTA animation heuristics, spring physics logic, and motion.dev best practices.

src/
  index.ts              # MCP server entry, tool routing (27 tools)
  rules.ts              # 17 design systems, palettes, archetypes, hybrids
  anti-patterns.ts      # 31-gate slop test + 6-axis self-critique
  a11y-audit.ts         # 25-check WCAG 2.1 accessibility auditor (no deps, regex-only)
  tokens.ts             # 16 curated themes, OKLCH token generation, dark mode derivation
  css-output.ts         # vanilla CSS / CSS Modules / SCSS / css-variables-only generator
  anime-motion.ts       # anime.js v3 integration — style-aware presets, CDN helper, snippet generator
  components.ts         # Component library — HTML/React TSX/Vue 3 SFC output
  components-8state.ts  # 8-state component demo generator (anime.js micro-interactions)
  preflight.ts          # Project context scanner (framework, fonts, palette, motion)
  evaluate.ts           # Style scoring engine
  palette.ts            # Color Hunt palette fetcher
  palette-convert.ts    # Format converter
  palette-variants.ts   # Light/dark/high-contrast variant generator
  templates.ts          # HTML template generator (anime.js baked in)
  tailwind-config.ts    # Tailwind config generator
  export.ts             # Project scaffold exporter
skills/
  ui-designer/          # Reference docs + genre files (git submodule)
  color-palette-hunter/ # Palette CLI scripts (git submodule)

Anti-Slop Design Philosophy

• Locked tokens — every color/font references a named CSS variable, never inline values
• No fabricated content — real metrics or labeled placeholders only
• No re-drawn chrome — no fake browser bars, phone frames, or code window chrome
• Typography purity — headings always roman, no italic display faces
• Structural variety — different briefs produce structurally different pages
• Mobile-responsiveness hard floor — 320/375/414/768px, overflow-x: clip, minmax(0, 1fr), no two-line clickable text
• OKLCH-first — all new tokens defined in OKLCH for perceptual uniformity
• Motion with restraint — animations are style-calibrated, spring-physics-grounded, and always gated on prefers-reduced-motion

Configuration

Configuring with AI Assistants

{
  "mcpServers": {
    "designer-mcp": {
      "command": "node",
      "args": ["/path/to/designer-mcp/dist/index.js"],
      "env": {}
    }
  }
}

License

MIT