Three Tiers: Primitive, Semantic, Component

Northwind’s first token file was a list of colors: --blue-600, --gray-200, --red-500. Every component used them directly. It looked tidy until the Tidewater acquisition, when someone asked a simple question: “Which blues are Northwind brand blues, and which are just links?” Nobody could answer without reading 300 files. A flat list of colors records values. It doesn’t record decisions.

Tier 1: primitives

Primitives are the palette: every raw value the system allows, named by what it is.

:root {
  --nw-blue-600: #1f5ae0;
  --nw-blue-700: #1848b8;
  --nw-gray-900: #1f2933;
  --nw-gray-200: #d9dee3;
  --nw-white: #ffffff;
  --nw-space-2: 0.5rem;
  --nw-space-4: 1rem;
}

Primitives answer “which values exist?” They deliberately carry no meaning. --nw-blue-600 doesn’t know whether it’s a button, a link or a chart line.

Tier 2: semantic tokens

Semantic tokens name an intent and point at a primitive:

:root {
  --nw-color-action-bg: var(--nw-blue-600);
  --nw-color-action-bg-hover: var(--nw-blue-700);
  --nw-color-action-text: var(--nw-white);
  --nw-color-text: var(--nw-gray-900);
  --nw-color-border: var(--nw-gray-200);
}

This is the tier people use most, and the one themes change. When dark mode or the Tidewater brand arrives, you remap these names to different primitives and leave every component alone.

Tier 3: component tokens

Component tokens name one component’s adjustable parts and point at semantic tokens:

.nw-button {
  --nw-button-bg: var(--nw-color-action-bg);
  --nw-button-text: var(--nw-color-action-text);
  --nw-button-padding-x: var(--nw-space-4);

  background: var(--nw-button-bg);
  color: var(--nw-button-text);
  padding: var(--nw-space-2) var(--nw-button-padding-x);
}

Now three kinds of change each have one obvious place:

• New palette (a slightly more accessible blue): change the primitive.
• New theme or brand (dark mode, Tidewater): remap semantic tokens.
• One component needs to differ (the marketing hero button uses a larger padding): override that component’s token.

The rule that makes this work: components reference semantic tokens, never primitives. The moment a component uses --nw-blue-600 directly, it stops following themes, and you have rebuilt the flat list with longer names.

How the browser resolves a token

Custom properties inherit like color does. When the browser computes styles for a button, it looks up --nw-button-bg on the button itself, finds var(--nw-color-action-bg), then looks that up on the button too, where the value is inherited from the nearest ancestor that set it. That’s why you can re-theme part of a page by setting a semantic token on a container:

.campaign-banner {
  --nw-color-action-bg: var(--nw-green-600);
}

Every button inside the banner turns green; every button outside stays blue. No new classes, no component changes. This scoping behavior is the foundation for themes in the next lessons.

Not just colors

Every category of token gets the same treatment. Spacing primitives are a scale (--nw-space-1 to --nw-space-12); semantic spacing names a role, such as --nw-space-inset-md for padding inside a card or --nw-space-stack-sm for the gap between stacked form fields. Typography primitives are font families, sizes and weights; semantic typography names styles such as --nw-font-body or --nw-font-heading-lg. Radii, shadows and motion durations follow the same pattern.

For scale, Northwind today has about 180 primitives, 120 semantic tokens and 90 component tokens. The semantic tier is where most of the design thinking happens, and it’s the tier designers and engineers should reach for first. If a team keeps asking for a primitive, that usually means a semantic token is missing, and the right fix is to add the role, not to hand out the raw value.

A quick way to check your tiers

Open any component’s CSS and search for your primitive prefix, such as --nw-blue or --nw-gray. In a healthy system those names appear in exactly one place: the semantic token definitions. Northwind runs this as a lint rule in CI, which you will meet in Section 4. In the exercise, you add the semantic and component tiers to a button that currently skips straight to a primitive. Next, you name these tokens so they still make sense in three years.