The DESIGN.md CLI: lint, diff, export and spec

The DESIGN.md CLI has four commands, run through npx with no install: lint, diff, export and spec. Together they turn the file from a passive document into something you can validate, compare and convert.

lint - validate the file

$ npx @google/design.md lint DESIGN.md

$ npx @google/design.md lint --format json DESIGN.md

Lint catches broken token references, flags a missing primary color, and verifies WCAG contrast. It returns structured JSON and exits non-zero on errors, so it works in CI:

{

  "findings": [{

    "severity": "warning",

    "path": "components.button-primary",

    "message": "contrast 15.42:1 - passes WCAG AA"

  }],

  "summary": { "errors": 0, "warnings": 1 }

}

diff - catch regressions

$ npx @google/design.md diff before.md after.md

Reports added, removed and modified tokens and flags regressions. Exits non-zero when a regression is found, so you can gate design changes like code.

export - convert tokens

$ npx @google/design.md export --format css-tailwind DESIGN.md

$ npx @google/design.md export --format dtcg DESIGN.md

Converts to a Tailwind v4 theme or the W3C DTCG standard.

spec - feed the format to an agent

$ npx @google/design.md spec

Outputs the format spec to inject into an agent's prompt. Because every command returns structured output, the CLI doubles as a feedback loop an agent can use to fix its own DESIGN.md.

In CI

Run lint on every change to catch broken references and contrast failures, and diff against the previous version to flag regressions before they merge.

FAQ

Need to install anything? No - npx fetches and runs it.

Use the linter from code? Yes - it is available as an importable library.

Bottom line

Four commands cover the whole lifecycle: validate, compare, convert, and feed the spec to an agent.

Free starter: The format, a complete annotated example, and the core idea are on a free cheat sheet: DESIGN.md Quick-Start Cheat Sheet

Go deeper: The full guide covers the entire format — the token schema, the CLI in depth, accessibility, Tailwind and DTCG export, agent integration, and a complete walkthrough: DESIGN.md: The Complete Guide to Design Systems for AI Agents

Are you running design-system checks in CI yet? Curious whether people are gating design changes the way they gate code.