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: tokens
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
—
Enter fullscreen mode
Exit fullscreen mode
This gives the agent precise values to use directly.
The body: prose
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.
Enter fullscreen mode
Exit fullscreen mode
Why pair them?
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.
# A tokens-only file: just data, no rules.
# A prose-only file: intent, but no precise values.
# DESIGN.md: both, so the agent applies the system correctly.
Enter fullscreen mode
Exit fullscreen mode
The canonical sections
Overview – the personality
Colors – roles and rules
Typography – the job of each style
Layout – grid and spacing
Elevation & Depth – how hierarchy is built
Do’s and Don’ts – hard guardrails
FAQ
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.
Bottom line
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.
Leave a Reply