How to Write a Design MD

A DESIGN.md fails in one of two ways: it's a mood board ("clean, modern, trustworthy") that constrains nothing, or it's a token dump that names values without jobs. Knowing how to write a design md means avoiding both — the file is a contract between the person who owns the visual decisions and the agent that implements them, and contracts need enforceable clauses. This guide is the process we use, section by section.

Start from evidence, not taste

Open the product (or the reference site) in DevTools and record what is actually there:

• Computed styles on real elements: body text color, heading sizes and weights, letter-spacing at display sizes.
• CSS custom properties — a site's :root variables are its design system confessing. Copy the list before interpreting anything.
• Repetition counts. The hex that appears 400 times is a system token; the one that appears twice is an accident. Frequency separates them.
• Shadows and radii from the most-reused components: primary button, default card, text input.

If the reference is a live site, the DESIGN.md generator automates this whole step — it fetches the page, mines colors/fonts/spacing/shadows with occurrence counts, and drafts the file from real values. Manual or automated, the rule is the same: every hex, font, and radius in the file must be observed, never invented.

The section order that works

After generating and reviewing hundreds of these files, the structure that consistently produces obedient agents is the nine-section layout used across our library:

1. Visual theme & atmosphere — three paragraphs of interpretation plus a "key characteristics" bullet list. This primes the model's overall direction.
2. Color palette & roles — every token gets a name, a value, and a job: "#0072F5 — interactive accent: links, focus rings. Never decorative."
3. Typography — families, the full size/weight/line-height/tracking table, and the weight rules ("600 max; no bold").
4. Spacing & layout — base unit, container widths, section rhythm.
5. Components — buttons, inputs, cards, nav with per-state styling (default/hover/focus/disabled).
6. Shadows & elevation — exact values, including tint.
7. Borders & radius — the scale and where each stop applies.
8. Motion — durations, easings, and what doesn't animate.
9. Do's and don'ts — the section agents follow most literally.

Hard values early, prose later. Agents (and truncated context windows) read top-down.

Write roles, not adjectives

The single biggest upgrade in how to write a design md is replacing adjectives with assignments. Compare:

❌ "Purple is used tastefully throughout."

✅ "#635BFF appears on: primary CTA fill, link text, active nav item. It never appears on: backgrounds, borders, icons, illustrations."

The second version is checkable. An agent can audit a diff against it; a reviewer can point at a violation. Every color, weight, and radius should be written this way — as an allowlist with an implicit or explicit denial of everything else.

Component states are where drift dies

Most agent-generated UI goes wrong on the second state: hover fills that invent new colors, focus styles that vanish, disabled buttons that just add opacity. Write the state table explicitly:

### Button (primary)

- Default: bg #171717, text #FFFFFF, radius 6px, weight 500
- Hover: bg #383838 — no transform, no shadow change
- Focus: double ring — 0 0 0 2px #FFF, 0 0 0 4px #0072F5
- Disabled: bg #EBEBEB, text #8F8F8F, cursor not-allowed

Four lines per component, and an entire class of review comments disappears.

End with don'ts — the enforcement section

Models treat prohibitions as strong signals. Collect every "never" your system implies and state them flatly:

• Never introduce a color outside this file.
• Never use font-weight 700.
• Never mix border and box-shadow borders on one element.
• Never animate layout properties; opacity and transform only.

Ten good don'ts protect more brand integrity than a thousand words of atmosphere prose.

Maintain it like code

A design file rots the day the design changes and the file doesn't. Two habits keep it alive: update DESIGN.md in the same PR as any visual change, and when you approve an agent's deviation, write the exception into the file immediately. Wire the file into your agent per our Claude Code and Cursor guides so it's read on every session.

Fastest path to a first draft

Don't start blank. Either adapt a reference from the library whose discipline matches your ambitions — the Vercel and Stripe files are the most instructive — or paste your own URL into the generator and edit a grounded draft. Learning how to write a design md is mostly learning to demand evidence and assign roles; the format does the rest.