What is the difference between a design token and a CSS variable?

A CSS variable (--color-primary: #3b82f6) is a browser feature scoped to the DOM cascade. A design token is the underlying concept — a named, platform-neutral decision compiled into CSS variables, Tailwind config, iOS color literals, or Android XML. All CSS custom properties can represent tokens; not all tokens are CSS variables.

Do design tokens require a specific tool to work with AI agents?

No tool is required. Any editor that accepts a rules file or system prompt can receive token context as plain text. Cursor, Claude Code, VS Code Copilot, and Windsurf all support referencing a file or including a snippet in their config — the agent reads it as context without native token integration.

Should I use DESIGN.md or tailwind.config.js as my token reference?

Use tailwind.config.js if your project is Tailwind-based and the file is current — agents generate Tailwind classes directly from the extended theme. Use DESIGN.md if you work across multiple stacks or want a single human-readable reference that works regardless of framework.

How often should I update my design token file?

Update it every time a design decision changes. An out-of-date token file is actively harmful: the agent generates components that contradict your current system. Treat it like a lock file — commit every update alongside the components that prompted it.

Design Tokens for AI Coding Agents

Design tokens are named design values — colors, spacing, type sizes, radii — stored as data rather than hard-coded in each component. AI coding agents like Cursor, Claude Code, and GitHub Copilot produce inconsistent UI without them because every prompt starts from scratch. Store your tokens in a DESIGN.md file or a Tailwind config and reference it from your editor rules file; agents that have read your tokens generate on-brand components without you correcting every output by hand.

AI editors generate UI that looks competent but uses the wrong blue, the wrong spacing, and type sizes that do not match your scale. Design tokens fix that — here are the four formats agents understand and how to wire each one into your editor.