# DESIGN.md

A file format specification for describing a product's visual identity to coding agents, combining machine-readable design tokens with human-readable design rationale.

DESIGN.md is a format specification for describing a visual identity to coding agents, giving them a persistent, structured understanding of a design system. A DESIGN.md file combines machine-readable design tokens, written as YAML front matter, with human-readable design rationale written as markdown prose; the tokens give an agent exact values, and the prose explains why those values exist and how to apply them.

Token types include colors in any CSS color format, dimensions with a unit, references to other tokens, and typography objects covering font family, size, weight, line height and letter spacing. A companion command-line tool validates a DESIGN.md file against the specification, checks WCAG contrast ratios, and reports findings as structured JSON; another command compares two versions of a design system to detect token and prose regressions.

It is maintained by Google Labs Code, written in TypeScript, and licensed Apache-2.0.

Website: https://stitch.withgoogle.com/docs/design-md/specification