How to Fix Orphaned Tokens Warnings in DESIGN.md Design Systems

To fix orphaned tokens warnings in DESIGN.md, either reference the token in a component, rename it to match an MD3 standard family, or add a placeholder reference if the token is intentionally reserved for future use.

DESIGN.md provides a markdown-first schema for design tokens and components maintained by the google-labs-code/design.md repository. When the built-in linter runs its orphaned-tokens rule, it warns about color tokens defined in your system but never referenced by any component, unless they belong to Material Design 3 (MD3) standard families. Understanding how the linter tracks token references and derives color families is essential to resolving these warnings and maintaining a clean design system.

How the Orphaned-Tokens Rule Works

The linter’s logic resides in packages/cli/src/linter/linter/rules/orphaned-tokens.ts and operates by comparing defined color tokens against actual component references.

Parsing the Design System State

The CLI parses your DESIGN.md file into a DesignSystemState model defined in packages/cli/src/model/spec.ts. This model contains maps for components, colors, and a symbolTable that links component property values to specific token references.

Collecting Referenced Token Paths

The rule walks every component and inspects property values to identify which tokens are actively used. According to lines 63–74 in orphaned-tokens.ts, the logic records the full token path whenever a property value matches an entry in the symbol table:

const referencedPaths = new Set<string>();
for (const [, comp] of state.components) {
  for (const [, value] of comp.properties) {
    if (typeof value === 'object' && value !== null && 'type' in value) {
      for (const [key, symValue] of state.symbolTable) {
        if (symValue === value) referencedPaths.add(key);
      }
    }
  }
}

Deriving Color Families

The colorFamily() function (lines 26–38) normalizes token names by stripping MD3-specific prefixes and suffixes. This ensures that referencing primary also counts as referencing primary-container, on-primary, or inverse-primary:

function colorFamily(name: string): string {
  let n = name;
  n = n.replace(/^on-/, '');
  n = n.replace(/^inverse-/, '');
  n = n.replace(/^on-/, '');
  n = n.replace(/-container.*$/, '');
  n = n.replace(/-fixed.*$/, '');
  n = n.replace(/-(dim|bright|tint|variant)$/, '');
  return n;
}

MD3 Standard Family Exemptions

The rule defines a hard-coded MD3_STANDARD_FAMILIES set (lines 46–54) that automatically excludes standard Material Design tokens from orphaned status:

const MD3_STANDARD_FAMILIES = new Set([
  'primary','secondary','tertiary','error',
  'surface','background','outline',
]);

Tokens belonging to these families are ignored even if no component references them directly.

Generating Findings

For each defined color token, the rule checks three conditions: the token path is not directly referenced, its family is not referenced via a sibling token, and the family is not a standard MD3 family. If all three conditions are met, the linter emits a warning (lines 95–98):

findings.push({
  path,
  message: `'${name}' is defined but never referenced by any component.`,
});

Common Scenarios That Trigger Warnings

• Custom tokens never used: A token like brand-blue that is not in MD3_STANDARD_FAMILIES and lacks component references will always trigger a warning.
• Removed component references: Tokens previously used by components that have been deleted or refactored will surface as orphaned.
• Non-MD3 families: Any color family outside the seven standard MD3 families will be flagged if unreferenced, even if stylistically similar to Material Design.

Resolving Orphaned-Tokens Warnings

Reference the Token in a Component

The most direct resolution is to consume the token in a component property. When the linter runs again, the token path appears in referencedPaths and the warning disappears:

# Component: Button

## Props

- backgroundColor: {colors.brand-blue}

Rename to an MD3 Standard Family

If the color represents a standard Material Design concept, rename it to fit the MD3_STANDARD_FAMILIES set. Because colorFamily() groups related tokens, renaming brand-blue to primary will suppress warnings for all primary-* variants:

colors:
  # Before (custom)

  brand-blue: "#1E88E5"

  # After (MD3 family)

  primary: "#1E88E5"

Add a Placeholder Reference

If a token is intentionally defined for future use, you can silence the warning by adding a dummy component reference. The CLI currently does not expose per-rule disabling, so creating a hidden "theme" component that references the token is the practical workaround:

# Component: Theme-Reserved

## Props

- reservedColor: {colors.future-accent}

Verify with the CLI

Use the @google/design.md CLI to confirm your fixes. The lint command displays warnings in markdown format, while the --rules flag shows the complete rule table:

# Lint a DESIGN.md file and show only warnings

npx @google/design.md lint --format markdown path/to/DESIGN.md

# Show the complete rule table (including orphaned-tokens)

npx @google/design.md lint --rules

Practical Code Examples

Example 1: Referencing a Custom Token

Define a Card component that consumes your custom token:

# Component: Card

## Props

- backgroundColor: {colors.brand-blue}
- textColor: {colors.on-brand-blue}

Running the linter now yields no orphaned-tokens warning for brand-blue because it appears in the referencedPaths set.

Example 2: Migrating to MD3 Families

Convert a custom semantic color to the standard MD3 primary family:

colors:
  primary: "#6200EE"
  primary-variant: "#3700B3"

Because primary belongs to MD3_STANDARD_FAMILIES, the linter suppresses the warning even if primary-variant is not directly referenced by any component.

Example 3: Exporting to Verify Token Usage

Export your design system to JSON to verify that only referenced tokens are included in the output:

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

Inspect tailwind.tokens.json; any token that triggered an orphaned-tokens warning will be omitted from the Tailwind output, confirming which tokens are actually considered "in use."

Summary

• Orphaned tokens warnings occur when a custom color token is defined but never referenced by any component and does not belong to an MD3 standard family.
• Fix by referencing the token in a component property, which adds it to the referencedPaths set tracked in packages/cli/src/linter/linter/rules/orphaned-tokens.ts.
• Fix by renaming the token to match an MD3 standard family (primary, secondary, tertiary, error, surface, background, or outline), which automatically exempts it from the rule.
• Fix by placeholder if the token is intentionally unused, creating a dummy component reference to suppress the warning until the token is needed.
• Verify fixes using npx @google/design.md lint to ensure the warning no longer appears in the output.

Frequently Asked Questions

What causes orphaned tokens warnings in DESIGN.md?

The warning appears when a color token defined in your DESIGN.md file is not referenced by any component property and does not belong to the MD3_STANDARD_FAMILIES set. The linter tracks references via the symbolTable in DesignSystemState and flags any token paths missing from the referencedPaths set after scanning all components.

Which MD3 families are exempt from orphaned token checks?

The MD3_STANDARD_FAMILIES set in orphaned-tokens.ts includes seven families: primary, secondary, tertiary, error, surface, background, and outline. The colorFamily() function groups related tokens (like primary-container or on-primary) under these base families, so any token matching these roots is automatically exempt from orphaned status.

Can I disable the orphaned-tokens rule for specific tokens?

The CLI currently does not support per-rule disabling or inline comment suppressions. To silence a warning for an intentionally unused token, you must add a placeholder reference in a component (such as a hidden "theme" component) or rename the token to fit an MD3 standard family if semantically appropriate.

How do I verify that my fixes resolved the warnings?

Run npx @google/design.md lint --format markdown path/to/DESIGN.md to see the current warning list. If the orphaned token no longer appears, the fix is successful. You can also run npx @google/design.md export --format json-tailwind to check the exported JSON; tokens that previously triggered warnings will be omitted from the export if they remain unreferenced.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}