Claude Code design tokens: a practical setup guide

Ask Claude Code for a settings page and you'll usually get something that works and looks fine. Look closer and it's #3b82f6 for the button, padding: 14px on the card and border-radius: 10px on the inputs. None of those are in your design system. Claude didn't ignore your tokens. It never saw them.

This guide fixes that in four steps, without any paid tool: put your tokens where Claude Code can read them, tell it the rules in CLAUDE.md, give it tools, and check what it writes. At the end there's a one-command version.

Why Claude Code invents colours

Claude Code builds its picture of your project from the files it opens and the instructions it's given. Your tokens often live somewhere it never looks: a Figma library, a package in another repo, or a Tailwind config with 40 custom colours and no note on which to use when.

When it can't find a value, it does what any developer new to the codebase would do. It picks something reasonable. Multiply that by every prompt, every developer and every repo, and you get brand drift: five slightly different blues and no single place where it went wrong.

The fix is context, plus a check.

Step 1: Put your tokens in one file Claude can read

The most reliable format is plain CSS custom properties: the browser uses the file and the model reads it.

/* src/tokens.css */
:root {
  --color-action-primary: #2563eb;
  --color-action-primary-hover: #1d4ed8;
  --color-text-default: #111827;
  --color-surface-default: #ffffff;
  --space-1: 4px;
  --space-2: 8px;
  --space-4: 16px;
  --radius-md: 8px;
  --font-body: "Inter", system-ui, sans-serif;
}

[data-theme="dark"] {
  --color-text-default: #f9fafb;
  --color-surface-default: #0b1220;
}

Three things make this file useful to an AI tool:

• Semantic names. --color-action-primary tells Claude when to use it. --blue-600 doesn't.
• One file. If tokens are split across six files, Claude has to find all six.
• Dark values next to light ones. Otherwise dark mode gets invented too.

If your tokens live in Figma or Tokens Studio, export them to DTCG JSON and generate this file with Style Dictionary or a small script. Don't hand-copy hex values.

Step 2: Tell Claude Code the rules in CLAUDE.md

Claude Code loads CLAUDE.md from the project root at the start of every session. It also supports imports with @path, so you can point it at the tokens file instead of pasting values that will go stale.

# UI rules

Our design tokens are in @src/tokens.css. When writing UI:

- Use the CSS variables from that file for every colour, spacing,
  radius and font. Never write a hex, rgb() or px value for these.
- Spacing: only --space-1, --space-2, --space-4. No other values.
- Primary buttons use --color-action-primary; hover uses
  --color-action-primary-hover.
- Use our components from src/components/ui before writing raw
  <button>, <input> or <select>.
- If no token fits, stop and ask. Don't invent one.

Keep it short and specific. Claude follows "use --space-2 between form fields" much better than "follow the design system". The last rule matters most: it turns a silent guess into a question you can answer.

If other tools work in the same repo, copy the rules into their files too: AGENTS.md for Codex, .cursor/rules for Cursor, .github/copilot-instructions.md for Copilot.

Step 3: Give it tools, not just text

CLAUDE.md works, but it costs context every session and it's static. A Model Context Protocol (MCP) server lets Claude Code ask for tokens and component docs when it needs them, and get current values every time.

You add any MCP server to Claude Code with one command:

claude mcp add <name> -- <command that starts the server>

A design-system MCP server should answer at least three questions: which tokens exist, which component to use for a need, and whether a snippet follows the rules. You can write a small one yourself, or use an open-source one (below).

Step 4: Check what it wrote

Instructions reduce drift; they don't remove it. Long sessions drift, and a prompt like "make it pop" invites a new colour. So check the output the way you'd lint it.

A quick manual check for hard-coded colours in changed files:

git diff --name-only main | xargs grep -nE "#[0-9a-fA-F]{3,8}\b|rgb\("

It's crude (it flags comments and SVGs), but it catches the most common problem. A proper checker also knows your spacing and radius scale, your fonts, and which components replace raw HTML.

The one-command version

Brandrail does steps 1 to 4 for you. Its CLI and MCP server are MIT-licensed and on npm as brandrail.

npx brandrail connect

You sign in through the browser, and it:

• writes your Brand Kit as CSS variables (src/brandrail.tokens.css), light and dark;
• writes the rule files Claude Code, Codex, Cursor, Copilot, Windsurf and Gemini read, including CLAUDE.md;
• sets up a local MCP server (npx brandrail mcp) with 7 tools, including get_design_tokens, find_component and validate_snippet.

The MCP server runs on your machine over stdio, so code is checked locally and never uploaded. It also works without an account, using starter tokens:

claude mcp add brandrail -- npx -y brandrail mcp

Then check a repo, or only the lines you changed:

npx brandrail check
npx brandrail check --changed

The checker has 12 rules (hard-coded colours, palette classes, spacing and radius scale, fonts, raw HTML instead of components, deprecated components and tokens, and more) and reads JSX, Angular, Vue, Svelte, HTML, CSS and several template languages. Each finding comes with a fix, and the repo gets a brand score.

If your tokens are already in Figma variables, Tokens Studio or DTCG JSON, import them rather than retyping:

npx brandrail import tokens.json

Summary

• Put tokens in one CSS file with semantic names.
• Point CLAUDE.md at it with @src/tokens.css and a short list of rules, ending with "ask, don't invent".
• Add an MCP server so Claude can look up tokens and components on demand.
• Check the output on every change.

To set it all up in one step, run npx brandrail connect in your repo. The free plan covers 1 repo and 3 people.