DESIGN.md is an open-source format specification from Google Labs that describes a visual identity to AI coding agents. It combines machine-readable YAML design tokens (colors, typography, spacing) with human-readable markdown explaining the design rationale.

How does DESIGN.md work?

A DESIGN.md file has two layers: YAML front matter with exact design token values (colors, fonts, spacing, component styles) and markdown prose sections explaining why those values exist and how to apply them. Agents read the tokens; humans read the prose.

What tools does DESIGN.md include?

The @google/design.md npm package includes a linter that validates tokens, checks WCAG contrast ratios, and outputs structured JSON — plus a diff tool that compares two versions of a design system to detect regressions.

Can DESIGN.md be used outside Google Stitch?

Yes. Google open-sourced the specification specifically so it can be used across any tool or platform. Any AI agent or code generator that reads the file can produce UI consistent with the defined design system.

How is DESIGN.md different from design tokens?

DESIGN.md includes standard design tokens but adds structured prose sections explaining design rationale, component behavior, and do's/don'ts — giving agents not just the values but the reasoning behind them.

Google's DESIGN.md: A Spec File That Tells AI Agents How Your Brand Looks

By Prahlad Menon Published 2026-04-23 3 min read

Every AI coding agent has the same problem with design: it guesses. You ask it to build a landing page and it picks some blue, slaps on Inter, and hopes for the best. If you want your blue, your typography, your spacing — you have to describe it in every prompt, every time.

Google’s answer is a file called DESIGN.md.

What It Is

DESIGN.md is a format specification that gives AI agents a persistent, structured understanding of a design system. One file, two layers:

YAML front matter — machine-readable design tokens:

---
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
---

Markdown body — human-readable design rationale:

## Colors

- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.
- **Neutral (#F7F5F2):** Warm limestone foundation, softer than pure white.

An agent reading this file doesn’t just know the hex values — it knows that #B8422E is called “Boston Clay” and it’s the only color used for interactive elements. That’s the difference between generating a technically correct UI and generating one that feels intentional.

Why This Matters

The insight is that design systems have two kinds of information, and AI agents need both:

Tokens — exact values that can be programmatically applied (colors, font sizes, border radii). These are the “what.”
Rationale — why those values exist and how they relate to each other. These are the “why.”

Existing design token formats (Style Dictionary, Figma tokens) handle the first part well. DESIGN.md handles both in a single file that lives in your repo alongside your code.

This means a coding agent that generates a React component, a marketing page, or a dashboard can read DESIGN.md from the project root and produce output that’s consistent with the brand — without any design instructions in the prompt.

The Tooling

Google ships an npm package with two commands that make DESIGN.md operational:

Lint — validates tokens, catches broken references, checks WCAG contrast:

npx @google/design.md lint DESIGN.md

{
  "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 }
}

Diff — compares two versions, detects token-level regressions:

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

The output is structured JSON that agents can act on. If a design change breaks accessibility, the linter catches it before the code ships.

Components and Token References

The spec supports component-level tokens that reference the base design tokens:

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

This is where it gets powerful. An agent generating a button doesn’t pick a color — it resolves {colors.tertiary} to Boston Clay. Change the tertiary color in one place, and every component updates.

The Bigger Pattern: .md Files as Agent Config

DESIGN.md fits a pattern we’re seeing across the AI agent ecosystem. Just as AGENTS.md tells coding agents how to behave in a repository, DESIGN.md tells them how things should look. These aren’t configuration files in the traditional sense — they’re context files that bridge machine precision with human intent.

The format choice is deliberate: markdown with YAML front matter. It’s readable by humans in any text editor, parseable by machines, version-controllable in Git, and doesn’t require any special tooling to create. You can write a DESIGN.md in five minutes and immediately improve every AI-generated UI in your project.

Try It

Generate a DESIGN.md from an existing design in Stitch, or create one manually and validate it:

npx @google/design.md lint DESIGN.md

The specification and source code are on GitHub. It’s early (version: alpha), but the idea is sound: give agents a persistent understanding of visual identity, and they stop guessing.