DESIGN.md by Google Labs CLI
DESIGN.md
The DESIGN.md format for agents and a CLI: lint contrast and references, diff versions, export tokens to Tailwind and DTCG
- 28,487 ★ on the repository
- Last commit
- Apache-2.0
Minimal access
Why this level
- The CLI runs through npx as an npm package, reads the file or stdin you name and prints a result, and writing to a file happens only through your own output redirection
Install
Manual install
npx @google/design.md lint DESIGN.mdRuns without installing, Node.js 18 or newer required. In PowerShell on Windows use `npx -p @google/design.md designmd lint DESIGN.md`.
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- The CLI runs through npx as an npm package, reads the file or stdin you name and prints a result, and writing to a file happens only through your own output redirection
This is third-party code. Review the repository files before installing.
What it does
DESIGN.md is a file format that describes a product's visual identity so that both a person and an AI agent can read it. The file opens with a YAML block of tokens: colors, typography, rounded corners, spacing and components. Below comes Markdown prose in a fixed section order (overview, colors, typography, layout, elevation, shapes, components, do's and don'ts) explaining why the values were chosen and how to apply them. Tokens give the agent exact values and the prose gives the reasons. Components refer to tokens as `{colors.primary}`, and variants such as hover are separate entries. Alongside the format the repository holds the `@google/design.md` CLI with four commands. `lint` parses a file and returns JSON findings: broken token references, a missing primary color or typography, component color pairs below 4.5:1 contrast under WCAG AA, unused colors, sections out of order and typos in keys. `diff` compares two versions of a file and reports token changes and a regression when errors or warnings grow. `export` converts tokens into a Tailwind v3 config, a Tailwind v4 `@theme` block or a W3C DTCG file. `spec` prints the specification so you can paste it into an agent prompt. The format needs no installation to be read: give the agent a DESIGN.md file and ask it to build the interface from it. The CLI is for checking the file before an agent relies on it.
Who it is for. For designers and frontend developers who want to keep a design system in one file for an agent and check it with a linter.
Good fit when
- The agent picks its own colors and fonts each time and you want them fixed in a project file
- You need to check that text and background color pairs in components have enough WCAG AA contrast
- The design system was updated and you want to see which tokens were added, changed or removed
- You need DESIGN.md tokens as a Tailwind config or a DTCG file
- You want to paste the format specification into an agent prompt before it creates the file
Not a fit when
- You need a ready-made skill for Claude Code or Cursor: the `.agents/skills` folder in the repository holds internal skills for developing the project itself
- You want to produce a DESIGN.md from an existing website: the CLI only reads and checks a file and cannot extract tokens from a site, extract-design-system in the catalog does that
- The machine has no Node.js 18 or newer: the CLI is published as an npm package
- You need a stable specification: the format is at version alpha and the authors warn about changes
Example request
Lint DESIGN.md and tell me which buttons lack contrast, then export the tokens for TailwindLimitations
The format is at version alpha: the specification, the token schema and the CLI are under development and the authors expect changes as it matures. The CLI version in the manifest is 0.4.0.
The linter finds formal problems and does not judge whether the style looks good. It checks contrast only for `backgroundColor` and `textColor` pairs in components, so with no components that check does not run. It asks for a primary color and typography through separate warnings, otherwise the agent fills them in on its own.
Section order is strict: a section may be omitted, but those present must follow the specification order, and a duplicate section heading is an error that rejects the file. Unknown headings and colors with a valid value are accepted without an error.
Exit codes differ by command: `lint` and `diff` return 1 on errors or a regression, `export` returns 2 when the file cannot be read. In PowerShell on Windows `npx @google/design.md` may print nothing because of the `.md` suffix in the command name, in that case run `npx -p @google/design.md designmd`.
The license is Apache-2.0.
How to disable. If the CLI is installed in a project, remove it with `npm uninstall @google/design.md`. A run through `npx` leaves nothing but the npm cache. Delete the DESIGN.md file from the project root or drop the reference to it from the agent's instructions.
FAQ
What parts does a DESIGN.md file have?
A YAML block of tokens at the top and Markdown prose below it. Tokens set the exact values and the prose, by section, explains how to apply them.
What does lint check?
Eleven rules. Only broken token references, `broken-ref`, count as errors; the rest give warnings or info: no primary color, no typography, low contrast, unused tokens, section order and key typos.
Which formats can tokens be exported to?
`export --format` accepts `json-tailwind` for Tailwind v3, `css-tailwind` for a Tailwind v4 `@theme` block and `dtcg` for the W3C Design Tokens format. The value `tailwind` is an alias for `json-tailwind`.
What does the diff command show?
Which tokens were added, removed and changed in colors, typography, rounded, spacing and components, plus the linter finding counts before and after. If errors or warnings grow, it reports a regression and returns code 1.
Can the linter be called from code?
Yes, the package exposes a `lint` function from `@google/design.md/linter`. It takes a Markdown string and returns findings, a summary and the parsed design system.
Discussion
No questions or reviews yet.
Related
CLI toolsA plugin and npx CLI that scaffold DESIGN.md from the official google-labs-code/design.md templates
designlang
designlang (design-extract)
A CLI and MCP server that reads a live website and pulls out its design system: DTCG tokens, a Tailwind config, Figma variables and a brand book
A registry of installable design skills: ready SKILL.md and DESIGN.md files with tokens, component rules and accessibility for different styles
A collection of DESIGN.md files by aesthetic family and remix recipes to set an interface style for the agent
A CLI that extracts any website's design system into tokens: colors, typography, spacing, shadows, in one run
A TypeUI Figma plugin that reads a file's styles and generates DESIGN.md and SKILL.md for Claude Code, Codex and Cursor
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| DESIGN.md by Google Labs (this entry) | yes | 28,487 | |
| DESIGN.md | no | 9 | a plugin and npx CLI that create a DESIGN.md from ready templates following this specification |
| extract-design-system | no | 251 | extracts colors, fonts and spacing from a public site and saves them as tokens |
README in short
The repository holds the full specification in `docs/spec.md`, three examples with ready DESIGN.md files, JSON tokens and a Tailwind config (atmospheric-glass, paws-and-paths, totality-festival) and the TypeScript CLI sources with tests for every linter rule. Beside them are files on the project's principles and contribution rules, a set of test DESIGN.md files in the fixtures folder and a GitHub Actions build. The front page shows a short file example, command usage and the rules table.