DesignDiff MCP

AI implementation verification engine for Figma and MCP-compatible coding agents.

DesignDiff verifies that AI-generated interfaces match your Figma design system before they ship. It reads the Figma spec, renders your component in a real browser, compares computed CSS output, and returns patch-ready fixes — all inside your existing coding agent session.

Claude Code / Cursor / Windsurf
         ↓
   DesignDiff MCP
         ↓
  Figma REST API  +  Playwright renderer
         ↓
  Scored diff  +  Patch-ready fix
         ↓
    Agent applies  →  Re-checks: 94/100

Why

AI agents generate UI code from Figma specs and get it mostly right — but not exactly. The typical failure pattern:

• Token violations — hardcoded #2563EB instead of var(--brand-blue-600). Works today, breaks on the next brand refresh.
• Spacing drift — padding is 12px not 16px because the agent approximated instead of reading the exact value.
• Missing states — hover, focus, and disabled were defined in Figma variants the agent didn't parse.

The component looks correct visually. That's what makes this dangerous. DesignDiff catches these errors before they land in a PR.

Quick start

1. Get your Figma API key Settings → Account → Personal access tokens

2. Add to your agent config

Claude Code (~/.config/claude/mcp.json):

{
  "mcpServers": {
    "designdiff": {
      "command": "npx",
      "args": ["-y", "designdiff-mcp"],
      "env": { "FIGMA_API_KEY": "your-token-here" }
    }
  }
}

Same format for Cursor (.cursor/mcp.json), Windsurf, VS Code Copilot, and Zed.

3. Say to your agent

"Build the Button component from Figma file abc123, node 123:456,
running at localhost:6006 — and verify it matches the spec"

DesignDiff is called automatically when the agent generates or modifies a component.

Works best with Storybook, local preview routes, or any stable component URL your agent can render.

Tools

check_component_parity — ships now

Diffs the Figma design spec against computed browser CSS. Returns a scored parity report with ranked mismatches and a patch-ready fix when score drops below threshold.

check_component_parity({
  file_id: "abc123",           // Figma file ID from URL
  node_id: "123:456",          // Component node ID
  component_url: "http://localhost:6006/story/button--primary",
  code_path: "src/components/Button.tsx",
  threshold: 80,               // Score below which fix is generated (default: 80)
})

What it checks: spacing, color tokens, typography, borders, border-radius, interactive states.

What it returns: 0–100 parity score, ranked mismatches with consequences, pattern detection (e.g. "AI-generated code signature"), and a patch-ready git diff.

---

flag_stale_mappings — ships now

Cross-references Code Connect mappings in your repo against Figma version history and git blame. Surfaces components that have drifted silently, ranked by blast radius and days since divergence.

flag_stale_mappings({
  file_id: "abc123",
  repo_root: ".",              // Path to your repo root
})

Reads from .figma/code-connect.json in your repo root.

---

generate_sync_patch — ships now

Generates a surgical patch for a specific component — token substitutions, prop corrections, missing state stubs. Output as git diff, JSX corrections, or CSS delta.

generate_sync_patch({
  file_id: "abc123",
  node_id: "123:456",
  code_path: "src/components/Button.tsx",
  format: "diff",              // "diff" | "jsx" | "css"
})

---

audit_state_coverage — v0.2

Checks whether every interactive state defined in a Figma component set (hover, focus, disabled, error, loading) exists in code. Flags WCAG 2.4.7 risk for missing focus rings.

check_responsive_parity — v0.2

Renders at 375/768/1280/1920px and catches overflow, collapsed containers, and flex direction errors.

check_theme_parity — v0.2

Runs parity across Figma variable modes — light/dark, brand variants, high-contrast. Catches hardcoded colors that are invisible in light mode but break in dark.

Finding your Figma IDs

File ID: From the URL — figma.com/file/{FILE_ID}/...

Node ID: Right-click a component in Figma → Copy link → extract the node-id parameter. Format: 123:456. Note: the URL uses 123-456 (hyphen) but the API uses 123:456 (colon) — DesignDiff handles the encoding automatically.

How it works

1. Fetch — Calls the Figma REST API and extracts the full design spec: exact pixel values, token references, and every variant state from the component set.

2. Render — Launches a headless Playwright browser and renders your component at its real URL. Captures computed CSS — what the browser actually produces after cascade and runtime overrides resolve.

3. Score — Compares the two. Token violations score highest (they break the entire design system contract). Missing focus states are flagged with WCAG reference. Every mismatch includes the real-world consequence of not fixing it.

4. Fix — When score is below threshold, generates a patch-ready diff the agent applies in the same response, then re-verifies the score improved.

Configuration

Environment variable	Required	Default	Description
FIGMA_API_KEY	✓	—	Figma personal access token
TRANSPORT	—	stdio	stdio or http
PORT	—	3847	HTTP port (when TRANSPORT=http)

HTTP transport

For use with non-stdio MCP clients:

FIGMA_API_KEY=xxx TRANSPORT=http npx designdiff-mcp
# → DesignDiff MCP v0.2 running at http://localhost:3847/mcp

Health check: GET /health

Development

git clone https://github.com/designdiff/designdiff-mcp
cd designdiff-mcp
npm install
npx playwright install chromium
npm run build
FIGMA_API_KEY=xxx npm start

Inspect tools interactively:

npm run inspector

This opens the MCP Inspector UI where you can call tools directly.

Roadmap

Stage	What ships
v0.1 — Now	Rendered parity check · token compliance · patch-ready diffs
v0.2	State coverage · responsive parity · theme parity · Storybook adapter
v1.0	Unified quality score · CI gate · score history · Slack alerts

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.

---

By Mathew Graham