Six Common Mistakes in Design Tokens Naming

Back to Devoured - September 17, 2026

DEVOURED

Six Common Mistakes in Design Tokens Naming

Design frontend Substack

Poor design token naming conventions often stem from baking specific values or temporary component needs into names, leading to long-term governance debt.

What: Common naming pitfalls include naming tokens after components, embedding values like colors or pixels in names, and inconsistent ordering of name segments.

Why it matters: Design tokens are essentially the API of a design system; failing to abstract them properly makes them brittle and impossible to migrate without breaking downstream implementations.

Takeaway: Adopt an alias strategy where raw base tokens map to semantic tokens, allowing you to update brand values without needing to rename every implementation instance.

Deep dive

Component-first naming: Avoid linking tokens to specific UI elements to prevent redundant naming.
Value-based naming: Never include specific sizes or color hex codes in the token name.
Segmentation: Ensure naming order remains consistent throughout the system.
Modifier ambiguity: Words like 'primary' need explicit scope to avoid collision.
Governance: Always provide a transition path when renaming to avoid system-wide breakage.

Decoder

Design Tokens: Key-value pairs used to store visual system values like colors, spacing, and typography that act as the single source of truth for design.
Alias: A reference to another token that provides a semantic layer for better maintainability.

Original article

Weak design token names slow searches, inflate duplicates, and turn governance into guesswork, according to six recurring naming mistakes design systems teams make. Common pitfalls include naming tokens after components too early, baking current values like colors or pixel sizes directly into names, and reordering name segments inconsistently. Other traps are mixing casing and separators, using vague modifiers like "primary" without defined scope, and renaming tokens without a phased migration and alias strategy.

Explore all 60 articles in today's digest