Validate with the CLI

Lint, diff, and export DESIGN.md files using the @google/design.md command-line tool.

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 -

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
}

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

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

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