How to Fix the 'orphaned-tokens' Warning in Design.md

The 'orphaned-tokens' warning indicates that a color token defined in your Design.md specification is never referenced by any component or sibling token, and you can resolve it by either referencing the token in a component property, removing the unused definition, or promoting it to a standard Material Design 3 family.

The orphaned-tokens rule is part of the Design.md CLI linter, which validates your design-system specification against the Material Design 3 (MD3) token architecture. When this warning appears in the command-line output, it signals that the linter has identified color tokens bloating your JSON without providing value to any component or token family.

What the orphaned-tokens warning means

In packages/cli/src/linter/linter/rules/orphaned-tokens.ts, the linter examines every token defined in state.colors and constructs a set of referenced token paths by traversing every component's property values that point to symbols in the design-system's symbol table (lines 60-74).

The rule then computes referenced families—if a component references one token in a family (e.g., primary), all semantic siblings such as on-primary and primary-container are considered "in-use" and exempt from warnings (lines 76-85).

Standard MD3 family exclusions

Tokens belonging to the standard MD3 families—primary, secondary, tertiary, error, neutral, and neutral-variant—are never flagged as orphaned, even if they are technically unused. According to the source code (lines 46-54), these families are hardcoded in MD3_STANDARD_FAMILIES because they constitute the core MD3 contract. Any remaining token that isn't referenced, isn't in a referenced family, and isn't part of the standard families is reported as an orphan (lines 88-97).

Three ways to fix the orphaned-tokens warning

Reference the token in a component

Add the token to a component's property using a color type reference. This adds the token path to the linter's referencedPaths set, which automatically exempts it from the warning.

Remove the unused token

Delete the token entry from the colors map in your design-system specification (e.g., design.json). If the token doesn't exist in state.colors, the linter cannot flag it as orphaned.

Promote to a standard MD3 family

Rename the token to belong to one of the families in MD3_STANDARD_FAMILIES (e.g., changing my-custom-blue to primary-custom). Since the rule automatically ignores tokens whose family matches a standard one, this suppresses the warning without requiring component usage.

Code examples: resolving orphaned tokens

Below is a minimal design-system fragment that triggers the warning, followed by the three correction strategies.

Original configuration (triggers warning)

{
  "colors": {
    "my-custom-blue": "#1e3a8a"
  },
  "components": {
    "Button": {
      "properties": {
        "label": { "type": "string" },
        "background": { "type": "color", "token": "primary" }
      }
    }
  }
}

The token my-custom-blue is never referenced, so the linter emits the orphaned-tokens warning.

Fix 1: Reference the token

{
  "colors": {
    "my-custom-blue": "#1e3a8a"
  },
  "components": {
    "Button": {
      "properties": {
        "label": { "type": "string" },
        "background": { "type": "color", "token": "my-custom-blue" }
      }
    }
  }
}

Now my-custom-blue appears in referencedPaths and the warning disappears.

Fix 2: Remove the token

{
  "colors": {},
  "components": {
    "Button": {
      "properties": {
        "label": { "type": "string" },
        "background": { "type": "color", "token": "primary" }
      }
    }
  }
}

With the token deleted from state.colors, nothing is orphaned.

Fix 3: Promote to standard family

{
  "colors": {
    "primary-custom": "#1e3a8a"
  },
  "components": {
    "Button": {
      "properties": {
        "label": { "type": "string" },
        "background": { "type": "color", "token": "primary" }
      }
    }
  }
}

Because the family primary is in MD3_STANDARD_FAMILIES, the linter ignores primary-custom even if no component references it directly.

Summary

• The orphaned-tokens warning surfaces color tokens defined in state.colors that are never referenced by components or their semantic siblings
• The linter exempts all tokens in MD3_STANDARD_FAMILIES (primary, secondary, tertiary, error, neutral, neutral-variant) from this rule
• Resolve warnings by referencing the token in a component property, deleting the unused definition, or renaming it to belong to a standard family
• The rule implementation resides in packages/cli/src/linter/linter/rules/orphaned-tokens.ts and is registered in packages/cli/src/linter/index.ts

Frequently Asked Questions

Why does the linter ignore standard MD3 families?

Standard families like primary, secondary, tertiary, error, neutral, and neutral-variant are part of the core Material Design 3 contract. The rule explicitly whitelists these families in MD3_STANDARD_FAMILIES (lines 46-54 of orphaned-tokens.ts) to ensure mandatory semantic colors are never flagged as orphaned, even when not actively used in a specific component.

Does referencing one token in a family mark the entire family as used?

Yes. According to the implementation in orphaned-tokens.ts (lines 76-85), the linter computes "referenced families" dynamically. If any component references one token in a family (e.g., primary), all semantic siblings such as on-primary, primary-container, and primary-fixed are considered in-use and will not trigger orphaned-token warnings.

Where does the warning appear in the CLI output?

The warning appears in the command-line table of linter warnings, as documented in the repository README (line 318). The table includes the warning name, the specific token path, and a description indicating the token is not referenced by any component or sibling token.

Can I disable the orphaned-tokens rule?

The rule is registered by default in packages/cli/src/linter/index.ts as part of the standard linting ruleset. While you could modify the linter registration to exclude it, the recommended approach is to fix the underlying token hygiene issues using the three resolution strategies above, as orphaned tokens increase JSON size and design-system complexity.

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