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

> Resolve orphaned tokens warnings in DESIGN.md. Learn to reference tokens in components, rename them per MD3 standards, or use placeholders for future use. Ensure your design system is clean and functional.

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

---

**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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) file into a `DesignSystemState` model defined in [`packages/cli/src/model/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/orphaned-tokens.ts), the logic records the full token path whenever a property value matches an entry in the symbol table:

```typescript
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`:

```typescript
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:

```typescript
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):

```typescript
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:

```markdown

# 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:

```markdown
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:

```markdown

# 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:

```bash

# 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:

```markdown

# 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:

```markdown
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:

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

```

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