DESIGN.md: Google's Spec for AI-Agent Design Systems

Originally published on andrew.ooo — visit the original for any updates, code snippets that aged out, or follow-up posts.

TL;DR

DESIGN.md is a format specification from Google Labs that lets you describe your visual identity in a single markdown file that AI coding agents can actually read and follow. It combines YAML front matter (machine-readable design tokens) with markdown prose (human-readable rationale) — so agents get exact color values and the context for why those values exist. It hit 23,000+ GitHub stars in its first week and is now the #1 most-starred new Google Labs open-source project on GitHub Trending this week.

Key facts:

• Dual-layer format: YAML tokens for agents, markdown prose for humans — same file
• Built-in CLI tools: lint (WCAG contrast checking, broken reference detection), diff (token-level regression detection), export (Tailwind v3/v4, DTCG/W3C Design Tokens)
• Token references: Components reference design tokens with {colors.primary} syntax — change one value, update everywhere
• 9 lint rules: broken-ref, contrast-ratio, orphaned-tokens, section-order, unknown-key detection, and more
• Already ecosystem-ready: Used by Google's Stitch MCP server, available as npx @google/design.md, exportable to Tailwind themes
• Zero dependencies: Just a markdown file and npx — no build step, no config file, no SDK
• 23,000+ GitHub stars, 6,700+ new stars this week

Quick Reference

What It Is

DESIGN.md is deceptively simple: a single markdown file with YAML front matter that defines colors, typography, spacing, rounded corners, and component tokens, followed by prose sections that explain why the design system works the way it does.

---
name: Heritage
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
  label-caps:
    fontFamily: Space Grotesk
    fontSize: 0.75rem
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
---

This isn't just another design spec format. What makes DESIGN.md different is that it's built for dual consumption — both humans and AI agents read the same file. The YAML front matter is the machine contract: agents parse it and get exact hex values, font stacks, spacing scales. The markdown body is the human contract: designers explain why "Boston Clay" (#B8422E) is the sole interaction color, and agents use that context to make better judgment calls.

The format is versioned (currently alpha) and published at docs/spec.md. It supports 8 named sections: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, and Do's and Don'ts.

Why It's Trending NOW

Three forces converged to make DESIGN.md explode this week.

First, the AI coding agent boom. Every major coding assistant — Claude Code, Codex CLI, Gemini CLI, Cursor, Zed, OpenClaw — now supports MCP (Model Context Protocol) and custom instruction files. Developers are rushing to give their agents context about codebases. DESIGN.md is the missing piece for visual context: it tells agents what the UI should look like.

Second, the design-system industry is converging on a standard. Meta just launched Astryx, an open-source React design system with an MCP server that lets agents browse 150+ components. Google Stitch, Google's agentic design workflow platform, already has a stitch-design plugin with a generate-design skill that outputs DESIGN.md files. The industry is realizing that for AI agents to produce decent UIs, they need structured access to design tokens — not screenshots, not Figma links, not prose descriptions.

Third, the timing is perfect for a "README.md for design." Every developer knows what README.md is. Every developer has been frustrated by AI agents generating UIs with random colors, mismatched typography, and broken spacing. DESIGN.md slots into the same mental model as README.md — a file you drop into your repo that agents read automatically. The parallel is so obvious it's surprising nobody standardized it before.

"DESIGN.md is to agentic UI development what README.md was to open-source documentation — a single file that changes everything." — @davideast, maintainer

Key Features (with Code Examples)

1. Structured Design Tokens with Component References

The token system supports references — components can reference tokens with {token.path} syntax:

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.tertiary-container}"

This means changing colors.tertiary from "#B8422E" to "#C94F3F" propagates to every component that references it. No more hunting through code for hard-coded hex values.

2. CLI Linter (WCAG Contrast Checking Built In)

The lint command validates your DESIGN.md against 9 rules:

npx @google/design.md lint DESIGN.md

Output:

{
  "findings": [
    {
      "severity": "warning",
      "path": "components.button-primary",
      "message": "textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA."
    }
  ],
  "summary": { "errors": 0, "warnings": 1, "info": 1 }
}

The contrast-ratio rule checks every component's backgroundColor/textColor pair against WCAG AA minimum (4.5:1). This catches accessibility bugs before any code is written.

3. Token-Level Diff (Regression Detection)

Compare two versions of a design system to detect token drift:

npx @google/design.md diff DESIGN.md DESIGN-v2.md

{
  "tokens": {
    "colors": { "added": ["accent"], "removed": [], "modified": ["tertiary"] },
    "typography": { "added": [], "removed": [], "modified": [] }
  },
  "regression": false
}

This is huge for design system maintainers. You can CI-check a PR that changes DESIGN.md and reject it if it introduces regressions like removing a token that components still reference.

4. Export to Tailwind (v3 and v4)

Probably the most immediately useful feature for most developers:

# Tailwind v3 config
npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json

# Tailwind v4 @theme block
npx @google/design.md export --format css-tailwind DESIGN.md > theme.css

This generates a complete theme.extend config (v3) or @theme { ... } block (v4) with every color, font, spacing, and radius token mapped to the correct Tailwind namespace. No manual token mapping, no copy-paste errors.

5. DTCG (W3C Standard) Export

npx @google/design.md export --format dtcg DESIGN.md > tokens.json

The W3C Design Tokens Format Module is the emerging standard for cross-tool token exchange. DESIGN.md converts to it natively, so you can sync tokens between Figma plugins, design tooling, and your codebase.

Community Reactions

The launch generated significant discussion across developer platforms:

Reddit r/UXDesign:

"Even with MD files it's not one size fits all. I created a semi automated framework for one of my projects and I still have to tweak things here and there." — r/UXDesign

TechTimes:

"Version 0.3.0 shipped on June 15. Artiverse reported that Google's specification notes that tokens give agents exact values while prose tells them why those values exist and how to apply them." — TechTimes

SlideSpeak (DESIGN.md for presentations):

"DESIGN.md is a small format with a big idea. Google Labs publishes the spec: one markdown file that tells AI coding agents how to build on-brand interfaces." — SlideSpeak

The community's biggest open question is adoption: will this become the standard, or will every company invent their own? Early signs are positive — Google Stitch already generates DESIGN.md files natively, and the awesome-agent-skills repo lists it as a recommended skill.

Getting Started

Getting started takes about 30 seconds:

1. Install the CLI

npm install @google/design.md
# or run directly:
npx @google/design.md lint DESIGN.md

Windows note: PowerShell may confuse design.md with the Markdown file association. Use the designmd alias instead:

npx -p @google/design.md designmd lint DESIGN.md

2. Create a DESIGN.md

Start with the minimal structure:

---
name: My App
colors:
  primary: "#1A1C1E"
typography:
  body:
    fontFamily: Inter
    fontSize: 1rem
---

3. Validate It

npx @google/design.md lint DESIGN.md

4. Export to Your Framework

npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json

5. Drop It in Your Repo

Just like README.md, commit DESIGN.md to the root of your repository. AI coding agents that support MCP or custom instructions will automatically read it.

How It Works Under the Hood

DESIGN.md is parsed into a structured DesignSystemState object:

1. The YAML front matter is parsed with a custom schema validator that recognizes Color, Dimension, Typography, and TokenReference types
2. Token references ({colors.primary}) are resolved into a dependency graph — the linter detects broken references as errors
3. Component definitions are validated against a whitelist of allowed properties (backgroundColor, textColor, typography, rounded, padding, size, height, width)
4. The linter runs 9 rule checks in parallel, each producing findings at error, warning, or info severity
5. The export command traverses the resolved token graph and generates framework-specific output (Tailwind theme config, DTCG JSON)

The token system is inspired by the W3C Design Token Format, but DESIGN.md is deliberately simpler: no nested groups, no aliases, no $type declarations. It's designed to be writable by humans, not just machines.

The CLI is a single TypeScript package compiled to Node.js. It has zero runtime dependencies beyond Node 18+.

Who Should Use This

✅ You should use DESIGN.md if:

• You use AI coding agents (Claude Code, Cursor, Codex, Gemini CLI) and want consistent UI output
• You maintain a design system and want agents to follow it
• You're tired of AI agents hallucinating colors, fonts, and spacing
• You use Tailwind CSS and want to share tokens between your design system and your codebase
• You want WCAG accessibility checking as part of your design token workflow

❌ You should NOT use DESIGN.md if:

• You don't use AI coding agents at all
• You have a design system that's already expressed in Storybook + Figma tokens with auto-sync
• You need runtime token resolution (DESIGN.md is a build-time spec, not a runtime token engine)
• You're looking for a replacement for CSS variables or Tailwind configs (it maps to them, doesn't replace them)

DESIGN.md vs Meta Astryx

Both Google and Meta launched design-system + AI-agent integrations within days of each other — but they're solving different parts of the problem.

In practice, they're complementary. You could put Astryx components in your repo and write a DESIGN.md that tells agents how to use them together with your brand colors. Astryx's MCP server handles "what components exist," while DESIGN.md handles "what should the UI look like."

Honest Limitations

DESIGN.md is at version alpha, and it shows:

• The spec is still evolving. Expected changes as it matures — the alpha label means no backward compatibility guarantees yet.
• No runtime token resolution. DESIGN.md is a build-time format. If you need runtime token access (themed UIs, dynamic color switching), you'll still need a runtime token system alongside it.
• Adoption is early. The format is only useful if agents actually read it. Right now, it requires a custom instruction or skill to wire into Claude Code, Cursor, etc. Google Stitch supports it natively, but other agents need manual setup.
• No Figma plugin (yet). The ideal workflow would be "design in Figma → export DESIGN.md → agents build UI." That pipeline doesn't exist yet — you're writing DESIGN.md by hand.
• Limited color space validation. The linter checks WCAG contrast, but it doesn't validate that your color palette has enough variance, or that accessibility modes work — those still need human judgment.
• Component model is basic. Components can only reference 7 property types. There's no support for state machines, responsive variants, or animation tokens.

FAQ

How is DESIGN.md different from a Tailwind config?

A Tailwind config defines everything available to your CSS framework. DESIGN.md defines what your brand looks like. DESIGN.md exports to Tailwind config (so you get both), but it also includes prose rationale, accessibility data, and component token references that a Tailwind config can't express.

Can I use DESIGN.md without Google Stitch?

Absolutely. DESIGN.md is format-first — the CLI is just tooling. Drop the file in any repo, and any AI coding agent with custom instructions can read it. Stitch is one integration; the ecosystem is growing.

Does DESIGN.md replace Storybook?

No. Storybook documents what components look like interactively. DESIGN.md documents what tokens and rules govern your visual identity. They serve different purposes and work well together — DESIGN.md defines the tokens, Storybook shows the components built with them.

What happens if I change a token?

Change the YAML value and re-lint. The diff command will show exactly what changed. Any component referencing the old value via {token.path} syntax automatically inherits the new value. The linter will catch broken contracts (removing a token that's still referenced).

How do I get Claude Code or Cursor to read DESIGN.md?

Add a custom instruction pointing to the file. For Claude Code, add to your CLAUDE.md: "Read DESIGN.md at the project root for design system tokens and visual identity rules." For Cursor, add a .cursorrules entry. The awesome-agent-skills repo has ready-to-use skill files for common agents.

Can DESIGN.md define dark mode tokens?

Version alpha doesn't have a native dark-mode namespace, but you can use two DESIGN.md files (DESIGN.md + DESIGN.dark.md) or extend the format with section-level overrides. The spec is flexible enough to accommodate this within existing constraints.

DESIGN.md is one of those rare developer tools that feels inevitable in hindsight. Just as README.md became the universal convention for project documentation, DESIGN.md has the potential to become the universal convention for design system documentation — especially in an age where AI agents read more code than humans do. It's alpha software, it has rough edges, and adoption is early. But the direction is right, and 23,000 stars in a week suggests the community agrees.