What it does

DESIGN.md is a file format that splits a design system into two parts: YAML front matter with exact tokens (colors, typography, spacing) and markdown prose explaining the rationale. You write it once; coding agents read it and stop generating purple buttons for a “warm limestone” brand.

The interesting bit

The format treats LLMs as first-class consumers. The prose isn’t decorative — it’s there so an agent understands why the primary color is “deep ink” and doesn’t swap it for convenience. The CLI even exports the spec itself to paste into prompts.

Key highlights

• Built-in linter catches broken token references, WCAG contrast failures, and orphaned colors
• diff command spots token-level regressions between design system versions
• Exports to Tailwind v3/v4 configs, raw CSS, or W3C DTCG standard tokens
• Programmatic TypeScript API for custom tooling
• Strict section ordering rules, with warnings for typos like colours: instead of colors:

Caveats

• Format is alpha; Google warns the spec is actively changing
• Windows users need the designmd alias because .md confuses shell file associations
• npm install @google/design.md can fail on corporate registries that haven’t synced the scoped package

Verdict

Worth adopting if you’re already using AI coding tools and tired of repeating design feedback. Skip it if your “design system” is a single CSS file and a prayer.