A README for your design system that AI actually reads

What it does

A DESIGN.md file puts machine-readable design tokens—colors, typography, spacing, and component properties—in YAML front matter, followed by human-readable rationale in markdown sections. Agents read the exact values and the reasoning behind them, so they know both what to use and why. A companion CLI validates structure, catches broken token references, checks WCAG contrast ratios, diffs versions, and exports to Tailwind or W3C DTCG formats.

The interesting bit

The format treats prose as a first-class citizen, not just decoration. Tokens are normative, but the markdown body explains design intent—think “Architectural Minimalism meets Journalistic Gravitas”—giving context that raw token JSON cannot. It is a bet that agents need brand philosophy as much as they need hex codes.

Key highlights

• Linting covers broken token references, orphaned colors, missing primary palettes, and section ordering.
• Built-in WCAG AA contrast checking for component color pairs.
• A diff command surfaces token-level and prose regressions between versions.
• Exports to Tailwind v3 config, Tailwind v4 CSS theme blocks, and W3C DTCG tokens.json.
• Programmatic TypeScript API for embedding validation into other tools.

Caveats

• The format is at version alpha; the spec, schema, and CLI are under active development and expected to change.
• The linter accepts unknown color and typography token names without error if the raw value is valid CSS, which could let typos slide.

Verdict

Worth a look if you are feeding design systems to LLMs and tired of repeating “no, the button should be Boston Clay, not orange.” Skip it if you need a battle-tested, stable token format today.