Docs / Reference

CLI

The official CLI is published as @google/design.md on npm. It provides linting with WCAG contrast checks, version diffing, and token export to Tailwind or W3C DTCG format.

Installation

# One-off (no install required)
npx @google/design.md <command>

# Dev dependency (recommended for teams)
npm install --save-dev @google/design.md

# Global
npm install -g @google/design.md

lint

Validates a DESIGN.md file against all 7 lint rules. Exits with code 0 on success, 1 on failure.

npx @google/design.md lint [file]

# Examples
npx @google/design.md lint DESIGN.md
npx @google/design.md lint ./design/brand.md --strict

Flag

Description

--file, -f

Path to the DESIGN.md file (default: ./DESIGN.md)

--strict

Treat warnings as errors

--quiet

Only output errors, suppress passing rules

--json

Output results as JSON (useful in CI)

Lint rules

The linter checks the following 7 rules on every run:

Rule

Description

yaml-valid

The front matter block is valid YAML

color-values

All color token values are valid CSS color strings

typography-values

fontSize, fontWeight, lineHeight, letterSpacing values are valid

spacing-values

All spacing values are valid CSS dimensions

references-resolve

All {token.reference} values point to existing tokens

version-semver

The version field, if present, is a valid semver string

wcag-aa-contrast

All components with textColor + backgroundColor have ≥ 4.5:1 contrast

A passing lint run prints:

✓ yaml-valid
✓ color-values
✓ typography-values
✓ spacing-values
✓ references-resolve
✓ version-semver
✓ wcag-aa-contrast

7/7 rules passed. All color pairs meet WCAG AA.

diff

Compares two DESIGN.md files (or two versions of the same file) and reports added, removed, and changed tokens.

npx @google/design.md diff <file-a> <file-b>

# Examples
npx @google/design.md diff DESIGN.md.old DESIGN.md
npx @google/design.md diff [email protected] [email protected]

export

Exports design tokens to an external format. Two formats are currently supported.

npx @google/design.md export --format <format> [file]

# Export to W3C DTCG (Tokens Studio, Figma Variables API)
npx @google/design.md export --format dtcg DESIGN.md
# → outputs tokens.json

# Export to Tailwind CSS config
npx @google/design.md export --format tailwind DESIGN.md
# → outputs tailwind.tokens.js

Format

Output file

Used with

dtcg

tokens.json

Tokens Studio, Figma Variables API, Style Dictionary

tailwind

tailwind.tokens.js

Tailwind CSS theme extension

spec

Prints the current format specification — the canonical field list, allowed value types, and lint rule descriptions. Useful for checking which spec version the installed CLI implements.

npx @google/design.md spec

# Check the installed CLI version
npx @google/design.md --version

CI integration: Add the lint step to your CI pipeline to catch token errors before they reach production. The --json flag makes the output machine-parseable for custom reporters.

# package.json scripts
{
  "scripts": {
    "lint:design": "design.md lint DESIGN.md",
    "lint:design:ci": "design.md lint DESIGN.md --json"
  }
}

Versioning REST API