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"