Common Token Mistakes

Common token mistakes are errors that frequently occur when creating, managing, or using design tokens. Recognizing these mistakes helps teams avoid them proactively. Learning from others’ mistakes accelerates token system maturity without experiencing the pain firsthand.

What Are Common Token Mistakes

Common token mistakes are patterns of error that recur across organizations implementing design tokens. These mistakes span token creation, architecture, naming, usage, and governance. While each organization’s context differs, certain mistakes appear consistently.

Understanding common mistakes helps teams recognize warning signs and course-correct before issues compound.

How Common Token Mistakes Manifest

Naming mistakes:

Too specific naming ties tokens to implementation:

/* Mistake */
{ "button-blue-background": "#3B82F6" }

/* Better */
{ "color.action.primary": "#3B82F6" }

Value-based naming breaks when values change:

/* Mistake */
{ "gray-500": "#6B7280" }

/* Better */
{ "color.text.secondary": "#6B7280" }

Architecture mistakes:

No semantic layer requires changing all usages:

Without semantic layer:
  components → primitives
  (Changing blue.500 affects everything)

With semantic layer:
  components → semantics → primitives
  (Can redirect semantics without touching components)

Over-tokenization creates unnecessary complexity:

/* Excessive */
{
  "button-primary-text": "{color.white}",
  "button-primary-text-default": "{button-primary-text}",
  "button-primary-text-default-normal": "{button-primary-text-default}"
}

/* Appropriate */
{
  "color.text.on-action": "{color.white}"
}

Usage mistakes:

Using primitives directly bypasses semantic meaning:

/* Mistake */
.button { background: var(--color-blue-500); }

/* Better */
.button { background: var(--color-action-primary); }

Hardcoding values that should be tokens:

/* Mistake */
.card { padding: 16px; }

/* Better */
.card { padding: var(--spacing-md); }

Key Considerations

• Mistakes compound over time if not addressed
• Early architecture mistakes are costly to fix later
• Code review should catch common mistakes
• Linting can prevent some mistakes automatically
• Education reduces mistake frequency
• Documentation should show correct patterns
• Retrospectives identify recurring mistakes
• Gradual improvement beats perfection paralysis

Common Questions

What naming mistakes are most harmful?

Naming mistakes that are most harmful are those that resist change.

Component-coupled naming:

/* Harmful: Component name in token */
"sidebar-background": "#f5f5f5"

/* Why: What if sidebar is removed? Token name is orphaned */
/* Better: Purpose-based name */
"color.surface.secondary": "#f5f5f5"

Value-based naming:

/* Harmful: Color value in name */
"blue-primary": "#3B82F6"

/* Why: Rebrand changes blue to green; name is misleading */
/* Better: Role-based name */
"color.brand.primary": "#3B82F6"

Inconsistent patterns:

/* Harmful: Mixed conventions */
{
  "color-primary": "...",
  "colorSecondary": "...",
  "COLOR_TERTIARY": "..."
}

/* Why: Unpredictable, hard to remember */
/* Better: Consistent convention */
{
  "color.primary": "...",
  "color.secondary": "...",
  "color.tertiary": "..."
}

What architecture mistakes cause the most problems?

Architecture mistakes that create rigid systems cause the most problems.

Missing abstraction layers:

Mistake: Components → Primitives directly
Problem: Theming is impossible
         Every usage must change when primitives change

Solution: Components → Semantics → Primitives
         Semantics redirect for themes
         Components unchanged

Excessive abstraction:

Mistake: 5+ layers of indirection
Problem: Impossible to trace values
         Maintenance nightmare
         Performance impact

Solution: 2-3 layers maximum
         Primitives → Semantics → (optional) Component

No governance from the start:

Mistake: Anyone can add any token
Problem: Duplicates accumulate
         Naming diverges
         No ownership

Solution: Establish contribution process early
         Review new tokens
         Define ownership

How can common mistakes be prevented?

Prevention through process and tooling reduces mistake occurrence.

Linting rules:

// Prevent primitives in component files
{
  "rules": {
    "no-primitive-tokens": "error"
  }
}

Code review checklist:

Token usage review:
- [ ] Uses semantic tokens, not primitives
- [ ] No hardcoded values that should be tokens
- [ ] Token names follow conventions
- [ ] No duplicate tokens created

Documentation of correct patterns:

## How to Add a Color

1. Check if appropriate semantic token exists
2. If not, request via #design-system
3. Never use primitives directly
4. Never create one-off tokens

Onboarding that covers mistakes:

## Common Pitfalls

New team members often:
- Use primitives directly → Use semantics
- Create component-specific tokens → Check for existing semantic
- Name tokens after values → Name after purpose

Summary

Common token mistakes include naming tokens after values or components, missing semantic abstraction layers, over-tokenizing, using primitives directly, and hardcoding values. Harmful naming mistakes are those that resist inevitable change. Architecture mistakes that create rigid systems cause the most long-term problems. Prevention through linting, code review, documentation, and onboarding reduces mistake frequency and catches issues early.