DESIGN.md Anatomy: How Design Tokens and Prose Work Together
A DESIGN.md file has two parts: YAML front matter holding machine-readable design tokens, and a markdown body holding human-readable rationale. The tokens give an agent exact values; the prose gives it the rules for using them. Pairing the two is the format's core insight.
What does the front matter contain?
The front matter is the design tokens — your colors, typography, spacing, rounded corners and components — as structured, typed values. It opens and closes with lines of three dashes, and the YAML between them is parsed against the format's schema. This is what gives an agent precise values to use directly.
What does the prose contain?
Below the front matter is the markdown body: the reasoning behind the values. It is organised into canonical sections — Overview, Colors, Typography, Layout, Elevation and Depth, and Do's and Don'ts. This is where you explain what each color is for, how the type scale works, and the rules an agent must follow.
Why pair tokens with prose?
This is the whole insight of the format. A hex value tells an agent what a color is. Only prose can tell it that this color is the sole interaction driver and must never be used decoratively. A tokens-only file is just data, with no rules; a prose-only file has intent but no precise values. Together, they let an agent apply your design system correctly, not just access its raw numbers.
What does a complete DESIGN.md look like?
A small one opens with a name, then colors and typography and spacing in the front matter, closed with three dashes, followed by an Overview describing the personality and a Colors section explaining that the accent is for the primary action only. Every line of the body does work the tokens cannot: it assigns roles, states rules, and sets boundaries.
FAQ
Is the front matter required? In principle it is optional, but in practice it is the heart of the file — it is what gives agents exact values.
Can I use only prose? You can, but you lose the precise values. The format is designed for tokens and prose together.