Here's a failure mode that plays out on a predictable schedule, and I've watched it happen enough times to recognize the stages. A team adopts semantic token naming — color-surface-interactive instead of color-blue-500 — and for about six months, everything feels right. The system is self-documenting. Developers guess correctly without reading the docs. Then the product grows. A second brand gets added. A new surface type appears that doesn't map cleanly to existing intent names. Someone adds color-surface-interactive-secondary. Then color-surface-interactive-secondary-hover. Then color-surface-interactive-secondary-hover-disabled.
The naming convention that was supposed to reduce maintenance overhead has become the maintenance overhead.
Back in May, I argued that semantic names age better than descriptive ones. That's still true. But "semantic naming is good" is not the same as "semantic naming scales infinitely," and conflating the two is where teams get into trouble.
The Architecture Problem Naming Alone Can't Fix
The real issue isn't whether to use semantic names — it's what semantic names are actually doing in your system. Most teams treat naming as a documentation layer. The name describes intent; the value delivers it. That's fine at small scale. At multi-brand scale, it breaks.
Shane P. Williams writes about this directly: value-based naming "bakes the specific value into the contract, which means the moment that value needs to change, or needs to be different per brand, the name either breaks or lies." The fix he proposes is a mode-based cascade — semantic tokens that resolve differently per brand context, rather than a flat list of intent names that grows with every new surface type.
The distinction matters because it changes what you're actually maintaining. A flat semantic layer with 200 tokens is still a flat list. A mode-based cascade with 40 semantic tokens that resolve across 5 brand contexts is a different architecture — one where adding a brand doesn't add tokens, it adds a mode. The naming convention is the same; the structure underneath it is completely different.
When Semantic Names Become a Naming Treadmill
The taxonomy pattern documented by Honcho — category.concept.property.variant.state — is genuinely useful as a structural guide. color.background.surface.elevated.hover is parseable, predictable, and tooling-friendly. The problem is that this pattern is infinitely extensible in the wrong direction. Every new variant, every new state, every new component-level exception gets its own node in the tree.
What starts as a principled hierarchy becomes a taxonomy that requires a map to navigate. And unlike value-based names, which at least fail obviously when the value changes, semantic names fail silently — the name still sounds intentful even when it's been stretched to cover something it was never designed for.
The DTCG specification pushes toward a three-layer model: primitives, semantic tokens, and component tokens. That structure is the right answer to the treadmill problem, but only if teams actually enforce the layer boundaries. Component-level tokens are where you handle the exceptions — not by adding more semantic names, but by letting components own their specific overrides while the semantic layer stays stable.
The reference token pattern makes this concrete: color-action-primary points to blue-500, and when the brand changes, you update the alias mapping rather than every component. The semantic layer stays small and stable; the primitive layer absorbs the variation. That's the architecture doing the work, not the naming convention.
The Signal That Your Naming Has Outrun Your Architecture
There's a practical test for whether your semantic layer has become overhead: count how many tokens a new developer has to learn before they can use the system correctly. If the answer is "most of them," the layer isn't semantic anymore — it's just a differently-shaped list of values.
The agent-readiness analysis of 50 design system token files found that most token files tell a consumer "what a value is without telling it what the value means." That's a naming problem, but it's also a structure problem. A token named color-surface-interactive still doesn't tell you whether it applies to buttons, links, form inputs, or all three. The name communicates intent; it doesn't communicate scope.
The fix isn't more granular names. It's metadata — usage guidance, component bindings, exclusion rules — attached to tokens as a separate layer. The name stays stable; the context travels with it.
What This Means for Your Next Token Audit
Semantic naming is still the right default. But if you're heading into a token audit, the question to ask isn't "are our names semantic enough?" It's "are our names doing work that our architecture should be doing instead?"
If your semantic layer has grown past roughly 60-80 tokens and keeps growing, that's a signal the layer boundaries aren't holding. The solution is usually to push variation down into component tokens and push brand differentiation into modes — not to keep extending the semantic namespace.
The naming convention is a surface. The architecture underneath it is what actually scales.
