Token Anatomy

Every BDS token answers seven independent questions. Without distinct vocabulary for each, agents and humans invent parallel taxonomies and the system drifts (portal #512 / #553, retired --theme-brik-*, retired --brand-{tier}). This page locks the vocabulary so the discipline lives in the words themselves.

Seven concepts, seven words

These are orthogonal. A token has one answer for each. Mixing them — calling --brand-tertiary a "tier" because it sits at the top level — is the failure mode the cleanup retired.

ID and the token shape

Every token name has one shape, declared once in tokens/naming-grammar.json (ADR-043):

--{id}-{body}

The ID is always the first segment. It names the system that owns the decision. The body is what the Tier defines (below). ID is the term, not "Layer": Layer already names the CSS @layer that carries a value, and one word for two meanings is the drift this page exists to stop.

The ID registry

An ID is a registered handle for the system (repo) that owns the decision. It is not derived from the repo slug. The registry is the ids.registry object in the grammar file, which is the source of truth; this table is a copy and the file wins.

Three rules govern every ID:

• Lowercase kebab-case.
• Never equals a reserved word (see below).
• Never prefixes another registered ID.

The Component tier's ID is always bds. Only BDS authors components, so only BDS authors Component tokens. A tenant declares only what its Brand Kit Library owns — colour ramps, brand Semantic roles, font families. Foundations scales (space, size, border-width, …) are bds only.

The first body segment names the tier

Every token now starts with the same ID, so the segment after it is what tells the tiers apart:

• color or a scale word → Primitive
• a purpose or role word (text · surface · background · border · page · gap · …) → Semantic
• anything else → a Component stem

So a component stem may not begin with a reserved word. The closed lists are reservedWords in the grammar file. Two live knobs break the rule and are renamed in #2670: --bds-text-area-min-width reads as Semantic text, and --bds-page-padding-inline reads as Semantic page.

Tier

Every token sits at exactly one Tier. Higher tiers reference lower tiers via var() — a Semantic resolves to a Primitive, a Component --bds-* knob to a Semantic. A Semantic aliasing another Semantic is off-model with one exception: a color role-alias, where the target resolves to a --color-* Primitive (e.g. --border-focus: var(--border-brand-primary)). Color is the theme-varying axis, so the alias theme-tracks for free; a non-color Semantic alias (spacing/size/type) instead parasitizes a scale ladder and is banned. scripts/lint-token-tiers.mjs enforces this (ADR-035, broadening the ADR-025 narrow gate). Components only consume the upper tiers.

┌─────────────────────────────────────────────────────────┐
│  Tier 4 — Component    (component-scoped knobs)         │
│  --bds-{component}-{property}: var(<Semantic>)          │
│  Example: --bds-toast-shadow: var(--shadow-md)          │
└─────────────────────────────────────────────────────────┘
                          ▲
                          │ var()
┌─────────────────────────────────────────────────────────┐
│  Tier 3 — Semantic     (what components consume)        │
│  body: {purpose}-{role}[-{state}]                       │
│  Example: --background-brand-primary:                   │
│             var(--color-poppy-500)                      │
└─────────────────────────────────────────────────────────┘
                          ▲
                          │ var()
┌─────────────────────────────────────────────────────────┐
│  Tier 2 — Primitive    (named raw values)               │
│  body: color-{family}-{step} · {scale}-{step}           │
│  Example: --color-poppy-500: #e35335                    │
└─────────────────────────────────────────────────────────┘
                          ▲
                          │
┌─────────────────────────────────────────────────────────┐
│  Tier 1 — Raw          (literal hex / numeric value)    │
│  Not a CSS variable — the literal value before naming.  │
│  Example: #e35335                                       │
└─────────────────────────────────────────────────────────┘

Tiers 2 and 3 show their body; the target name is --{id}-{body}. The examples are names in use today (see ID and the token shape).

What lives at each Tier

How a tenant binds BDS names

After #2670, components read only --bds-* names. A tenant does not silently redefine a BDS name with its own value. It declares its values under its own registered ID, then binds each BDS Semantic name it changes, in @layer client-theme (ADR-043 § 6):

@layer client-theme {
  .theme-vale-partners {
    --vale-partners-color-{family}-500: /* brand value */;
    --vale-partners-background-brand-primary: var(--vale-partners-color-{family}-500);
    --bds-background-brand-primary: var(--vale-partners-background-brand-primary);
  }
}

The cascade mechanism is unchanged: @layer client-theme still wins over @layer bds-tokens. What changes is that the override is a visible, greppable binding from one system's name to another's, not an anonymous re-declaration. This replaces the earlier "client themes override values with the same names" contract.

About Tier 4

The Component tier is --bds-{component}-{property} — a component- or blueprint-scoped custom property, where {component} is the component/blueprint identifier and {property} is the styled aspect (--bds-toast-shadow, --bds-slider-thumb-shadow, --bds-hero-img-card-bg). Its ID is always bds. This is the only sanctioned Component-tier namespace (ADR-014).

A Tier 4 token serves one of two roles, both under the same name:

1. Override knob — a hook a component reads so a consumer can re-skin one instance without forking the CSS. It must resolve to a Semantic token, never a raw value:

   /* ✅ knob resolves to a Semantic token */
   box-shadow: var(--bds-toast-shadow, var(--shadow-md));
   
   /* ❌ raw literal in the fallback — reintroduces an off-token value
      that ships silently if the token fails to resolve, and lint can't see it */
   box-shadow: var(--bds-toast-shadow, 0 4px 12px rgba(0, 0, 0, 0.08));

2. Runtime binding — a value the component's JS/TSX sets at render (e.g. --bds-slider-percent), read by the CSS to position or size an element.

Anatomy

A token's name is --{id}-{body}. The formulas below are the body of each Tier. A body is read left to right, but its first slot answers a different question at each Tier — cross-applying one tier's formula to another is the single most common naming mistake. (Until #2670 ships, Primitive and Semantic names in dist/tokens.css are the body alone.)

Slot order by tier

The color Primitive row is closed on both slots, read from tokens/naming-grammar.json (tiers.primitive.color):

• {family} is one of blue · grayscale · green · orange · pink · poppy · purple · tan · yellow.
• {step} is one of 50 · 100 · 200 · 300 · 400 · 500 · 600 · 700 · 800 · 900 · 950 — numeric only (ADR-043 § 4). The word steps lightest · lighter · light · dark · darker · darkest · base retire from every tier and every system.

If the grammar file and this list disagree, the file wins.

Color anatomy

Color Semantic tokens follow the one Semantic formula, --{purpose}-{role}[-{state}]. Its {role} slot expands one of two ways — an intent form or a scoped-intent form:

Semantic:       --{purpose}-{role}[-{state}]

{role} slot, intent:         {role}[-{modifier}]
{role} slot, scoped intent:  {scope}-{scope-value}[-{modifier}]

Each segment is fixed vocabulary:

color is not a purpose. It is the reserved word that opens a color Primitive (--color-{family}-{step}), so a Semantic name never begins with it.

Status, service-line, and presence semantic tokens use the scoped-intent form — the scope (service-marketing, presence-online) already names the hue, so they never also take a -brand/-primary role segment. Everything else uses the plain intent form.

Tenant colour

A tenant's brand colour ramp is --{tenant-id}-color-{family}-{step}: a registered ID (the registry), then the same color Primitive body, with numeric steps. A tenant binds the BDS Semantic names it changes to its own ramp, in @layer client-theme (how a tenant binds). The --color-system-* names that ship today are not a tenant precedent — identity in a name is the ID's job now.

When to add a hierarchy modifier

Never preemptively. A role starts as a single-level token set — one token, no hierarchy modifier (--text-service-marketing, which ships with no -primary / -secondary sibling). Add a -primary / -secondary pair only when the design carries a genuine second emphasis level within that role, distinct from the generic --text-secondary / --text-muted that already exist for de-emphasis.

/* ✅ single-level — one emphasis, no hierarchy modifier (real token) */
--text-service-marketing

/* ❌ preemptive — no --text-service-marketing-secondary exists to pair it,
   so the -primary suffix is just a longer name for the single-level token */
--text-service-marketing-primary

The pair earns its place only when a second emphasis tier actually ships alongside the first; until then, --text-secondary / --text-muted already cover generic de-emphasis. Scoped tokens never stack a hierarchy modifier under a context modifier either — the (text, surface) pairing carries emphasis implicitly, so --text-service-brand-on-dark is complete without a -primary.

The modifier slot's light/dark vocabulary (on-color, -on-light/-on-dark, -inverse, tone -light/-dark) is where four look-alike concepts diverge — documented in full at Color → Color modifiers.

Non-color anatomy

Half the registry is not a color. 325 of the 701 token names in dist/tokens.css sit outside the color purpose list above — --font-size-100, --gap-md, --ease-spring. They are a second legitimate formula, not drift. The distinction the color form draws between purpose and role does not apply, because there is no hue to place: a length, a duration, or a weight is fully described by the property it feeds and the step on that property's scale.

Primitive:  --{scale}-{step}         --font-size-100, --border-radius-400
Semantic:   --{role}-{step}          --gap-md, --heading-xl, --ease-spring

The first slot is a scale at the Primitive tier (named for the CSS property it feeds) and a semantic role at the Semantic tier. Both may be hyphenated (font-line-height, content-width) — the slot is the whole property or role name, not the first segment.

Primitive tier scales

Semantic tier roles

Named exceptions

Two kinds of thing live outside the tables above. Both are in the registry today; neither should be referenced in new work.

Renames owed — tracked on #1910, sequenced behind the naming ADR.

Slotless by exception — --web, --tablet, --mobile (tokens/figma-tokens.css:319-321) carry no purpose slot and are a deliberate carve-out, not a rename target. They are unitless leftovers in the primitives collection that no longer exist in Figma, and they are unconsumed — zero var() references anywhere in brik-bds, brik-client-portal, or brikdesigns (measured 2026-08-20). Deleting them rather than renaming them is tracked under #2595. Mirrored in EXCEPTIONS at scripts/__tests__/inspect-widget-tokens.test.mjs.

--breakpoint-* is a separate case and not slotless — breakpoint is its slot. It also records zero var() references, but that is by design, not dormancy: a custom property cannot appear inside an @media condition, so the CSS family carries the values for Figma and the docs while the breakpoints / mediaQueries TS exports carry them into conditions (ADR-025 §4). "Should BDS ship breakpoint tokens at all" was the open question here; #2591 answered yes and made all five rungs Figma-backed.

Colour families beyond the numeric ramps

lint-naming-canon rule 7 fails any --color-* in dist/tokens.css that does not parse as color-{family}-{step}, or match a family registered in tokens/naming-grammar.json. Beyond the nine numeric ramps, the grammar registers four named groups. Each exists for one purpose, stated in the grammar as $purposes. A colour that does not serve that purpose belongs in a different family, not in this one.

The retired word-step ramp rungs (--color-poppy-light, 54 names) live only in the generated bridge (#2670); the old --color-system-youtube spelling and the nine others resolve through tokens/compat/prefix-bridge.css.

Outside the colour grammar

lint-naming-canon rule 7 fails any --color-* in dist/tokens.css that does not parse as color-{family}-{step}. Of 190 distinct --color-* names (measured 2026-10-01), 99 parse; 91 do not. Each is baselined to the issue that removes or reshapes it, and none should be referenced in new work.

This section is gated: npm run lint-token-purpose-slots fails when a slot ships in dist/tokens.css that is neither named above nor dispositioned as drift. That is the only thing keeping the tables from going stale — a color-only formula describing half a system is exactly how #1910 started.

Role discipline

A token names a role, and two roles can resolve to the same value today without being the same role. --subtitle-md and --body-xs both alias --font-size-50; --subtitle-lg and --body-md both alias --font-size-100. That coincidence is a fact about this theme's current type ramp, not a licence to substitute one for the other.

Pick the token whose role matches the content, even when the values coincide. A subtitle uses --subtitle-*; reading copy uses --body-*. Values converge and diverge as the ramp is retuned — reference the role and you track every retune for free; reference the same-valued alias and you silently desync the moment those two steps split. Board.css and Table.css already hold this line ("Uses --subtitle-md for correct semantic sizing"), and it is why InteractiveListItem reaching for --body-xs on its subtitle slot is drift, not an equivalent (#2384).

How the seven concepts map to a real token

Take --background-brand-primary (the hot path):

Every legitimate token answers all seven. If a token doesn't fit any one of them, it's drift.

Drift patterns to avoid

Verifying a token before referencing it

# Is this name in the canonical registry?
rg '\-\-{token-name}' node_modules/@brikdesigns/bds/dist/tokens.css

# Or run the consumer-side gate
./scripts/token-audit.sh --canonical-only

If the gate is missing or the name isn't found, stop. Don't ship a var() call against a name that doesn't exist — if it isn't in dist/tokens.css, it isn't real.

Related

• The cascade — Layer ordering, modes, color foundations vocabulary
• Color — the full color registry and the color-modifier vocabulary (on-color, -on-light/-on-dark, -inverse, tone) the modifier slot draws from
• Theming — how a client brand overrides these Semantic tokens per the four Theming Dimensions; the "How Content feeds Theming" section separates theming layers from content vocabularies
• Composition Layers — the pedagogical Blueprint → Layout → Container → Block or Control → Component model that composes tokenized primitives
• ADR-043 — System ID and the naming grammar — the ID, the shape, and the closed word lists this page copies
• Figma Library architecture — Foundations Library vs Brand Kit Library
• Color Pairings — the accessible foreground/background pairing system the on-color and -on-light/-on-dark modifiers feed into, with the contrast matrix and CI gate
• Color primitive tiers — the closed tier vocabulary used by the portal theme generator
• Slot Vocabulary — BEM slot vocabulary (different domain — component class names, not token names)
• Style Dictionary build pipeline — how Figma → Library → Layer → CSS happens