design-md-mcp

Give your AI agent your design system.

An MCP server that reads any DESIGN.md and answers your agent in a few lines: the exact token, the component class to reuse, the rule not to break.

Why

When an agent builds UI, it either guesses your colours or reads your whole design system on every prompt. design-md-mcp sits in between: the agent asks a small question and gets a short answer, a couple of lines for a colour or about a page of text to set up a whole screen, with the light and dark values, the CSS variable to use and the component class that already exists.

• On-system output. Exact tokens, not "close enough" hex codes.

• Reuse over rebuild. It points the agent at your existing component classes, with a markup example.

• Catches drift. check_value flags made-up colours and pixel sizes and suggests the nearest token.

• Works with any DESIGN.md. Bring your own, or try the bundled Tidepool demo.

Related MCP server: weave-design-system-mcp

Quick start

Needs Node 18+. Works with any MCP client: Claude Code, Cursor, Windsurf, Claude Desktop, VS Code.

Try the Tidepool style

# 1. Copy the demo design system into ./tidepool
npx -y github:tingowiggle/design-md-mcp init tidepool

# 2. Connect it (Claude Code)
claude mcp add tidepool -- npx -y github:tingowiggle/design-md-mcp --file ./tidepool/DESIGN.md

Then ask your agent: "Build a proposal voting screen in the Tidepool style, light and dark. Start with get_screen_kit."

Just exploring? Skip the copy step: --example tidepool uses the bundled files directly.

Use your own DESIGN.md

claude mcp add my-design -- npx -y github:tingowiggle/design-md-mcp --file ./DESIGN.md

{
  "mcpServers": {
    "my-design": {
      "command": "npx",
      "args": ["-y", "github:tingowiggle/design-md-mcp",
               "--file", "./DESIGN.md",
               "--css", "./src/styles/tokens.css"]
    }
  }
}

Add it to your client's MCP config (e.g. .cursor/mcp.json) and restart the client.

Options

Tools

Loading the tools adds ~800 tokens to your agent's context. For comparison, reading Tidepool's full DESIGN.md and stylesheet is ~6,300 tokens.

What goes in a DESIGN.md

YAML tokens between --- fences, then markdown sections with your rules:

---
name: My Product
colors:
  primary: "#0F7B6C"
  ink: "#10221F"
rounded:
  md: 10px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    rounded: "{rounded.md}"
---

## Colors
| Token | Light | Dark | Use |
|---|---|---|---|
| `--primary` | `#0F7B6C` | `#3FBFA8` | The confirm action |

## Components
### Primary button
`.btn .btn-primary`. One per view.

## Do's and Don'ts
| Do | Don't |
|---|---|
| One primary button per view | Two primary buttons side by side |

The server links YAML names to CSS variables that share a value, maps component names to your stylesheet's classes (button-primary → .btn-primary, bottom-sheet → .sheet), and indexes every section so get_rules can answer by topic. A ## Setup section travels with get_screen_kit.

Tidepool, the demo design system

A fictional community wallet with an AI copilot, Tide, bundled as a complete example in examples/tidepool. Teal means a person confirmed it; violet means the copilot suggested it.

Open index.html for the full showcase page.

Develop

npm install
node src/smoke.js                          # calls every tool against Tidepool
node src/cli.js get_token '{"name":"primary"}' -- --example tidepool

License

Apache-2.0 · made by Web3 Story Lab. Tidepool and all its names and data are fictional.