Week 51 · Future Architectures

One Name,
Every Surface

Swap one blue for a slightly different blue in a raw stylesheet, and that is thirty places to remember, across thirty files. Swap it in a token system, and it is one field, in one file — every surface that ever borrowed that blue's meaning moves with it, unasked.

Part I

Pull One Lever

Below is a real, if miniature, product surface — a nav, a button, a card, a form — built exactly the way this week’s dossier describes it: three tiers, each one a named decision resting on the last.

Primitive tokens are literal and context-free — blue.500, space.3. Semantic tokens name the job a primitive is doing right now — color.action.primary aliases blue.500 today, and only today. Component tokens are what a button or a card actually reads at render time, and mostly just point at a semantic name.

Predict

One slider below moves the primitive named blue.500. How far does that reach?

Token cascade

drag either control

Primitive

blue.100

blue.500

blue.900

space.3

space.5

Semantic

color.action.primary

color.action.primary.hover

color.border.subtle

space.inset.md

space.stack.lg

Component

button.bg

card.border

button.paddingBlock

card.padding

Atlas

DocsTokens

hover

Component tokens are now live. Read the changelog.

Notify the team

Workspace name

design-tokens

{
  "blue": { "500": { "$value": "hsl(202deg 71% 52%)" } },
  "action": { "primary": { "$value": "{color.blue.500}" } },
  "button": { "bg": { "$value": "{action.primary}" } },
  "space": { "3": { "$value": "16px" } }
}

Token name: color.action.primary; never changes
Resolved value: hsl(202deg 71% 52%)
Tokens downstream: 11; 3 semantic · 8 component
Live elements: 8; nav link, active-tab indicator, button fill, button hover fill, card border, card checkbox, input border, form focus ring

Primitive · blue.500 (hue)202°

BlueFull turn

Primitive · space.3 (base unit)16px

TightRoomy

Part II

What a Token Actually Is

Per the group that eventually standardized this, a design token is nothing more than “information associated with a human-readable name, at minimum a name/value pair.”

#2d9cdb does not know it was chosen to mean “trustworthy, primary action.” color.action.primary carries that reasoning forward — so when the blue changes, every surface that meant primary action updates together instead of being independently re-guessed by whoever touches it next.

The vocabulary itself is credited to Jina Anne and Jon Levine, describing shared values inside Salesforce’s Lightning Design System around 2014. The dossier is careful here: the exact coining moment is not pinned to one dated document — the earliest independently fetchable public record is a 2016 conference talk, not a founding artifact. “Coined at Salesforce, popularized from 2016” is the best-attested version, not a single verified event.

A token is not a CSS custom property — a custom property is one possible compiled output of a token, the same way an iOS constant or an Android XML entry is. The token itself is meant to be authored once, in a platform-agnostic name/value/type shape, and compiled everywhere it is needed.

With design tokens, you can capture low-level values and then use them to create the styles for your product or app.

Jina Anne, quoted in Robin Rendle, CSS-Tricks, April 2019

The W3C Design Tokens Community Group is a Community Group, not a formal W3C Recommendation — its draft pages carry explicit “do not implement” banners. Its first stable release, version 2025.10, finalized three modules: Format, Color and Resolver.

Part III

The Middle Tier Is Not Optional

Skip the semantic layer, and dark mode is not hard to add later — it is impossible to add later, without first quietly building the very layer you skipped.

A component wired straight to a primitive has no stable name for a second, dark-mode value to attach to. Toggle the layer off below, then flip the shell to dark, and watch the one card that has nowhere left to hold on.

Collapse the middle tier

toggle the layer, then the theme

Shell — light mode

Weekly digest

Every color still resolves through a name. Flip the theme and card, button and page move together.

Every color pair rendered here is illustrative, not a shipped system. A real one runs this dossier’s Rule 3: every text/background pair validated against WCAG 2.1 §1.4.3 — 4.5:1 for normal text, 3:1 for large — as a CI gate on any token change, not a one-time design-review glance.

Part IV

Five Systems, One Argument

Every major design system agrees tokens should exist. Almost none of them structure the tiers the same way — and the honest version of this section says so where the dossier could not confirm the details.

How each system structures its tiers

SLDSMaterial · Spectrum

SLDS — ~2014, flat categories

Salesforce Lightning Design System's own v1 docs organize tokens into fifteen flat categories (color, spacing, font, radius, z-index…) via $[category]-[property]-[modifier] — e.g. $brand-primary. No strict primitive/semantic/component split; the layered model most teams teach today is a later refinement of what SLDS proved at scale.

verified

The reusable lesson sits inside the first stop: Salesforce shipped a flat, category-based system at real enterprise scale before the strict three-layer model existed as a taught pattern. Do not wait for the theoretically correct architecture before shipping — ship, then refine the layering once real usage shows you where meaning and value are still tangled together.

Part V

Swap the Palette, Keep the Names

A category is graded and prototype-centered, not a rigid boundary around one value — swap the brand’s whole blue family for violet or green, and the category survives because nobody had to rename it.

Same three semantic names below, however you set the palette. Only what they resolve to moves.

Token cascade

swap the palette

Primitive

blue.100

blue.500

blue.900

space.3

space.5

Semantic

color.action.primary

color.action.primary.hover

color.border.subtle

space.inset.md

space.stack.lg

Component

button.bg

card.border

button.paddingBlock

card.padding

Atlas

DocsTokens

hover

Component tokens are now live. Read the changelog.

Notify the team

Workspace name

design-tokens

{
  "blue": { "500": { "$value": "hsl(202deg 71% 52%)" } },
  "action": { "primary": { "$value": "{color.blue.500}" } },
  "button": { "bg": { "$value": "{action.primary}" } },
  "space": { "3": { "$value": "16px" } }
}

Token name: color.action.primary; unchanged across all three palettes
Resolved value: hsl(202deg 71% 52%)
Semantic aliases touched: 3; same three names, new colors

Primitive palette

The prototype-theory framing (Rosch, 1973) is this curriculum’s own citation, carried via a secondary (Wikipedia) summary of the original paper, not independently re-checked against it this session.

Challenge · Rebind the notice

Open

The notice card below is set to a hardcoded hex — #f7f7f8, this month's light-mode surface color, baked in and frozen. Tap it, then choose the semantic role it should have carried from the start.

Shell — light mode

Reference card — already tokenized. Watch how it behaves.

Tap the notice card to open the token choices, then pick the one that names what it is sitting on.

Insight

A token system is not a color palette with extra steps. It is where the rest of this curriculum gets written down.

Miller explains why a dozen named categories beat four hundred raw values sitting in a stylesheet. Sweller explains why that hierarchy has to live in the file itself, not in whoever remembers the reasoning. Rosch explains why swapping the exemplar during a rebrand does not cost you the category. And the weeks before this one confirm it is not a color-only trick: spacing tokens encode Gestalt’s proximity, motion tokens encode Fitts’s and Hick’s interaction cost, color tokens encode function instead of fashion. A design token is simply the format in which all of that gets shipped.

Mental model

Whenever you are about to write a literal color, size, or duration straight into a component,

look for the role that value is playing, not the value itself, and reach for a name that already exists before minting a new one,

because a name survives the next rebrand a raw number never will, and every consumer of that name moves together, for free, the moment its resolved value changes.

Tomorrowgrep your own codebase for one repeated hex or pixel value. Name the role it plays, once, in one place, and point every instance at that name instead.

End of experience

← Back to the constellation

One Name,Every Surface

Pull One Lever

What a Token Actually Is

The Middle Tier Is Not Optional

Five Systems, One Argument

Swap the Palette, Keep the Names

Where this idea goes next

One Name,Every Surface

Pull One Lever

What a Token Actually Is

The Middle Tier Is Not Optional

Five Systems, One Argument

Swap the Palette, Keep the Names

One Name,
Every Surface

One Name,
Every Surface