design.md, open format spec for ai coding agent design systems
About DESIGN.md
DESIGN.md is a format specification from Google Labs for describing a visual identity to coding agents. It pairs machine-readable design tokens (YAML front matter) with human-readable design rationale (Markdown prose), giving agents a persistent, structured understanding of your design system. Ships with an official CLI (@google/design.md) for linting (WCAG contrast, broken refs), diffing, and exporting to Tailwind v3/v4 or DTCG. Still in alpha.
Key Capabilities
Open format spec from Google Labs (origin of Google Stitch)
Combines machine-readable YAML tokens with human-readable Markdown rationale
Official CLI: lint, diff, export, spec commands
Built-in WCAG contrast checking and broken token reference detection
Exports to Tailwind v3/v4 config and DTCG (W3C Design Tokens)
Works with Claude Code, Cursor, Stitch, and any agent that reads repo files
Standout Features
Tokens + Rationale
YAML front matter for exact token values, Markdown prose for the why behind each design decision.
Official CLI
Run npx @google/design.md to lint, diff versions, export to Tailwind or DTCG, and inspect the spec.
WCAG Contrast Linting
Built-in accessibility checks catch contrast failures and broken token references before commit.
Component Variants
Define variants like button-primary-hover with token references like {colors.primary} for clean composition.
Repo-Native
Lives as a single portable DESIGN.md file in your repo, agents read it the same way they read README or AGENTS.md.
Perfect for
Compare DESIGN.md
Community Buzz
Community Buzz
No recent posts yet
We are monitoring X for fresh discussions about DESIGN.md.
Related Articles
ready to try design.md?
join thousands of developers already using DESIGN.md.
try design.md now