Three weeks ago I wrote about premature semantic layers — the failure mode where teams build elaborate alias hierarchies before they have enough product surface to justify them. Today I want to go one level more specific: the naming conventions themselves, and the hidden iteration cost they carry.
Here's the friction point. You've committed to semantic token names. You've read the right articles, you understand that color-action-primary-bg-hover ages better than blue-500-hover. That's true. But there's a cost nobody mentions until you're three sprints in and every new component requires a naming committee.
The Grammar Is Right. The Overhead Is Real.
A recent practitioner essay on Medium makes the case for semantic naming with genuine clarity: a token name is a sentence with grammar, and every slot in that name answers a different question. color-action-primary-bg-hover reads as a color, in service of an action, meaning "the primary one," applied to the background, in the hover state. That's elegant. It holds together. If you're maintaining a system across dozens of engineers and multiple product surfaces, that grammar pays for itself.
The same essay also admits something most token evangelism skips: "there's no single right way to name tokens." That caveat is doing a lot of work. Because the grammar that makes color-action-primary-bg-hover legible also makes it expensive to author. You have to decide the category, the role, the concept, the property, and the state — in the right order — every time you add a token. Get one slot wrong and you've introduced an inconsistency that will confuse the next person as much as button-primary-label-text confuses you now.
GitLab's Pajamas documentation shows what full semantic naming looks like at scale. Their full naming pattern is: [group].[component].[variant/category].[element].[position].[relationship].[property].[type].[scale].[state]. Ten slots. The guidance is to "add the level of specificity needed for clarity by only including necessary parts of the pattern" — which is sensible, but also means every token author is making a judgment call about which slots to include. That judgment call is where teams diverge, and divergence is where the system quietly forks.
This is the overhead that doesn't show up in the architecture diagram. It shows up in the PR where someone added button-label-text-filled and someone else added button-primary-label-text and both are in production and nobody's sure which one is canonical.
The Velocity Signal You're Probably Ignoring
The tell that your naming convention is slowing iteration isn't a dramatic incident. It's a slow accumulation of small hesitations. Developers pause before adding a token because they're not sure where it fits in the hierarchy. Designers propose names that don't match the engineering convention. Someone adds a one-off value directly in the component rather than authoring a new token, because authoring the token feels like more work than the feature warrants.
The DEV Community post on design token layers frames the core problem as a "UI review tax" — the time spent verifying that new components match existing ones. The argument is that a well-structured token layer eliminates that tax by making consistency automatic. That's correct. But a naming convention that's too complex to apply consistently creates a different tax: the authoring tax, paid every time someone needs to add or modify a token and has to reason through a ten-slot grammar to do it.
The review tax and the authoring tax are in tension. Semantic naming reduces the review tax. It increases the authoring tax. At startup scale, where the team is small and the product surface is changing fast, that tradeoff often lands differently than the enterprise case studies suggest.
Where to Draw the Line
The practical answer isn't "use primitive names" or "use semantic names." It's about where you invest the semantic layer and where you don't.
Figma design system guidance from Atomize recommends a tokens-first architecture with primitives and semantic aliases — but notes that the naming convention should be shared between design and engineering, not owned by one side. That shared ownership is the constraint that matters. A naming convention that only designers can apply fluently, or only engineers can implement correctly, is already broken.
The Masterly's roundup of public design systems notes that Shopify Polaris and GOV.UK have the best documentation in the industry specifically because they explain when and why to use a pattern — not just what it looks like. That's the model worth copying: document the intent behind your naming decisions, not just the convention itself. When a developer understands why color-action is a different category than color-feedback, they can apply the grammar without a committee. When they're just pattern-matching on examples, they'll diverge the moment they hit a case the examples don't cover.
The signal that your semantic layer is working: developers author new tokens without asking. The signal it's failing: they hardcode values instead.
If your team is hardcoding, the problem probably isn't discipline. It's that the naming convention costs more to apply than the token is worth. That's a system design problem, not a culture problem — and it's worth treating it as one.
