DESIGN.md — making your design system readable by agents

Google Labs just published DESIGN.md (15k+ stars within weeks), a spec format for describing a design system to coding agents. The problem it solves is real: every new session, the agent starts fresh and generates an inconsistent UI because the design context doesn’t exist anywhere in the files it reads.

The answer is a plain-text file at the root of your project. Two layers: a YAML front matter for tokens (colors, typography, spacing, components with their hover/active variants), and a Markdown body for rationale: why those values exist, how to apply them, what not to do.

---
name: Heritage
colors:
  primary: "#1A1C1E"
  tertiary: "#B8422E"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
---

## Overview

Architectural Minimalism meets Journalistic Gravitas.
Warm limestone background, deep ink headlines.
One accent color, "Boston Clay", reserved strictly for primary actions.

The less obvious part, from the project’s philosophy: tokens are context, not rendering instructions. The prose does the real work. A specific reference like “a 1970s graduate lecture handout from an established university” automatically carries all the implicit constraints no one has to enumerate.

The CLI works today:

# Lint — checks broken refs, WCAG contrast ratios, orphaned tokens
npx @google/design.md lint DESIGN.md

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

# Diff two versions of your design system
npx @google/design.md diff DESIGN.md DESIGN-v2.md

The project is in alpha, and parts of it (components, motion) are still moving. Unknown tokens get accepted rather than rejected, which means you can extend the format without waiting for the spec to catch up. A deepdive on wiring this into an AI agent workflow is coming.