Docs

What is DESIGN.md?

DESIGN.md is a plain-text file that describes a design system for AI agents. YAML front matter at the top holds the exact design tokens: colors, typography, spacing, rounded corners and components. The markdown body below explains how and why to apply them. Humans and agents can both read it, edit it and enforce it.

README.md explains what a project is. AGENTS.md tells coding agents how to build it. DESIGN.md tells them how it should look and feel, so the screens an agent generates share one palette, type scale and component language instead of drifting apart.

Where DESIGN.md comes from

Google introduced DESIGN.md with Google Stitch, its AI design tool, as the design counterpart to AGENTS.md. Google Labs publishes the format as an open specification in the google-labs-code/design.md repository under the Apache 2.0 license. The DESIGN.md specification is labeled alpha, so expect the format to change as it matures.

The same repository ships an npm package, @google/design.md, with a lint command that checks structure, broken token references and WCAG contrast, and a diff command that compares two versions of a file token by token.

Anatomy of a DESIGN.md file

Every DESIGN.md file has two layers. The YAML front matter contains machine-readable design tokens such as exact color values, font properties, spacing scales and component token references. The markdown body provides the human-readable design rationale.

The spec treats the tokens as the normative values and the prose as context for applying them. Tokens give agents precise values. Prose tells them why those values exist and how to use them consistently across screens.

---
name: DevFocus Dark
colors:
  primary: "#2665fd"
  secondary: "#475569"
  surface: "#0b1326"
  on-surface: "#dae2fd"
  error: "#ffb4ab"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
rounded:
  md: 8px
---

# Design System

## Overview
A focused, minimal dark interface for a developer productivity tool.
Clean lines, low visual noise, high information density.

## Colors
- **Primary** (#2665fd): CTAs, active states, key interactive elements
- **Secondary** (#475569): Supporting UI, chips, secondary actions
- **Surface** (#0b1326): Page backgrounds
- **On-surface** (#dae2fd): Primary text on dark backgrounds
- **Error** (#ffb4ab): Validation errors, destructive actions

## Typography
- **Headlines**: Inter, semi-bold
- **Body**: Inter, regular, 14-16px
- **Labels**: Inter, medium, 12px, uppercase for section headers

## Components
- **Buttons**: Rounded (8px), primary uses brand blue fill
- **Inputs**: 1px border, subtle surface-variant background
- **Cards**: No elevation, relies on border and background contrast

## Do's and Don'ts
- Do use the primary color sparingly, only for the most important action
- Don't mix rounded and sharp corners in the same view
- Do maintain 4:1 contrast ratio for all text

The eight canonical sections

The markdown body uses ## headings. Sections can be omitted when they are not relevant, but when present they should follow this order. A heading that appears twice makes the file invalid; unknown sections are kept.

Overview (also Brand & Style). The look and feel in a few sentences: mood, density, personality.
Colors. Each color token and the role it plays, such as primary actions or page surfaces.
Typography. Font families and the type scale, from display headlines to small labels.
Layout (also Layout & Spacing). The spacing scale, grid, content widths and gutters.
Elevation & Depth (also Elevation). How surfaces separate: shadows, borders, tints.
Shapes. Corner radii and other shape rules.
Components. Buttons, inputs, cards and other atoms, with their tokens and states.
Do's and Don'ts. The rules an agent should not break.

A compact markdown body with each canonical section in order. Adjust the content to your product, keep the headings and sequence.

## Overview
A minimal dark interface for a developer productivity tool.
Clean lines, low visual noise, high information density.

## Colors
- Primary (#2665fd): CTAs and active states
- Surface (#0b1326): Page backgrounds
- On-surface (#dae2fd): Text on dark backgrounds

## Typography
- Headlines: Inter, semibold
- Body: Inter, regular, 14-16px
- Labels: Inter, medium, 12px, uppercase

## Layout
- 8px base spacing unit, scale: 4 / 8 / 16 / 24 / 32 / 48
- Max content width 720px with 24px gutters on mobile

## Elevation & Depth
- Surfaces rely on background contrast instead of shadow
- Overlays use an 8 percent white tint on dark surfaces

## Shapes
- Rounded 8px for controls, 16px for cards
- Avoid mixing sharp and rounded corners in one view

## Components
- Buttons: 8px rounded, primary filled with brand blue
- Inputs: 1px border, subtle surface-variant background
- Cards: no elevation, rely on border and background contrast

## Do's and Don'ts
- Do use the primary color sparingly, for the most important action
- Don't mix rounded and sharp corners in one view
- Do maintain at least a 4:1 contrast ratio for all text

Design tokens and schema

DESIGN.md embeds design tokens as YAML front matter at the beginning of the file. The front matter block begins with a line containing exactly --- and ends with the same delimiter.

version: <string>
name: <string>
description: <string>
colors:
  <token-name>: <Color>
typography:
  <token-name>: <Typography>
rounded:
  <scale-level>: <Dimension>
spacing:
  <scale-level>: <Dimension | number>
components:
  <component-name>:
    <token-name>: <string | token reference>

Common scale names include xs, sm, md, lg, xl and full, but any descriptive key is valid. Spacing tokens live in the YAML under spacing: and are described in the markdown body's Layout section.

Token types

Color: Any valid CSS color string. Hex in #RRGGBB form is the recommended default, for example "#1A1C1E".
Dimension: Number plus a px, em or rem unit. Examples:48px,-0.02em.
Token Reference: Wrapped in curly braces and pointing to a value in the YAML tree. Example:{colors.primary}.
Typography: A composite object containing font properties such as family, size, weight, line height and letter spacing. See Typography properties.

Typography properties

fontFamily: The font family name.
fontSize: The font size as a dimension.
fontWeight: Numeric weight such as 400 or 700.
lineHeight: A dimension or a unitless multiplier. Unitless values are recommended.
letterSpacing: Letter spacing adjustment as a dimension.
fontFeature: Configures font-feature-settings.
fontVariation: Configures font-variation-settings.

Token references

A token reference is wrapped in curly braces and contains an object path to another value in the YAML tree. For most token groups, the reference should point to a primitive value instead of a group. Within the components section, references to composite values such as typography levels are allowed.

components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
    rounded: "{rounded.md}"
  button-primary-hover:
    backgroundColor: "{colors.primary-70}"

Components

The components section captures style guidance for component atoms such as buttons, chips, lists, inputs, checkboxes, radio buttons and tooltips. Design systems can define additional components that matter to their product domain.

Variants for hover, active or pressed states are defined as separate component entries with related key names, such as button-primary-hover.

backgroundColor: Color
textColor: Color
typography: Typography
rounded: Dimension
padding: Dimension
size: Dimension
height: Dimension
width: Dimension

Recommended token names

These names are guidance, not requirements. They provide useful defaults for consistency across systems.

Colors: primary, secondary, tertiary, neutral, surface, on-surface, error

Typography: headline-display, headline-lg, headline-md, body-lg, body-md, body-sm, label-lg, label-md, label-sm

Rounded: none, sm, md, lg, xl, full

How AI agents use DESIGN.md

Put DESIGN.md in the root of your repository, next to README.md and AGENTS.md. Any agent with file access can read it, but most do not load it on their own. Point to it from the instructions your agent already reads, or name it in the prompt when you ask for UI work. A short pointer is enough:

## Design
Follow DESIGN.md for every UI change: use its color, typography,
spacing and component tokens instead of inventing new values.

Claude Code: Reads files in your repo and loads CLAUDE.md on start. Add a line there that points to DESIGN.md, or mention the file in your prompt.
Cursor: Add DESIGN.md to the chat context, or reference it from a project rule so it applies to every UI request.
GitHub Copilot: Point to DESIGN.md from your repository's Copilot instructions file, or attach it in chat when you ask for UI work.
Google Stitch: Where the format started. Stitch uses a DESIGN.md so that generated screens share one palette, type scale and component language.

The agent then takes exact values from the tokens (the hex for a primary button, the size of a body-md label) and uses the prose to decide where they belong.

DESIGN.md vs AGENTS.md vs README.md

The three files sit side by side and answer different questions. DESIGN.md does not replace AGENTS.md; the two work together.

File	Written for	Answers
`README.md`	People who use or contribute to the project	What is this, and how do I run it?
`AGENTS.md`	Coding agents	How do I build, test and change this code?
`DESIGN.md`	Coding and design agents	How should the interface look and feel?

Real DESIGN.md examples

The fastest way to understand the format is to read a few real files. Each of these gallery pages shows a DESIGN.md extracted from the brand's public website, with its palette and type specimen. They are not official brand guidelines.

Browse all DESIGN.md examples

How to get a DESIGN.md

Write it by hand. Start from the spec and the examples above, then check the file with the free DESIGN.md Validator or Google's lint command.
Start from an example. Copy a file from the gallery and edit the tokens and prose to match your product.
Generate it from a live website. Paste a public URL into Design Extractor. It renders the site in a browser and returns a DESIGN.md with its colors, typography, spacing and components that follows the spec above. The DESIGN.md generator page explains what you get. The same extraction runs from the Chrome extension and from your agent through the MCP server.

FAQ

DESIGN.md questions

Short answers about the DESIGN.md format, where it comes from, and how to use it with AI agents.

A DESIGN.md is a plain-text file that describes a design system for AI agents. YAML front matter at the top holds the exact tokens (colors, typography, spacing, rounded corners and components), and the markdown body below explains how and why to apply them. Agents read the tokens for values and the prose for intent.

Google introduced DESIGN.md with Stitch, its AI design tool. Google Labs publishes the specification on GitHub (google-labs-code/design.md) under the Apache 2.0 license. The format is labeled alpha, so expect changes as it matures.

AGENTS.md tells coding agents how to build and work on a project: commands, conventions, tests. DESIGN.md tells them how the product should look and feel: colors, type, spacing, shapes and components. README.md is for the humans who use or contribute to the project. Many repos keep all three side by side.

Put it in the repository root, next to README.md and AGENTS.md, so agents with file access can find it. Then point to it from the instructions your agent already loads, such as AGENTS.md, CLAUDE.md, a Cursor rule or your Copilot instructions, or mention it in the prompt when you ask for UI work.

No. The spec lets you leave out sections that do not apply, but the ones you keep should follow the canonical order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts. A section heading must not appear twice, and unknown sections are kept rather than rejected.

Google's npm package @google/design.md has a lint command that checks structure, broken token references and WCAG contrast. Design Extractor also has a free DESIGN.md Validator that checks the structure and tokens in your browser and previews the file, without uploading it.

Write it by hand from the spec, copy one from a gallery of real examples as a starting point, or generate one from the live site. Design Extractor takes a public URL, renders the site in a browser, and returns a DESIGN.md with its colors, typography, spacing and components, ready to drop into your repo.

Want one for a site you like?

Paste a public URL and get its DESIGN.md.

Extract a site

Token types

Typography properties

Token references

Components

Recommended token names

DESIGN.md questions

What is a DESIGN.md file?

Who created the DESIGN.md format?

What is the difference between DESIGN.md and AGENTS.md?

Where do I put DESIGN.md in my project?

Do I need all eight sections?

How do I check that a DESIGN.md is valid?

How do I get a DESIGN.md for an existing website?