Book a call

WritingFoundations & tokensPart 3 of 5 in Building components well

Component tokens: when you need a third tier, and when you don't

Component tokens are powerful and easy to overdo: ten components with ten tokens each is already a hundred names. When the third tier earns its place, how to map a component's anatomy to tokens, and how to name them.

On this pageWhere component tokens fit
  1. Where component tokens fit
  2. When a component deserves its own tokens
  3. Mapping a component's anatomy to tokens
  4. Naming them
  5. How it works in code and in Figma
  6. Keeping them healthy
  7. The short version
  8. Frequently asked questions
  9. Further reading

The short answer

Component tokens are the third tier of design tokens: names for one property of one component, like button.primary.container.background, that point to a semantic token like color.action.primary.bg. Most single-brand products with light and dark mode don't need them: components can use semantic tokens directly. Create component tokens when you have a reason: brands that style specific components differently, white-label products where customers adjust components, a component that genuinely departs from the semantic rule, or platform-specific sizes. Then create them only for the properties that vary.

  • Never let components use primitive tokens or raw values. That's where dark mode breaks first.
  • Name them {component}.{variant}.{part}.{property}.{state}, using the anatomy's part names.
  • Component tokens multiply fast: ten components with ten tokens each is already a hundred names to maintain.

Where component tokens fit

Tier 1 · PrimitiveWhat it is

Raw values with neutral names. Components never use these directly.

color.brand.700radius.4
→
Tier 2 · SemanticWhat job it does

Names a purpose and points to a primitive. Enough for most components.

color.action.primary.bgradius.control
→
Tier 3 · ComponentWhere it's used

Names one property of one component and points to a semantic token. Optional.

button.primary.container.backgroundbutton.container.radius
The three tiers. Component tokens sit on top and only exist where a component needs to vary on its own. See design tokens for the first two tiers.

There are two good ways for a component to get its values, and one bad one:

GOOD

Semantic tokens

The button's background is action.primary.bg. Simple, and enough for most single-brand products.

GOOD

Its own tokens

The background is button.primary.container.background, pointing to action.primary.bg. More flexible, more to maintain.

BAD

Primitives or raw values

The background is brand.700 or #AB2800. Dark mode and theming break here first.

An illustration: dark mode works everywhere except the date picker

The situation

A product launches dark mode. Every screen looks right except the date picker, whose selected day stays bright orange on a white square.

The cause

The date picker was built in a hurry using brand.700 and neutral.50 directly. Those are paints, not jobs, so dark mode had no way of switching them.

The fix

Point it at job names (action.primary.bg, bg.surface) and add a lint rule that flags any component using primitives. One component fixed; a whole class of bugs prevented.

When a component deserves its own tokens

SituationComponent tokens?Why
One brand, light and dark modeUsually noSemantic tokens already switch with the theme
Several brands that differ only in colourUsually noA brand level under the semantic tokens handles it
Brands that style specific components differentlyYesEach brand overrides just those components' tokens
White-label products customers can adjustYesA safe, limited list of things customers can change
A component that departs from the semantic ruleYes, for that partRecords the exception in one visible place instead of hiding it in code
Native apps with platform-specific sizesYes, for sizesiOS and Android can map sizes to their own guidelines
A decision guide. Practitioner view Even Nathan Curtis has cautioned that the industry may focus too much on tokens at the expense of the rest of a system. Create them for a reason, not by default.

A good middle path, used by many teams, is to create component tokens only for the properties that vary. A system might give buttons a button.container.radius token because one brand wants pill-shaped buttons, while the button's colours keep using semantic tokens directly. The token list stays short and every token has a reason.

Mapping a component's anatomy to tokens

Start from the component's anatomy. For each part, ask which visual properties could ever change with a theme, a brand, a density or a platform. Those come from tokens. Properties that never change (the label sits above the field) are just part of the design.

PartPropertyComponent tokenPoints toChanges with
LabelColourinput.label.colortext.primaryTheme
ContainerBackgroundinput.container.backgroundbg.surfaceTheme
ContainerBorderinput.container.borderborder.strongTheme
ContainerBorder, errorinput.container.border.errorfeedback.danger.textTheme
ContainerBorder, focusinput.container.border.focusfocus.ringTheme
ContainerHeightinput.container.heightsize.control.heightDensity
ContainerCornersinput.container.radiusradius.controlBrand
Helper textColourinput.helper.colortext.secondaryTheme
A text field's anatomy mapped to tokens. Even if you decide not to create component tokens, this map tells you exactly which semantic tokens the component must use.

Naming them

{component}.{variant}.{part}.{property}.{state}

button.primary.container.background          // default state left out
button.primary.container.background.hover
button.primary.label.color
input.container.border.error                 // no variant needed
table.row.background.selected
  • Use the anatomy's part names, so the token, the anatomy diagram and the Figma layer names match.
  • Leave out levels that don't apply rather than inventing filler like "default".
  • Use the same property words everywhere: if one component says background, none should say bg or fill.
  • Test with a newcomer: show someone a component's anatomy and ask them to guess the token for the error border. If they can't, simplify.

More in design token naming conventions.

How it works in code and in Figma

Here's the whole point in one example: a second brand gets pill-shaped buttons by changing one value, and no component code changes.

/* generated from the token files */
:root {
  --button-container-radius: var(--radius-control);
  --button-primary-container-background: var(--color-action-primary-bg);
}
/* brand B overrides one component token */
[data-brand="b"] { --button-container-radius: 999px; }

/* Button.css never changes */
.button { border-radius: var(--button-container-radius); }

In Figma, the same tokens become variables attached to the component's layers, with modes for each brand or theme. When the variable names match the token names, switching a mode restyles every component exactly as the code does. See keeping Figma and code in sync.

Keeping them healthy

CheckWhat it findsHow
Raw values in componentsColours or sizes typed directly into component stylesA lint rule on every change
Primitives in componentsThe date picker problemA lint rule allowing only semantic and component tokens
Unused tokensTokens nothing uses any moreA script comparing the token list with usage
Missing tokensProperties that should change with themes but don'tSwitch every theme and density in the workshop and look
Figma–code mismatchVariables that don't match tokensCompare the exported variable list with the token source
A light quarterly audit. Before changing any token, check its blast radius: which components and products use it.

The short version

  • Component tokens are optional; semantic tokens are enough for most products.
  • Create them for brands, white-label, real exceptions or platform sizes, and only for properties that vary.
  • Components must never use primitives or raw values.
  • Name them from the anatomy: component, variant, part, property, state.
  • Audit quarterly for raw values, primitives, unused and missing tokens.

Frequently asked questions

What are component tokens?

Tokens that name one property of one component, like button.primary.container.background, and point to a semantic token. They're the optional third tier after primitive and semantic tokens.

Do I need component tokens for dark mode?

Usually not. Semantic tokens switch with the theme. Component tokens help when brands or customers need to restyle specific components.

How many component tokens should a system have?

As few as possible. Create them only for properties that genuinely vary by brand, customer or platform.

Can component tokens point to primitives?

Avoid it. Point them to semantic tokens, so themes still work. A component token pointing at a primitive is the date picker problem one level up.

Further reading