Why AI Coding Agents Need DESIGN.md

Ask an AI coding agent to build a settings page and it will usually give you something functional, responsive, and strangely unrelated to the rest of your product. The buttons work. The form submits. The layout compiles. But the agent has invented a blue, chosen its own spacing, added a shadow you stopped using two years ago, and made the empty state sound like a marketing page.

That is not mainly a model failure. It is a context failure. The agent cannot know that your buttons use a 10px radius, that your body copy is 15px, that destructive actions are never filled red, or that operational screens should be quiet and dense. Those decisions exist in a designer’s head, a Figma file, a component library, scattered code, or nowhere at all. When the decision is not available in the repository context, the agent guesses.

This is why DESIGN.md matters. It gives the agent a durable, readable record of the visual decisions it would otherwise reinvent on every task.

One slightly generic screen is easy to fix. The problem appears when an agent works across a whole product. A single prompt can touch a dashboard, a settings page, a modal, a table, and a mobile navigation state. If each surface makes independent visual decisions, the product slowly becomes a collection of plausible screens rather than one recognizable system.

The cost is not only aesthetic. Reviewers spend time correcting the same details: wrong spacing, inconsistent states, invented components, noisy hierarchy, and copy that does not belong in the product. Those corrections are repeated because the correction lives in a chat message or a pull request, not in the context the next agent will read.

# Design rules

## Tokens
- Primary action: --color-primary
- Default spacing: 4px scale
- Card radius: 10px

## Rules
- Reuse existing components before creating new ones.
- Never use raw color values in UI code.
- Define loading, empty, error, and disabled states.

The format matters less than the clarity. Some teams keep one file; larger products split it into a short root file that links to focused documents for tokens, components, and content voice. What stays constant is the goal: give the agent enough concrete, unambiguous guidance that its default guesses get overridden by your actual decisions.

A Figma library, Storybook, or token file can be the source of truth for a team and still be a weak instruction for an agent. Those systems are built to be browsed, inspected, and interpreted by people. An agent needs the decisions in a form it can load next to the code and apply while it edits files.

DESIGN.md is not a replacement for those systems. It is their agent-readable layer: a concise contract that translates visual intent into concrete rules, component patterns, states, and things the product should never do.

The first change is practical: fewer corrections on the first pass. Instead of repeating “use our spacing” or “that blue is wrong” in every session, the agent has a reference it can check before it writes UI.

The second change is consistency. Two teammates working on different days can ask for different screens and still get decisions that rhyme, because both sessions load the same visual contract. The agent does not wake up with a new opinion about what “modern” means.

The third change is organizational. Writing the file exposes decisions the team had been carrying informally. A rule becomes reviewable, versioned, and changeable in the same repository as the implementation it governs.

DESIGN.md does not create a visual direction from nothing. If the product has no decisions, the file cannot invent a good one on your behalf. It also does not replace visual review: screenshots, browser checks, accessibility checks, and human judgment still matter.

The file works when it is specific and current. “Make it feel premium” leaves the agent guessing. “Use the neutral surface for operational cards; reserve the accent for primary actions and active states” gives it something it can actually apply. A stale file is worse than a short file because it makes old decisions look authoritative.

• It can preserve explicit decisions across agent sessions.
• It can reduce repeated corrections and visual drift.
• It cannot replace taste, product judgment, or visual QA.
• It should evolve when the product or its components evolve.

The most useful DESIGN.md is not the longest one. Start with the decisions that change the output most often, then refine the file from real work.

1. Write a thin first version with product character, core tokens, canonical components, and anti-patterns.
2. Tell the agent to read DESIGN.md before any UI task and reuse existing components first.
3. Ask it to build one representative surface, such as a settings page or dashboard state.
4. Review the result in the browser and list every recurring mismatch.
5. Turn the highest-value corrections into specific rules in DESIGN.md.
6. Repeat the cycle whenever a new surface reveals a missing decision.

## Design\n\nBefore writing or changing UI, read DESIGN.md.\nTreat its tokens, components, states, and anti-patterns as binding.\nReuse existing components before creating new ones.\nIf the task conflicts with a design rule, explain the conflict first.

The point is to stop asking the agent to invent taste on every task. DESIGN.md turns a product’s visual decisions into something a coding agent can load, search, and apply. It moves design consistency out of memory and into the workflow.

If you want the practical definition, structure, and starting checklist, read the complete guide to what DESIGN.md is. If you want a ready-made starting point, use the DESIGN.md template and adapt it to your product. The blog argument is simple: agents are becoming capable of building more of the interface, so the design decisions they need must live where they can actually read them.