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.

License: MIT TypeScript MCP

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).

Install in your design-token project:
```
npm install -D systembridge-mcp
```

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"] }

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

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

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

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