skip to content

In a design system with primitive, semantic and component token tiers, what does each tier hold, and which tier should product screens reference?

level: juniorimportance: must knowfreq 64%

answer

  1. raw options vs recorded decisions
  2. purpose, not appearance
  3. brand blue behind the primary action
  4. component tier scoped to one part

basics

~20 s

Primitive tokens hold raw options such as every blue in the palette, semantic tokens alias them by purpose such as the primary-action color, and component tokens scope a decision to one component. Product screens reference semantic tokens.

solid answer

~40 s

A **primitive** token names a raw option with no intent: `color.blue.600` is simply one blue. A **semantic** token names a decision and aliases a primitive: `color.action.primary` points at that brand blue, so everything that means "primary action" gets it. A **component** token scopes a decision to one part of one component, such as the primary button's background, and usually aliases a semantic token. Product screens should reference the semantic tier, or use library components that already do, because the reference then records *why* the color is there: when the system re-points the primary action, every screen follows. Referencing the primitive, or pasting its value, ties the screen to an appearance the system is free to change.

go deeper

for a junior

Name the three tiers, give one example of each, and state clearly that product screens reference semantic tokens, not primitives or pasted values.

for a middle

Trace one decision from primitive to screen and show that re-pointing one semantic alias moves every primary action while the primitive itself stays unchanged.

for a senior

Show what goes wrong in practice: primitives referenced directly, semantic gaps filled with raw values, and how you make the semantic tier the easy path for many teams.

for a principal

Treat the tiers as a contract: decide which tiers are public and which stay internal to the library, and explain how that choice limits future brand or theme changes.

## What a design token is A **design token** is a named design decision — a color, a spacing step, a corner radius, a motion duration — stored once in a platform-neutral source and delivered to every place the system ships: web apps, native mobile apps and the shared library inside a design editor. Tokens exist so that a value is decided once instead of being copied by hand into hundreds of files. Most mature systems do not keep their tokens on one flat list. They arrange them in **tiers**, where a token in a higher tier holds no value of its own but refers to a token in a lower tier. That reference is called an **alias**. ## The three tiers | Tier | Other common names | What it holds | Example | Typically referenced by | |---|---|---|---|---| | **Primitive** | base, core, global, option | A raw value with no stated purpose | `color.blue.600`, one specific brand blue | Semantic tokens | | **Semantic** | alias, decision, system | A purpose, expressed as an alias to a primitive | `color.action.primary` aliasing `color.blue.600` | Product screens and library components | | **Component** | component-specific | One component's decision, usually an alias to a semantic token | `button.primary.background` aliasing `color.action.primary` | That component's implementation | The **primitive** tier is the menu of options: every blue, every gray, every step of the spacing scale. A primitive answers "what values exist?" and says nothing about where they belong. The **semantic** tier answers "what is this value for?" It names decisions such as the primary-action color, the default text color or the error surface, and each one points at a primitive. The **component** tier, where a system has one, narrows a decision to one part of one component, so that part can later be set differently without changing the shared decision. ## Following one decision through the tiers Take a ride-hailing driver app whose design system uses a brand blue for its most important actions: 1. The palette defines `color.blue.600` as the brand blue. It is a primitive: just a color. 2. The system decides that primary actions use that blue, so the semantic token `color.action.primary` aliases `color.blue.600`. 3. The button component's primary variant reads `button.primary.background`, which aliases `color.action.primary`. 4. The accept-ride screen and the go-online screen use the primary button. Neither screen mentions blue anywhere. Now suppose a brand refresh moves primary actions to a different color. The system re-points one alias, `color.action.primary`, and every primary action — accept ride, go online, confirm drop-off — follows in the next release. The primitive `color.blue.600` did not change: it is still the same blue, still available to anything that truly means "that blue". ## Which tier a product screen should reference - **Product screens reference semantic tokens**, or use library components that already carry them. The question to ask is about meaning: is this a primary action, secondary text, an error, a selected state? - **Library components reference component tokens** where the system defines them, and semantic tokens otherwise. - **Primitives are referenced mainly by semantic tokens.** Many systems hide primitives from product teams or mark them as not for direct use, because a direct reference quietly opts that spot out of every future change to the decision it was standing in for. - **When no semantic token fits, raise it** with the system team rather than reaching for a primitive or pasting a value. A missing semantic token is a gap in the system, and filling it helps every other team with the same need. Some systems allow a documented primitive reference for one-off content such as an illustration; that should be a deliberate exception, not the default. ## Common confusions - **Tiers are a convention, not part of the token format.** The Design Tokens Community Group format defines aliases — a `$value` that holds a reference to another token in curly braces — but it does not define or require any tiers. Teams choose how many to have. - **Not every system has a component tier.** Two tiers, primitive and semantic, is common and enough for many systems; the component tier is added when components need to diverge from shared decisions. - **Tiers are not only for color.** Spacing, radius, typography, elevation and motion use the same shape: a scale of raw options, semantic tokens that name uses, and optional component tokens. - **A copied value is not a reference.** Pasting a token's current value into code looks identical on screen today, but it has no link to the system, so the next change never reaches it.

  • If no semantic token fits what a screen needs, should the team reference a primitive directly?
    Usually not. A direct primitive reference works today but opts that spot out of every future change to the decision it stands in for. Raise it with the system team: either an existing semantic token fits once the intent is stated plainly, or the system is missing a decision, and adding it helps every team with the same need. A documented primitive reference for one-off content, such as an illustration, can be a deliberate exception.
  • Do token tiers apply only to color?
    No. Spacing, radius, typography, elevation, border widths and motion durations use the same shape: a primitive scale of raw options, semantic tokens that name uses such as the gap between list items or the default card radius, and component tokens where a component needs its own knob. Color gets the most attention because it carries the most meaning and changes most visibly.

saying these in an interview costs you the question

  • Product screens should reference primitives because primitives are the real source of truth.
  • A semantic token is just a second name for the same color, so it adds nothing.
  • Copying a token's current value into code is the same as referencing the token.
  • Every design system must have exactly three token tiers.
  • The tier structure is defined by the Design Tokens Community Group format.