Lint Rules Overview

Invocation#

The CLI is shipped as the design.md binary inside @google/design.md. Use npx to run it without a global install:

npx @google/design.md <command> [args]

The binary name is design.md. An alias designmd is also registered in the package. Both point to the same entry point (dist/index.js).

Commands#

lint#

Validate a DESIGN.md file for structural correctness and run all built-in lint rules.

npx @google/design.md lint <file> [--format json|text]

Arguments:

Exit code: 1 if any error-severity findings are present; 0 otherwise.

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, 2 typography scales, 2 rounding levels."
    }
  ],
  "summary": { "errors": 0, "warnings": 1, "infos": 1 }
}

diff#

Compare two DESIGN.md files and report added, removed, and modified tokens, plus a finding-count delta.

npx @google/design.md diff <before> <after> [--format json|text]

Arguments:

Exit code: 1 if the after-file has more errors or more warnings than the before-file (regression); 0 otherwise.

Example output:

{
  "tokens": {
    "colors": { "added": ["accent"], "removed": [], "modified": ["tertiary"] },
    "typography": { "added": [], "removed": [], "modified": [] },
    "rounded": { "added": [], "removed": [], "modified": [] },
    "spacing": { "added": [], "removed": [], "modified": [] },
    "components": { "added": [], "removed": [], "modified": [] }
  },
  "findings": {
    "before": { "errors": 0, "warnings": 1 },
    "after": { "errors": 0, "warnings": 0 },
    "delta": { "errors": 0, "warnings": -1 }
  },
  "regression": false
}

export#

Export DESIGN.md tokens to another format. The --format flag is required.

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

Arguments:

Export targets:

Exit code: 1 if the input has error-severity lint findings; 0 otherwise.

Examples:

# Tailwind v4 CSS
npx @google/design.md export DESIGN.md --format css-tailwind > tokens.css

# W3C DTCG JSON
npx @google/design.md export DESIGN.md --format dtcg > tokens.json

# Tailwind v3 JSON (theme.extend)
npx @google/design.md export DESIGN.md --format json-tailwind > tailwind-tokens.json

spec#

Print the DESIGN.md format specification and, optionally, the active lint rules table.

npx @google/design.md spec [--rules] [--rules-only] [--format markdown|json]

Options:

Built-in lint rules#

All nine rules run on every lint invocation. Findings are grouped by severity: error (file rejected, CLI exits 1), warning (file accepted with caveats), info (informational, no action required).

broken-ref#

Severity: error (for unresolved token references); warning (for unknown component sub-token names)

What triggers it: The rule fires in two situations:

1. A component property value is a token reference ({path.to.token}) that does not resolve to any defined token. This produces an error-severity finding.
2. A component property name is not one of the eight recognized sub-tokens (backgroundColor, textColor, typography, rounded, padding, size, height, width). This produces a warning-severity finding.

Example finding:

{
  "severity": "error",
  "path": "components.button-primary",
  "message": "Reference {colors.accent} does not resolve to any defined token."
}

How to fix: Check the reference path against the token names defined in colors, typography, rounded, or spacing. Ensure the token exists before referencing it.

Full guide: Fixing broken-ref errors in DESIGN.md

missing-primary#

Severity: warning

What triggers it: The colors map has at least one entry, but no key named primary is present.

Example finding:

{
  "severity": "warning",
  "path": "colors",
  "message": "No 'primary' color defined. The agent will auto-generate key colors, reducing your control over the palette."
}

How to fix: Add a primary entry to colors:

colors:
  primary: "#1A1C1E"

Full guide: Fixing missing-primary warnings in DESIGN.md

contrast-ratio#

Severity: warning

What triggers it: A component defines both backgroundColor and textColor as values that resolve to colors (literal hex or resolved references such as {colors.primary}), and the computed WCAG contrast ratio between the two is below 4.5:1 (the WCAG AA minimum for normal text). The rule skips components where either property is absent or does not resolve to a color.

Example finding:

{
  "severity": "warning",
  "path": "components.button-secondary",
  "message": "textColor (#818A91) on backgroundColor (#F7F5F2) has contrast ratio 3.23:1, below WCAG AA minimum of 4.5:1."
}

How to fix: Increase the lightness contrast between backgroundColor and textColor until their ratio meets or exceeds 4.5:1. Use the tool to preview pairs interactively.

Full guide: Fixing contrast-ratio warnings in DESIGN.md

orphaned-tokens#

Severity: warning

What triggers it: The rule fires only when components is non-empty. A color token defined in colors is considered orphaned when no component's resolved backgroundColor or textColor references it, AND the token's color family (derived by stripping on-, inverse-, -container, -fixed, -dim, -bright, -tint, -variant suffixes) is not referenced by any component either, AND the family is not one of the seven Material Design 3 standard families (primary, secondary, tertiary, error, surface, background, outline).

Example finding:

{
  "severity": "warning",
  "path": "colors.promo",
  "message": "'promo' is defined but never referenced by any component."
}

How to fix: Either reference the token in a component definition, or remove it if it is no longer needed.

Full guide: Fixing orphaned-tokens warnings in DESIGN.md

token-summary#

Severity: info

What triggers it: Always fires when the file contains at least one token in any of colors, typography, rounded, spacing, or components. It emits a single informational message summarizing the token counts.

Example finding:

{
  "severity": "info",
  "message": "Design system defines 4 colors, 3 typography scales, 2 rounding levels, 2 spacing tokens, 1 component."
}

How to fix: No action required. This is an informational diagnostic.

Full guide: Understanding token-summary in DESIGN.md

missing-sections#

Severity: info

What triggers it: The colors map is non-empty, and either spacing or rounded (or both) have no entries. The rule emits a separate finding for each absent section.

Example findings:

[
  {
    "severity": "info",
    "path": "spacing",
    "message": "No 'spacing' section defined. Layout spacing will fall back to agent defaults."
  },
  {
    "severity": "info",
    "path": "rounded",
    "message": "No 'rounded' section defined. Corner rounding will fall back to agent defaults."
  }
]

How to fix: Add spacing and/or rounded sections if you want to express layout and rounding choices explicitly:

rounded:
  sm: 4px
  md: 8px
  lg: 16px
spacing:
  sm: 8px
  md: 16px
  lg: 32px

Full guide: Fixing missing-sections findings in DESIGN.md

missing-typography#

Severity: warning

What triggers it: The colors map is non-empty, but the typography map has no entries.

Example finding:

{
  "severity": "warning",
  "path": "typography",
  "message": "No typography tokens defined. Agents will use default font choices, reducing your control over the design system's typographic identity."
}

How to fix: Add at least one typography token. The recommended starting set:

typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6

Full guide: Fixing missing-typography warnings in DESIGN.md

section-order#

Severity: warning

What triggers it: Two or more of the eight canonical Markdown sections are present, and they appear in a different order than the canonical sequence: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts. The rule checks only sections whose headings match a canonical name or alias; custom sections do not affect the check. Only the first out-of-order pair is reported.

Example finding:

{
  "severity": "warning",
  "message": "Section 'Components' appears before 'Typography', which is out of order. Expected order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts"
}

How to fix: Reorder the ## sections in the Markdown body to match the canonical sequence. The export command does not reorder prose, but the fixer utility (available in the JavaScript API via fixSectionOrder) can reorder sections automatically.

Full guide: Fixing section-order warnings in DESIGN.md

unknown-key#

Severity: warning

What triggers it: A top-level YAML key is not one of the eight recognized schema keys (version, name, description, colors, typography, rounded, spacing, components), AND the Levenshtein distance between the unknown key and the nearest known key is 2 or fewer characters (suggesting a typo).

Keys that are more than 2 edits away from any known key are silently ignored (not flagged).

Example finding:

{
  "severity": "warning",
  "path": "colour",
  "message": "Unknown key \"colour\": did you mean \"colors\"?"
}

(Note: the actual CLI output uses an em dash as the separator between the key name and the suggestion, not a colon or hyphen. The example above substitutes a colon for readability.)

How to fix: Correct the spelling of the top-level key to match the recognized schema key.

Full guide: Fixing unknown-key warnings in DESIGN.md

Rule severity summary#

Print this table from the CLI at any time:

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

For the full field reference, see DESIGN.md Field Reference.