FISYCO

Public beta
The gapImpactHow it worksProductSecurity
BlogDocumentation
Sign in

Primitive and semantic tokens

A primitive token names a raw value, like blue 500. A semantic token names what a value is for, like the accent background, and points at a primitive.

All terms

Components use semantic tokens such as bg.accent, so a rebrand changes which primitive a semantic token points at, not the names in code.

Primitive vs semantic: an example

GitHub's Primer system follows this split: base tokens map directly to raw values, and functional tokens such as bgColor-inset carry the meaning (Primer token names). Primer also has a third level, component tokens such as button-primary-bgColor-hover, which point at semantic tokens.

Why the split holds up

A value name turns into a lie after a rebrand: once the accent is green, blue.500 in a component is wrong. A purpose name stays true. The palette can change, dark mode can swap the values, and components keep the same names.

The practical rule: keep primitives in a small palette layer and let components use only semantic names. A component that reaches for a primitive directly is usually a sign of design system drift starting.

  • Design token
  • Mode: a semantic token can have a different value in each mode.
  • Design tokens from Figma to code: naming tokens by purpose, step by step.