Design Token Hierarchy — Primitive, Semantic, and Component

Three-Tier Token Hierarchy

Production design systems often use three layers of tokens. Each layer adds specificity and narrows the scope of decisions.

Layer 1: Primitive Tokens

Raw color values with no meaning attached:

:root {
  --blue-50:  #eff6ff;
  --blue-500: #3b82f6;
  --blue-900: #1e3a5f;
  --gray-50:  #fafafa;
  --gray-800: #27272a;
  --gray-950: #0a0a0b;
}

Layer 2: Semantic Tokens

Abstract roles referencing primitives:

:root {
  --bg:          var(--gray-50);
  --text:        var(--gray-950);
  --primary:     var(--blue-500);
  --border:      var(--gray-200);
}

html.dark {
  --bg:          var(--gray-950);
  --text:        var(--gray-50);
  --primary:     var(--blue-400);
  --border:      var(--gray-800);
}

Layer 3: Component Tokens

Scoped variables for specific components:

:root {
  --button-bg:      var(--primary);
  --button-text:    white;
  --button-radius:  0.375rem;
  --card-bg:        var(--bg);
  --card-border:    var(--border);
  --input-bg:       var(--bg);
  --input-border:   var(--border);
}

When to Use Each Layer

Decision	Layer
"What blue is this?"	Primitive
"What role does this color play?"	Semantic
"What does this component look like?"	Component

Maintenance Benefits

When marketing says "make our blue warmer," you change one primitive token. When design says "error state should feel softer," you remap one semantic token. When engineering says "buttons need more rounding," you update one component token. Each concern is isolated.

Tooling

The CSS Variable Generator outputs Layer 1 (primitive) and Layer 2 (semantic) tokens. Layer 3 tokens are typically added per-component during development.