Design Systems

DESIGN.md vs design tokens

Why DESIGN.md complements tokens instead of replacing them.

April 10, 20267 min read

Different jobs

Design tokens and DESIGN.md solve related but distinct problems. Tokens are a data format: they store named values for colors, typography, spacing, and other visual properties, enabling those values to be shared consistently across design tools, codebases, and component libraries. DESIGN.md is a specification format: it stores intent, context, hierarchy, behavioral rules, and anti-patterns. An agent given only a token file knows what "--color-primary" is (a specific hex value), but it does not know when to use "--color-primary," which interactive states require it, how it interacts with "--color-surface," or whether it is appropriate for backgrounds or only for interactive elements. DESIGN.md answers the interpretive questions that tokens deliberately leave unanswered. Tokens define the vocabulary; DESIGN.md defines the grammar and the rules for when each word is appropriate.

What tokens cannot express

Token systems are designed to be tool-agnostic and value-centric. They do not express hierarchy, priority, or intent. A token file can tell you that "--spacing-4" equals 16px and "--spacing-6" equals 24px, but it cannot tell you that cards should use 16px internal padding at standard density and 12px at compact density. It cannot tell you that modals should have 24px padding but not 32px. It cannot tell you that the danger button shares its hex value with "--color-danger" but should never appear next to a primary action button in the same row. Tokens also cannot encode anti-patterns: the most valuable part of a design specification is often the list of things not to do, and token systems have no mechanism for that. DESIGN.md fills every one of these gaps because it is a prose document rather than a data schema, and prose can express intent, context, and constraint in ways that key-value pairs cannot.

How DESIGN.md interprets tokens for agents

When a product has an existing token system, DESIGN.md becomes the interpretation layer on top of it. Instead of writing raw hex values in the spec, reference the token names and explain their meaning: "--color-primary (brand blue, #3B82F6) — used for CTAs, active navigation indicators, and focus rings. Use on dark backgrounds only when there is sufficient contrast. Do not use for purely informational highlights or background fills." This approach gives agents two things at once: the concrete value needed to implement the rule and the semantic context needed to apply the rule correctly. The same principle applies to spacing tokens: instead of listing the spacing scale abstractly, DESIGN.md maps it to use cases — "--spacing-3 (12px) is the standard padding inside compact components; --spacing-4 (16px) is standard for default components; --spacing-6 (24px) is the gap between major page sections."

A concrete example: mapping your token system to DESIGN.md

Suppose your product defines CSS variables --color-interactive: #3B82F6 and --space-4: 16px. A token file records these as bare facts — a hex value and a pixel measurement. Neither entry tells an agent when to use them, with what, or under what constraints. A DESIGN.md entry for the same tokens reads differently: "--color-interactive (#3B82F6) — the primary action color. Use for CTA buttons, active navigation indicators, and focus rings. Do not use for background fills, informational highlights, or disabled states. On dark surfaces, verify contrast exceeds 4.5:1 before applying." For the spacing token: "--space-4 (16px) is the standard internal padding for default-density components. Compact-density components use --space-3 (12px). Never mix densities within the same card or form group." Now the agent has both the value and the interpretation: it can implement the button correctly and know not to apply that same blue to a decorative background section. That gap — between a dictionary of values and a usable specification — is exactly what DESIGN.md fills on top of any token system.

Migration path

If a product already has a mature token system, starting a DESIGN.md is straightforward. The token file already handles the values layer; DESIGN.md only needs to add the interpretation layer on top. Start by listing the core tokens in the file and writing one or two sentences about each one's meaning and appropriate use. Then add the component rules section: take the most common components — buttons, cards, forms, tables — and write one paragraph for each that describes how the token values combine into correct component behavior. Then add the anti-patterns section: look at the most common AI-generated UI mistakes in the codebase and document each one explicitly. A complete migration from a pure token system to a token-plus-DESIGN.md system typically takes one working session. The result is a richer spec that agents can follow more reliably than a raw token file alone.

What to document beyond tokens

The sections of DESIGN.md that go furthest beyond a token system are page-level layout patterns, state design, and anti-patterns. Page-level patterns describe what a full screen looks like: how the header relates to content, where the primary action sits, how the page behaves at mobile width, and how data-heavy screens differ from form-based screens. State design describes how components look in loading, empty, error, and disabled conditions — surfaces that are easy to omit from a token system and easy to get wrong in AI-generated code. Anti-patterns document the gap between what an agent would do by default and what the product actually requires: "data tables should not use card-style backgrounds for rows," "empty states should not use decorative illustration," "settings panels should not resemble landing page sections." These three categories alone account for most of the quality gap between generic AI-generated UI and product-specific AI-generated UI.

Use DESIGN.md with a real product reference

Browse curated DESIGN.md examples from product teams, design systems, developer tools, SaaS dashboards, and AI-native apps. Use them as references before your agent builds the next screen.

Browse directory Submit DESIGN.md

Related guides

Design Systems6 min read