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
---

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.

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.

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.