DEV Community

Cover image for The DESIGN.md CLI: lint, diff, export and spec
PromptMaster
PromptMaster

Posted on

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

#webdev #ai #tutorial #design

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
Enter fullscreen mode Exit fullscreen mode

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 }
}
Enter fullscreen mode Exit fullscreen mode

diff - catch regressions 

$ npx @google/design.md diff before.md after.md
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

spec - feed the format to an agent 

$ npx @google/design.md spec
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)