Google DESIGN.md

DESIGN.md is a self-contained, plain-text representation of a design system from Google Labs. It combines machine-readable design tokens (YAML front matter) with human-readable design rationale (markdown prose), giving AI coding agents a persistent, structured understanding of a visual identity.

How It Works

A DESIGN.md file has two layers:

1. YAML front matter — Machine-readable design tokens delimited by --- fences at the top of the file. These are the normative values.
2. Markdown body — Human-readable design rationale organized into ## sections. This prose provides context for how to apply the tokens.

Token Schema

---
version: alpha
name: Heritage
description: "Architectural Minimalism meets Journalistic Gravitas"
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
    letterSpacing: -0.02em
  body-md:
    fontFamily: Public Sans
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
  label-caps:
    fontFamily: Space Grotesk
    fontSize: 12px
    fontWeight: 500
    lineHeight: 1
    letterSpacing: 0.1em
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
---

Token Types

Type	Format	Example
Color	Any CSS color (hex, rgb(), oklch(), named)	"#1A1C1E", "oklch(62% 0.18 250)"
Dimension	number + unit (px, em, rem)	48px, -0.02em
Token Reference	{path.to.token}	{colors.primary}
Typography	object with fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, fontVariation	—

Component Tokens

Components map a name to a group of sub-token properties for consistent component styling:

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

Valid component properties: backgroundColor, textColor, typography, rounded, padding, size, height, width.

Variants (hover, active, pressed) are expressed as separate component entries with a related key name.

Section Structure

Every DESIGN.md follows this canonical order. Sections can be omitted, but those present must appear in this sequence:

1. Overview (alias: "Brand & Style") — Holistic description of the product's look and feel
2. Colors — Color palettes and their semantic roles
3. Typography — Font families, scales, and usage
4. Layout (alias: "Layout & Spacing") — Grid system, spacing scale, containment principles
5. Elevation & Depth (alias: "Elevation") — Shadow, layering, and visual hierarchy
6. Shapes — Corner radius and form language
7. Components — Per-component styling guidance
8. Do's and Don'ts — Guardrails and common pitfalls

CLI Tool

npm install @google/design.md

Lint — Validate a DESIGN.md file

npx @google/design.md lint DESIGN.md

Exit code 1 if errors are found, 0 otherwise. Outputs structured JSON with findings (broken refs, missing tokens, contrast ratios, etc.).

Diff — Compare two DESIGN.md files

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

Reports token-level changes (added, removed, modified) and detects regressions.

Export — Convert tokens to other formats

# Tailwind v3 config (JSON)
npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json

# Tailwind v4 theme (CSS)
npx @google/design.md export --format css-tailwind DESIGN.md > theme.css

# W3C Design Tokens Format Module
npx @google/design.md export --format dtcg DESIGN.md > tokens.json

Spec — Output the format specification

npx @google/design.md spec               # Full spec in markdown
npx @google/design.md spec --rules       # Spec + linting rules
npx @google/design.md spec --rules-only --format json  # Rules as JSON (for agent prompts)

Linting Rules

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 color pairs below WCAG AA (4.5:1)
orphaned-tokens	warning	Color tokens defined but never referenced by any component
missing-typography	warning	Colors defined but no typography tokens
section-order	warning	Sections out of canonical order
unknown-key	warning	Top-level key looks like a typo of a known key
missing-sections	info	Optional sections absent when other tokens exist
token-summary	info	Summary of how many tokens are defined per section

Programmatic API

import { lint } from '@google/design.md/linter'

const report = lint(markdownString)
console.log(report.findings)       // Finding[]
console.log(report.summary)        // { errors, warnings, info }
console.log(report.designSystem)   // Parsed DesignSystemState

Integration with AI Agents

1. Generate — Create a DESIGN.md in Google Stitch or write one manually
2. Lint — npx @google/design.md lint DESIGN.md to validate
3. Export — Convert to tailwind config, CSS variables, or DTCG tokens
4. Consume — Drop into Claude Code, Cursor, or any agent that reads context files

Design Token Interoperability

DESIGN.md tokens are inspired by the W3C Design Token Format. Export supports:

• Tailwind v3 — theme.extend JSON object
• Tailwind v4 — CSS @theme block with --color-*, --font-*, --text-*, --radius-*, --spacing-* namespaces
• DTCG — W3C Design Tokens Format Module JSON

Status

The DESIGN.md format is at version alpha. The spec, token schema, and CLI are under active development.

Links

• Specification
• GitHub Repository
• Google Stitch