The Designer MCP

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.

46 tools across 18 design systems (including Awwwards SOTA / Avant-Garde): anti-slop quality gates, motion.dev & anime.js integration, WCAG 2.1 auditing, React/Vue component output, framework-agnostic CSS, logo & brand-mark design backed by a 1,432-mark reference library, and Stitch Canvas & workflow integration.

Table of Contents

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

Features

• Anti-Slop Quality Gates — 35-gate slop test + 6-axis self-critique (P-H-E-S-R-V). Rejects anything < 3.
• OKLCH Token System — 19 curated themes across 5 genres (including avant-garde: Obsidian Kinetic, Tokyo Neo-Brutal, Atelier Craft) with auto dark-mode derivation (full_css field ships both :root and @media (prefers-color-scheme: dark) + [data-theme="dark"] overrides).
• Design Rules Generator — 18 design systems (including awwwards) + 7 palettes (including obsidian-noir, copper-cyber, acid-avant) + 6 archetypes (including awwwards-bento) + 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 (14 categories including magnetic, text-split, smooth-scroll, marquee, noise-grain, clip-path-mask, all reduced-motion guarded).
• Color Palette Hunter — Live palettes from Color Hunt with format conversion.
• Brand Design References — brand_fetch_design_md resolves DESIGN.md from the full 328+ brand getdesign catalog (Stripe, Vercel, Notion, Claude, Tesla, etc.); brand_list returns the 62-brand curated subset shipped locally.
• Stitch Canvas & Visual Workflow Integration — 9 Stitch tools superseding the standalone Stitch MCP server: 7 core resource tools (stitch_get, stitch_find, stitch_create, stitch_edit, stitch_delete, stitch_generate, stitch_url) plus 2 Phenotype bridge tools: stitch_sync_design_system (exports OKLCH tokens to Stitch DESIGN.md & designSystem JSON) and stitch_screen_audit (evaluates Stitch-captured screens against WCAG 2.1, 35 anti-slop gates, and 6-axis craft critique).
• Logo & Brand-Mark Design — the in-tree logo-design skill plus 8 logo_* tools: SVG audit, a searchable 1,432-mark reference library, PNG/favicon rendering, mono/square/app-icon delivery variants, concept sheets, test sheets, and client presentation boards.

Tools

Core Design Flow

Stitch Canvas & Workflow Integration

Theme & Token System

Quality Gates

Component & Template

CSS Output

Motion (motion.dev & anime.js)

Color & Palette

Brand References

Logo Design (see "Logo design" below)

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/Hela-Ecosystem/designer-mcp.git
cd designer-mcp
npm install
npm run build

Requirements: Node.js >= 18. The logo_* tools additionally need Python 3 (nothird-party packages) and at least one SVG renderer — cairosvg, rsvg-convert, Inkscape, orheadless Chrome. Check what is available with the logo_renderers tool. The other 29 tools haveno runtime dependency beyond Node.

Usage

npm start

npx @modelcontextprotocol/inspector node dist/index.js

Development

npm run build   # tsc
npm test        # 39 checks across two suites

Tests are plain node scripts that import the TypeScript sources directly through--experimental-strip-types; there is no test framework dependency. path-containment.test.mjsdrives the real server over stdio to keep the CWE-22 regression honest (see below). logo-tools.test.mjsruns the real Python scripts in a temp directory rather than mocking them, so a change to ascript's CLI surface fails the suite instead of silently drifting from src/logoTools.ts.

Path handling and the security boundary

Two different rules, and the difference is deliberate:

• Names that address a bundled file — get_reference (a reference doc) andget_ellis_ui_template (a design folder) — go through resolveWithinRoot() insrc/envelope.ts. It refuses separators, .., absolute paths and NUL bytes, resolves againstthe real path of the trusted root, and verifies the result is still inside it, so neither acrafted argument nor a symlink can read outside the skill. This closes CWE-22 in get_reference(issue #14), which concatenated the argument straight into a path.
• Paths the caller deliberately supplies — pre_flight_scan on a project directory, and thelogo_* tools on artwork files — are allowed anywhere, because supplying your own project pathis the feature. They validate that the path exists and is the right kind of thing, and are theone place an MCP client can still read a file of its choosing.

pre-commit

Hooks are configured in .pre-commit-config.yaml and cover this repo:

Three trees are kept byte-stable and excluded from the reformatting hooks, each for astated reason rather than by convenience: examples/ (demo artifacts must match what wasdesigned), skills/video/ (canonical upstream HyperFrames packages), andskills/logo-design/assets/library/ (generated indexes plus third-party reference marks).The list is repeated per hook because pre-commit has no shared exclude — keep the three in syncwhen you add a fourth.

prettier runs as a system command via scripts/prettier-hook.sh, not through pre-commit'snodeenv installer: pre-commit 4.6.x installs node hooks with npm install --allow-git=root, whichnpm >= 11 rejects for non-root users, so the stock mirrors-prettier hook cannot install at allon this machine. The wrapper prefers node_modules/.bin/prettier, falls back to prettier onPATH, and warns instead of blocking when neither exists.

Heads-up: this machine sets a global core.hooksPath whose hook is scoped tochaining-mcp, so these hooks do not fire automatically on git commit here. Runpre-commit run --all-files before pushing, or add the repo to that global hook's allowlist.

Architecture

designer-mcp operates on a multi-tier architecture. An MCP server on its own is just an API; by pairing the MCP with four 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.
• logo-design skill: Professional logo and brand-mark design, brief to production files, plus a searchable library of 1,432 real-world SVG logos for category research.

src/
  index.ts              # MCP server entry, tool routing (37 tools)
  rules.ts              # 17 design systems, palettes, archetypes, hybrids
  anti-patterns.ts      # 35-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
  logoTools.ts          # logo-design wrappers: validate, exec, envelope
skills/
  ui-designer/          # Reference docs + genre files (git submodule)
  color-palette-hunter/ # Palette CLI scripts (git submodule)
  motion-designer/      # Motion/physics heuristics (in-tree)
  logo-design/          # Logo/brand-mark design skill (in-tree, origin in ATTRIBUTION.md)
  video/                # Canonical upstream HyperFrames v0.8.77 packages (byte-stable)
test/
  designer-envelope.test.mjs  # envelope shape, side-effect contract
  logo-tools.test.mjs         # 30 checks: validation + real script subprocesses
scripts/
  prettier-hook.sh      # pre-commit formatter entry point
examples/
  ellis-ui/             # 24 design systems showcase (byte-stable, deployed as the demo)

Skills live here in two forms. ui-designer and color-palette-hunter are git submodulespointing at standalone repos; motion-designer and logo-design are in-tree because they aretied to this server's tools. See Development for the rules that follow from that.

Logo design (logo_* tools)

The logo-design skill lives in-tree at skills/logo-design/ and is maintained here like anyother source. It began as a copy ofkaankiziltug/logo-design-skill (MIT; upstreamcopyright and licence retained, origin and maintenance rules inskills/logo-design/ATTRIBUTION.md). It ships the design workflow (brief → concepts → mark type →SVG construction → optical refinement → testing → presentation → delivery), nine dependency-freePython scripts (seven wrapped as tools, plus a shared svglib and a maintainer catalog builder),fourteen reference docs, two templates, and a 1,432-mark SVG library. skills/logo-design/HELA.mdis the HeLa overlay: palettes must come from the token engine, logotypes ship as outlines, gradientsand filters are rejected, and rendering before presenting is mandatory.

Eight tools expose the scripts to an agent. All of them are read-only with respect to your sourceartwork; the writers create new output files in the directory you name.

The design conversation itself still belongs to the skill. A typical run: logo_search_library tostudy the category, then the skill's concept phase, then logo_concept_sheet to show threedirections, then — only after the user picks one — logo_export_variants for the delivery set,gated on logo_audit and a rendered logo_preview_sheet.

{
  "name": "logo_audit",
  "arguments": { "files": ["/tmp/concepts/acme-a.svg"], "bg": "#ffffff" }
}

Renderer notes: on a machine with only headless Chrome, logo_render still works for PNG outputand HTML screenshots, but favicon assembly and multi-size batches are slower. Runlogo_renderers first when a deliverable depends on it.

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