DESIGN.md Specification

A DESIGN.md is the single source of truth for a project's visual language. Create it BEFORE building UI. Two layers: machine-readable design tokens (YAML front matter) + human-readable rationale (markdown body). Tokens are normative; prose gives context. Prose may use descriptive names ("Midnight Forest Green") that map to systematic token names (primary).

Format adapted from the DESIGN.md spec (Google Labs, Apache-2.0). A linter/exporter exists: npx @google/design.md.

📚 Reference library: collection.md — 70+ real-world DESIGN.md files (Airbnb, Stripe, Linear, Vercel, Apple…) to study or adapt as a starting point.

When to produce a DESIGN.md

This is a hard gate for UI work (see .agents/rules/design-rules.md): before writing components, pages, or styles, a DESIGN.md must exist at the project root. If absent, create it first from the brief; if present, read it and conform.

The token block converts cleanly to/from tokens.json, Figma variables, and Tailwind theme config — so it is the bridge between design intent and code.