google-labs-code/design.md
OfficialA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.
DESIGN.md is google-labs-code's format specification for describing a visual identity to AI coding agents. YAML front matter declares design tokens (colors, typography, spacing), markdown prose explains the rationale, and the bundled validator catches broken references and WCAG contrast issues.
Our Review
DESIGN.md is Google Labs Code's official format specification for describing a visual identity to coding agents -- 14,200 stars and 1,300 forks in under six weeks as of May 2026. Released April 2026 by google-labs-code under Apache 2.0 and hosted as a Google Labs / Stitch project, the spec defines a YAML-front-matter-plus-markdown file that gives Claude Code, Cursor, Gemini CLI, and any other coding agent persistent structured access to a project's design system.
What DESIGN.md does:
- •YAML + markdown hybrid format machine-readable design tokens in front matter (colors, typography, spacing, radii) combined with human-readable rationale prose.
- •Token-aware validator catches broken token references, checks WCAG contrast ratios, surfaces structural findings as JSON.
- •CLI for validation run
design-md lintor similar to verify a DESIGN.md against the spec before handing it to an agent. - •Agent-consumable specification agents read the file once and use its tokens consistently across generated UI code.
- •Token categories colors, typography (font families and sizes per role like h1, body-md, label-caps), spacing, radii, shadows, and more as extensible groups.
- •Prose context per token each token group can have explanatory prose so agents understand the design intent rather than only the raw values.
- •WCAG-aware the validator runs contrast-ratio checks across color pairings to surface accessibility violations.
DESIGN.md ecosystem:
- •Stitch by Google Labs the parent product that hosts DESIGN.md docs at stitch.withgoogle.com/docs/design-md/specification.
- •Coding agents Claude Code, Cursor, Gemini CLI, and OpenAI Codex can all read and apply DESIGN.md files in a project.
- •Apache 2.0 license specification and tooling fully open for adoption by other tooling vendors.
- •TypeScript reference implementation the tooling itself is TypeScript, easy to embed or extend.
Getting started:
Add a DESIGN.md file to your project root with YAML front matter for tokens and markdown for rationale. Use the published spec at stitch.withgoogle.com/docs/design-md/specification as the reference for valid token keys. Run the validator CLI from the repo to lint your file. Then commit DESIGN.md alongside your code; AI coding agents will pick it up automatically when they see it.
Limitations:
DESIGN.md is a specification, not a styling library -- you still need Tailwind, CSS variables, or another styling approach to actually apply the tokens. Agent support depends on the agent recognizing DESIGN.md as a context file; not every agent does this automatically. The spec is young (released April 2026), so expect breaking changes in token category structure as it stabilizes. Currently focused on visual identity; component-level specifications (button states, motion, etc.) are not yet covered.
Our Verdict
DESIGN.md in 2026 is Google Labs Code's emerging standard for telling AI coding agents what a project's visual identity looks like. 14,200 stars in six weeks, 1,300 forks, Apache 2.0, and backed by Google Labs / Stitch -- making this the closest thing to a vendor-blessed convention for design-system context in agent-driven UI generation.
For Vibe Builders, DESIGN.md is the way to stop fighting your AI agent for consistent visual output. Write the tokens once, commit DESIGN.md to your project, and every prompt-driven UI change uses the same palette, typography, spacing, and rationale automatically. The validator catches broken references and accessibility issues before they ship.
For Developers building agent-driven design systems or product tooling, DESIGN.md is the canonical hand-off format between design teams and agent codebases. The YAML-plus-prose structure is more readable than a JSON Design Tokens file and richer than CLAUDE.md-style natural-language instructions.
Skip DESIGN.md if your project has no design system and you do not want one -- the spec assumes you have or want tokens. Skip if your agent does not auto-discover DESIGN.md and you do not want to wire it manually. For pure design-token storage (no rationale prose), the W3C Design Tokens Format Module covers that ground with broader tooling support.
Frequently Asked Questions
What is DESIGN.md?
DESIGN.md is a format specification from Google Labs Code for describing a visual identity to AI coding agents. A DESIGN.md file combines YAML front matter (machine-readable design tokens like colors, typography, spacing) with markdown prose (the rationale for each token group). Agents read the file and produce UI that uses those tokens consistently. As of May 2026 it has 14,200 GitHub stars.
How is DESIGN.md different from JSON Design Tokens?
JSON Design Tokens (the W3C spec) store token values in a strict machine-readable format with no prose. DESIGN.md adds human-readable rationale alongside each token group, so agents understand the design intent rather than only the raw values. The trade-off is DESIGN.md has fewer existing tooling integrations than the W3C format, but is more agent-friendly for AI coding workflows.
Which AI coding agents support DESIGN.md?
DESIGN.md is designed to be agent-agnostic. Any coding agent that scans the repository for context files can recognize DESIGN.md. Claude Code, Cursor, Gemini CLI, and OpenAI Codex pick it up via their respective context-discovery mechanisms. Some agents may need a small instruction to look for DESIGN.md by name; the spec docs at stitch.withgoogle.com explain integration patterns.
How do I create a DESIGN.md file?
Add a file called DESIGN.md to your project root. Start with YAML front matter declaring your tokens (colors, typography, spacing, radii), then write markdown prose explaining the design language and how each token group should be used. Use the spec at stitch.withgoogle.com/docs/design-md/specification as the schema reference. Run the validator from the google-labs-code/design.md repo to lint.
What does the DESIGN.md validator check?
The validator catches broken token references (e.g. using a typography role that is not defined), checks WCAG contrast ratios across color pairings to surface accessibility violations, and produces structured JSON findings that agents can act on directly. It runs as a CLI command on a single DESIGN.md file or across a project. Apache 2.0 licensed so you can embed it in your own tooling.
What license does design.md use?
design.md uses the Apache-2.0 license.
What are alternatives to design.md?
Explore related tools and alternatives on My AI Guide.
Open source & community-verified
Apache-2.0 licensed: free to use in any project, no strings attached. 14,448 developers have starred this, meaning the community has reviewed and trusted it.
Reviewed by My AI Guide for relevance, quality, and active maintenance before listing.
Topics