design.md: If Your AI-Generated UI Keeps Drifting, You're Missing Google's design.md

Have you ever done some Vibe Coding and noticed the AI's layout is always a little off? You keep saying "the spacing is wrong here, the colour is inconsistent there", and it still produces a slightly broken screen? If yes, the real reason is that you haven't given the AI the rules of your design system properly.

To fix exactly that, this post walks through design.md, an AI design system spec released by Google Labs. The goal is to let AI Coding tools like Claude Code, Cursor, and GitHub Copilot actually read your design system and produce consistent UI — so you don't have to keep repeating "wrong colour, wrong font size" forever.

If you're not familiar yet with rules files for AI like CLAUDE.md / AGENTS.md, take a look at CLAUDE.md and Rules for AI: Writing Tips That Make AI Understand Your Project and Agent Skills: More Token-Efficient Than MCP first — it'll make a lot more sense why design.md exists.

Where design.md came from

design.md actually comes out of Stitch, Google's AI design tool (first shown at Google I/O 2025). Stitch is a UI design tool powered by Gemini — you give it a Prompt or upload a sketch and it generates a UI screen, frontend code included.

Around 2026, Google released the design.md format itself under Apache 2.0 on GitHub (google-labs-code/design.md). What does that mean in practice? They're trying to "standardise" Stitch's design system rules.

The most common pain point for Vibe Coding developers is inconsistent UI and inconsistent style. But if you open-source this design spec, the business value gets pretty huge — whether you use Claude Code, Cursor, GitHub Copilot, or any other AI Coding tool, you can use this spec to produce consistent UI.

A few examples of what that gets Google:

• Becoming the standard means owning the definition. Think OpenAPI or Kubernetes — looked harmless at launch, but once everyone adopted them, the contributor with the loudest voice on where the spec goes was the one who shipped it.
• Other AI tools voluntarily become allies. Once Claude Code, Cursor, and Copilot start marketing "we support design.md", competitors are basically promoting Google's format for free.
• The training data flywheel. People will put their project's design.md in public repos. Structured design tokens plus human-written rationale is honestly the perfect combo for AI training data. Future Gemini gets stronger.
• Stitch's free marketing funnel. Once developers get used to design.md, when they need a "tool that speaks design.md", the first thing they think of is Stitch.

Big-company open source that looks like a loss is usually trading time for ecosystem. Chromium, Kubernetes, TensorFlow all played this game — on the surface it's a community contribution, in reality it's using "free" to lock in the standard early.

What problem is design.md actually solving?

Basically just this:

Making sure the UI that AI generates uses the same colours, font sizes, and corner radii every time.

Everyone Vibe Coding has hit this. You ask the AI to make a Button, and then:

• The first time it gives you #3B82F6
• The second time #2563EB
• The third time straight up bg-blue-500

The screen looks fine, all blue. But they're not actually the same blue, so your project ends up with a whole watercolour palette of "blues". Font sizes have the same issue — sometimes 1.25rem, sometimes 20px, sometimes text-xl.

This kind of inconsistency makes the UI feel disjointed, which makes the user experience inconsistent, which hurts the brand.

Why does this happen? The main reason is you haven't given the AI a "design system rules" document.

"Can't I just put it in CLAUDE.md?" — you can. But CLAUDE.md (and AGENTS.md) are "natural-language rules" for the AI. There's no structured palette or token system. After reading it, the AI still has to guess "which hex is Primary" or "which corner radius should this button use", and it ends up guessing anyway.

So design.md is basically turning that "design system rules" document into a file that machines can parse precisely + humans can understand the reasoning behind.

What does design.md actually look like?

Pretty simple — design.md is just a Markdown file. The structure splits into two parts:

• YAML Front Matter: the precise design tokens (colours, typography, spacing, corner radius, components).
• Markdown body: the design rationale — why this colour, when to use it, when not to use it.

By splitting the file this way, the AI doesn't just know "Primary is #1A1C1E" — it also knows "Primary is the deep ink used for headlines and core text". So when it produces UI, it's a lot less likely to use the wrong colour for a button or the wrong size for a piece of text.

YAML token block

The YAML block looks roughly like this:

---
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
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"
---

A few key points:

• colors, typography, rounded, spacing, components are the five main token categories.
• Tokens can reference each other — button-primary's backgroundColor is "{colors.tertiary}", so when you change tertiary later, everything using it updates automatically.
• Colours support any valid CSS colour string: hex, rgb, hsl, oklch — all good.

If you've used Tailwind's tailwind.config.js or the W3C Design Tokens Format Module (DTCG), this'll feel familiar.

Markdown body block

After the closing --- of the YAML, you get the design reasoning written for humans (and AI) to read.

Officially recommended section order:

• Overview
• Colors
• Typography
• Layout
• Elevation & Depth
• Shapes
• Components
• Do's and Don'ts

Only Colors (and the primary colour inside it) is required. The rest is optional — write them only if your design system has that piece.

A concrete example — the Colors block might look like this:

## Colors

Primary (#1A1C1E): Deep ink for headlines and core text.
Use on light surfaces to maximize legibility.

Tertiary (#B8422E): Warm rust accent reserved for primary actions
and brand moments. Avoid using as body text colour due to contrast.

That's basically telling the AI "this colour is called Tertiary, use it for primary action buttons, don't use it for body text".

Wait — there's a CLI?

Yep. design.md ships with a CLI that does four things: lint, diff, export, spec.

Install and use:

npm install @google/design.md
npx @google/design.md lint DESIGN.md

On Windows the .md extension can get eaten by file association, so use the designmd alias:

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

lint: validate the DESIGN.md structure

Same vibe as ESLint, Stylelint, Prettier. lint checks:

• Whether the YAML schema is correct
• Whether token references are broken (e.g. {colors.tertiery}, missing an a?!)
• Whether there's a primary colour
• Whether WCAG AA contrast passes (this one's the killer feature)
• Whether there are orphan tokens defined but never used
• Whether the section order matches the recommendation

For the WCAG AA rule, it tells you straight up "on-secondary against secondary only hits X.X:1 contrast, doesn't pass AA". Accessibility checks baked right into the design system file.

diff: compare two versions

Like git diff for design systems:

npx @google/design.md diff old/DESIGN.md new/DESIGN.md

Tells you which tokens changed, which were deleted, which were added. Use case: bump primary from #1A1C1E to #0A0A0A and want to know "how many components are about to change colour because of this".

export: convert to other formats

This one's genuinely impressive, especially if you want design.md as the "upstream" source.

Format	Description
json-tailwind	Converts to a Tailwind v3 config object
css-tailwind	Converts to a Tailwind v4 @theme CSS block
dtcg	Converts to the W3C Design Tokens Format Module

Usage:

npx @google/design.md export DESIGN.md --format json-tailwind > tailwind.config.js
npx @google/design.md export DESIGN.md --format css-tailwind > tailwind.css
npx @google/design.md export DESIGN.md --format dtcg > design-tokens.json

You only have to focus on design.md, then export to Tailwind / CSS / DTCG. Frontend, designers, and AI Coding tools all use the same source of truth.

spec: hand the spec to the AI

npx @google/design.md spec

Outputs design.md's own format spec. Hand that to Claude Code / Cursor / Copilot and tell it "please follow this spec when reading my DESIGN.md". The AI then knows how to parse the YAML schema, that token references use {path.to.token} syntax, what's required, what's optional. Add --rules and it'll output the linting rules as well.

Using it with AI Coding tools

The whole design goal is "turn the UI design system into something that can be continuously understood by AI", so the usage is simple:

1. Put DESIGN.md in your project root.
2. In CLAUDE.md / AGENTS.md / .cursor/rules/*.mdc, add a line: "For UI-related tasks, please read DESIGN.md first and strictly follow the tokens and design rationale inside."

That's it.

One reminder at the end, kind of an old chestnut:

Don't stuff design.md with irrelevant junk.

The whole design philosophy is to give the AI a distilled version of your design knowledge — same direction as Agent Skills. Give the AI the key points, not everything.

Right now, design.md doesn't ship with official integration examples for Claude Code / Cursor / Copilot — only the CLI and TypeScript API. So you need to guide the AI to read design.md via your CLAUDE.md / AGENTS.md / rules file.

Wrap-up

So what is design.md, really?

• A design system document for AI Coding tools, in a "YAML token + Markdown design rationale" format.
• The pain point it solves is AI-generated UI having inconsistent colours, font sizes, and spacing.
• The built-in CLI can lint (with WCAG contrast checks), diff, export to Tailwind / DTCG, and output a spec for the AI.

Hope this helps you fix the "AI generates UI with inconsistent colours, font sizes, and spacing" pain so your AI Coding workflow goes a lot more smoothly.