Component-Level Tokens: Why Button Tokens Beat Global Tokens

The cascading breakage problem

Semantic tokens are a huge improvement over raw values. But they create a new problem: over-coupling. When your primary button, link underline, badge background, focus ring, and chart accent all use var(--color-accent), any change to that token ripples through every component simultaneously.

Sometimes that is exactly what you want. A brand color change should update everything. But sometimes you want to adjust the button's hover state without affecting the focus ring, or darken the badge background without changing the link color. Semantic tokens alone do not give you that granularity.

You suspected this was a problem the first time you changed a global token and something unexpected broke. You were right.

What component tokens look like

Component tokens sit on top of semantic tokens. They reference the semantic layer by default but can be overridden independently.

By default, --button-bg resolves to the same value as --color-accent. But now you can override --button-bg independently without touching the global accent. The card, input, and every other component are unaffected.

When component tokens are worth the overhead

Component tokens add a layer of indirection. That is not free. Every layer has a maintenance cost. Here is when the cost is justified:

Multiple consumers of the same semantic token

If --color-accent is used by buttons, links, badges, and focus rings, component tokens let you decouple them. Each consumer gets its own override point.

Complex interactive states

Buttons need hover, active, disabled, and loading states. Each state may need different values for background, text, and border. Encoding all of this in semantic tokens pollutes the semantic layer with component-specific concerns.

Variant-heavy components

A button with primary, secondary, outline, and ghost variants. Each variant has different colors but the same structure. Component tokens make variants a token swap rather than a style rewrite.

This pattern is how shadcn/ui handles button variants under the hood. The visual template is constant. Only the token values change per variant. For the full picture on how shadcn/ui theming works, see customizing shadcn/ui globals.css.

The naming convention

Component token names follow a consistent pattern: --{component}-{property}, optionally with a state or variant suffix.

When to skip component tokens

Not every project needs the third layer. Two layers (primitives + semantic) are sufficient when:

Small team or solo developer. If one person controls all the components, the overhead of an extra layer may not pay off. You already know which components use which tokens.

Simple component library. If your UI has buttons, cards, and inputs with one variant each, semantic tokens cover it. Component tokens become valuable when you have multiple variants with complex state.

Early-stage product. Ship first, optimize later. You can always add component tokens later by wrapping existing semantic references. The refactor is mechanical.

Component tokens in practice

Here is a complete example showing how a card component uses all three token layers:

Now you can override any card property without touching the semantic layer. Need a card with no shadow? Set --card-shadow: none. Need a card with a colored border? Set --card-border: var(--color-accent). The override is scoped to the card and nothing else changes.

For the complete guide to building a token system from the ground up, read about CSS custom properties explained. To understand which variables every product needs at the semantic layer, see design variables that actually matter.

Component tokens are the third layer that most projects skip. When your system is small, you do not miss them. When your system scales and a single token change breaks three components, you wish you had them. The overhead is minimal: define --button-bg: var(--color-accent) once. The insurance is enormous: every component can be adjusted independently without side effects. Start adding component tokens to your highest-traffic components first, and expand the layer as your system grows.