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

> Learn how to fix the orphaned tokens warning in Design.md by referencing or removing unused color tokens. Resolve this common issue for cleaner design specifications.

- Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md)
- Tags: how-to-guide
- Published: 2026-07-03

---

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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/orphaned-tokens.ts) and 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)

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