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

The DESIGN.md CLI has four commands, run through npx with no install: lint validates structure, references and WCAG contrast; diff compares versions and flags regressions; export converts tokens to Tailwind or DTCG; and spec outputs the format specification for agent prompts.

What does the lint command do?

The lint command checks a DESIGN.md for structural correctness: it catches broken token references, flags a missing primary color, and verifies WCAG contrast ratios. It returns structured JSON an agent can act on, and exits with a non-zero code on errors, so it works in continuous integration.

What does the diff command do?

The diff command compares two versions of a DESIGN.md and reports token-level and prose changes — which colors were added, removed or modified — and whether the change counts as a regression. It exits non-zero when regressions are detected, so you can gate design changes the same way you gate code.

What does the export command do?

The export command converts your tokens to formats downstream tools understand: a Tailwind theme as CSS or JSON, and the W3C DTCG tokens standard. This is how your design tokens reach your actual codebase without you maintaining them twice.

What does the spec command do?

The spec command outputs the DESIGN.md format specification itself, which you can inject into an agent's prompt so it knows how to read and write the format correctly. Because every command returns structured output, the CLI doubles as a feedback loop an agent can use to validate and fix its own DESIGN.md.

FAQ

Do I need to install anything? No. Every command runs through npx, which fetches and runs the tool without a permanent install.

Can I use the linter from code? Yes — it is available as a library you can import, returning the same structured findings.