{"id":"l-ds-2-1","courseId":"design-systems","lang":"en","kind":"lesson","summary":"Structure design tokens in primitive, semantic and component tiers as CSS custom properties, so one change of intent updates every component that shares it.","html":"

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.

\n

Tier 1: primitives

\n

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

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

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.

\n

Tier 2: semantic tokens

\n

Semantic tokens name an intent and point at a primitive:

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

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.

\n

Tier 3: component tokens

\n

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

\n
CSS
.nw-button {\n  --nw-button-bg: var(--nw-color-action-bg);\n  --nw-button-text: var(--nw-color-action-text);\n  --nw-button-padding-x: var(--nw-space-4);\n\n  background: var(--nw-button-bg);\n  color: var(--nw-button-text);\n  padding: var(--nw-space-2) var(--nw-button-padding-x);\n}
\n

Now three kinds of change each have one obvious place:

\n
\n Component token button-bg points to semantic token color-action-bg, which points to primitive blue-600 with the value 1f5ae0. Each tier is changed for a different reason.\n \n --nw-button-bg\n \n --nw-color-action-bg\n \n --nw-blue-600\n \n \n Component\n Semantic\n Primitive\n Change one component\n Change a theme or brand\n Change the palette\n #1f5ae0\n \n
Each tier references only the tier below it
\n\n

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.

\n\n

How the browser resolves a token

\n

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:

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

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.

\n\n

Not just colors

\n

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.

\n

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.

\n

A quick way to check your tiers

\n

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.

\n","toc":[{"id":"sec-1","text":"Tier 1: primitives","level":2},{"id":"sec-2","text":"Tier 2: semantic tokens","level":2},{"id":"sec-3","text":"Tier 3: component tokens","level":2},{"id":"sec-4","text":"How the browser resolves a token","level":2},{"id":"sec-5","text":"Not just colors","level":2},{"id":"sec-6","text":"A quick way to check your tiers","level":2}],"takeaways":["Primitive tokens name raw values (--nw-blue-600); semantic tokens name intent (--nw-color-action-bg); component tokens name one component’s knobs.","Components reference semantic tokens, never primitives, so re-theming only changes the semantic tier.","Declare component tokens on the component’s selector, not on :root, so they resolve against overrides in that part of the page.","Add component tokens sparingly; each one is public API you will have to support."],"further":[{"title":"Using CSS custom properties (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascading_variables/Using_custom_properties"},{"title":"var() (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/var"},{"title":"Design tokens (Material Design 3)","url":"https://m3.material.io/foundations/design-tokens"}],"quiz":[{"q":"

Marketing wants every primary action on the site to turn green for a campaign. With a three-tier system, which tier do you change?

","options":[{"text":"The primitive tier, by changing --nw-blue-600 to green.","why":"That turns every use of that blue green, including links and info badges that aren’t actions, and makes the name a lie."},{"text":"The semantic tier, by pointing --nw-color-action-bg at a green primitive.","why":"Correct. Every component that expresses “primary action” follows the change, and nothing else does."},{"text":"The component tier, by overriding the background of each component one by one.","why":"It works, but you would have to find every component with an action color, which is the problem tiers are meant to solve."},{"text":"None; add a new .green class to each button.","why":"One-off classes bypass the system entirely and leave cleanup for after the campaign."}],"answer":1},{"q":"

Why does the button inside .promo stay blue?

\n
CSS
:root {\n  --nw-color-action-bg: var(--nw-blue-600);\n  --nw-button-bg: var(--nw-color-action-bg);\n}\n.promo { --nw-color-action-bg: var(--nw-green-600); }\n.nw-button { background: var(--nw-button-bg); }
\n","options":[{"text":"Custom properties don’t inherit into buttons.","why":"Custom properties inherit by default, including into buttons; inheritance is what delivers the blue."},{"text":".promo has lower specificity than :root.","why":"The two rules target different elements, so specificity isn’t compared; both declarations apply where they are written."},{"text":"The browser caches the first value of each custom property.","why":"There is no caching; values are computed per element during the normal cascade."},{"text":"--nw-button-bg was resolved on :root, so buttons inherit the already-computed blue.","why":"Correct. var() inside a custom property is substituted where it is declared; move --nw-button-bg onto .nw-button and it resolves against .promo’s override."}],"answer":3},{"q":"

A teammate proposes a component token for every CSS property of every component. What’s the main cost?

","options":[{"text":"Browsers slow down noticeably with more than 100 custom properties.","why":"Browsers handle thousands of custom properties fine; performance isn’t the issue at this scale."},{"text":"Every token becomes public API that teams depend on, so the system gets hard to change.","why":"Correct. Each exposed knob is a promise; renaming or removing it later is a breaking change."},{"text":"Component tokens can’t reference semantic tokens.","why":"They can and should; that’s how the tiers connect."}],"answer":1}],"exercise":{"kind":"web","mode":"dom","starter":{"html":"
\n \n
\n
\n \n
","css":"/* Tier 1: primitives (done) */\n:root {\n --nw-blue-600: #1f5ae0;\n --nw-blue-700: #1848b8;\n --nw-white: #ffffff;\n --nw-space-2: 0.5rem;\n --nw-space-4: 1rem;\n}\n\n/* Tier 2: add semantic tokens here */\n\n/* Tier 3: the button skips straight to primitives. Fix it. */\n.nw-button {\n background: var(--nw-blue-600);\n color: var(--nw-white);\n padding: var(--nw-space-2) var(--nw-space-4);\n border: 0;\n border-radius: 6px;\n font: inherit;\n}\n.promo { margin-top: 16px; }\n","js":""},"solution":{"html":"
\n \n
\n
\n \n
","css":"/* Tier 1: primitives (done) */\n:root {\n --nw-blue-600: #1f5ae0;\n --nw-blue-700: #1848b8;\n --nw-white: #ffffff;\n --nw-space-2: 0.5rem;\n --nw-space-4: 1rem;\n}\n\n/* Tier 2: semantic tokens */\n:root {\n --nw-color-action-bg: var(--nw-blue-600);\n --nw-color-action-text: var(--nw-white);\n}\n\n/* Tier 3: component tokens, declared on the component */\n.nw-button {\n --nw-button-bg: var(--nw-color-action-bg);\n --nw-button-text: var(--nw-color-action-text);\n\n background: var(--nw-button-bg);\n color: var(--nw-button-text);\n padding: var(--nw-space-2) var(--nw-space-4);\n border: 0;\n border-radius: 6px;\n font: inherit;\n}\n.promo { margin-top: 16px; }\n","js":""},"checks":[{"id":"still-blue","test":"return style('#main', 'background-color') === 'rgb(31, 90, 224)' && style('#main', 'color') === 'rgb(255, 255, 255)';"},{"id":"semantic","test":"const cs = getComputedStyle(document.documentElement); return cs.getPropertyValue('--nw-color-action-bg').trim() !== '' && cs.getPropertyValue('--nw-color-action-text').trim() !== '';"},{"id":"component","test":"const b = $('#main'); b.style.setProperty('--nw-button-bg', 'rgb(4, 5, 6)'); const ok = style(b, 'background-color') === 'rgb(4, 5, 6)'; b.style.removeProperty('--nw-button-bg'); return ok;"},{"id":"follows-semantic","test":"const p = $('.promo'); p.style.setProperty('--nw-color-action-bg', 'rgb(10, 130, 60)'); const ok = style('#promo', 'background-color') === 'rgb(10, 130, 60)' && style('#main', 'background-color') === 'rgb(31, 90, 224)'; p.style.removeProperty('--nw-color-action-bg'); return ok;"},{"id":"no-primitives","test":"const rules = [...document.styleSheets].flatMap((s) => [...s.cssRules]).filter((r) => r.selectorText); const btn = rules.filter((r) => r.selectorText.includes('nw-button')); return btn.length > 0 && btn.every((r) => !/--nw-(blue|white)/.test(r.style.cssText));"}],"title":"Give the button three tiers","prompt":"

The primitives are done, but .nw-button reaches straight for --nw-blue-600, so no theme can ever change it. Add the two missing tiers:

\n
    \n
  1. On :root, declare the semantic tokens --nw-color-action-bg and --nw-color-action-text, pointing at the right primitives.
    2. \n
  2. On .nw-button, declare the component tokens --nw-button-bg and --nw-button-text, pointing at the semantic tokens, and use them for background and color.
    3. \n
\n

The button must look exactly as it does now, and no .nw-button rule may mention a --nw-blue-… or --nw-white primitive.

\n","hints":["Semantic tokens look like --nw-color-action-bg: var(--nw-blue-600); inside :root.","Component tokens go inside the .nw-button { … } rule, not on :root, so they resolve on each button.","Then change background: var(--nw-blue-600) to background: var(--nw-button-bg), and the same for color."],"explanation":"

The button now resolves --nw-button-bg → --nw-color-action-bg → --nw-blue-600. Because the component tokens are declared on .nw-button, each button looks up the semantic token from its own ancestors, so setting --nw-color-action-bg on .promo re-colors only the promo button. Had you declared --nw-button-bg on :root, the value would be computed once at the root and the promo override would do nothing.

\n","checkLabels":{"still-blue":"The button still renders blue with white text","semantic":":root defines --nw-color-action-bg and --nw-color-action-text","component":"The button’s background comes from --nw-button-bg","follows-semantic":"Overriding --nw-color-action-bg on .promo re-colors only the promo button","no-primitives":"No .nw-button rule references a primitive token"}},"words":697,"readMinutes":3}