Back

Design Systems · Token Architecture

Where flexibility should live

Push flexibility into one shared token and components get stuck. Spread it into a token per component and you maintain forty copies of the same value. Try both failure modes, then break a live example.

6 min read

0 50 100

Tokens to maintain

1

for this border

Local hardcodes

3

values the system no longer controls

  • Shared, healthy
  • Stuck / hardcoded
  • Extra / skips the system layer

Too tight

Balanced

Too loose

Try it yourself

This changes a real CSS color token — not a mock. Flip the overrides. Watch what stays in sync.

3 of 3 components in sync

Input

Always uses system/border. It has no override, so it always follows the color above.

Does this need its own token?

Three questions design systems teams ask before they add a component token.

How leaders name the system layer

Different names. Same idea: a thin, purpose-named layer between raw values and components.

Type Vois GitHub Primer Uber Base Atlassian IBM Carbon
Text system/text fgColor-default contentPrimary color.text $text-primary
Surface system/surface bgColor-default backgroundPrimary color.background.* $layer-01
Border system/border borderColor-default borderOpaque color.border $border-subtle
Icon system/icon (part of fgColor-*) contentPrimary color.icon $icon-primary
Surface overlay system/surface-overlay overlay-bgColor theme overlay elevation.surface.overlay $overlay

Not a spec — a working model. These five token names aren't the answer for every system. Put most flexibility in the semantic layer. Keep component tokens rare enough that each one still means something.

Sources