Skip to content
FrontDepth, Home

Design Systems

Design tokens and theming

What design tokens are and how they are organised, from primitive and semantic tiers to CSS custom properties, dark mode without a flash, token pipelines, multi-brand theming, contrast checks and token governance.

JuniorMiddleSeniorUpdated 16 November 2026

Reading level

Shows sections up to the selected level.

Before you start

No prerequisites.

This topic starts at Junior level.

JuniorConcept

What a design token is

A design token is a named design decision: color-text-default is #1f2328, space-4 is 16px, radius-control is 6px. The name says what the value is for; the value says how it looks today. Designers and engineers talk about the name, and only the token source knows the value.

Without tokens the same decision is copied by hand into hundreds of places:

CSS
.button {
  background: #0b5fff;
  border-radius: 6px;
  padding: 8px 16px;
}

.link {
  color: #0b5fff;
}

When the brand blue changes, someone has to find every #0b5fff and decide whether each one is "the action color" or just happens to be the same blue. With tokens, components refer to the decision and the value changes in one place:

CSS
.button {
  background: var(--color-action-bg);
  border-radius: var(--radius-control);
  padding: var(--space-2) var(--space-4);
}

.link {
  color: var(--color-link);
}

What becomes a token

  • Color: backgrounds, text, borders, focus rings, status colors.
  • Spacing and sizing: a spacing scale (4, 8, 12, 16, 24…), control heights, icon sizes.
  • Typography: font families, sizes, weights, line heights, often grouped into styles like text-body.
  • Shape and depth: radius, border width, shadows, z-index layers.
  • Motion: durations and easing curves.

Not every number needs a token. A token pays off when the value is a decision that repeats and should change everywhere at once.

A shared format

Tokens are usually kept as data and turned into code for each platform. The W3C Design Tokens Community Group publishes a vendor-neutral format for that data, the Design Tokens Format Module. Its first stable version, 2025.10, was published on 28 October 2025; it is a Community Group report, not a W3C Standard. A token is an object with a $value; $type can be set once on a group, and a reference to another token is written in curly braces:

JSON
{
  "color": {
    "$type": "color",
    "blue-600": {
      "$value": { "colorSpace": "srgb", "components": [0.043, 0.373, 1], "hex": "#0b5fff" }
    },
    "action-bg": { "$value": "{color.blue-600}" }
  }
}
JuniorConcept

Tiers and naming: primitive, semantic, component

Most token sets have three tiers, and each tier refers only to the tier below it.

  1. Primitive (base) tokens hold raw values: the palette and the scales. color-blue-600, color-gray-900, space-4. They are named after what they are and carry no meaning yet: blue-600 says nothing about where it is used.
  2. Semantic (alias) tokens give a value a purpose: color-bg-surface, color-text-muted, color-border-focus, color-status-danger. Their value is a reference to a primitive. Themes are mostly built in this tier: the dark theme points color-bg-surface at gray-900 instead of white.
  3. Component tokens (optional) belong to one component: button-primary-bg, input-border. They usually alias semantic tokens. They help when one component must look different in one brand; they cost a lot when every component gets dozens of tokens nobody ever overrides.
CSS
:root {
  --color-blue-600: #0b5fff;
  --color-blue-700: #0047d6;
  --color-gray-0: #ffffff;
  --color-gray-900: #1f2328;

  --color-bg-surface: var(--color-gray-0);
  --color-text-default: var(--color-gray-900);
  --color-action-bg: var(--color-blue-600);
  --color-action-bg-hover: var(--color-blue-700);

  --button-primary-bg: var(--color-action-bg);
}

Why components use semantic tokens

A component that reads --color-blue-600 has hard-coded a decision: "my background is blue". When dark mode or another brand needs a different action color, that component has to change. A component that reads --color-action-bg asks "what is the action color here?" and the theme answers. The rule: components read semantic or component tokens; only theme files read primitives. Teams often enforce it with a lint rule that rejects raw hex values and primitive names in component styles.

Naming

A good name is predictable: you can guess it without looking it up. A common order is category, property, role, then state:

Text
color-bg-surface
color-bg-surface-raised
color-text-muted
color-border-focus
color-action-bg-hover
font-size-body

Name semantic tokens by role, never by value: color-text-danger, not color-red. "Red" stops being true the day a brand shows errors in orange. Keep scale names neutral (blue-600, space-4) so a step can be added without renaming the others.

MiddleWeb platform

Theming with CSS custom properties

On the web, tokens usually become CSS custom properties. Three of their properties make theming work.

They inherit. A custom property declared with -- is inherited by every descendant until one of them sets it again. So :root holds the defaults, and a theme is simply an element that redeclares some of them:

CSS
:root {
  --color-bg-surface: #ffffff;
  --color-text-default: #1f2328;
}

[data-theme="dark"] {
  --color-bg-surface: #0d1117;
  --color-text-default: #e6edf3;
}

.card {
  background: var(--color-bg-surface);
  color: var(--color-text-default);
}

Put data-theme="dark" on <html> for a dark page, or on one <section> for a dark block inside a light page. The same .card rule works in both, because each element resolves var() with the values it inherits.

They are resolved late. The browser accepts almost any value when it parses a custom property and substitutes it where var() is used, when it computes styles. Two consequences:

  • var(--name, fallback) uses the fallback only when --name has no value, typically because it is not defined anywhere up the tree. Everything after the first comma is the fallback, so var(--a, red, blue) falls back to red, blue. Several fallbacks are nested: var(--a, var(--b, red)).
  • If the substituted value is wrong for the property (--size: 20px; color: var(--size)), the declaration is invalid at computed-value time. The property then behaves as unset: inherited properties like color take the parent's value, others their initial value. The earlier color declarations are already discarded, and the fallback is not used, because --size is defined.

They can be typed. @property registers a custom property with a syntax, an inheritance flag and an initial value. It is Baseline 2024 (newly available since July 2024); syntax and inherits are required, and initial-value is required unless the syntax is "*".

CSS
@property --color-accent {
  syntax: "<color>";
  inherits: true;
  initial-value: #0b5fff;
}

A value that does not match the syntax is rejected, so the element keeps a valid color (the inherited value or initial-value). The browser can also animate a registered <color>, and inherits: false stops a token from leaking into descendants.

From JavaScript, getComputedStyle(element).getPropertyValue("--color-bg-surface") reads the value an element sees, and element.style.setProperty("--color-accent", value) sets one inline.

MiddleExample

Dark mode: system preference, user choice, no flash

A complete dark mode has three parts: follow the system, let the user override it, and never paint the wrong theme first.

Follow the system. The prefers-color-scheme media feature reports the user's preference (Baseline widely available since January 2020). Also declare color-scheme, so the browser's own UI follows: the default canvas, form controls, scrollbars (Baseline widely available since January 2022). The light-dark() function picks its first color when the used color scheme is light and the second when it is dark. It needs color-scheme: light dark and is Baseline 2024, newly available since May 2024, so check your browser targets.

CSS
:root {
  color-scheme: light dark;
  --color-bg-surface: light-dark(#ffffff, #0d1117);
  --color-text-default: light-dark(#1f2328, #e6edf3);
  --color-link: light-dark(#0b5fff, #4c8dff);
}

:root[data-theme="light"] {
  color-scheme: light;
}

:root[data-theme="dark"] {
  color-scheme: dark;
}

Without light-dark(), the same thing takes two rules: the dark values inside @media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { … } } and again in :root[data-theme="dark"].

Let the user override it. Store a three-way choice, system, light or dark, and reflect it as data-theme on <html>; system means no attribute. CSS follows OS changes on its own; listen to matchMedia("(prefers-color-scheme: dark)") only for things drawn in JS, like a canvas chart.

No flash of the wrong theme. If the stored choice is applied in a React effect, the first frame is painted with the default theme and then flips. Apply it before the first paint with a small inline script in <head>. An inline classic script is , so it runs before the body is parsed and rendered:

HTML
<head>
  <meta name="color-scheme" content="light dark" />
  <script>
    try {
      const theme = localStorage.getItem("theme");
      if (theme === "light" || theme === "dark") {
        document.documentElement.dataset.theme = theme;
      }
    } catch {}
  </script>
  <link rel="stylesheet" href="/app.css" />
</head>

With server rendering, keep the choice in a cookie too, so the server can send <html data-theme="dark"> straight away. When a script changes attributes of <html> before , React warns about the mismatch; suppressHydrationWarning on <html> silences it for that element's attributes only.

MiddlePitfalls

Pitfalls that break themes

An alias resolved too early. This looks like a working brand switch, but every button in the red brand stays blue:

CSS
:root {
  --brand-primary: blue;
  --button-bg: var(--brand-primary);
}

[data-brand="red"] {
  --brand-primary: red;
}

button {
  background: var(--button-bg);
}

var() inside a custom property is substituted on the element that declares it, here :root. Descendants inherit the result (blue), not the formula. Fix it by declaring the aliases on every element that can set a theme, for example :root, [data-brand] { --button-bg: var(--brand-primary); }, or by letting each theme block set its semantic tokens directly.

Hard-coded values. #fff, rgba(0, 0, 0, 0.1), colors inside inline SVGs, images with a white background, a chart palette in JavaScript. They look right in the light theme and break in the dark one. Use currentColor in icons, read tokens with getComputedStyle for canvas drawing, and lint raw values out of component styles.

Components that use primitives. var(--color-blue-600) in a component looks themed, but it ignores dark mode and every other brand.

Silent typos. var(--color-bg-surfce) logs nothing: the property becomes unset and the card turns transparent. Generate a list of token names for editor autocompletion and lint unknown names; run visual regression tests in every theme.

Dark is not inverted light. Shadows barely show on dark surfaces, so elevation is usually expressed with lighter surfaces. Brand colors often need a lighter step: #0b5fff reaches 5.13:1 against white but only 3.69:1 as text on #0d1117, below the 4.5:1 needed for body text. Every theme needs its own contrast check.

No color-scheme. Without it, native inputs, scrollbars and <select> popups stay light inside a dark theme.

Theme applied after paint. Setting the theme in an effect or after a fetch gives the flash described in the dark mode section, and the whole page is styled twice.

Tokens no one can find. Fifty near-identical grays with names like gray-light-2 make people copy hex values again. A small, documented set beats a complete one.

SeniorWeb platform

One source, many platforms: the token pipeline

When the same product ships on the web, iOS and Android, tokens need one source of truth: JSON files in the DTCG format, edited in pull requests or exported from the design tool. A build step resolves references, renames tokens, converts units and colors, and generates code for each platform:

Text
tokens/*.tokens.json  (DTCG)
        |
        v
  Style Dictionary
        |
        +--> web/tokens.css, web/tokens.js, web/tokens.d.ts
        +--> ios/Tokens.swift
        +--> android/colors.xml, android/Tokens.kt

Style Dictionary is the most common build tool. For each platform it applies a transform group (renaming to kebab or Pascal case, converting sizes to rem, formatting colors) and writes files in formats such as css/variables, javascript/es6, typescript/es6-declarations, ios-swift/class.swift, android/resources and compose/object. Since version 4 it supports the DTCG format; its docs say full support for 2025.10 is still in progress in version 5.

JavaScript
import StyleDictionary from "style-dictionary";

const sd = new StyleDictionary({
  source: ["tokens/**/*.tokens.json"],
  platforms: {
    css: {
      transformGroup: "css",
      buildPath: "dist/web/",
      files: [
        {
          destination: "tokens.css",
          format: "css/variables",
          options: { outputReferences: true },
        },
      ],
    },
    js: {
      transformGroup: "js",
      buildPath: "dist/web/",
      files: [{ destination: "tokens.js", format: "javascript/es6" }],
    },
  },
});

await sd.buildAllPlatforms();

outputReferences: true keeps references in the CSS (--color-action-bg: var(--color-blue-600)), which makes the output readable and the tiers visible in DevTools. Without it every token is written as a literal value, which avoids the "alias resolved too early" trap when themes override primitives on nested elements.

Rules that keep a pipeline healthy

  • Generated files are build output. Nobody edits tokens.css by hand; reviews happen on the JSON diff.
  • Typed access. Generated TypeScript declarations give autocompletion, and a removed token becomes a compile error instead of a silent unset.
  • Version the package. Publish tokens as a versioned package with semver: renaming or removing a token is a breaking change. A changed value is not breaking in the API sense, but it changes pixels, so run visual regression tests before release.
  • One direction of truth. Design tools such as Figma have variables with modes (light, dark, brand). Decide whether the design file or the repository is the source, and sync in one direction, or the two drift apart.
SeniorExample

Multi-brand theming: runtime or build time

The platform's system design problem multi-brand-design-system asks for one codebase and one component library that serve several store brands, each with its own look, fonts, features and markets. Tokens solve only the look, and that is the point: components stay brand-agnostic, and a brand is a set of token values.

CSS
[data-brand="north"] {
  --font-family-brand: "Inter", system-ui, sans-serif;
  --radius-control: 4px;
  --color-action-bg: #0b5fff;
  --color-action-fg: #ffffff;
}

[data-brand="south"] {
  --font-family-brand: "Fraunces", Georgia, serif;
  --radius-control: 999px;
  --color-action-bg: #c2410c;
  --color-action-fg: #ffffff;
}

[data-brand="south"][data-theme="dark"] {
  --color-action-bg: #fb923c;
  --color-action-fg: #0d1117;
}

Themes form a matrix, brand × mode (sometimes × density or high contrast), and every cell is a palette of its own. Note the last rule: white text on #fb923c is only 2.26:1, so the dark theme changes the foreground too.

Features and markets are not tokens. Feature flags, locales, currencies and payment methods belong to a brand configuration in data; mixing them into the token set makes both harder to change. Fonts are partly a token (--font-family-brand) and partly loading: each store should load only its own font files, otherwise every visitor downloads every brand's fonts.

Runtime or build time

Runtime: CSS custom propertiesBuild time: values compiled per brand
SwitchingInstant: change an attribute (dark mode toggle, brand preview in a CMS)Needs a different bundle and a reload
Shipped CSSAll themes in one stylesheet (usually a few KB of variables)Only the brand's values
NestingA themed subtree is one attributeHard
Limitsvar() does not work in media query conditions; a switch restyles the whole treeN builds, N artifacts to test and deploy

A common hybrid: each store loads its brand's generated tokens.css (build time), and light/dark stays a runtime attribute inside that brand. Runtime CSS-in-JS theming, where a JS theme object generates styles during render, costs JavaScript on every render and fits poorly with server components; CSS custom properties keep the theme out of JavaScript.

SeniorConcept

Contrast checks and token governance

Contrast per theme. WCAG 2.2 level AA requires a contrast ratio of at least 4.5:1 for text (1.4.3) and 3:1 for large text (at least 18 point, or 14 point bold). UI components and meaningful graphics, including focus indicators, need 3:1 against adjacent colors (1.4.11). The ratios are thresholds and are not rounded: 4.49:1 fails. Because tokens are data, CI can check the pairs that are actually used together, in every brand and mode:

JavaScript
function luminance(hex) {
  const [r, g, b] = [1, 3, 5].map((i) => {
    const c = parseInt(hex.slice(i, i + 2), 16) / 255;
    return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
  });
  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
}

function contrast(a, b) {
  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
  return (hi + 0.05) / (lo + 0.05);
}

console.log(contrast("#ffffff", "#0b5fff").toFixed(2)); // "5.13"
console.log(contrast("#0b5fff", "#0d1117").toFixed(2)); // "3.69"

Declare the pairs next to the tokens (text-default on bg-surface, action-fg on action-bg, border-focus on bg-surface) and fail the build when a cell of the brand × mode matrix drops below its threshold.

Governance. Tokens are the public API of a design system, so they need the same care as any API:

  • Adding. A new semantic token needs a real role used in more than one place. Otherwise reuse an existing token or add a component token.
  • Deprecating. Mark the token (the DTCG format has $deprecated: true or an explanation string), keep it as an alias of its replacement for at least one major version, warn in the build or the linter, ship a codemod that renames usages, and remove it in the next major.
  • Ownership. Someone approves new tokens, a changelog lists every change, and a search across repositories shows who still uses a token before it is removed.
  • Documentation. Generate a reference page that shows each token's value in every brand and mode, so nobody has to read the JSON.
SeniorInterview tips

Interview tips

A 30-second definition. "A design token is a named design decision, such as a color, spacing step or font size, stored as data and generated into code for each platform. Primitive tokens hold the raw palette, semantic tokens give values a role, and components read only semantic tokens, so a theme or brand changes values without touching components." Then sketch :root defaults and a [data-theme="dark"] override.

Questions you are likely to get

  • How would you implement dark mode? Semantic tokens as custom properties, prefers-color-scheme as the default, a stored user override as data-theme on <html>, color-scheme for native UI, and an inline script in <head> (or a cookie with SSR) so the first paint is right.
  • Primitive vs semantic tokens? Value vs role. Explain why a component that reads blue-600 breaks the dark theme.
  • One component library for several brands? Point to the multi-brand-design-system problem: brand-agnostic components, a brand × mode token matrix, brand config for features and markets, fonts loaded per brand, and your runtime or build-time choice with its trade-offs.
  • How do tokens reach iOS and Android? One DTCG source, a build step such as Style Dictionary, generated platform files, a versioned package.
  • What happens with var(--x, red) when --x holds an invalid value? The fallback is not used; the property becomes unset.

Mistakes that cost points

  • Naming tokens by value (color-blue as a role) or letting components use primitives.
  • Applying the theme in useEffect and calling the flash "a small glitch".
  • Forgetting color-scheme, so form controls stay light.
  • Checking contrast once for the light theme and assuming every brand and mode passes.
  • Treating feature flags and markets as part of theming.

Senior signal

Talk about the system around the tokens: the pipeline and its outputs, typed access, semver and deprecation with codemods, contrast checks per matrix cell in CI, visual regression tests, and a clear statement of what is decided at build time and what stays switchable at runtime.

JuniorReview checklist

What to check when reviewing design tokens and theming

Use this list for style and theme code you did not write: a teammate's, a library's or an AI assistant's. Token mistakes are silent: the light theme looks fine, and another theme breaks.

  • Do component styles read only semantic tokens? Search the diff for raw values (#fff, rgba(…)) and primitives such as --color-blue-600: each one ignores the other themes. Check inline SVG fills (use currentColor) and chart colors in JavaScript too.
  • Does every name inside var() exist? A typo like var(--color-bg-surfce) logs nothing and makes the property unset; with a fallback, var(--color-bg-surfce, #fff) silently paints white in every theme. getComputedStyle(el).getPropertyValue("--name") returns "" for an undefined token.
  • Was the change checked in every theme, contrast included? Switch data-theme and look at each changed screen. Text needs 4.5:1 (large text and focus rings 3:1), and a color can pass in one theme and fail in another: #0b5fff gives 5.13:1 on white but 3.69:1 on #0d1117.
  • Is an alias declared only on :root while a nested theme changes what it points to? var() inside a custom property resolves where it is declared; descendants inherit the result. So --button-bg: var(--color-accent) on :root ignores a [data-theme] section that changes --color-accent; declare the alias on :root, [data-theme].
  • Does dark mode set color-scheme and apply the saved choice before the first paint? Without color-scheme, form controls and scrollbars stay light. Applied in useEffect, the choice flashes the default theme first; it belongs in an inline <head> script (or a cookie with server rendering). Reload with dark saved and watch the first frame.
  • Are new tokens named by role and treated as an API? color-text-danger, not color-red. Renaming or removing a token is breaking: keep the old name as an alias until the next major version. Generated files such as tokens.css are never edited by hand.

Check your understanding

  • Practice

    Predict-output and open interview questions with self-assessment.

    4 predict-output · 3 open

  • Quiz

    Multiple-choice questions with explanations and a score.

    6 questions

Hands-on work that uses this topic.