Primitive vs Semantic Tokens

The difference between raw value tokens and purpose-driven tokens. Understanding this distinction is essential for scalable design systems.

All Dictionary

The difference

Primitive tokens store raw values. They describe what the value is.

blue-500 = #3B82F6
gray-100 = #F7F6F3
spacing-4 = 16px

Semantic tokens reference primitives and add meaning. They describe what the value is for.

color.background.primary = blue-500
color.text.muted = gray-500
spacing.card.padding = spacing-4

Why this matters

Semantic tokens are what components should use because they adapt across themes and brands. If you switch from a light theme to a dark theme, color.background.primary can point to a different primitive without touching a single component.

The rule

  • Primitives = the palette. Never use directly in components.
  • Semantic tokens = the vocabulary. Always use in components.
  • If you see blue-500 in a component file, it should be color.background.primary instead.

Common mistakes

  • Using primitive tokens directly in Figma components (breaks when you add themes)
  • Creating semantic tokens that are too specific (button-primary-hover-background instead of color.interactive.hover)
  • Skipping the semantic layer entirely and going straight from primitives to components