Design tokens and theming: the contract between design and code

Three tiers, or no theming

A design token is a named design decision — --color-accent, not #2563eb. The naming is what makes it a contract: code references the decision, and the decision can change without the code knowing. Mature systems converge on three tiers with strictly one-directional references:

• Primitive palette — raw values with no meaning attached: --blue-600: #2563eb, --gray-100, --space-4. A complete, ordered set of options. Nothing in product code may reference these.
• Semantic tokens — intent: --color-surface, --color-on-surface, --color-accent, --color-danger, --radius-interactive. Each maps to a primitive. This tier answers “what is this color for” — and it is where every theme lives.
• Component tokens — per-component bindings consumed by the component’s styles: --button-primary-bg: var(--color-accent). Optional but valuable at scale: they give each component a stable styling API and a place for targeted overrides.

Why the middle tier is the one you cannot skip: themes are re-mappings of intent. Dark mode does not say “make blue darker” — it says “surface is now near-black, on-surface is near-white, accent shifts one step lighter for contrast.” If component tokens bind directly to primitives — --button-bg: var(--blue-600) — there is no place to express that statement except by re-declaring every component token, hundreds of them, per theme. With a semantic tier, a theme is ~30 lines. And if product code uses primitives directly, the brand is hardcoded with extra steps: the rebrand from the Hook becomes find-replace again, just with prettier names.

The runtime: CSS custom properties versus JS theme objects

Two implementation camps. CSS custom properties make the browser’s cascade the theming runtime:

:root {
  --blue-600: #2563eb;            /* primitive — never referenced by products */
  --color-accent: var(--blue-600); /* semantic — the theme lives here */
  --color-surface: #ffffff;
  --color-on-surface: #111827;
}
[data-theme="dark"] {
  --color-surface: #0b0f1a;       /* re-map intent; primitives untouched */
  --color-on-surface: #e5e7eb;
  --color-accent: var(--blue-400); /* one step lighter for contrast on dark */
}

Switching themes is document.documentElement.dataset.theme = "dark" — the browser recomputes styles and no React re-render happens at all, because no React state changed. It survives SSR (an inline script can set the attribute before first paint, killing the theme flash), works across micro-frontends and non-React surfaces, and costs nothing per component. The weaknesses are real: values are untyped strings (mitigated by generating TypeScript declarations from the token source), and anything computed from a token in JS needs getComputedStyle.

JS theme objects — a ThemeProvider holding { colors: { accent: ... } } consumed via context — give you typed, composable values in the language. The bill: the theme is runtime-coupled — switching themes changes the context value, which must re-render every consumer; at design-system scale that is thousands of components re-rendering to change colors the browser could have swapped in the cascade. It is also framework-locked. The synthesis that won in practice: author tokens as data, type them at build time, deliver them as CSS custom properties — typed authoring, cascade runtime.

One dark-mode rule transcends the implementation choice: theme at the semantic tier, never by inverting primitives. Inverted gray scales produce illegible disabled states and broken shadows; dark surfaces need elevation-based lightening (a raised card is lighter than the page, not darker, because shadows are nearly invisible on dark); accent colors often need a lighter step to keep contrast. These are design decisions per intent token — which is the entire argument for the tier they live in.

Distribution: tokens as a versioned package

At more than one consuming app, tokens become an API with consumers, and need the discipline of one. The source of truth is a data file (JSON), built into platform outputs — CSS custom properties, a TypeScript module with types, mobile formats — and published as a versioned package consumed like any dependency. That enables the policies that keep the contract trustworthy:

• Breaking-change policy. Renaming a token is an API break. Ship deprecation aliases — the old name re-exported as a reference to the new one, with a build-time warning — for at least one major version; remove only on a major bump, ideally with a codemod.
• Drift control. The contract erodes one raw hex at a time. Lint for it: a stylelint rule forbidding raw color literals and px values in product code, enforced in CI. The token-based app in the Hook finished in six days because this lint had kept its codebase clean; the find-replace apps were paying down years of un-linted drift.
• Review the token diff like an API diff. A changed semantic mapping alters every consumer of that intent; the diff is small to read and huge in blast radius — --color-accent changing is a product-wide visual change reviewed in one file.

The interop layer, honestly

Tokens outlive any one toolchain, so the format matters. Style Dictionary is the established transformer: one token source in, per-platform outputs out (CSS, TS, iOS, Android), with custom transforms. The W3C Design Tokens Community Group format (the design-tokens/community-group spec on GitHub) is the interop bet: a JSON format with $value/$type/$description, designed so design tools, transformers, and documentation generators can exchange tokens. Honest status: it spent years as a draft, tool support is real but uneven — Style Dictionary v4 reads it, major design tools track it with varying fidelity — and migrating an existing token source to it is work. It is still the right bet, because the alternative is per-tool lock-in of the one artifact your design and code teams must share for years.