Understanding orphaned-tokens in DESIGN.md

Why orphaned tokens matter#

A DESIGN.md file can accumulate colors that were defined during an earlier brand iteration but are no longer wired to any component. Agents and exporters silently carry those tokens into generated CSS, design token files, and AI prompts. The resulting output includes unreferenced palette entries that increase cognitive noise, can trigger accidental use by agents seeking "available" colors, and make the diff output harder to read when the design system evolves.

The orphaned-tokens rule surfaces this category of drift before export.

Precondition: components must be non-empty#

The rule only runs when state.components.size > 0. If your DESIGN.md has no components section at all (or an empty one), the rule returns no findings regardless of how many colors you have defined. This avoids false positives for files that are intentionally palette-only.

A file with colors and without components will never see this warning.

Color family matching#

The rule does not check individual token names in isolation. It computes a "color family" for each token by stripping well-known suffixes and prefixes:

• on- prefix (e.g. on-primary resolves to family primary)
• inverse- prefix, followed by a second on- strip if present
• -container suffix and anything after it (e.g. primary-container-dim resolves to primary)
• -fixed suffix and anything after it
• -dim, -bright, -tint, -variant suffixes

A token is considered referenced if any of the following is true:

1. The full token path (e.g. colors.brand-accent) appears in a component property's resolved symbol table.
2. The token's derived family matches the family of any token that is directly referenced.

This means that if brand-accent is referenced directly, then on-brand-accent will not be flagged as orphaned, because they share the brand-accent family.

The MD3 standard families exemption#

Seven color families are permanently exempt from the rule regardless of whether any component references them:

These exact seven families are defined in MD3_STANDARD_FAMILIES in the linter source. A token whose derived family is in this set will never produce an orphaned-tokens finding, even if no component references it. This is intentional: MD3-aligned files commonly define these roles at the palette level without tying each one to a specific component definition.

What triggers it#

Example that trips the rule:

---
name: Acme Brand
colors:
  primary: "#1A1C1E"
  on-primary: "#FFFFFF"
  promo: "#E63946"
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
---

promo is defined but no component references it or any other promo-family token, and promo is not in the MD3 exempt set. The linter emits:

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

on-primary does not trigger a warning: its family is primary, which is MD3-exempt.

How to fix#

You have two options:

Option A: reference the token in a component

Wire the orphaned token to a component definition so it enters the symbol table:

---
name: Acme Brand
colors:
  primary: "#1A1C1E"
  on-primary: "#FFFFFF"
  promo: "#E63946"
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
  badge-promo:
    backgroundColor: "{colors.promo}"
    textColor: "#FFFFFF"
---

Now promo is referenced by badge-promo.backgroundColor. The warning disappears.

Option B: remove the token

If the token is genuinely unused and not planned, delete it from colors:

---
name: Acme Brand
colors:
  primary: "#1A1C1E"
  on-primary: "#FFFFFF"
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
---

After either fix, npx @google/design.md lint DESIGN.md will report zero orphaned-tokens warnings.

Checking with JSON output#

Run with --format json to see orphan warnings alongside other findings:

npx @google/design.md lint DESIGN.md --format json

The summary.warnings count reflects all warning-severity rules including orphaned-tokens. To isolate orphan findings only, filter the findings array by "path" starting with "colors." and "message" containing "never referenced".

Related rules#

• broken-ref: errors when a token reference does not resolve to any defined token.
• missing-primary: warns when colors are defined but no primary key is present.
• contrast-ratio: warns when a backgroundColor/textColor pair falls below WCAG AA.
• CLI and Lint Rules Reference: full rules table and severity summary.

Try it in the tool