DESIGN.md Review 2026: Googles Open Format for AI Design Systems

If you have ever asked an AI coding agent to "build me a settings page that matches our brand" and watched it return something that looks like a screenshot from 2014, you already understand the problem DESIGN.md is trying to fix.

Agents do not see your Figma file. They do not see your Notion page where the color palette is locked. They guess. And every new chat is a fresh guess.

DESIGN.md is Google Labs' attempt to make that guessing stop. It is a markdown file that lives in your repo and tells agents, with machine precision, what your design system actually is. The spec is open source, the CLI is free, and the format was originally extracted from Google Stitch before the team open-sourced it.

This is an independent review based on the official spec (verified against the GitHub README on 2026-05-14), the community response on Reddit and X, and side-by-side testing with Claude Code.

Quick verdict: If you are an AI-first dev team shipping a single product, adopt DESIGN.md now. The alpha-stage breakage risk is real but small. If you run a multi-brand design org that already lives in Tokens Studio or Figma variables, watch the format mature for a quarter before migrating.

---

What DESIGN.md actually is

The official one-liner, verbatim from the spec: "A format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system."

Structurally, every DESIGN.md file has two layers:

1. YAML front matter at the top. This is the machine-readable layer. It defines tokens for colors, typography, spacing, rounded, and components. Token references work the way they do in any design token system: {colors.primary} resolves to your primary color, even inside component variants like button-primary-hover.
2. Markdown prose below the front matter. This is the human-readable layer. It explains why each token exists, when to use which variant, and how the system holds together as a brand.

The spec puts it cleanly: "Tokens give agents exact values. Prose tells them why those values exist and how to apply them."

That split is the actual idea worth stealing. Most existing design token formats give agents values without context. Most design system documentation gives agents context without values. DESIGN.md is the first format that puts both in one file an agent can read in a single pass.

---

The CLI: @google/design.md

DESIGN.md ships with an official command-line tool published to npm as @google/design.md. Latest release at the time of writing is 0.1.1. Four commands matter:

• lint validates structural correctness. It catches malformed YAML, broken token references like {colors.primry}, and most importantly it runs WCAG contrast checks against your color pairs. If your primary button text fails AA contrast against your primary background, you know before the agent generates the component.
• diff compares two versions of a DESIGN.md file and reports token-level changes. Useful in code review when somebody bumps the spacing scale and you want to see what shifted.
• export converts the YAML tokens into other formats. Three targets are supported today: json-tailwind (Tailwind v3 config), css-tailwind (Tailwind v4 theme with CSS variables), and dtcg (the W3C Design Tokens Format Module). DTCG export is the bridge to every other token tool in the ecosystem.
• spec prints the format specification itself. Handy when you want to hand the spec to an agent in the same conversation as your DESIGN.md file.

You can run all four without installing anything: npx @google/design.md lint. That low-friction install matters more than it should, because the cost of adoption is now "open your terminal and type one command."

---

Pricing

DESIGN.md is free. The spec is Apache 2.0. The CLI is on npm with no paywall. There is no enterprise tier, no cloud sync, no SaaS layer waiting to bite you later.

Context worth knowing: Google Stitch, the design tool that spawned DESIGN.md, is currently free with daily credit limits in research preview. DESIGN.md predates and outlives Stitch. Even if Google's product team killed Stitch tomorrow, the DESIGN.md spec would continue, because it is just a Markdown file format and an Apache-licensed CLI.

---

What works

After two weeks of using DESIGN.md across three repos, here is what holds up.

Agents actually obey it. I tested with Claude Code and Cursor. Both picked up the file with zero special prompting and produced UI that matched the tokens. With Claude Code, "build me a CTA section in the brand style" returned a section using the exact hex codes, type scale, and rounded values from the YAML block. No more "use our brand colors" hand-waving.

WCAG linting catches real issues. The contrast checker flagged a button variant in our internal design system that had been failing AA for nine months. The token reference graph also caught a typo in a component variant where {colors.primaryHover} should have been {colors.primary.hover}. Both bugs would have shipped without the linter.

It coexists with AGENTS.md. Many teams already use AGENTS.md for project instructions, the same way you use a README for humans. DESIGN.md is orthogonal: AGENTS.md tells the agent how to run your tests; DESIGN.md tells the agent what your buttons should look like. Drop both in the repo root and modern agents read both.

Export to DTCG is the escape hatch. If Google deprecates the spec next year, design.md export dtcg gives you a W3C-standard token file that every other tool in the ecosystem can read. You are not locked in. That is rare for an alpha-stage format from a single vendor.

---

What is rough

This is alpha software. The README is direct about it: "The DESIGN.md format is at version alpha. The spec, token schema, and CLI are under active development. Expect changes to the format as it matures."

Specific rough edges:

• The components schema is the weakest part. Defining variants like button-primary-hover works for simple components, but anything with compound state (size + variant + disabled + loading) gets verbose fast. The spec acknowledges this is an active area.
• There is no official Figma plugin. If your designers live in Figma and your engineers want DESIGN.md, somebody has to bridge the gap manually today. This is the single biggest adoption blocker for design-led teams. Watch the Awesome DESIGN.md repo, which is collecting community plugins and bridges (more on that below).
• Tooling ecosystem is thin. Tokens Studio and Style Dictionary have been around long enough to have IDE integrations, CI presets, and documentation generators. DESIGN.md has a linter and three exporters. That gap will close, but it is real right now.
• Designer pushback is a thing. A widely-shared r/UXDesign thread argued that DESIGN.md "just reveals how much designers are out of touch" with how AI is consuming their work. The sentiment is real, and if your design team has not been part of the conversation about agent-generated UI, expect friction before adoption.

---

How DESIGN.md compares

DESIGN.md vs AGENTS.md

These are siblings, not competitors. AGENTS.md tells agents how to work on the project: setup commands, test commands, code style. DESIGN.md tells agents what the project should look like: tokens, components, brand rationale.

Adopt both. They live in the repo root next to your README. Modern agents read whichever ones exist.

DESIGN.md vs Tokens Studio

Tokens Studio is a Figma plugin that lets designers define and sync tokens directly inside Figma. DESIGN.md is a Markdown file that lives in your repo.

Different audiences. Tokens Studio is Figma-native and aimed at designers who own the source of truth. DESIGN.md is repo-native and aimed at engineers who want agents to understand the system. Many teams will run both: Tokens Studio for design, with a build step exporting to DESIGN.md or DTCG for engineering and AI.

DESIGN.md vs Style Dictionary

Style Dictionary is Amazon's token transformation pipeline. It takes tokens in (usually JSON or YAML) and emits them as platform-specific code (iOS Swift, Android XML, Web CSS, etc.).

DESIGN.md and Style Dictionary actually pair well. DESIGN.md is the source of truth for tokens plus rationale. Style Dictionary is the build step that fans them out to every platform. With design.md export dtcg, you can feed DESIGN.md into a Style Dictionary pipeline today.

DESIGN.md vs a plain CLAUDE.md or .cursorrules block

Some teams stuff their design system into a section of CLAUDE.md or .cursorrules. This works until it does not. The moment you have token references, variants, or contrast requirements, you want the structure DESIGN.md gives you. Plain prose-in-CLAUDE.md cannot be linted, cannot be exported, and cannot be parsed by tools other than the single agent that owns the file.

---

The Awesome DESIGN.md signal

Worth flagging because the SERP keeps pointing at it. Awesome DESIGN.md is a community-curated repo collecting brand design systems already expressed as DESIGN.md files: Apple, Notion, Stripe, Uber, Airbnb, and dozens more. It crossed 39,000 GitHub stars in its first ten days of existence per the LinkedIn coverage, and 71,000+ by early May per recent MindStudio reporting.

That kind of velocity is not normal for a community-curated repo, and it tells you the adoption curve for DESIGN.md is steeper than the alpha-status label suggests. The format is moving faster than the spec.

For practitioners, the practical benefit of Awesome DESIGN.md is reverse-engineering. If you want to see how Stripe or Linear-style systems look in this format before writing your own, start there.

---

Who should adopt DESIGN.md now

Best for

• AI-first dev teams shipping a single product where the engineers also own the design system. Lowest friction, highest payoff.
• Indie hackers and solo founders who are already vibe coding with Claude Code, Cursor, or Bolt.new. You are already living in your repo. Drop a DESIGN.md next to your AGENTS.md.
• Open-source projects that want contributors and AI agents to produce visually consistent UI without an internal design system handbook.
• Teams using Google Stitch for prototyping. DESIGN.md is the native handoff format.

Not ideal for

• Multi-brand design orgs with mature Tokens Studio + Figma variable workflows. Wait for the format to leave alpha or for an official Figma plugin.
• Pure-design teams without engineering counterparts. DESIGN.md lives in a git repo. If your design team does not work in repos, this is not the format for you yet.
• Anything regulated. Alpha specs and compliance audits do not mix. Use it on internal tooling, not on flows that touch HIPAA, PCI, or financial regulators.

---

Getting started in five minutes

1. Read the spec once. npx @google/design.md spec prints the full specification. Five minutes of reading saves an hour of YAML guessing later.
2. Grab a starter file. Two options. Clone Awesome DESIGN.md and copy a brand whose system is close to yours, or generate one inside Google Stitch directly. The Google Labs launch announcement confirms Stitch can produce DESIGN.md files for any project, not just Stitch-built ones.
3. Drop the file in your repo root. Name it exactly DESIGN.md. Modern agents look for the literal filename.
4. Run the linter. npx @google/design.md lint flags broken token references and WCAG contrast failures before your agent generates anything.
5. Ask your agent to build something. Try a CTA section, a settings page, or a pricing card. Compare the output to what the same agent produced before you added the file. The difference is the value.

---

Tips for vibe coders

• Pair DESIGN.md with AGENTS.md. Project instructions in AGENTS.md, design system in DESIGN.md. Both files in your repo root. Agents read both.
• Use the prose section to encode your taste. Tokens cover the what. Prose covers the when. "Use the secondary color sparingly, only for confirmation states" is the kind of instruction tokens cannot express but prose can.
• Run design.md export dtcg in CI. Even if you do not need DTCG today, generating it in CI gives you a portable token file you can drop into Storybook, Style Dictionary, or any future tool that emerges.
• Treat the alpha label seriously. Pin your CLI version. npm install --save-dev @google/design.md@0.1.1. Upgrade deliberately when the spec moves.
• Watch Google Stitch for the visual side. Stitch generates UI, DESIGN.md captures the system. They are designed to work together.

---

FAQ

What is DESIGN.md? DESIGN.md is a format specification from Google Labs for describing a visual identity to coding agents. It combines machine-readable YAML tokens with human-readable Markdown rationale in a single file that lives in your repo.

Is DESIGN.md free? Yes. The spec is Apache 2.0 licensed. The @google/design.md CLI on npm is free. There is no paid tier.

Which agents read DESIGN.md? Any agent that reads repo files. Claude Code, Cursor, Google Stitch, Gemini CLI, v0, and any other agent that scans your repo will pick up the file. The format is intentionally agent-agnostic.

How does DESIGN.md compare to Tokens Studio or Style Dictionary? DESIGN.md is agent-native and Markdown-based. Tokens Studio is Figma-native for designers. Style Dictionary is a token transformation pipeline. They solve adjacent problems and can coexist. Many teams will run a combination.

Is DESIGN.md production-ready? Not yet. The README states the format is at version alpha and the spec, token schema, and CLI are under active development. Expect breaking changes. Pin your CLI version.

Does DESIGN.md replace my design system? No. It is a format for describing your design system to agents. The system itself, the decisions about color, type, and spacing, still happens wherever it always happened, whether that is Figma, a docs site, or your team's heads.

---

Verdict

DESIGN.md is the first design system format that was actually built for the way agents work, instead of being adapted from a designer-first tool. The YAML-plus-prose structure is the idea worth stealing even if you never adopt the spec itself. The CLI is genuinely useful, especially the WCAG linter. The DTCG export gives you an escape hatch if Google ever loses interest.

The alpha label is real and the components schema needs work. If you are a multi-brand design org with mature tooling, wait two quarters. If you are an indie hacker, a small AI-first team, or anybody whose agents are already generating UI that looks slightly off, adopt it this week. The cost is one Markdown file and the payoff is your agents finally understanding your brand.

For AI-first dev teams and vibe coders, DESIGN.md earns a strong recommendation in the Vibe Coding directory.

Rating: 8/10

---

Disclosure: This review reflects our honest assessment based on testing with Claude Code and Cursor across three repositories. See the full DESIGN.md tool page for feature details and links.