To write DESIGN.md prose agents follow, describe intent and rules, not just values. A token says a color is a hex; good prose says it is for the primary action only. Reasoning is what lets an agent generalise to cases you did not explicitly cover.
Weak vs strong prose
## Colors # WEAK - restates the tokens: Primary is #1A1C1E. Secondary is #6C7278. # STRONG - 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.
Why prose works on agents
LLMs read markdown with very high fidelity – most of their training is structured this way. That makes prose an ideal channel for design intent. The value tells the model what a color is; only prose tells it the rules.
Cover the canonical sections
Each section answers a question the agent would otherwise guess at:
## Overview -> the personality ## Colors -> roles and rules ## Typography -> the job of each style ## Layout -> grid and spacing ## Do's and Don'ts -> hard guardrails Do’s and Don’ts is where the value is
## Do's and Don'ts - Do use the accent for one primary action per screen - Don't mix rounded and sharp corners in the same view - Do maintain WCAG AA contrast (4.5:1 for normal text) - Don't use more than two font weights on a screen Each line removes a whole category of off-brand output.
How much is enough?
A good test: would the prose let a designer who had never seen your product apply your system correctly? Write what prevents a mistake, and stop there.
FAQ
Descriptive color names? Yes – tie them to the token name so the agent can map rationale onto values.
Most important section? Do’s and Don’ts – it directly prevents agent mistakes.
Bottom line
Tokens are easy; the rationale is the work. Spend your time on the prose that turns values into your identity.
Free starter: The format, a complete annotated example, and the core idea are on a free cheat sheet: DESIGN.md Quick-Start Cheat Sheet
Go deeper: The full guide covers the entire format — the token schema, the CLI in depth, accessibility, Tailwind and DTCG export, agent integration, and a complete walkthrough: DESIGN.md: The Complete Guide to Design Systems for AI Agents
What is the one design rule you wish your agent would stop breaking? Drop it below – it probably belongs in your Do’s and Don’ts.