systembridge-mcp
Enables extraction of design tokens from Figma variables, validation of Figma tokens against the design system, and generation of component documentation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@systembridge-mcp Audit my design tokens for accessibility issues."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: ds-mcp
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-mcpAdd 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.
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 |
|
Token management |
|
Semantic tokens |
|
Color & accessibility |
|
Themes & brands |
|
Scales |
|
Migration |
|
Figma |
|
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 |
Full installation, config options, troubleshooting | |
Per-client setup (Cursor, VS Code, Claude Desktop, Claude Code) | |
Optional AI usage guidance and rule templates | |
Test with | |
Designer workflow, example prompts, no-code usage | |
CLI, MCP API, extending the server, tests, benchmarks | |
Full feature and tool reference | |
Config file, env vars, token paths | |
Risk assessment and scenario generation | |
Execution, validation, and rollback | |
Figma variable sync and validation | |
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
Available Tools
37 toolsanalyze_coverageA
Show the semantic token coverage matrix — which UX contexts have which property classes covered, and where the gaps are. Displays a table of contexts × property classes with status indicators.
Inputs: pathPrefix.
analyze_scalesA
Analyze existing design token scales (spacing, typography, etc.). Detects mathematical patterns (linear, modular, fibonacci, etc.), identifies outliers, and suggests improvements based on design principles.
Inputs: tokens (required), dimension, compareAgainst.
analyze_topologyA
Analyze token topology with dependency graph, anti-pattern detection, and structure analysis. Shows token relationships, reference chains, isolated tokens, circular dependencies, and common anti-patterns like primitive leakage, naming inconsistencies, and redundant tokens. Includes visual dependency graph (Mermaid), distribution charts, and coverage matrix.
Inputs: pathPrefix, includeGraph, graphMaxDepth, graphMaxNodes, +2 more.
analyze_uiA
Analyze UI elements and colors against the design system. Describe the components you see and the colors used — get back which components are in the system, which colors match existing tokens (using perceptual color distance), and what gaps exist. Useful for reverse-engineering a screenshot or mockup into system terms.
Inputs: components (required), colors, description.
audit_designA
Audit a partial or complete design against the design system. Provide the components used in your design and get a gap analysis: missing tokens, naming issues, accessibility problems, and concrete fixes. Use this before handoff to ensure design-system coverage.
Inputs: components (required), description, checkAccessibility.
audit_figma_usageA
Audit Figma variable usage and cross-reference with local design tokens. Analyzes sync status between Figma variables and local token definitions, identifies unused tokens, missing definitions, and naming discrepancies. Helps maintain consistency between Figma designs and token system. Note: Requires Figma variable data from mcp_figma_get_variable_defs.
Inputs: figmaFileUrl (required), figmaNodeId, figmaVariableDefs.
audit_scale_complianceA
Audit design token scales against accessibility and platform standards. Checks WCAG 2.2 (44px touch targets, 1.5 line height), Material Design (8dp grid), and iOS HIG (8pt grid) compliance.
Inputs: tokens (required), standard, dimension.
audit_semanticsA
Run a comprehensive semantic token audit on your existing token set. Analyzes naming compliance, property-class separation, coverage gaps, scoping violations, accessibility pairing, and suggests migrations. Returns a health score (0-100) and detailed report.
Inputs: skipRules, pathPrefix.
check_contrastA
Check color contrast ratios using WCAG 2.1 and/or APCA algorithms. Two modes: (1) provide explicit foreground + background colors, or (2) scan your token set for all foreground/background pairs and report failures.
Inputs: algorithm, threshold, background, foreground, +1 more.
derive_density_modeA
Derive a new density mode (compact/spacious) from existing tokens. Applies scale factors while respecting WCAG accessibility constraints (44px minimum touch targets). Outputs conditional tokens.
Inputs: sourceTokens (required), targetDensity (required), roundTo, sourceDensity, +2 more.
describe_ontologyA
Explain the semantic token naming model — property classes (CSS targets), semantic intents, UX contexts, interaction states, emphasis modifiers, and the canonical naming formula. Use this to understand how semantic tokens should be structured.
Inputs: no named parameters.
diff_brandsA
Compare two brands side-by-side, showing which tokens differ between them. Optionally resolves both under the same theme.
Inputs: brandA (required), brandB (required), theme, pathPrefix.
diff_themesB
Compare two themes side-by-side and show which tokens differ, which are added, and which are removed.
Inputs: themeA (required), themeB (required), pathPrefix.
execute_migrationA
Execute token migration with automated reference updates, validation, and rollback. Applies scenario phases to token system, updates references across codebase, validates integrity (no broken refs/circular deps), and checks accessibility. DEFAULTS TO DRY RUN for safety - set dryRun:false to apply changes. Creates snapshot before execution for rollback if needed.
Inputs: dryRun, pathPrefix, scenarioId, phaseNumber, +3 more.
extract_figma_tokensA
Extract Figma variables and convert to standardized token formats (W3C, Tokens Studio, Style Dictionary). Takes Figma variable definitions from mcp_figma_get_variable_defs and transforms them into design tokens with proper type inference, collection mapping, and metadata. Useful for syncing Figma variables to your local token system.
Inputs: format (required), includeMetadata (required), figmaVariableDefs (required), collections.
extract_stylesA
Extract design tokens from CSS and SCSS files. Reverse-engineers colors, spacing, typography from stylesheets. Use when project has styles but no design tokens. Scans for CSS custom properties (--var: value) and SCSS variables ($var: value).
Inputs: stylePaths, outputFormat, writeToTokens.
generate_component_docsA
Generate comprehensive component documentation combining local tokens, Figma component data, and design system knowledge. Creates LLM+human-readable markdown with frontmatter, token references, code examples, and accessibility information. Perfect for design-to-development handoffs.
Inputs: format (required), componentNames (required), includeTokenRefs (required), includeCodeExamples (required), +2 more.
generate_fluid_scaleB
Generate fluid/responsive scales using CSS clamp(). Creates viewport-aware tokens that scale between min/max sizes. Based on Utopia fluid typography methodology.
Inputs: maxSize (required), minSize (required), unit, ratio, +4 more.
generate_make_guidelinesA
Generate a structured 'guidelines/' folder for Figma Make. Exports your design system's tokens and component rules into Markdown format that Figma Make's AI can use to understand your system context.
Inputs: outputDir, components.
generate_paletteA
Generate color palettes using pluggable strategies. Supports HSL ramp (built-in), Leonardo (optional), manual hex values, or importing from existing tokens. Returns tonal scales with contrast metadata.
Inputs: scales (required), steps, smooth, strategy, +1 more.
generate_refactor_scenariosA
Generate migration scenarios for token refactoring with risk assessment. Produces 3 approaches (conservative, progressive, comprehensive) with detailed action plans, effort estimates, and risk profiles. Helps plan B→C token migration by comparing trade-offs and recommending best path forward based on readiness.
Inputs: teamSize, approaches, pathPrefix, hoursPerWeek, +1 more.
generate_scaleA
Generate a mathematical scale for design tokens. Supports linear, modular (geometric), exponential, fibonacci, golden ratio, harmonic, and hybrid strategies. Returns token-ready values.
Inputs: strategy (required), base, step, unit, +4 more.
generate_systemB
Generate a new design-token system from a template. Supports color palettes, spacing scales, and full systems. Use dryRun=true to preview first.
Inputs: template (required), dryRun, params, outputDir.
list_brandsA
List all brands defined in config, showing their token paths, token-set overrides, and dimension defaults.
Inputs: no named parameters.
list_dimensionsA
List all variation dimensions (e.g. color-scheme, density) defined in your design-token theming config, with their allowed values and defaults.
Inputs: no named parameters.
list_templatesA
List all available factory templates for generating new token systems. Shows required parameters and built-in algorithm options.
Inputs: no named parameters.
list_themesA
List all named themes defined in config. Each theme is a specific combination of dimension values (e.g. dark + compact).
Inputs: no named parameters.
map_palette_to_semanticsA
Map generated palette scales to semantic tokens using configurable rules. Includes built-in presets for light-mode and dark-mode mappings. Can write output to disk with merge and split strategies.
Inputs: palette (required), rules, dryRun, preset, +5 more.
plan_flowA
Solve 'blank canvas syndrome' — describe a screen, feature, or user problem in plain language and get back suggested UI patterns, component inventories, token surface requirements, and next steps. Perfect for starting a new design or understanding what a feature needs from the design system.
Inputs: description (required), maxPatterns, includeScaffold.
resolve_brandA
Resolve design tokens for a specific brand, optionally combined with a theme. Shows how brand overrides affect the token system. When truncated, offer to fetch more by calling again with limit set to the total count.
Inputs: brand (required), limit, theme, pathPrefix.
resolve_themeA
Resolve the full set of design tokens for a specific theme (or arbitrary coordinate set). Shows how tokens change from the default. When truncated, offer to fetch more by calling again with limit set to the total count.
Inputs: theme (required), limit, pathPrefix.
scaffold_semanticsA
Generate a minimum viable semantic token set from a component inventory. Provide a comma-separated list of components (e.g. 'button, text-input, card, alert') and get properly structured tokens with CSS property class separation, intent coverage, and state completeness.
Inputs: components (required), dryRun, format, outputDir, +6 more.
search_tokensA
Search and discover design tokens by name, type, value, or other criteria. Use this to answer questions like 'What color tokens exist?', 'Find all spacing tokens', or 'Show deprecated tokens'. When results are truncated (e.g. '50 of 200'), offer to fetch more by calling again with limit: . Do not report truncation as a failure.
Inputs: text, type, limit, category, +5 more.
suggest_scaleB
Suggest optimal scale parameters based on design principles. Combines Swiss style, Material Design, iOS HIG, financial UI, and other industry standards to recommend strategy, ratio, base, and constraints.
Inputs: dimension (required), principles (required), useCase.
transform_tokensA
Transform design tokens into platform-specific output files using Style Dictionary. Generates CSS custom properties, SCSS variables, JavaScript modules, iOS/Swift code, Android XML, Compose code, etc. Use dryRun=true to preview without writing files.
Inputs: dryRun, platforms.
validate_figma_tokensA
Validate Figma variables against local token definitions. Checks for naming mismatches, type errors, missing mappings, and value discrepancies. Provides detailed validation report with errors, warnings, and sync status. Use strict mode to fail on any mismatch, or non-strict for warnings only.
Inputs: strict (required), figmaVariableDefs (required).
validate_tokensA
Validate design tokens against configurable rules. Checks naming conventions, value formats, type requirements, deprecated references, and architectural patterns. Returns a structured report with errors, warnings, and suggestions.
Inputs: preset, pathPrefix.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 37 tools
Each tool has a clearly distinct purpose: listing dimensions/brands/themes, searching/validating/transforming tokens, auditing various aspects, generating palettes/scales/systems, diffing, and figma integration. Even overlapping areas like audits are differentiated by scope (semantic vs design vs figma usage). No two tools appear to do the same thing.
Tools follow a consistent verb_noun pattern: list_, search_, validate_, transform_, generate_, audit_, analyze_, etc. All use lowercase snake_case. The naming is predictable and easily understood.
37 tools is on the higher side, but the server covers a broad domain: token management, audit, generation, Figma sync, accessibility, documentation, etc. Each tool serves a specific need, and the count is justified by the comprehensiveness. Could be slightly trimmed, but overall reasonable.
The tool set covers nearly the entire design token lifecycle: creation (generate), reading (list, search, resolve), transformation, validaton, auditing, migration, and scaling. Missing an explicit delete/remove tool, but migration execution can handle removal. Minor gap, but overall very complete.
Maintenance
Related MCP Connectors
The Figma MCP server brings Figma design context directly into your AI workflow.
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server that exposes your design system components and tokens to AI agents, preventing duplicate component creation and hardcoded token values.6 npm9MIT
- AlicenseNot gradedqualityCmaintenanceA read-only MCP server that provides AI coding agents with a queryable contract for design system tokens, components, patterns, and anti-patterns.13 npm1Apache 2.0
- AlicenseAqualityDmaintenanceAn MCP server that connects AI clients to Figma components, design tokens, and variables from the BrixUI Design System, enabling component browsing, searching, and token retrieval.44 npmMIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that gives AI assistants structured access to a design system's tokens, components, guidelines, and patterns, enabling them to read, lint, and author design system data.1MIT