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

> The orphaned-tokens linting rule in design.md flags unreferenced custom color tokens. Ensure your design tokens are used by components to maintain consistency and avoid unused code.

- Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md)
- Tags: deep-dive
- Published: 2026-06-25

---

**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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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:

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

```

The rule is registered in [`packages/cli/src/linter/index.ts`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/README.md) linting rules table.

## Example Output Structure

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

```json
{
  "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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/orphaned-tokens.ts).
- Test coverage exists in [`orphaned-tokens.test.ts`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/index.ts), and comprehensive test cases are located in [`orphaned-tokens.test.ts`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/orphaned-tokens.ts) or filter findings in post-processing.