Docs / Getting started
What is DESIGN.md?
DESIGN.md is an open format specification for describing a product's visual identity to AI coding agents. Published by Google Labs under the Apache 2.0 license, currently at alpha status.
The format combines two layers in a single .md file: a machine-readable YAML block of design tokens (colors, typography, spacing, components) and a human-readable markdown body that explains the design rationale — so both engineers and AI agents understand what to build and why.
package.json is the dependency manifest and README.md explains the codebase to human contributors, DESIGN.md explains your design system to AI agents.Without a design spec, AI agents produce arbitrary colors, inconsistent typography, and components that follow no coherent system. With DESIGN.md the agent has exact token values and a prose-level understanding of when and how to apply each one. Practitioners report AI-generated UIs with DESIGN.md need only minor adjustments versus dozens of back-and-forths without a spec.
The file is version-controllable in Git, human-readable without any tooling, and requires no build step — a single DESIGN.md at your project root is all you need.
Two layers in one file
Exact values: hex colors, font sizes, spacing scale, border radius, component properties. Used by the CLI and AI agents for precise, consistent output.
The eight standard sections explain the brand, usage rules, and constraints — giving AI agents the “why” that raw token values can't capture.
Works with your existing tools
Claude Code reads DESIGN.md automatically from the project root. Cursor picks it up via the @DESIGN.md reference. GitHub Copilot accepts it as a system prompt constraint. Google Stitch has native generation and export support. See Integrations for step-by-step setup for each tool.
The official CLI (@google/design.md) provides linting with WCAG contrast checks, version diffing, and export to Tailwind config or the W3C DTCG standard for Figma and Tokens Studio.
Ready to drop a design.md into your project?
Browse 30+ curated design system files — pick one, download, and drop it in your repo.
Browse the library