How to Write DESIGN.md Prose That AI Agents Actually Follow

A developer argues that DESIGN.md files should describe intent and rules rather than just token values to guide AI agents effectively. The post explains that prose explaining design rationale, such as color roles and typography jobs, enables agents to generalize correctly, with a 'Do's and Don'ts' section being the most critical for preventing off-brand output.

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. 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. 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. Each section answers a question the agent would otherwise guess at: php 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 - 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. 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. 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. 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 https://promptmasterstore.gumroad.com/l/design-md-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 https://promptmasterstore.gumroad.com/l/design-md-guide 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.