DESIGN.md began at Google Labs as the format behind Stitch, its UI generation tool. Google open-sourced the specification, and the spec now lives on GitHub. It spread quickly beyond Google: Atlassian published an account of testing portable design context in practice, and a catalogue ecosystem grew up around it.

The .md is simply markdown. The file has no special syntax, no schema to validate against, and no build step. That is deliberate: an agent reads it the way it reads any other file in your repository.

A coding agent asked to build UI has to get its visual values from somewhere. Absent a source, it uses library defaults — which is why AI-built products converge on one look. You can supply values in a prompt, but prompts live in a conversation and conversations decay as they grow.

A file does not decay. That is the entire mechanism, and everything else about the format follows from it.

Rather than assume, we sampled. We pulled 299 repository-root DESIGN.md files from GitHub code search and measured what was in each one. The first result was a surprise and it reframes everything else.

Within those 72 genuine visual-design files, the picture is consistent. The median file is 1,337 words across 263 lines, so these are not stubs — people are putting real effort in. They are putting it into the same three sections and skipping the same four.

Colour and typography are near-universal. Radius, elevation, iconography and accessibility are rare. And one omission is bigger than any of these, because it is invisible until someone flips a switch.

Of the 72 visual-design files we measured, 50 contain no dark mode at all — no .dark block, no prefers-color-scheme, no second set of values. That is 69%.

This is the most consequential gap in the format as it is practised, and it fails quietly. Everything looks correct in light mode. Then a user toggles the theme and the agent has to invent every dark value on the spot: a background that was never chosen, a foreground that was never contrast-checked, an accent that washes out because nobody raised its chroma for a dark ground.

## Color

### Light
--background: oklch(0.98 0.006 85)
--foreground: oklch(0.22 0.014 85)
--card:       oklch(1 0 0)
--muted-foreground: oklch(0.48 0.012 85)
--primary:    oklch(0.52 0.13 152)
--border:     oklch(0.90 0.008 85)

### Dark
--background: oklch(0.17 0.010 85)   /* not pure black */
--foreground: oklch(0.95 0.006 85)   /* not pure white */
--card:       oklch(0.22 0.010 85)   /* raised, not shadowed */
--muted-foreground: oklch(0.70 0.010 85)
--primary:    oklch(0.68 0.16 152)   /* higher chroma to survive the dark ground */
--border:     oklch(0.30 0.010 85)

Only 6% of the files we measured use OKLCH. It is worth the switch here specifically because its lightness channel is perceptually uniform, so you can move a hue without re-checking every contrast pair.

The single most consequential decision in the file is naming by *role* rather than by hue. --primary tells an agent where the value goes; --blue-600 does not. Roles let it apply your system correctly in situations you never anticipated, and they survive a rebrand.

86% of the files we measured use no semantic role names. They list hexes, or they name colours by hue. That is the difference between a file an agent can apply to a component you never described and a file it can only copy from. The semantic token layer is doing the real work here.

Name the families, the weights, the tracking, and the scale steps. The common failure is writing *a serif for headings, a sans for body* — an instruction the agent has to resolve, and it will resolve it differently each time.

## Typography

Heading: "Fraunces", serif — 600, tracking -0.02em
Body:    "Inter", sans-serif — 400, line-height 1.6
Mono:    "JetBrains Mono" — 400, tabular figures in tables

Scale: 0.8125 / 0.875 / 1 / 1.25 / 1.5 / 2 / 3rem
H1 uses 3rem at 1.05 line-height; body copy never exceeds 68ch.

One spacing scale, radius that varies with element size, and two or three elevation levels that agree about a light source. Radius is covered by only 21% of files and elevation by 26%, which is why so much generated UI carries one 0.5rem corner on every element regardless of size.

## Spacing
Scale: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96px
Section rhythm: 96px desktop, 64px mobile.

## Radius
sm 0.25rem (inputs) · md 0.5rem (buttons) · lg 0.875rem (cards) · xl 1.25rem (modals)

## Elevation
0 flush — use a border, no shadow
1 cards — 0 1px 2px rgb(0 0 0 / 0.06)
2 dropdowns — 0 4px 12px rgb(0 0 0 / 0.08)
Dark mode: raise the surface, do not deepen the shadow.

Tokens tell an agent which values to use. They say nothing about what to do when it meets a component your file never mentioned. Motifs and prohibitions cover that gap, and they are the difference between a file that constrains output and one that merely colours it.

76% of files state no prohibitions and 57% state no motifs. These are the two cheapest sections to write and the two most often absent.

## Motifs
- Hairline rules separate sections; no boxed cards on marketing pages.
- Numerals are tabular everywhere they can be compared.
- One accent per screen. If two things compete, one becomes muted.

## Don't
- No gradient text, ever.
- No shadow on a flush surface — use --border.
- Never hardcode a hex. If a role is missing, add the role.

Cover the primitives that carry the most identity: buttons, inputs and cards, with their states. You do not need every component. Iconography is the cheapest section in the file and the rarest in practice at 10% — name the icon library, the stroke width, the size steps, and one line on image treatment.

Beyond the missing sections, one failure mode shows up in over half the corpus: writing an adjective where a value belongs.

54% of the files we measured contain at least one vague adjective standing in for a decision. The most common were *clean* (39% of files), *modern* (36%) and *professional* (22%), followed by *generous whitespace*, *elegant* and *beautiful*. And 44% contain no concrete spacing or size value anywhere in the file.

1. Adjectives instead of values. The most common defect, in over half of files.
2. Dark mode omitted. In 69%, and it fails silently.
3. Colours named by hue rather than role. In 86%, and it breaks the moment the agent meets a component you did not describe.
4. No prohibitions. In 76%. Prohibitions are followed more reliably than preferences.
5. A section that says 'use your judgment'. Worse than no section, because it grants back exactly the discretion the rest of the file was trying to withdraw.

Put it at the repository root, beside AGENTS.md. The root matters: a DESIGN.md nested in docs/ is a document for humans, and agents that look for the convention look at the root.

Then reference it from your agent instructions in one line, so it is discovered rather than stumbled upon. It is a sibling of those files rather than a competitor — the four files do different jobs.

# AGENTS.md

## Design
Never hardcode theme colors, spacing or radii. Use the tokens in DESIGN.md.

AGENTS.md is the broader convention for agent instructions and is read by a growing set of tools. DESIGN.md holds the visual contract; AGENTS.md points at it.

This is the part every other explainer leaves out. A DESIGN.md is only as good as the interface it produces, and the sections above are not an illustration — they are the serialised form of the kit below.

If you hand-write it, the two sections to force yourself through are dark mode and the don'ts. The corpus is unambiguous that those are the ones people skip, and they are the ones that determine whether the file constrains anything.