How to Write DESIGN.md Prose That AI Agents Actually Follow
To write DESIGN.md prose that agents follow, describe intent and rules, not just values. A token says a color is a specific hex; good prose says that color is for the primary action only and never decorative. Reasoning is what lets an agent generalise correctly to cases you did not explicitly cover.
Why does prose matter to an agent?
Large language models read markdown with very high fidelity — most of their training is structured this way, so they need no special instruction to parse it. That makes prose an ideal channel for design intent. The raw value tells the model what a color is; only prose can tell it the rules for using it.
What is weak prose versus strong prose?
Weak prose restates the tokens: "primary is this hex, secondary is that hex." It adds nothing the front matter did not already say. Strong prose explains intent: "high-contrast neutrals with one warm accent; use the accent only for the single most important action, never decoratively." The strong version gives the agent a rule it can apply to situations you never listed.
Which sections should the prose cover?
The canonical sections are Overview (the personality), Colors (roles and rules), Typography (the job of each style), Layout (grid and spacing), Elevation and Depth (how hierarchy is built), and Do's and Don'ts (hard guardrails). You do not need every section, but each one answers a question the agent would otherwise guess at.
How much prose is enough?
A useful test: would the prose let a designer who had never seen your product apply your system correctly? If a rule is implicit in the tokens, you do not need to state it. If it could not be guessed from the values alone — that the accent is interaction-only, that corners are always rounded — it belongs in the prose. Write what prevents a mistake, and stop there.
FAQ
Should I use descriptive color names? Yes — names like "Boston Clay" alongside the token name give the agent a richer sense of each color, as long as you tie them to the systematic token name.
What is the most important section? Do's and Don'ts, because it directly prevents the mistakes agents make most.