Token Anti-Patterns

Token anti-patterns are recurring problematic approaches to token design and usage that seem reasonable initially but cause significant problems over time. Recognizing anti-patterns helps teams avoid paths that lead to unmaintainable, confusing, or ineffective token systems.

What Are Token Anti-Patterns

Token anti-patterns are common mistakes that are codified into patterns, often because they solve an immediate problem while creating larger future problems. Unlike simple errors, anti-patterns often persist because they appear to work until scale or change reveals their weaknesses.

Anti-patterns typically emerge from short-term thinking, lack of experience, or copying patterns without understanding context.

How Token Anti-Patterns Develop

The “Just One More” anti-pattern:

/* Initial: Seems fine */
{ "button-background": "#3B82F6" }

/* Later: Just one more for this variant... */
{ "button-secondary-background": "#6B7280" }

/* Even later: And one more... */
{ "button-tertiary-background": "#F3F4F6" }
{ "button-ghost-background": "transparent" }
{ "button-destructive-background": "#DC2626" }
{ "card-button-background": "#3B82F6" }  /* Wait, duplicate? */

/* Result: Explosion of nearly identical tokens */

The “Copy the Value” anti-pattern:

/* Multiple tokens with same value */
{
  "header-background": "#ffffff",
  "footer-background": "#ffffff",
  "sidebar-background": "#ffffff",
  "card-background": "#ffffff"
}

/* Should be */
{
  "color.surface.primary": "#ffffff"
}
/* Then used everywhere appropriate */

The “Magic Number” anti-pattern:

/* Arbitrary values without system */
{
  "spacing-a": "13px",
  "spacing-b": "17px",
  "spacing-c": "22px"
}

/* Should follow a scale */
{
  "spacing.sm": "8px",
  "spacing.md": "16px",
  "spacing.lg": "24px"
}

Key Considerations

• Anti-patterns often feel right in the moment
• Scale reveals anti-pattern problems
• Refactoring away from anti-patterns is costly
• Prevention through education is most effective
• Code review catches anti-patterns early
• Documentation should show positive patterns
• Team agreement on patterns prevents divergence
• Periodic audits identify emerging anti-patterns

Common Questions

What are the most damaging anti-patterns?

Damaging anti-patterns are those that compound over time and resist fixing.

The “Token Per Use Case” anti-pattern:

/* Every unique usage gets a token */
{
  "login-button-background": "...",
  "signup-button-background": "...",
  "checkout-button-background": "...",
  "dashboard-button-background": "..."
}

/* Problem: Impossible to maintain consistency
   Fix: Semantic tokens applied to use cases
   "color.action.primary" used for all primary buttons */

The “Shallow Tokens” anti-pattern:

/* Tokens that are just renamed values */
{
  "blue": "#3B82F6",
  "padding": "16px"
}

/* Problem: No abstraction benefit, breaks on change
   Fix: Proper primitive → semantic layers */

The “Token Soup” anti-pattern:

/* No organization or hierarchy */
{
  "thing1": "...",
  "primary": "...",
  "spacing-medium": "...",
  "HEADING_COLOR": "...",
  "card.bg": "..."
}

/* Problem: Impossible to navigate, predict, or maintain
   Fix: Consistent naming and categorization */

How can anti-patterns be identified in existing systems?

Detection helps remediate before problems grow.

Duplication detection:

function findDuplicates(tokens) {
  const valueMap = new Map();
  const duplicates = [];

  tokens.forEach(token => {
    const existing = valueMap.get(token.value);
    if (existing) {
      duplicates.push([existing, token.name]);
    } else {
      valueMap.set(token.value, token.name);
    }
  });

  return duplicates;
}

Pattern analysis:

Warning signs in token audit:
- Many tokens with same/similar values
- Token names containing component names
- Inconsistent naming patterns
- No clear hierarchy (flat structure)
- Unused tokens accumulating
- New tokens for every feature

Usage analysis:

// Find tokens used only once
function findSingleUseTokens(tokens, codebase) {
  return tokens.filter(token => {
    const usages = countUsages(token.name, codebase);
    return usages === 1;
  });
}

How can anti-patterns be remediated?

Remediation involves refactoring toward better patterns.

Consolidation:

/* Before: Duplicated values */
{
  "header-bg": "#fff",
  "card-bg": "#fff"
}

/* After: Single semantic token */
{
  "color.surface.primary": "#fff"
}
/* Update usages to reference the semantic token */

Restructuring:

Remediation steps:
1. Audit current tokens for anti-patterns
2. Design target architecture
3. Create migration mapping
4. Deprecate old tokens
5. Add new tokens following patterns
6. Migrate usages incrementally
7. Remove deprecated tokens

Process improvement:

Prevent recurrence:
- Add linting rules
- Update contribution guidelines
- Review new tokens against patterns
- Train team on correct patterns

Summary

Token anti-patterns are problematic approaches that seem reasonable initially but cause significant problems at scale. Common anti-patterns include creating tokens per use case, shallow tokens without abstraction, and disorganized token collections. Detection through duplication analysis and pattern review identifies existing anti-patterns. Remediation involves consolidation, restructuring, and process improvements to prevent recurrence. Early recognition and prevention are far less costly than later remediation.