What is a design.md file?

A design.md file is a single markdown document that describes a design system (colors, typography, spacing, components, and the rules that tie them together) in a way both humans and AI coding agents can read and apply consistently. The format was published by Google Labs.

The short answer

A design.md file has two layers stacked into one file:

1. YAML frontmatter at the top, delimited by ---. This is the machine-readable part: every token (every color, every typography role, every component) is named and given a value here.
2. Markdown body below. This is the human-readable part: an editorial walk-through of the system, organized into a canonical sequence of sections.

Tokens defined in the frontmatter can be referenced anywhere in the file using a curly-brace syntax such as {colors.primary}, {rounded.lg}, {spacing.md}. That single rule is what lets an agent read both the values and the rationale from one source of truth.

Why design.md exists

Coding agents need persistent, structured context. A README tells an agent what a project does. A CLAUDE.md or .cursorrules tells it how to behave. There was no equivalent for the visual design of a product: the kind of information a designer keeps in Figma, a brand book, or a custom Tailwind config.

Without it, agents end up inventing colors, picking arbitrary typography, and producing UI that drifts from the brand on every generation. design.md closes that gap by giving the agent a file it can both read for intent and parse for exact values.

The frontmatter: tokens an agent can resolve

The YAML frontmatter contains five core token categories. Token names are kebab-case, color values are hex sRGB strings, and dimensions carry a unit (16px, 1.5rem, -0.02em).

---
version: alpha
name: "Acme Studio"
description: "A sober editorial workflow tool: white canvas, near-black ink, single-violet brand voltage on CTAs."

colors:
  primary: "#533afd"
  primary-active: "#4530e0"
  canvas: "#ffffff"
  surface-soft: "#f8fafd"
  ink: "#061b31"
  body: "#50617a"
  on-primary: "#ffffff"

typography:
  display-lg:
    fontFamily: "sohne-var, 'SF Pro Display', sans-serif"
    fontSize: "32px"
    fontWeight: "300"
    lineHeight: "1.1"
    letterSpacing: "-0.02em"
  body-md:
    fontFamily: "sohne-var, 'SF Pro Display', sans-serif"
    fontSize: "16px"
    fontWeight: "400"
    lineHeight: "1.5"

rounded:
  sm: "4px"
  DEFAULT: "6px"
  md: "8px"
  lg: "12px"
  pill: "9999px"

spacing:
  xs: "4px"
  sm: "8px"
  md: "16px"
  lg: "24px"
  section: "80px"

components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.body-md}"
    rounded: "{rounded.DEFAULT}"
    padding: "10px 20px"
  button-primary-active:
    backgroundColor: "{colors.primary-active}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.DEFAULT}"
---

Notice that button-primarydoesn’t hard-code its background color; it points at {colors.primary}. Change the brand color in one place and every component that references it follows. State variants (-active, -disabled, -focus) are separate top-level entries, not nested objects.

The body: editorial guidance an agent can read

Below the frontmatter, the markdown body uses a canonical sequence of ##-level sections. Each is optional individually, but if present they must appear in this order:

1. Overview: the editorial summary: voice, mood, color philosophy, the single typographic move that defines the system.
2. Colors: sub-grouped by role (Brand & Accent, Surface, Text, Hairlines, Semantic, plus any brand-specific palette).
3. Typography: the type scale as a table, plus principles and a Note on Font Substitutes.
4. Layout: spacing system, grid and container, whitespace philosophy.
5. Elevation & Depth: the shadow vocabulary and the philosophy behind it.
6. Shapes: border-radius scale and (when relevant) photography geometry.
7. Components: every component from the frontmatter, described in prose, sub-grouped (Buttons, Cards, Inputs, Navigation, Sub-systems).
8. Do’s and Don’ts: token-grounded rules that prevent the most common drift.

Inside the body, the same {colors.primary} reference syntax is used. Hex codes appear at most once next to their token reference, never duplicated downstream. That keeps the file consistent: every color mentioned in prose resolves to the same value the components use.

Linting: the format checks itself

The reference implementation ships a linter with seven rules:

• broken-ref: every {token.path} must resolve. Misspelled or undefined references fail at error level.
• missing-primary: every system needs a colors.primary.
• missing-typography: typography block must be populated.
• contrast-ratio: on-* color pairs must meet WCAG AA against the surface they sit on.
• orphaned-tokens: tokens defined but never referenced are flagged.
• missing-sections: informational warning when canonical sections are absent.
• token-summary: informational rollup of how many tokens exist per category.

Run npx @google/design.md lint DESIGN.mdin CI to keep a project’s design system honest as it evolves.

How design.md compares to other agent files

The closest neighbor is the W3C Design Tokens Community Group tokens.json format. The difference is that design.md bundles the tokens with the editorial rationale in a single file, so an agent can both look up a value and understand the design intent. The two formats can coexist: tokens.json as the build-tool input, design.md as the human + agent reference.

Tools and references

• github.com/google-labs-code/design.md is the canonical specification, schema, and reference linter.
• Stitch design.md specification is Google’s hosted spec page.
• awesome-design-md is a community registry of example files and tooling.
• getdesign.md is a third-party gallery of example design.md files for popular sites.

Generating a design.md from a live site

Hand-writing a design.md from scratch is doable but slow. Imitation reads any public URL, screenshots the page, extracts the live CSS, and writes a spec-compliant DESIGN.md: frontmatter, body, and extension sections for motion, imagery, icons, framework recommendations, responsive behavior, and known gaps. Paste a URL on the homepage to try it.

Frequently asked questions