What is DESIGN.md

In March 2026, Google Stitch introduced DESIGN.md as part of an update that included infinite canvas, a design agent with project memory, instant prototyping and voice interaction. Among all these features, DESIGN.md is the least visible — but the most reusable outside the Stitch ecosystem.

DESIGN.md is a Markdown file that combines machine-readable design tokens (YAML front matter) with human-readable design rationale (Markdown prose). Tokens give agents exact values. Prose tells them why those values exist and how to apply them. The official specification is open-source and maintained by Google.

The most accurate analogy: DESIGN.md is to design what AGENTS.md is to code conventions. It's persistent context that the agent consults on every interaction.

Created by

Google Labs

GitHub Stars

8.5k ★

License

Apache 2.0

Status

Alpha

Format

Two layers in one file

According to the official specification, a DESIGN.md has two parts: YAML front matter with design tokens and a Markdown body with design rationale. The tokens are the normative values. The prose provides context for how to apply them.

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

## Overview

Architectural Minimalism meets Journalistic Gravitas.
The UI evokes a premium matte finish.

## Colors

- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.

An agent that reads this file will produce a UI with deep ink headlines in Public Sans, a warm limestone background, and Boston Clay call-to-action buttons.

Tokens

Design token schema

Design tokens are embedded as YAML front matter. The system is inspired by the W3C Design Tokens spec, adopting typed token groups and the {path.to.token} reference syntax for cross-referencing values.

version: <string>          # optional, current: "alpha"
name: <string>
description: <string>      # optional
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>

Token types

Type	Format	Example
Color	# + hex (sRGB)	"#1A1C1E"
Dimension	number + unit (px, em, rem)	48px, -0.02em
Token Reference	{path.to.token}	{colors.primary}
Typography	object with fontFamily, fontSize, fontWeight, lineHeight, letterSpacing	see example above

Structure

8 sections from the official spec

Sections use ## headings. They can be omitted, but those present must appear in this order. The LLM processes top to bottom.

1. Overview (alias: Brand & Style)

Holistic description of the product's look and feel. Defines brand personality, target audience, and the emotional response the UI should evoke. Foundational context for the agent's high-level stylistic decisions.

## Overview
Architectural Minimalism meets Journalistic Gravitas.
The UI evokes a premium matte finish — a high-end broadsheet
or contemporary gallery.

2. Colors

Defines color palettes with semantic roles. Naming convention: primary, secondary, tertiary, neutral. Hex + descriptive name + usage rule. Without a semantic name, the LLM might use the error color as accent.

## Colors
- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Secondary (#6C7278):** Sophisticated slate for borders, captions.
- **Tertiary (#B8422E):** "Boston Clay" — sole driver for interaction.
- **Neutral (#F7F5F2):** Warm limestone foundation.

3. Typography

Defines typography levels (9-15 is common). Tokens include fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, and fontVariation. The agent needs numbers — "large font" is not a useful instruction.

## Typography
- **Headlines:** Public Sans Semi-Bold — institutional, trustworthy.
- **Body:** Public Sans Regular at 16px — long-form readability.
- **Labels:** Space Grotesk — geometric precision. Uppercase, generous spacing.

4. Layout (alias: Layout & Spacing)

Describes layout and spacing strategy. Grid-based, margins, safe areas. Spacing tokens define the scale (xs, sm, md, lg, xl).

## Layout
Fluid Grid model for mobile, Fixed-Max-Width Grid for desktop (max 1200px).
Strict 8px spacing scale with 4px half-step for micro-adjustments.

5. Elevation & Depth (alias: Elevation)

How visual hierarchy is conveyed. If elevation is used, defines spread, blur, and shadow color. For flat designs, explains alternative methods (borders, color contrast).

## Elevation & Depth
Depth through Tonal Layers rather than heavy shadows.
Background uses soft off-white, primary content on pure white cards.

6. Shapes

Shape language of the design system. Defines border-radius for buttons, cards, and other rectangular elements. Rounded tokens (sm, md, lg, full).

## Shapes
Architectural Sharpness. All interactive elements use minimal 4px corner radius.
Just enough softness to feel modern while maintaining a rigid aesthetic.

7. Components

Component tokens map a name to a group of sub-token properties. Valid properties: backgroundColor, textColor, typography, rounded, padding, size, height, width. Variants (hover, active, pressed) are separate entries with a related key name.

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

8. Do's and Don'ts

Explicit constraints and guardrails. LLMs respond well to negative instructions — saying what not to do is as important as saying what to do.

## Do's and Don'ts
- Do use primary only for the single most important action per screen
- Don't mix rounded and sharp corners in the same view
- Do maintain WCAG AA contrast ratios (4.5:1 for normal text)
- Don't use more than two font weights on a single screen

Tools

Official CLI

The @google/design.md package includes four commands to validate, compare, export, and inspect DESIGN.md files.

lint — Validate structure

Checks broken references, WCAG AA contrast, orphaned tokens, section order, and missing typography.

npx @google/design.md lint DESIGN.md

diff — Compare versions

Detects token-level changes between two versions. Exit code 1 if regressions are detected.

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

export — Convert tokens

Exports tokens to Tailwind theme config or DTCG tokens.json (W3C Design Tokens Format).

npx @google/design.md export --format tailwind DESIGN.md
npx @google/design.md export --format dtcg DESIGN.md

spec — Inject spec into prompts

Outputs the full format specification. Useful for injecting spec context into agent prompts.

npx @google/design.md spec
npx @google/design.md spec --rules --format json

Validation

Linting rules

The linter runs 8 rules against a parsed DESIGN.md. Each rule produces findings at a fixed severity level.

Rule	Severity	What it checks
broken-ref	error	Token references that don't resolve to any defined token
missing-primary	warning	Colors defined but no primary color exists
contrast-ratio	warning	Component backgroundColor/textColor pairs below WCAG AA minimum (4.5:1)
orphaned-tokens	warning	Color tokens defined but never referenced by any component
missing-typography	warning	Colors defined but no typography tokens exist
section-order	warning	Sections appear out of the canonical order defined by the spec
token-summary	info	Summary of how many tokens are defined in each section
missing-sections	info	Optional sections (spacing, rounded) absent when other tokens exist

Format

Why Markdown + YAML and not just JSON

Markdown is the format LLMs understand with the highest fidelity. Most of the training corpus uses this structure. The model needs no extra instruction to interpret it.

JSON design tokens define values, but not rules. There's no way to express "use primary only for the main action" in a tokens.json file. DESIGN.md combines YAML tokens (exact values for machines) and Markdown prose (semantics for agents) in the same file, without a build pipeline. The export command converts to Tailwind or DTCG when needed.

Criteria	DESIGN.md	Tokens (JSON)	Style Guide
LLM-readable	Native (trained on MD)	Requires parsing	Not readable
Machine-readable tokens	Yes (YAML front matter)	Yes (JSON)	No
Human-readable	Yes, no tooling	Partial	Yes
Versionable (Git)	Yes	Yes	No (binary)
Context window	Light (~2-5K tokens)	Medium	N/A
Build pipeline	None (export available)	Required	N/A
Semantic rules	Yes (Do's/Don'ts)	No (values only)	Yes
Token references	Yes ({path.to.token})	Yes ($ref)	N/A
Official CLI/linter	Yes (@google/design.md)	Varies	N/A

Markdown doesn't replace design tokens in projects that already use a build pipeline. Both can coexist — use export to convert.

How to get one

How to get a DESIGN.md

Four paths, from fastest to most controlled.

1. Copy from the designmd.app library

Choose by vertical or visual style, customize values for your project and use. The library has over 400 documented files.

2. Generate with the design-md skill

The skill analyzes the existing codebase — components, CSS variables, tokens — and extracts a structured DESIGN.md from the patterns found.

3. Export from Google Stitch

If the project already uses Stitch, the export is native. The generated file follows the same structure documented here.

4. Write manually

Follow the 8-section structure above. Validate with npx @google/design.md lint. Full control over every design decision.

Compatibility

Works with every AI coding agent

DESIGN.md is plain Markdown — any agent that reads project files can use it. No plugins, no integrations, no vendor lock-in.

🟣

Claude Code

Anthropic

🔵

Cursor

Anysphere

🟢

Kiro

Amazon

🎨

Google Stitch

Google Labs

🌊

Windsurf

Codeium

⚡

GitHub Copilot

Microsoft

Quick start

Get started in 3 steps

Get a DESIGN.md file

Pick one from the designmd.app library (400+ styles), generate one in Google Stitch, or write your own.

Drop it in your project root

my-project/
├── DESIGN.md    ← your design system
├── AGENTS.md
├── src/
└── package.json

Ask your agent to build UI

The agent reads DESIGN.md automatically and applies your design system. No extra configuration needed.

> Build a pricing page with 3 tiers

The agent reads DESIGN.md → uses your colors,
typography, spacing, and component patterns.

💡 Validate your file: npx @google/design.md lint DESIGN.md

FAQ

Frequently asked questions

What is DESIGN.md?

DESIGN.md is a Markdown file with YAML front matter that defines a project’s design system — colors, typography, spacing, and components — in a format that AI coding agents like Claude Code, Cursor, and Kiro read automatically.

Does DESIGN.md replace Figma?

No. DESIGN.md complements Figma by translating design decisions into a format AI agents read and apply automatically. Figma remains the visual design tool.

Do I need design skills to use DESIGN.md?

No. You can copy a ready-made DESIGN.md from the designmd.app library or generate one with an AI skill. The file comes with expert design decisions built in.

Does it work with any AI agent?

Yes. Any agent that reads project files can use DESIGN.md: Claude Code, Cursor, Kiro, Windsurf, Google Stitch, and others. The Markdown format is universal.

What's the difference between DESIGN.md and JSON design tokens?

Design tokens in JSON require tooling and build pipelines. DESIGN.md is plain Markdown — readable by humans and LLMs without any additional tools. Tokens are for build systems, DESIGN.md is for AI agents.

Can I use it in an existing project?

Yes. Add the DESIGN.md file to the project root and reference it in your agent's configuration file. It doesn't alter existing code.

How do I validate my DESIGN.md?

Use the official CLI: npx @google/design.md lint DESIGN.md. It checks broken references, WCAG AA contrast, orphaned tokens, section order, and missing typography.

How do I update it when the design changes?

Edit the file. It's Markdown — any text editor works. Use npx @google/design.md diff before.md after.md to compare token-level changes. Version with Git to keep change history.

Does it work with React, Vue, Svelte?

DESIGN.md is framework-agnostic. It defines visual rules, not implementation. The agent applies these rules regardless of framework. Use export --format tailwind to generate a Tailwind theme automatically.

What are Token References?

Cross-references between tokens using the {path.to.token} syntax. Example: a component can reference {colors.primary} instead of repeating the hex value. Inspired by the W3C Design Tokens spec.