Unused Token Detection

Unused token detection identifies tokens that exist in the system but are not referenced by any consuming application. Unused tokens add maintenance burden, create confusion, and bloat token outputs. Regular detection and cleanup keeps the token system lean and relevant.

What Is Unused Token Detection

Unused token detection is the process of finding tokens that have no references in application code. These tokens may be remnants of removed features, duplicates that lost to consolidation, or tokens added speculatively but never adopted.

Detection requires analyzing both token definitions and their usage across consuming codebases.

How Unused Token Detection Works

Detection process:

async function detectUnusedTokens(tokens, codebases) {
  const usage = new Map();

  // Initialize all tokens as unused
  tokens.forEach(token => usage.set(token.name, 0));

  // Scan codebases for token references
  for (const codebase of codebases) {
    const files = await getFiles(codebase);

    for (const file of files) {
      const content = await readFile(file);
      tokens.forEach(token => {
        if (containsReference(content, token.name)) {
          usage.set(token.name, usage.get(token.name) + 1);
        }
      });
    }
  }

  // Return tokens with zero usage
  return Array.from(usage.entries())
    .filter(([name, count]) => count === 0)
    .map(([name]) => name);
}

Reference patterns to check:

function containsReference(content, tokenName) {
  const patterns = [
    // CSS custom property
    `var(--${tokenName.replace(/\./g, '-')})`,
    // JavaScript import
    `tokens.${tokenName}`,
    // JSON reference
    `{${tokenName}}`,
    // String literal
    `"${tokenName}"`
  ];

  return patterns.some(pattern => content.includes(pattern));
}

Detection report:

## Unused Token Report

Found 23 unused tokens:

### Color (8)
- color.legacy.brand
- color.legacy.accent
- color.deprecated.primary
- ...

### Spacing (5)
- spacing.legacy.sm
- spacing.legacy.md
- ...

### Typography (10)
- typography.legacy.body
- ...

Key Considerations

• Scan all consuming codebases, not just one
• Consider token-to-token references
• Account for dynamic token access patterns
• Verify before removing
• Deprecate before removing
• Document removal decisions
• Track unused token trends
• Prevention is better than cleanup

Common Questions

How can false positives be avoided?

False positives occur when detection misses valid usage.

Dynamic access patterns:

// This usage won't be detected by simple string matching
const tokenName = `color.${variant}`;
const value = tokens[tokenName];

Solution: Check for dynamic patterns and flag for manual review.

Cross-codebase usage:

Token used in:
- Main app: 0 references
- Marketing site: 12 references
- Mobile app: 3 references

A single-codebase scan would incorrectly mark this as unused.

Solution: Scan all consuming codebases.

Token-to-token references:

{
  "color.action.primary": "{color.brand.primary}",
  "color.brand.primary": "#3B82F6"
}

If color.action.primary is used but color.brand.primary is not directly used, both should be considered used.

Solution: Build reference graph and mark transitively used tokens.

How should unused tokens be handled?

Handling requires verification before removal.

Verification steps:

1. Confirm detection accuracy
   - Search manually for edge cases
   - Check dynamic usage patterns
   - Verify all codebases scanned

2. Understand why unused
   - Recently added, not yet adopted?
   - Removed feature?
   - Superseded by another token?

3. Decide action
   - Keep: Expected future use
   - Deprecate: No future need, allow transition
   - Remove: Confirmed unnecessary

Deprecation period:

{
  "color.legacy.brand": {
    "$value": "#3B82F6",
    "$deprecated": true,
    "$deprecationMessage": "No longer used. Will be removed in v3.0."
  }
}

Removal process:

Removal checklist:
- [ ] Verified unused across all codebases
- [ ] No planned future use
- [ ] Added to changelog
- [ ] Version bumped (major if breaking)
- [ ] Removal documented

How can token accumulation be prevented?

Prevention reduces future cleanup needs.

Contribution process:

New token requirements:
- Documented use case
- At least one confirmed consumer
- Not duplicating existing token
- Follows naming conventions

Regular cleanup:

# Monthly unused token check
schedule:
  - cron: '0 0 1 * *'
jobs:
  unused-check:
    runs-on: ubuntu-latest
    steps:
      - run: npm run detect-unused
      - run: npm run create-cleanup-issue

Usage monitoring:

// Track token usage over time
const usageHistory = {
  'color.action.primary': {
    '2024-01': 156,
    '2024-02': 148,
    '2024-03': 23  // Dramatic drop - investigate
  }
};

Summary

Unused token detection identifies tokens without references across consuming codebases. Detection requires scanning all consumers and accounting for token-to-token references. False positives can occur with dynamic access patterns, requiring manual verification. Unused tokens should be verified before removal, with deprecation periods allowing transition time. Prevention through contribution requirements and regular monitoring reduces accumulation of unused tokens.