Validate with the CLI

The @google/design.md CLI validates your design system against the spec, catches broken token references, checks WCAG contrast ratios, and exports tokens to other formats — all as structured JSON that agents can act on.

Install

npm install @google/design.md

Or run directly without installing:

npx @google/design.md lint DESIGN.md

All commands accept a file path or - for stdin. Output defaults to JSON.

Lint a DESIGN.md

Validate a DESIGN.md file for structural correctness. The linter parses the YAML front matter, resolves all token references, runs 8 lint rules, and reports findings.

npx @google/design.md lint DESIGN.md

Example output:

{
  "findings": [
    {
      "severity": "warning",
      "path": "colors",
      "message": "No 'primary' color defined. The agent will auto-generate key colors, reducing your control over the palette."
    },
    {
      "severity": "info",
      "message": "Design system defines 4 colors, 3 typography scales, 2 rounding levels."
    }
  ],
  "summary": { "errors": 0, "warnings": 1, "infos": 1 }
}

Pipe from stdin if you’re generating DESIGN.md files programmatically:

cat DESIGN.md | npx @google/design.md lint -

Option	Type	Default	Description
file	positional	required	Path to DESIGN.md (or - for stdin)
--format	json	text	json

Exit code 1 if errors are found, 0 otherwise.

Compare two versions

Detect token-level changes between two DESIGN.md files. The diff command reports which tokens were added, removed, or modified, and flags regressions (more errors or warnings in the “after” file).

npx @google/design.md diff DESIGN.md DESIGN-v2.md

Example output:

{
  "tokens": {
    "colors": { "added": ["accent"], "removed": [], "modified": ["tertiary"] },
    "typography": { "added": [], "removed": [], "modified": [] }
  },
  "findings": {
    "before": { "errors": 0, "warnings": 1 },
    "after": { "errors": 0, "warnings": 2 },
    "delta": { "errors": 0, "warnings": 1 }
  },
  "regression": true
}

Option	Type	Default	Description
before	positional	required	Path to the “before” DESIGN.md
after	positional	required	Path to the “after” DESIGN.md
--format	json	text	json

Exit code 1 if regressions are detected.

Export tokens

Convert DESIGN.md tokens to other formats for use in your codebase.

Tailwind CSS

Generate a theme.extend configuration object:

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

The output is a JSON object with colors, fontFamily, fontSize, borderRadius, and spacing mapped from your design tokens. Drop it into your tailwind.config.js.

DTCG (W3C Design Tokens)

Generate a W3C Design Tokens Format Module compliant tokens.json:

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

Option	Type	Default	Description
file	positional	required	Path to DESIGN.md
--format	tailwind	dtcg	required

View the spec

Output the DESIGN.md format specification. This is useful for injecting spec context into agent prompts so the agent knows exactly what structure to produce.

npx @google/design.md spec
npx @google/design.md spec --rules
npx @google/design.md spec --rules-only --format json

Option	Type	Default	Description
--rules	boolean	false	Append the active linting rules table
--rules-only	boolean	false	Output only the linting rules table
--format	markdown	json	markdown

Programmatic API

The linter is also available as a TypeScript library:

import { lint } from '@google/design.md/linter';

const report = lint(markdownString);

console.log(report.findings);      // Finding[]
console.log(report.summary);       // { errors, warnings, infos }
console.log(report.designSystem);  // Resolved DesignSystemState
console.log(report.tailwindConfig); // Generated Tailwind theme