DESIGN.md Anatomy: How Tokens and Prose Work Together

A developer introduced DESIGN.md, a file format that pairs YAML front matter with machine-readable design tokens and a markdown body containing human-readable rationale. The format aims to give AI agents both precise values and contextual rules for applying design systems. A free cheat sheet and a full guide are available.

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. 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. 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 https://promptmasterstore.gumroad.com/l/design-md-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 https://promptmasterstore.gumroad.com/l/design-md-guide Do you write rationale in your design docs, or just list the tokens? Curious how teams handle the 'why' in the comments.