DESIGN.md in an AI Agent Workflow

The most common reason a DESIGN.md fails is not the writing — it is that the agent never actually loads it. A beautifully specified file sitting in a folder the agent does not scan is invisible. Before you polish the content, make sure the file is on the path the agent reads, on every task, without you having to remember to paste it in.

How you do that depends on the tool, but the principle is universal: the design instructions have to enter the context automatically, the same way the agent already picks up your README or your config. Manual pasting works exactly until the one time you forget, which is the task where the output regresses.

Each tool has its own front door. The goal in all of them is the same — reference DESIGN.md from the file the agent reads on startup.

• Claude Code — reference DESIGN.md from CLAUDE.md, which is loaded into every session. A single line pointing the agent at the file, plus an instruction to read it before UI work, is enough.
• Cursor — add a rule in your project rules that points to DESIGN.md and instructs the agent to follow it for any interface change.
• Copilot and others — keep DESIGN.md at the repo root; most agents that scan the workspace will surface it, and you can reference it directly in prompts for the rest.

## Design

Before writing or changing any UI, read `DESIGN.md` and follow it.
It defines our tokens, components, and anti-patterns. Treat its
rules as binding; if a task seems to require breaking one, stop
    and ask rather than guessing.

Before UI work:
1. Read DESIGN.md.
2. Inspect the nearest existing component.
3. Implement with the documented tokens and states.
4. Render the result and report any rule you could not apply.

A lightweight daily loop keeps the file useful without turning every UI task into a documentation project. Start by asking the agent to name the relevant DESIGN.md rules before it edits. During review, separate one-off preference from a repeatable product rule. Only the repeatable rule belongs in the file, and it should include the condition that makes it true — for example, compact density for tables but comfortable density for forms.

At the end of the task, compare the rendered result rather than only the diff. Code review catches raw values and missing component reuse; the browser catches hierarchy, awkward wrapping, and states that were never exercised. If the same visual correction appears twice, update DESIGN.md in the same change and make the next agent inherit the fix.

1. Read the relevant DESIGN.md section and list the rules that apply.
2. Inspect one nearby canonical component before creating a new pattern.
3. Implement the route and verify loading, empty, error, responsive, and keyboard states.
4. Record repeated corrections as explicit rules, not as private review comments.

A DESIGN.md is never finished on the first write, and it should not be. The way it gets good is the same way any instruction set gets good: you run it, you see where it fails, and you patch the gap. Every time you find yourself correcting the agent on something the file should have covered, that correction is a pending edit to DESIGN.md.

Build this into your review habit. When you review agent-generated UI and something is off, ask whether the file told it the right thing. If not, fix the file before you fix the code — because fixing the code solves one instance, and fixing the file solves every future instance. Over a few weeks this compounds into a document that genuinely encodes your taste.

Products drift. You rebrand, you drop a component, you change the radius, you decide shadows are fine after all. When the product moves and the DESIGN.md does not, the file becomes a source of confident, wrong instructions — the agent will faithfully apply rules you have abandoned. Stale design guidance is worse than none, because the agent trusts it completely.

The fix is to treat DESIGN.md as living code, not documentation. It belongs in the same pull request as the change it describes, it gets reviewed, and it has git history. A rule that is no longer true gets deleted in the change that makes it untrue. Done this way, the file stays trustworthy, the agent stays aligned, and the whole loop — write, run, correct, update — keeps your interface consistent no matter who is prompting or which agent is doing the work.

A useful maintenance signal is repeated uncertainty. If the agent asks whether a component should use the compact or comfortable density, the answer belongs in the file. If the answer changes by surface, document the condition rather than adding a vague exception. That turns review discussion into reusable context instead of private team memory.