What DESIGN.md Changes in Practice

The token-only trap#

The most common way a DESIGN.md disappoints is also the most invisible on a quick read. The file looks thorough. Every hex value is present, the type scale is complete, the spacing grid and corner radii are defined. And the agent still returns the same generic screen: rounded corners everywhere, a plausible accent color, uniform cards with soft shadows you never use.

The tokens are correct. The decisions are wrong.

The reason is that a token records a value, not its meaning. A primary color token says #0D7377. It does not say "this is reserved for interactive elements and must never appear on a background, a decorative divider, or an info banner." Without that sentence, an agent treats the color as a general-purpose accent and reaches for it wherever it senses emphasis. Every use is technically valid. The intent is wrong in all of them.

A design document that lists only values is like a product brief that lists only features: it looks complete, and it gives the reader nothing to reason with in the situations the document does not spell out. Generating UI is almost entirely those situations.

Two layers: values and decisions#

A DESIGN.md has two parts, and they carry different kinds of knowledge.

The YAML frontmatter is the machine-readable layer: colors, typography, spacing, rounded corners, component defaults. This is what most coverage of the format focuses on, because it is the tidy, structured part.

The Markdown body is the layer that changes output. It explains why the tokens exist, when to apply them, and where the agent should show restraint. When people say a DESIGN.md "did not do much," they almost always mean they shipped the frontmatter and left the body thin.

colors:
  primary: "#0D7377"     # <- a value

## Colors

Primary is reserved for interactive elements: buttons, links, focus
rings. It never appears on backgrounds, dividers, or informational
banners.                 # <- a decision

The first line makes the color available. The second makes it behave.

The three sections that do most of the work#

The spec defines eight canonical body sections (Overview, Colors, Typography, Layout, Elevation and Depth, Shapes, Components, Do's and Don'ts). They do not contribute equally. In practice, three carry most of the improvement.

Overview#

The Overview sets the product's personality and visual direction, so the agent has a reference point for the choices no token covers: whitespace, hierarchy, how busy or restrained a screen should feel. It is tempting to leave it blank because it feels soft. That is a mistake. With no Overview, an agent defaults to whatever it has seen most in training, which is the generic look.

Vague copy does not help either. "Clean and modern" produces the same generic output as an empty Overview. "Information-dense, no gradients, no illustrations, closer to a financial terminal than a consumer app" produces visibly more restrained screens. Specificity is what travels.

Colors (the prose, not the hex)#

The frontmatter gives the hex values. The Colors prose says what each one is for: which is the primary action color, which are backgrounds, which is reserved for errors. This is where the tightest cause and effect shows up. Every time an agent misapplies a color, the fix is a sentence here, and the misapplication tends to stop on the next generation. In a mature file, this section is mostly constraints.

Do's and Don'ts#

This is where negative constraints live, and they are stronger than they look. "No box shadows on cards; use a 1px border in the lightest neutral for containment." "Secondary buttons should feel quiet: neutral background, subtle border, no fill." "The primary color appears on at most one CTA per screen."

In practice, a "never do X" instruction is followed more reliably than a soft "prefer Y." The section grows naturally: every useful line traces back to a specific generation where the output was off. That feedback loop is what makes the file practical rather than aspirational.

The remaining sections (Typography, Layout, Elevation and Depth, Shapes, Components) matter to varying degrees, but the three above account for most of the change you will notice.

Writing prose an agent can use#

A useful frame: you are onboarding a developer with perfect CSS skills and zero context about your brand. That is the audience.

• Be specific, not descriptive. "Minimal aesthetic" is weaker than "flat, no gradients, consistent 1px borders in neutral-200, no decorative elements."
• Explain intent, because it generalizes. A sentence that says the product prioritizes information density over whitespace produces tighter tables and denser forms without you specifying pixels per component. Intent reaches the cases the file does not enumerate.
• Cover edge cases. Empty states, error messages, long text in tight spaces, loading states. Agents fail most predictably here because there is nothing to guess from. One sentence about empty states fixes the blank-screen-with-a-tiny-grey-label pattern for good.
• Name what you do not want. "Never on backgrounds" is more actionable than "for interactive elements." Negative constraints land harder.
• Keep it short. This is a configuration file, not a brand bible. Every sentence competes for the agent's finite context window with the actual component being generated. Trim lines that are not pulling their weight.

Do not just auto-generate it#

The temptation is to have an agent, a browser extension, or a hosted generator produce the whole file. The result will be thorough and it will be missing the part that matters. Auto-generation extracts values well and skips the reasoning entirely: what the product is, who uses it, what the UI must always and never do. A token dump has all the measurements and none of the decisions.

Use generators for structure and token extraction, then write the prose yourself. For a survey of what each kind of tool does, see DESIGN.md Tools Compared; for authoring from scratch, How to Write a DESIGN.md. Whichever route you take, lint the result before you commit:

npx @google/design.md lint DESIGN.md

The linter validates structure, catches broken token references, and checks WCAG contrast on component color pairs. Then render the file in the DESIGN.md viewer to see it as a navigable guideline and confirm it says what you think it says. Parsing runs in your browser, so nothing is uploaded.

What it does not solve yet#

Being honest about the limits matters as much as the benefits.

The spec is still alpha (v0.3.0). Dark mode tokens, responsive breakpoints, and motion are gaps the format has no clean way to express yet. Tools like Claude Code and Cursor consume a DESIGN.md because they read Markdown from the repo, not because they have first-class parsing for it, so behavior depends on the agent. And an agent can still ignore the file, especially on complex multi-component screens: it follows prose constraints most of the time, not deterministically. Reviewing generated output still matters. The file also spends context window, which is a real tradeoff on long sessions.

If you ship a single product with a coding agent, the payoff shows up quickly. If you run a multi-brand system with an established token pipeline, it is reasonable to watch the spec mature before standardizing on it.

What actually changes#

When the prose is doing its job, the shift is concrete. The agent stops using the brand color decoratively. It stops adding shadows to a flat design language. Secondary buttons stop competing with primary ones. Screens start to look like something your team would have built rather than generic framework output, and each improvement traces back to a sentence in the body, not a token in the frontmatter.

There is a quieter change too. Writing these constraints forces a team to put into words the design reasoning that usually lives in people's heads, the kind of thing everyone knows and nobody documents. A file written for an agent turns out to explain the visual direction to a new human hire better than a component library does, because the library shows what things look like while the DESIGN.md says why. That reasoning is the part a person writes. Extracting tokens is mechanical; knowing which constraints to write, and why, takes someone who understands the product.

Render your DESIGN.md in the tool

Read about AI coding agents and DESIGN.md