A DESIGN.md has two parts: YAML front matter with machine-readable design tokens, and a markdown body with human-readable rationale. Tokens give an agent exact values; prose gives it the rules. Pairing them is the format's core insight.
The front matter holds your colors, typography, spacing, rounded corners and components as typed values. It opens and closes with three dashes:
---
colors:
primary: "#1A1C1E"
surface: "#FFFFFF"
spacing:
sm: 8px
md: 16px
---
This gives the agent precise values to use directly.
Below the front matter is the rationale, in canonical sections:
## Overview
A calm, focused reading environment. The UI recedes so content leads.
## Colors
Warm neutrals carry the interface. The accent is reserved strictly
for interactive elements - never decorative.
A hex value tells the agent what a color is. Only prose can tell it that this color is the sole interaction driver and must never be used decoratively.
Is the front matter required? In principle optional, but in practice it is the heart of the file.
Can I use only prose? You can, but you lose precise values. The format is designed for both.
Tokens are the values; prose is the meaning. A DESIGN.md works because it carries both in one file the agent reads together.
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
Do you write rationale in your design docs, or just list the tokens? Curious how teams handle the 'why' in the comments.