DESIGN.md: A format spec for describing visual identity to coding agents

Google Labs released DESIGN.md, a format specification for describing a visual identity to coding agents. The file combines machine-readable design tokens (YAML front matter) with human-readable design rationale (markdown prose). Tokens give agents exact values; prose explains why those values exist and how to apply them.

Format Overview

A DESIGN.md file has two layers delimited by --- fences at the top: YAML front matter for tokens and a markdown body with ## sections. Example excerpt:

---
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"
  label-caps:
    fontFamily: "Space Grotesk"
    fontSize: "0.75rem"
rounded:
  sm: "4px"
  md: "8px"
spacing:
  sm: "8px"
  md: "16px"

The tokens are the normative values. Prose provides context for application.

Key Features

• Token types: Colors (hex sRGB), Typography objects (fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, fontVariation), Dimensions (number+unit), Token references ({path.to.token}).
• Components: Map a name to sub-token properties, e.g. components.button-primary.backgroundColor: "{colors.tertiary}".
• Section order (optional but enforced): Overview, Colors, Typography, Layout & Spacing, Elevation & Depth, Shapes, Components, Do's and Don'ts.

CLI Tools

Validate a DESIGN.md with the linter:

npx @google/design.md lint DESIGN.md
{
  "findings": [
    {
      "severity": "warning",
      "path": "components.button-primary",
      "message": "textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA."
    }
  ],
  "summary": { "errors": 0, "warnings": 1, "info": 1 }
}

Detect regressions between versions:

npx @google/design.md diff DESIGN.md DESIGN-v2.md
{
  "tokens": {
    "colors": {
      "added": ["accent"],
      "removed": [],
      "modified": ["tertiary"]
    },
    "typography": { "added": [], "removed": [], "modified": [] }
  },
  "regression": false
}

Use Case

An agent reading the Heritage example will produce a UI with deep ink headlines in Public Sans, a warm limestone background (#F7F5F2), and Boston Clay (#B8422E) call-to-action buttons — all from a single file.