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
Primary is #1A1C1E. Secondary is #6C7278.
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:
## 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
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.