Updated 3 November 2026

What is DESIGN.md?

DESIGN.md is an open, plain-text format, published by Google Labs, for describing a design system to AI coding agents. A DESIGN.md file pairs machine-readable design tokens (colours, typography, spacing, corner radii and component styles) in YAML front matter with Markdown prose that explains how to apply them. Agents read the file so the UI they write matches your product instead of their defaults.

Why DESIGN.md exists

Coding agents produce working UI, but not your UI. Without design context, an agent falls back on framework defaults: a stock blue, a generic grey, the template's font. An agent working in a repository needs the design system as text it can read and check against.

DESIGN.md fills that gap. The spec describes it as a self-contained representation of a design system that keeps stylistic choices consistent across sessions, agents and tools. As a single Markdown file, it lives in version control next to the code and any agent that can open a file can use it.

The DESIGN.md format

A DESIGN.md file has two layers: optional YAML front matter holding design tokens, then a Markdown body holding design rationale. In the spec's words, "The tokens are the normative values"; the prose explains when and why to use them. Prose can use descriptive names ("warm limestone") for token names (neutral).

Front matter: the design tokens

The front matter sits between two lines that each contain exactly ---. Its top-level keys are:

• version (optional; the current version is alpha)
• name and description (description is optional)
• colors: a map of token name to colour
• typography: a map of token name to a typography object
• rounded: corner radius scale
• spacing: spacing scale
• components: per-component style tokens
• omitted (optional): sections you have deliberately left out, optionally with a reason, which silences the linter's missing-section warnings

Values use a small set of types:

lineHeight accepts a dimension or a unitless multiplier such as 1.5. References normally point at a single value; inside components they may also point at a composite such as {typography.label-md}. The token model borrows typed groups and the reference syntax from the W3C Design Tokens format.

Markdown body: the sections

The body is organised into ## sections. Any can be left out, but those present should follow this order:

1. Overview (alias: Brand & Style): personality, audience and the feel the UI should have
2. Colors: palettes and the role of each
3. Typography: type levels and what each is for
4. Layout (alias: Layout & Spacing): grid model and spacing scale
5. Elevation & Depth (alias: Elevation): shadows, or how a flat design shows hierarchy
6. Shapes: corner radii and shape language
7. Components: buttons, chips, lists, inputs and other atoms
8. Do's and Don'ts: guardrails and common mistakes

An optional # title may appear above the sections but is not parsed as one. Headings the spec does not define, such as ## Iconography, are preserved rather than rejected. A duplicated section heading, such as two ## Colors, is an error.

Component tokens and variants

Each entry under components maps a component name to properties: backgroundColor, textColor, typography, rounded, padding, size, height and width. Values can be literals or references to other tokens. States are separate entries with related keys, for example button-primary and button-primary-hover. Unknown properties such as borderColor are accepted with a warning.

A DESIGN.md example

This is a complete, minimal DESIGN.md for a fictional company, Acme. It passes the official linter with no errors or warnings.

---
version: alpha
name: Acme
colors:
  primary: "#4f46e5"
  on-primary: "#ffffff"
  surface: "#f9fafb"
  text: "#111827"
typography:
  h1:
    fontFamily: Cal Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.5
rounded:
  md: 6px
spacing:
  sm: 8px
  md: 16px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.md}"
    padding: "{spacing.md}"
  card:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.text}"
---

## Colors

- **Primary (#4f46e5):** Indigo, reserved for the main action on each screen.
- **Surface (#f9fafb):** Off-white for cards and panels.
- **Text (#111827):** Near-black ink for headings and body copy.

A real file usually adds a fuller type scale, all eight sections and explicit do's and don'ts.

How coding agents use DESIGN.md

Agents use DESIGN.md the way they use any other file in the repository: they read it. Claude Code, Cursor, Codex and GitHub Copilot can all open Markdown files in a project; what differs is how reliably they are told to look. Each tool has its own instruction files that it picks up on its own: Claude Code skills, Cursor project rules, Copilot instruction files and AGENTS.md. Pointing those files at DESIGN.md is what makes an agent consult it before writing UI rather than only when asked.

The official package can also print the spec (spec) for inclusion in an agent's prompt.

For tool-specific setup, see Claude Code and DESIGN.md and Cursor and DESIGN.md. To serve the design system to agents over the Model Context Protocol instead of, or alongside, files, see Designrail MCP.

How to create a DESIGN.md

Write it by hand

Start from the section list above. Put the values you are sure of in the front matter, at minimum a primary colour and a few typography levels, then write a short paragraph per section explaining intent. Lint as you go.

Start from existing tokens

The spec notes that its tokens convert easily to and from tokens.json, Figma variables and Tailwind theme configs, so an existing token set can be restructured into the colors, typography, rounded, spacing and components groups. The official CLI documents export only (DESIGN.md to Tailwind or DTCG), not import, so this mapping is a manual or scripted step.

Extract it from a live site with Designrail

If the design already exists as a working website, Designrail reads the rendered page in Chrome or Edge, through the extension or the CLI, and writes a spec-shaped DESIGN.md from the colours, type, spacing, radii, shadows and components it measures. designrail scan https://example.com writes DESIGN.md and SKILL.md; adding --install writes the full project layout, including a Claude skill, a Cursor rule, Copilot instructions, an AGENTS.md section and Tailwind, shadcn/ui, CSS and DTCG token files. Its output adds two extra sections, Motion and Agent Workflow, which the spec permits. See the CLI reference.

DESIGN.md vs SKILL.md vs AGENTS.md vs Cursor rules

DESIGN.md is the full reference for the design system; the other files are entry points that tell a specific agent to use it. Only DESIGN.md is covered by the Google spec; the other rows describe the files Designrail generates.

Keep DESIGN.md as the single source of truth and treat the others as pointers and summaries. For other ways of giving agents design context, see Compare.

Validating and linting a DESIGN.md

The @google/design.md package includes a linter that checks a file against the spec and returns JSON findings agents can act on:

npx @google/design.md lint DESIGN.md

The documented rules include:

• broken-ref (error): a {token.reference} that does not resolve
• missing-primary (warning): colours are defined but none is called primary
• contrast-ratio (warning): a component's backgroundColor and textColor fall below WCAG AA (4.5:1)
• orphaned-tokens (warning): a colour no component references
• missing-typography (warning): colours are defined but no typography tokens
• section-order (warning): sections out of the canonical order
• token-summary and missing-sections (info): token counts, and absent optional groups such as spacing or rounded

The command exits with code 1 when it finds errors. The package also offers diff, which reports added, removed and modified tokens between two versions and flags regressions, and export, which writes Tailwind v3 JSON, a Tailwind v4 @theme block or W3C DTCG tokens.json.

Linting checks the file, not your product. Designrail's check command measures a running build against DESIGN.md and reports a score; lint-code flags raw colours, off-grid spacing and stray fonts in source.

FAQ

Who created DESIGN.md?

DESIGN.md is published by Google Labs as an open specification with a reference linter, in the google-labs-code/design.md repository. The format is at version alpha and is expected to change as it matures.

Where should DESIGN.md go in a repository?

The spec does not mandate a location. The common choice, and the one Designrail uses, is the repository root, with AGENTS.md, skills or rule files pointing to it.

Is the YAML front matter required?

No. The spec makes it optional, and the linter passes a prose-only file with one warning. Without tokens, though, agents get descriptions rather than exact values.

What colour formats can DESIGN.md use?

Any valid CSS colour string, including hex, named colours, rgb(), hsl(), oklch() and color-mix(). Hex (#RRGGBB) is the recommended default, and all values are converted to sRGB for contrast checks.

Can I add sections that are not in the spec?

Yes. Unknown ## headings are preserved, not treated as errors. A duplicated section heading, however, is an error.

Is DESIGN.md the same as SKILL.md?

No. DESIGN.md is the full, tool-neutral description of a design system; SKILL.md is an agent skill (Claude Code reads it from .claude/skills, Codex from .agents/skills) that summarises the rules and tells the agent when to apply them. Designrail generates both, and its SKILL.md names DESIGN.md as the full reference.

Does DESIGN.md replace design tokens JSON or Figma?

No. DESIGN.md adds the rationale agents need alongside token values, and the official CLI exports its tokens to W3C DTCG tokens.json and Tailwind themes.