DEV Community

정상록
정상록

Posted on

DESIGN.md is now open source — Google's spec that makes Claude Code, Cursor, and Copilot ship the same brand

TL;DR

Google Labs open-sourced DESIGN.md on April 21, 2026 — a single-file contract that tells Claude Code, Cursor, GitHub Copilot, and Antigravity exactly which colors, typography, and component rules to use. Apache 2.0. Comes with a CLI (npx @google/design.md) for lint, diff, export (Tailwind / DTCG), and prompt injection. This post walks through what it is, how it works, and how to wire it into a Claude Code project in five minutes.

The problem

Every AI coding agent loses your brand the moment you open a new chat. You ask for a dashboard, you get Tailwind blue. You re-paste your brand guide into the prompt, you get a slightly different blue next time. The next component is a different beast altogether.

This is the every-time-from-zero problem, and it has cost me hours of "no, the primary is #B8422E, not blue, and yes I told you last time."

What Google shipped

On April 21, 2026, Cassia Xu (Google Labs) announced that the DESIGN.md spec — the format that powers Stitch internally — is now open source under Apache 2.0.

Item Detail
Spec DESIGN.md (alpha)
License Apache 2.0
Released 2026-04-21
Maintainer Google Labs
CLI npx @google/design.md
Companion Stitch MCP server, design-md Agent Skill

Three things matter: the spec itself is portable markdown, the CLI does real validation work (WCAG contrast, token resolution, regression diff), and it ships with MCP integration so any agentic IDE can read it.

DESIGN.md structure — two layers, nine sections

DESIGN.md is two layers:

  1. YAML frontmatter — machine-readable tokens
  2. Markdown body — human-readable rationale

Tokens alone tell the AI what value to use; rationale alone tells it why. Together, you get a contract.

Frontmatter example 

---
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
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
---
Enter fullscreen mode Exit fullscreen mode

Nine standard sections

  1. Visual Theme & Atmosphere
  2. Color Palette & Roles
  3. Typography Rules
  4. Component Stylings
  5. Layout Principles
  6. Depth & Elevation
  7. Do's and Don'ts
  8. Responsive Behavior
  9. Agent Prompt Guide ← the new one

Section 9 is the novel part. Traditional design systems were written for humans. DESIGN.md assumes the reader is an AI agent from the first line.

Tokens as semantic roles

The hex #B8422E means nothing on its own. But:

Boston Clay — the sole interaction driver

Now the agent knows: this color is reserved for clickable, interactable elements. That's the difference between a variable and a contract.

The CLI — four commands you'll actually use 

# 1. LINT — schema + WCAG validation
npx @google/design.md lint DESIGN.md

# 2. DIFF — regression detection in CI
npx @google/design.md diff DESIGN.md DESIGN.next.md

# 3. EXPORT — convert to Tailwind or W3C DTCG
npx @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json
npx @google/design.md export --format dtcg DESIGN.md > tokens.json

# 4. SPEC — inject the spec itself into agent prompts
npx @google/design.md spec --rules-only --format json
Enter fullscreen mode Exit fullscreen mode

Lint output looks like:

✓ Schema valid
✓ All token references resolved
⚠ Warning: textColor (#888) on backgroundColor (#FFF) has contrast 3.54:1 — fails WCAG AA
Result: 1 warning, 0 errors
Enter fullscreen mode Exit fullscreen mode

Free WCAG audit, built in. The diff command exits with code 1 if the new file has more errors than the old, so CI catches design drift automatically.

Wiring it into Claude Code (5 minutes)

Step 1: Get a DESIGN.md

Fastest path is the community catalog at VoltAgent/awesome-design-md, which has 69+ real-world templates including Stripe, Vercel, Linear, Cursor, Spotify, Apple. Clone it, copy the closest brand, swap your colors:

git clone https://github.com/VoltAgent/awesome-design-md.git /tmp/adm
cp /tmp/adm/stripe/DESIGN.md ./DESIGN.md
# Edit colors, typography, spacing for your brand
Enter fullscreen mode Exit fullscreen mode

Step 2: Add the rule to CLAUDE.md 

## Design System

Always read DESIGN.md at project root before generating any UI.
Reference colors by semantic role, not raw hex.
Use spacing scale tokens only (xs, sm, md, lg, xl).
Run `npx @google/design.md lint DESIGN.md` after UI changes.
Enter fullscreen mode Exit fullscreen mode

For Cursor, the same pattern goes into .cursorrules.

Step 3: Lint 

npx @google/design.md lint DESIGN.md
Enter fullscreen mode Exit fullscreen mode

Fix any warnings. Done.

Step 4: Test

Open a new Claude Code session, ask for a dashboard. Watch it use your brand on the first try.

Tailwind integration

If you're on Tailwind, this is one command:

npx @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json
Enter fullscreen mode Exit fullscreen mode 
// tailwind.config.js
const theme = require('./tailwind.theme.json')

module.exports = {
  theme: { extend: theme }
}
Enter fullscreen mode Exit fullscreen mode

Now bg-primary, text-accent, rounded-md map 1:1 to DESIGN.md tokens.

CI integration

.github/workflows/design-lint.yml:

name: DESIGN.md Lint
on:
  pull_request:
    paths: ['DESIGN.md', '**/*.tsx', '**/*.css']

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - name: Lint
        run: npx @google/design.md lint DESIGN.md
      - name: Diff vs main
        run: |
          git show origin/main:DESIGN.md > /tmp/DESIGN.main.md
          npx @google/design.md diff /tmp/DESIGN.main.md DESIGN.md
Enter fullscreen mode Exit fullscreen mode

PRs that introduce new lint errors fail CI. Drift caught before merge.

Where it falls short

Three things to be honest about:

  1. Governance is single-vendor. Apache 2.0 is permissive, but Google Labs is the sole maintainer. No W3C-style independent committee yet. For now, you're betting on Google's stewardship.
  2. Team workflows are weak. Figma's permissions, comments, branching, shared resources — DESIGN.md delegates all of this to Git. Git is great for engineers and weak for designers. A 20-person UX team is not going to drop Figma for this.
  3. Compliance is probabilistic. Gemini reads DESIGN.md as natural-language context. It's guidance, not enforcement. If you need pixel-perfect output, you still need explicit checks.

Adoption signals

awesome-design-md grew from a small list to 69+ brand templates within days of the announcement. The catalog includes Stripe, Vercel, Linear, Cursor, Raycast, Anthropic (Claude), Cohere, ElevenLabs, MongoDB, Supabase, Sentry, Shopify, Airbnb, Tesla, Spotify, Apple, The Verge, WIRED, Notion. Each folder ships a preview.html and preview-dark.html so you can eyeball the look before committing.

This kind of curation usually takes months. The fact that it happened in a week tells me the format hits a real pain point.

Why I'm betting on it

I built an awesome-design-md skill into my agent stack months before this announcement, with 58 brand templates. It worked, but it was niche — basically a private convention. With Google's release, the format graduates from convention to candidate-standard. The CLI gives me free WCAG audits. The --format tailwind export collapses two steps into one. The MCP server makes integration native instead of bolted-on.

If you're building anything with AI coding agents and you care about visual consistency, the cost of trying this is one file and one CLAUDE.md edit. Five minutes. Worth it.

Reading list

If you've already wired DESIGN.md into your stack, I'd love to hear what worked and what didn't — drop a comment.

Top comments (0)