systembridge-mcp: MCP Server for Design Systems

An AI-native Model Context Protocol (MCP) server that gives LLMs and agents deep knowledge of design systems and design tokens, enabling intelligent design system evolution, token analysis, and designer-to-developer handoffs.

What is this?

systembridge-mcp teaches AI assistants (like Claude, GPT, or custom agents) how to work with your design system. Instead of just answering questions about design, the AI can:

• Understand your design tokens: browse, search, and explain color palettes, spacing scales, and typography
• Plan new features: describe what you need ("a login page"), get components and tokens required
• Audit designs before handoff: check if your design has all the tokens it needs, find gaps, verify accessibility
• Match colors and components: upload a screenshot or describe UI, get back what matches your system
• Generate and validate tokens: create palettes, check WCAG contrast, scaffold semantic tokens
• Evolve your system: transform tokens, migrate naming, manage themes and brands

Designers: Think of it as a design system assistant that knows your token library. Ask "what red for error states?" or "what tokens should I apply on this mockup?" — no code required.

Developers: A programmatic interface to design tokens with AI-native tooling for analysis, transformation, and code generation.

Quick Start

What you need: Node.js 18+ and an AI assistant that supports MCP (e.g. Claude Desktop, Cursor).

1. Install in your design-token project:

   npm install -D systembridge-mcp

2. Add a config file in your project root (optional; sensible defaults apply):

   // .systembridge-mcp.json or systembridge-mcp.config.json
   { "tokenPaths": ["tokens/**/*.json", "design-tokens/**/*.json"] }

3. Add to your MCP config (e.g. .cursor/mcp.json for Cursor):

   {
     "mcpServers": {
       "systembridge-mcp": {
         "command": "npx",
         "args": ["systembridge-mcp"]
       }
     }
   }

4. Restart your AI assistant. Look for the MCP icon — you should see 32 tools from systembridge-mcp. No path configuration needed when using project-level config.

Next: Getting Started | Setup by Client (Cursor, VS Code, Claude) | Agent Instructions (optional AI guidance).
For local development: TESTING.

Example Conversations

For Designers

"I need to design a dashboard with data tables and stat cards. What components and tokens do I need?"

The AI uses plan_flow to identify UI patterns, list required components, and tell you what token slots to fill.

"I'm using button, text-input, card, and modal. Does my design system cover everything?"

The AI uses audit_design to check for missing tokens, naming issues, and accessibility problems.

"I see a UI with colors #3B82F6, #EF4444, #F3F4F6. Which tokens match?"

The AI uses analyze_ui with perceptual color matching to find the closest tokens.

For Developers

"Generate a brand color palette with hue 220, chroma 0.7, and map it to semantic tokens for light mode."

The AI uses generate_palette + map_palette_to_semantics + check_contrast to create accessible tokens.

"Run a full audit of my design tokens. Check naming, accessibility, and coverage."

The AI uses audit_semantics + analyze_coverage + check_contrast to produce a health report.

"I have legacy tokens that don't follow our naming convention. Help me migrate them safely."

The AI uses analyze_topology → generate_refactor_scenarios → execute_migration to plan and execute the migration.

Features

| Area | Tools | |------|-------| | Designer intelligence | plan_flow, audit_design, analyze_ui | | Token management | search_tokens, validate_tokens, transform_tokens | | Semantic tokens | scaffold_semantics, audit_semantics, analyze_coverage, describe_ontology | | Color & accessibility | generate_palette, map_palette_to_semantics, check_contrast | | Themes & brands | list_brands, resolve_brand, list_themes, resolve_theme, diff_brands, diff_themes | | Scales | analyze_scales, generate_scale, suggest_scale, derive_density_mode, audit_scale_compliance, generate_fluid_scale | | Migration | analyze_topology, audit_figma_usage, generate_refactor_scenarios, execute_migration | | Figma | extract_figma_tokens, validate_figma_tokens, generate_component_docs |

7 pre-built prompts orchestrate multiple tools: create-token, audit-tokens, design-semantic-tokens, design-color-palette, design-from-scratch, design-handoff-review, component-reference.

Full reference: docs/features.md

Documentation

| Guide | Description | |-------|-------------| | Getting Started | Full installation, config options, troubleshooting | | Setup by Client | Per-client setup (Cursor, VS Code, Claude Desktop, Claude Code) | | Agent Instructions | Optional AI usage guidance and rule templates | | Local Testing | Test with npm link without absolute paths | | For Designers | Designer workflow, example prompts, no-code usage | | For Developers | CLI, MCP API, extending the server, tests, benchmarks | | Features | Full feature and tool reference | | Configuration | Config file, env vars, token paths | | Migration System | Risk assessment and scenario generation | | Migration Executor | Execution, validation, and rollback | | Figma Integration | Figma variable sync and validation | | AGENT_HANDOFF | Architecture guide for LLMs and agents |

Contributing

Contributions welcome. Fork, create a feature branch, make your changes, run npm run build, and submit a pull request.

See docs/AGENT_HANDOFF.md for codebase architecture.

License

MIT — see LICENSE. Copyright © 2024–2026 Tasos Dervenagas.

Acknowledgments

Built on Model Context Protocol, Style Dictionary, Leonardo, and WCAG 2.1. Inspired by W3C DTCG, Tokens Studio, and design systems from Primer, Polaris, and Carbon.

Support: GitHub Issues · GitHub Discussions · MCP Discord