\n
\n 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.<\/p>\n
The front matter: tokens<\/p>\n
The front matter holds your colors, typography, spacing, rounded corners and components as typed values. It opens and closes with three dashes:<\/p>\n
—
\ncolors:
\n primary: “#1A1C1E”
\n surface: “#FFFFFF”
\nspacing:
\n sm: 8px
\n md: 16px
\n—<\/p>\n
Enter fullscreen mode<\/p>\n
Exit fullscreen mode<\/p>\n
This gives the agent precise values to use directly.<\/p>\n
The body: prose<\/p>\n
Below the front matter is the rationale, in canonical sections:<\/p>\n
## Overview
\nA calm, focused reading environment. The UI recedes so content leads.<\/p>\n
## Colors
\nWarm neutrals carry the interface. The accent is reserved strictly
\nfor interactive elements – never decorative.<\/p>\n
Enter fullscreen mode<\/p>\n
Exit fullscreen mode<\/p>\n
Why pair them?<\/p>\n
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.<\/p>\n
# A tokens-only file: just data, no rules.
\n# A prose-only file: intent, but no precise values.
\n# DESIGN.md: both, so the agent applies the system correctly.<\/p>\n
Enter fullscreen mode<\/p>\n
Exit fullscreen mode<\/p>\n
The canonical sections<\/p>\n
Overview – the personality<\/p>\n
Colors – roles and rules<\/p>\n
Typography – the job of each style<\/p>\n
Layout – grid and spacing<\/p>\n
Elevation & Depth – how hierarchy is built<\/p>\n
Do’s and Don’ts – hard guardrails<\/p>\n
FAQ<\/p>\n
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.<\/p>\n
Bottom line<\/p>\n
Tokens are the values; prose is the meaning. A DESIGN.md works because it carries both in one file the agent reads together.<\/p>\n
Free starter: The format, a complete annotated example, and the core idea are on a free cheat sheet: DESIGN.md Quick-Start Cheat Sheet<\/p>\n
Go deeper: The full guide covers the entire format \u2014 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<\/p>\n
Do you write rationale in your design docs, or just list the tokens? Curious how teams handle the ‘why’ in the comments.<\/p>\n