design-token-architecture

---
name: design-token-architecture
description: "Structure design tokens across the primitive → semantic → component tiers, with theming/dark-mode and multi-brand solved as a semantic-tier value swap, then emit the platform outputs consumers use. Traverses the token branch of the design-systems decision tree: source of truth → tier structure → naming → theming → platform outputs. Reach for this when the user asks 'how should our tokens be structured?', 'set up design tokens', 'how do we do dark mode / multi-brand?', or 'primitive vs semantic tokens?'. Used by design-systems-architect (structure) and design-tokens-and-component-engineer (pipeline)."
---

# Skill: design-token-architecture

> **Invoked by:** `design-systems-architect` (the tier structure & naming decision) and
> `design-tokens-and-component-engineer` (the pipeline that realizes it).
>
> **When to invoke:** "how should our tokens be structured?"; "set up our design tokens"; "how do
> we do dark mode / multi-brand?"; "primitive vs semantic vs component tokens?"; any "what's the
> token model" question.
>
> **Output:** a token architecture — the tier structure (primitive → semantic → component), naming
> conventions, the theming/multi-brand strategy resolved at the semantic tier, and the platform
> outputs — plus the conditions that would restructure it.

## Procedure

1. **Establish the source of truth.** Decide where tokens *live* authoritatively — a
   framework-agnostic format (the W3C DTCG `$value`/`$type` JSON, or a Figma variables export) —
   not scattered in CSS. One source, transformed to every platform. Everything downstream derives
   from it.
2. **Define the primitive tier — raw, context-free values.** `color.blue.600`, `space.4`,
   `font.size.300`. These are the palette: no meaning, no intent, never consumed directly by a
   product. They exist so the semantic tier has something to point at.
3. **Define the semantic tier — intent, not appearance.** `color.bg.surface`, `color.text.default`,
   `color.border.focus`, `space.inset.md`. Each **references a primitive** and names a *role*.
   This is the tier products and components consume. The rename test: if renaming your company's
   brand color would force edits in product code, your semantic tier is missing or bypassed.
4. **Define the component tier where a component needs its own scoped tokens.** `button.bg.primary`
   → references `color.bg.brand`. Use it when a component's styling should be tunable independently
   of the global semantic value; skip it when the semantic token is enough (don't create ceremony).
5. **Solve theming at the semantic tier — a value swap, never a component fork.** A theme
   (light/dark, brand A/brand B) is a *set of semantic-token values*: `color.bg.surface` resolves
   to different primitives per theme, the component tree is identical. Wire it with CSS custom
   properties scoped by a `[data-theme]` (web) or a theme object (native). Dark mode is just
   another theme; multi-brand is just more themes.
6. **Emit the platform outputs consumers actually use.** Transform the source (e.g. Style
   Dictionary) to: CSS custom properties (+ a typed TS map) for web, and native formats if
   targeted. Types matter — a mistyped token name should fail at build, not render wrong.
7. **State the resize conditions** — the 1–2 facts that restructure the model (e.g. "if we add a
   third brand with a different type scale, the semantic tier needs a typography theme axis"; "if a
   product keeps reaching for primitives, the semantic tier has a gap — add the missing role rather
   than letting it bypass").

## Worked example

> User: "We have a web app and are about to launch a second brand. How should tokens be structured
> so dark mode and the second brand aren't a rewrite?"

- **Source:** author tokens in DTCG JSON, one repo, transformed via Style Dictionary
  *(retrieval-dated 2026-07; verify Style Dictionary config API at use)*.
- **Primitive:** `color.slate.{50..900}`, `color.brandA.{...}`, `color.brandB.{...}`, `space.*`.
- **Semantic:** `color.bg.surface`, `color.text.default`, `color.action.primary`, `space.inset.md`
  — components reference only these.
- **Component:** `button.bg.primary → color.action.primary` (kept because the button may want to
  diverge from the global action color later).
- **Theming:** four themes = {brandA, brandB} × {light, dark}; each is a semantic-value map. CSS
  vars under `[data-brand][data-theme]`. No component knows which brand/theme it's in.
- **Outputs:** CSS custom properties + a typed TS token map; `pnpm build:tokens` runs in CI so a
  bad token name fails the build.
- **Resize condition:** if brand B needs a different type scale, add a typography axis to the
  semantic tier rather than forking components.

## Guardrails

- **Products consume semantic/component tiers, never primitives** — a direct primitive reference is
  a leak that makes rebrands a refactor. Flag it.
- **Theming is a value swap at the semantic tier** — never fork or branch a component per brand/mode.
- **One source of truth, transformed** — tokens duplicated across CSS/JS/native drift; derive them.
- **Type the outputs** — an unknown token name should fail at build time.
- **Don't over-tier** — a component-tier token with no reason to diverge from its semantic parent is
  ceremony; add it only when the component genuinely needs an independent knob.
- **Retrieval-date volatile tooling** (Style Dictionary API, DTCG spec status); durable tiering
  principles don't need a date.