How to Write a DESIGN.md Agents Follow

The single most useful mental model for writing a DESIGN.md is this: your reader is fast, literal, and has no memory of anything you said before. That is what an agent is at the start of every task. It will not infer your intent from tone, it will not remember the correction you made yesterday, and it will take a vague instruction as license to guess. Every sentence you write is either a decision it can act on or a gap it will fill on its own.

This changes how you phrase things. "Keep spacing consistent" is not a rule an agent can follow — consistent with what? "Use 4px spacing increments; the default gap between form fields is 16px" is. The difference between a DESIGN.md that works and one that gets politely ignored is almost entirely specificity.

You do not need every section below, but this order works because it moves from the most reused decisions to the most situational. Start at the top and stop when the remaining sections would not change your output.

1. Principles — three to five sentences on the character of the product. What it should feel like, and what it should never feel like.
2. Color — your tokens, their names, and when each is used. Especially: which color is primary, and when destructive or muted apply.
3. Typography — the type scale, the default body size and line height, and which weights exist. Name the display font if it differs from body.
4. Spacing and layout — the base increment, default gaps, and container widths. Whether you use a grid.
5. Shape and depth — radius values, border conventions, and your stance on shadows.
6. Components — the patterns you consider canonical, named, with a one-line description of each.
7. States and interaction — hover, focus, disabled, loading. How motion is used, if at all.
8. Anti-patterns — the explicit list of things the agent must not do.

Bad:  Keep the spacing consistent.
Good: Use 4px increments; form fields use a 16px gap.

Bad:  Make destructive actions clear.
Good: Use the danger variant with text + border; never a filled red CTA.

Agents apply concrete values far more reliably than they interpret adjectives. If your file says "use a calm, neutral palette," the agent will pick its own calm neutrals — and they will not be yours. Give it the actual tokens and it will use them verbatim.

## Color

Use these tokens only. Never introduce raw hex values in components.

| Token         | Value     | Use for                          |
| ------------- | --------- | -------------------------------- |
| `--bg`        | #faf9f7   | Page background                  |
| `--fg`        | #1a1a1a   | Body text, primary content       |
| `--muted-fg`  | #6b6b6b   | Secondary text, captions, meta   |
| `--primary`   | #d4502a   | Primary buttons, active states   |
| `--border`    | #e6e3dd   | Hairline dividers and card edges |

- Primary is the only accent. Do not add a second brand color.
- Destructive actions use text + border, never a filled red button.

## Button tokens

- Primary buttons use --color-primary with --text-on-primary.
- Secondary buttons use --surface with a 1px --border outline.
- Disabled buttons use --muted-fg and never invent a new gray.
- Do not use raw hex values in component files.

The table format is deliberate. It pairs each token with the situations it applies to, which is exactly the information the agent needs to choose correctly. A bare list of hex codes tells it what colors exist; the "Use for" column tells it when to reach for each one.

Most DESIGN.md files spend all their words on what to do and none on what to avoid. This is backwards. An agent has strong defaults, and many of your design decisions are precisely rejections of those defaults. If you do not name them, the defaults win.

Write anti-patterns as direct prohibitions with the reason attached, because the reason helps the agent generalize to cases you did not list. "Do not use drop shadows on cards; we use a 1px border instead" is better than "no shadows," because the agent now understands the underlying preference and applies it to a modal you never mentioned.

• Do not center body text or form labels — everything is left-aligned.
• Do not use emoji as UI icons; use the lucide icon set.
• Do not add gradients or glassmorphism; surfaces are flat with hairline borders.
• Do not invent new spacing values; snap to the 4px scale.
• Do not make the destructive action the primary button in a dialog.

There is a real tension here. A DESIGN.md that is too thin lets defaults leak back in; one that is too bloated gets truncated, skimmed, or crowds out the actual task in the context window. The target is the smallest file that changes the most output.

A practical way to stay on the right side of that line: earn every rule. Add a rule when you catch yourself making the same correction twice, and delete one when it stops being true. If your file is growing without your output improving, you are documenting a design system, not writing agent instructions — split the reference material into linked files and keep the root DESIGN.md to the decisions that matter on most tasks.

Finally, test it the way the agent will use it. Give a fresh session a real task, load the file, and read the output critically. Every place the result disappoints is either a missing rule or a vague one. That feedback loop, run a few times, produces a file that genuinely steers the work — which is the only measure of a DESIGN.md that matters.