Here's the failure mode: you spend a week naming tokens correctly. color-action-primary, color-feedback-danger, color-surface-overlay. The names communicate intent. They survive a rebrand. They're the kind of thing that gets praised in design system reviews.
Then a product team needs a new component in two days, and nobody can remember whether the disabled state of a secondary button uses color-action-secondary-disabled or color-interactive-muted or color-text-on-surface-subdued. They open the token docs, find three plausible candidates, pick the one that looks right, and move on. You've now got inconsistency — not because the naming convention was wrong, but because it was too abstract to be usable under time pressure.
This is the core tension with semantic token naming that rarely gets addressed honestly: the same properties that make semantic names durable make them slow to use.
The Three-Tier Architecture Is Correct and Insufficient
The three-tier model — primitives, semantic tokens, component tokens — has become the de facto standard for a reason. GitHub Primer, Atlassian, and Shopify Polaris have all converged on it, and the convergence isn't coincidence. The architecture solves real problems: it creates a single swap point for theming, it separates raw values from intent, and it prevents components from hardcoding blue-500 directly.
GitLab's Pajamas system articulates the logic clearly: a token like text.color.subtle communicates both what it applies to and its relative visual weight, which is genuinely useful when you're auditing a system or onboarding a new designer.
The problem isn't the architecture. The problem is that semantic names optimize for the person maintaining the system, not the person using it under deadline. When you're building a new card component at 4pm on a Thursday, color-surface-overlay requires you to hold a mental model of the entire token hierarchy to use correctly. gray-100 requires nothing.
Artofstyleframe's token guide puts it plainly: "Skip the semantic layer and you glue components directly to raw values. That feels faster on day one." The implicit admission is right there — it does feel faster, because for a single developer on a single component, it often is faster.
The Abstraction Cost Compounds at the Semantic Layer
The real velocity hit isn't naming tokens — it's the cognitive overhead of resolving them at point of use.
Primitive tokens are easy to reason about. blue-500 is a color. space-4 is 16px. You know what you're getting. Semantic tokens require you to understand the system's intent model: what counts as "action" vs. "interactive" vs. "brand"? Is a destructive button action or feedback? Does color-surface-inset apply to the inside of a card or just to nested containers?
Polar's writeup on their Orbit design system frames this as a problem of the "author" changing — in their case, from humans to LLMs — but the underlying issue applies to human developers too. When the token surface is open-ended, developers reach for whatever looks plausible. The result is what Polar describes as "a thousand slightly different grays" — not because anyone was careless, but because the naming didn't constrain the decision space tightly enough at the moment of use.
This is where semantic naming creates a specific kind of debt: the tokens exist, the names are correct, but the actual usage is inconsistent because the mapping from "I need a muted text color" to the right token name requires knowledge that isn't in the token name itself.
When Semantic Names Actually Pay Off
None of this means semantic naming is wrong. It means the payoff is deferred and conditional.
The semantic layer earns its keep in two specific situations. First, theming: if you need dark mode, white-label variants, or brand experiments, the semantic tier is the swap point — redefine color-action once and every component that references it updates. Without that indirection, dark mode becomes a manual audit of every hardcoded value. Second, scale: once a system has multiple teams consuming it, semantic names create a shared vocabulary that reduces the surface area for disagreement. bgColor-inset means the same thing to the team building the settings page as it does to the team building the dashboard.
The mistake is applying enterprise-scale token architecture to a team that isn't there yet. Luis Ouriach's piece on design system architecture makes the governance point implicitly: the complexity of extended collections, cascading overrides, and delta exports only makes sense when you have multiple verticals with competing release cycles. Before that, it's overhead.
The Practical Heuristic
If your team can't correctly identify which semantic token to use for a new component without opening the docs, your semantic layer is too abstract for your current team size. That's not a failure of the naming convention — it's a signal that you've built for a future state that hasn't arrived.
Start with primitives and component tokens. Add the semantic layer when you have a concrete theming requirement that demands it, not because the architecture is theoretically correct. The three-tier model is the right destination. It's a poor starting point for a team of four.
The tokens that slow you down aren't the ones with bad names. They're the ones that require a map to use.
