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.
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.
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.jsonfor 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.
"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.
"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.
| 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
| 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 |
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.
MIT — see LICENSE. Copyright © 2024–2026 Tasos Dervenagas.
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