Design Tokens for AI Coding Agents: How to Give Cursor and Claude Code Your Design System

Why AI agents generate inconsistent UI

Every AI coding agent — Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Windsurf — starts each session with no memory of your codebase's visual decisions. Ask it to build a button and it will pick a color. That color will almost certainly not be yours.

This is not a model quality problem. It is a context problem. The agent knows how to write a button. It does not know that your primary color is #0F172A, your border radius is 8px, and your type scale uses Inter at 14px/500 for labels. That information lives in your CSS, your Figma file, or your muscle memory — none of which the agent can access unless you give it explicitly.

The result: every generated component needs manual correction. Colors, spacing, radius — all wrong. Developers fix them by hand, per component, per session. Multiply that across a team and across a year and the cost is substantial.

What design tokens are (and why agents need them)

Design tokens are the named values that define your visual system: your exact color hex codes, type sizes, spacing increments, border radius values, and shadow definitions. They are the decisions underneath the design — not "blue button" but --color-primary: #0F172A.

For AI agents, the most useful token format is plain text in a structured markdown file (DESIGN.md). Language models parse structured prose reliably — a labeled section like ## Colors followed by explicit values is easier for a model to extract and apply than raw JSON or minified CSS.

## Colors
- Primary:   #0F172A  (brand, buttons, headings)
- Accent:    #6366F1  (interactive elements, links)
- Surface:   #F8FAFC  (page background, cards)
- Muted:     #94A3B8  (secondary text, borders)

## Typography
- Display:   Inter 700, 48px / 1.1 leading
- Heading:   Inter 600, 24px / 1.3 leading
- Body:      Inter 400, 16px / 1.6 leading
- Label:     Inter 500, 12px / 1.4 leading

## Spacing
- Base unit:     4px
- Component gap: 24px
- Section gap:   80px

## Radius
- Button: 8px    Card: 12px    Modal: 16px

When an agent reads this file at session start, it has everything it needs to write on-brand components without correction. The tokens tell it the exact values — no guessing, no defaults.

Step 1: Extract your design tokens

If your project has a DESIGN.md already — check the repo root. If not, you have two options:

Option A: Extract from your live site (recommended)

Paste your production URL into MYDESIGN.MD. The extractor runs CSS parsing, DOM inspection, and visual analysis in parallel. In under a minute you get:

• DESIGN.md — structured markdown, ready to paste into any agent
• design-tokens.json — DTCG format for Style Dictionary, Figma Tokens
• variables.css — CSS custom properties, drop into any stylesheet
• tailwind.config.v4.css — Tailwind v4 theme config

Commit DESIGN.md to your project root. This is the file your agents will read.

Option B: Write it by hand

If you know your token values, create a DESIGN.md file at the project root. Copy the format from the example above. Cover at minimum: colors (with hex values and semantic labels), type scale (font, size, weight, line-height per role), spacing scale (the actual pixel values your site uses), and border radius per component type.

Step 2: Load tokens into each agent

Each agent has a different mechanism for persistent context. Here is the setup for the five most common tools.

Setup reference: Claude Code, Codex, Cursor, Copilot, Windsurf

# Design System
@DESIGN.md

# Design System
@DESIGN.md

## Design tokens
Primary color: #0F172A
Accent: #6366F1
Border radius (button): 8px
Font: Inter
Body size: 16px / 400 / 1.6

## Design system
Paste your DESIGN.md contents here.
Windsurf reads this file as context for every Cascade conversation.

Step 3: Verify the agent is using your tokens

After loading your tokens, open a new session and ask the agent to build a simple component — a button, a card, or a nav item. Check for:

• Color — does it use your exact primary hex, not a generic blue or black?
• Border radius — does it match your specified value (e.g. 8px), not 4px or rounded-md?
• Typography — does it reference your font family and the correct weight and size for the component role?
• Spacing — does padding match your spacing scale increments?

If any of these are wrong, the agent did not load the token context. Check that the file reference is correct (CLAUDE.md, AGENTS.md, .cursor/rules/design-tokens.mdc, etc.) and that the token values are explicitly stated with hex codes and pixel values — not just color names like "brand blue."

Refreshing tokens after a design update

When your design system changes, re-run the extraction and commit the updated DESIGN.md. Because the file is version-controlled, every agent using the project automatically gets the updated tokens on their next session — no manual context pasting required.

Frequently asked questions