DESIGN.md is a file format for stating a design system so that an AI agent generating a user
interface has a fixed specification to work from. A single file holds both halves of that
specification: machine-readable design tokens — colours, typography, spacing, components — in a
leading YAML block, and the human-readable design intent behind them in the Markdown body beneath.
Google Labs published the format in April 2026, from a repository named google-labs-code/design.md,
as the reference implementation of its AI UI-generation product Google Stitch; the specification
document itself is published on the Stitch side.
Usage
What distinguishes the format from a style guide is that it ships with a checker. A CLI invoked as
npx @google/design.md lint validates a DESIGN.md for the consistency of its token references, for
WCAG contrast ratios, and for conformance to the format’s structural conventions, and returns its
result as JSON — which is what lets it run in CI and report per pull request. A companion diff
command compares two DESIGN.md files and returns the token-level changes between them in
structured form, putting design-system version control on a mechanical footing.
AIに渡す指示書の役割分担: AGENTS.md/SKILL.md/DESIGN.mdと仕様駆動開発の現在地 places the format as one of three layers of
instruction file handed to an AI agent, the layer covering appearance, alongside
AGENTS.md for an agent’s premises and SKILL.md for individual tasks. It is also the
layer that post treats as most explicitly split between machine-readable and human-readable content,
since the front matter and the body carry each separately rather than mixing them. In that post’s
framing, the format’s role is to gather a design system that had been spread across Figma files and
style-guide PDFs into one file that is readable both ways.
That post also records a gap for Japanese-language interfaces: the typography requirements specific
to Japanese — CJK font fallback, line height, letter-spacing, line-breaking rules and mixed-script
setting — are not defined in Google Labs’ own samples, and a separate community repository
(kzhrknt/awesome-design-md-jp) publishes DESIGN.md files covering them for a number of Japanese
services. The suggestion made there is to use the two together rather than either alone.
Tooling has begun to treat the format as one output among several: the post names a CLI able to
generate and update a specification in either SKILL.md or DESIGN.md form, which it reads as a
sign of a toolchain built on the assumption that the layers are distinct.
Related Terms
AGENTS.md, Agent Skills, AI IDE Rules, Spec-driven development