Design Token Architecture: From Primitives to Semantic to Component

The three layers

Think of design tokens as a stack. Each layer has a specific job, and each layer only talks to the one directly below it.

Each layer has a clear boundary. Primitives never appear in component styles. Component tokens never reference primitives directly. The semantic layer is the bridge.

Layer 1: Primitives

Primitive tokens are your raw materials. Hex codes, pixel values, font stacks, easing functions. They are named after what they are, not what they do. --indigo-500 is an indigo. --space-4 is 16px. --radius-lg is 12px.

Primitives are the only layer where raw values (hex, px, rem) appear. Everything above is a reference. This constraint is what makes the system auditable. If you need to know every place a specific hex code is used, you check one place: the primitive definition.

Why primitives matter

Without primitives, your semantic tokens contain hardcoded values. --color-accent: #6366F1 looks fine until you realize that same hex appears in --color-accent, --color-link, and --color-focus-ring. If the brand color changes, you need to find and update all three. With primitives, all three reference var(--indigo-500), and you update one line.

Layer 2: Semantic tokens

The semantic layer is where meaning is assigned. A primitive says "this is indigo at 500 lightness." A semantic token says "this is the accent color." The distinction unlocks everything: theming, dark mode, multi-brand support, and AI comprehension.

The semantic layer is also the theming boundary. To switch from light to dark mode, you reassign the semantic layer to different primitives. Components never change. For a deep dive into semantic naming, read about design tokens for AI.

How many semantic tokens do you need?

For color, most products need 12 to 18 semantic tokens. Background, surface (with hover), text (with muted), border, accent (with hover and soft), and three state colors (success, warning, error). If you have 40+ semantic tokens, you are likely encoding component-level decisions at the wrong layer.

Layer 3: Component tokens

Component tokens are the most specific layer. They answer: "What does this specific UI element look like?" A button has a background, text color, border, and focus ring. Each of those references a semantic token.

Are component tokens always necessary?

No. For small projects or early-stage products, two layers (primitives + semantic) are often enough. Component tokens become valuable when you have a complex component library, multiple teams consuming the same tokens, or when you need to override individual component styles without affecting the global theme.

The rule of thumb: if you find yourself writing var(--color-accent) in a button component and wishing you could change it for just buttons, you need a component token.

How the layers interact

The critical rule is: each layer only references the one below it. Component tokens reference semantic tokens. Semantic tokens reference primitives. Primitives hold raw values.

This means three types of changes are each handled at exactly one layer:

Brand color change (new hex value): Update the primitive. --brand-500: #6366F1 becomes --brand-500: #7C3AED. Every semantic and component token that references it updates automatically.

Theme switch (light to dark): Reassign the semantic layer. --color-bg points to a different primitive. Components don't change at all.

Component redesign (button gets a new style): Update the component token. --button-primary-bg could reference a different semantic token or even a new primitive. Nothing else in the system is affected.

Real-world examples

Shopify Polaris

Polaris uses a three-layer architecture with primitives (color scales), semantic aliases (surface, text, decorative), and component-specific tokens. Their --p-color-bg-surface is a semantic token. Their --p-color-bg-surface-secondary adds specificity for nested surfaces.

Material Design 3

Material uses "tonal palettes" as primitives (primary0 through primary100), "color roles" as semantic tokens (primary, onPrimary, primaryContainer), and component tokens per widget (buttonPrimary, chipOutline). The tonal palette is generated algorithmically from a single seed color.

SeedFlip seeds

Each SeedFlip seed provides two layers out of the box. Primitives (the raw hex values in the palette) and semantic tokens (bg, surface, text, accent, muted, border, and all derived variants). You add the third layer (component tokens) based on your specific UI components. This approach is explained in detail in CSS custom properties explained.

Building the architecture yourself

Start with semantics, not primitives. Define the roles your interface needs first, then create the primitive palette to fill them.

This roles-first approach prevents primitive bloat. You only create the palette entries you actually need, and every primitive has at least one semantic consumer. No orphan tokens. For the complete list of tokens most products need, see design variables that actually matter.

The three-layer token architecture is not academic theory. It is the pattern that every mature design system converges on because it solves the three most common scaling problems: brand changes, theme switches, and component redesigns. Each happens at exactly one layer. Nothing bleeds across boundaries. Start with the semantic layer, build primitives to support it, and add component tokens when your component library demands it.