What the Orphaned-Tokens Linting Rule Checks For in Design.md

The orphaned-tokens linting rule flags custom color tokens defined in a DESIGN.md file that are never referenced by any component, while ignoring Material Design 3 standard families.

The orphaned-tokens linting rule is a key validation tool in the google-labs-code/design.md repository that helps maintain clean design system files. It analyzes DESIGN.md files to detect color tokens that exist in the definition but remain unused by any component, helping authors eliminate dead code and reduce file bloat.

How the Orphaned-Tokens Rule Works

The rule implements a three-stage analysis pipeline in packages/cli/src/linter/linter/rules/orphaned-tokens.ts to distinguish between actively used tokens and truly orphaned definitions.

Step 1: Collecting Referenced Token Paths

First, the rule scans every component property in the design file to locate token references. When it encounters a reference like {colors.primary}, it extracts the full path and adds it to the referencedPaths set. This collection phase occurs in the orphanedTokens function around lines 63-71.

Step 2: Grouping Tokens by MD3 Families

Next, the rule analyzes tokens to determine their Material Design 3 family associations. Using the colorFamily helper function, it normalizes token names and identifies semantic groupings. If a component references primary, the rule automatically treats the entire family—including semantic siblings like on-primary and primary-container—as "in-use". These families are stored in the referencedFamilies set, implemented around lines 80-85.

Step 3: Identifying Truly Orphaned Tokens

Finally, the rule iterates over every color token defined in the design system. A token is excluded from orphan reporting if:

• It appears in referencedPaths (directly used by a component)
• Its family exists in referencedFamilies (semantic siblings are used)
• It belongs to MD3 standard families: primary, secondary, tertiary, error, surface, background, or outline

Tokens failing all three checks are reported as findings with the warning message: 'brand-blue' is defined but never referenced by any component. This logic resides in lines 92-98 of the source file.

CLI Usage and Configuration

To run the orphaned-tokens check, use the Design.md CLI linter:

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

The rule is registered in packages/cli/src/linter/index.ts and executes automatically as part of the standard linting suite. You can view the rule descriptor and severity settings in the README.md linting rules table.

Example Output Structure

When the linter detects orphaned tokens, it generates structured findings like this:

{
  "findings": [
    {
      "severity": "warning",
      "path": "colors.brand-blue",
      "message": "'brand-blue' is defined but never referenced by any component."
    }
  ]
}

In this example, brand-blue is a custom token defined in the colors section but never referenced by any component property, while standard MD3 tokens like primary are ignored even if unused.

Summary

• The orphaned-tokens rule detects unused custom color tokens in DESIGN.md files according to the google-labs-code/design.md source code.
• It tracks directly referenced paths via referencedPaths and MD3 family usage via referencedFamilies.
• Standard MD3 families (primary, secondary, tertiary, error, surface, background, outline) are never flagged.
• The rule implementation lives in packages/cli/src/linter/linter/rules/orphaned-tokens.ts.
• Test coverage exists in orphaned-tokens.test.ts to verify correct detection logic.

Frequently Asked Questions

Does the orphaned-tokens rule flag Material Design 3 tokens?

No. The rule explicitly excludes MD3 standard families including primary, secondary, tertiary, error, surface, background, and outline. These tokens are considered part of the core design system and are never reported as orphaned, even if currently unused in your components.

How does the rule distinguish between used and unused tokens?

The rule builds two data structures: referencedPaths for tokens directly referenced in component properties, and referencedFamilies for MD3 families where any sibling is used. A token passes the check if it appears in either set or belongs to a standard MD3 family. Only tokens failing all checks are reported.

Where is the orphaned-tokens rule implemented in the codebase?

The core logic resides in packages/cli/src/linter/linter/rules/orphaned-tokens.ts, specifically in the orphanedTokens function between lines 63-98. The rule is registered with the CLI engine in packages/cli/src/linter/index.ts, and comprehensive test cases are located in orphaned-tokens.test.ts.

Can I customize which tokens are considered orphaned?

Currently, the rule uses hardcoded MD3 family exclusions in the source code. Custom tokens are evaluated strictly based on whether they are referenced by components. To modify behavior, you would need to edit the rule implementation in orphaned-tokens.ts or filter findings in post-processing.

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