Skip to content
Tutorials Center
My learning

Topics

Lesson 110 of 139 ยท Modern CSS

Design Tokens and Theming

Build a three-layer design token system with CSS custom properties, then switch between several themes, density modes and dark mode with a single attribute.

A design token is a named design decision: "our brand color", "the medium spacing step", "the card corner radius". Instead of typing #4f46e5 in forty places, you give that decision a name once and refer to the name everywhere. When the decision changes, you change one line.

You already met the basic idea in Custom Properties and used it for a light and dark switch in Dark Mode. This lesson shows how to organize tokens into layers so that you can support many themes, not just two, without touching a single component rule. That structure is how design systems stay consistent across hundreds of screens.

Why layers of tokens?

If every token holds a raw value, a theme change means rewriting every token. If components use raw values, there is nothing to change. The solution is three layers, each one referring only to the layer below it:

flowchart LR
  P["Primitive tokens<br/>--blue-600: #2563eb"] --> S["Semantic tokens<br/>--color-action: var(--blue-600)"]
  S --> C["Component tokens<br/>--btn-bg: var(--color-action)"]
  C --> R["Rules<br/>background: var(--btn-bg)"]

Primitives hold raw values, semantic tokens give them a purpose, and component tokens connect purposes to one component. A theme swaps the semantic layer.

  1. Primitive (or global) tokens are the raw palette: every color, size and font you allow. Names describe what it is: --blue-600, --space-4, --radius-2. They never change between themes.
  2. Semantic (or alias) tokens describe what it is for: --color-surface, --color-text, --color-action. They point at primitives, and themes work by pointing them at different primitives.
  3. Component tokens are optional private variables inside a component, such as --btn-bg. They make a component easy to restyle without rewriting its rules.

Components should almost never use primitives directly. If a button uses --blue-600, it will stay blue in every theme. If it uses --color-action, it follows the theme.

Step 1: primitives

Put primitives on :root, and use a numbered scale so there is room to grow. A small excerpt:

CSS
:root {
  /* color scale */
  --indigo-100: #e0e7ff;
  --indigo-600: #4f46e5;
  --indigo-800: #3730a3;
  --slate-50:  #f8fafc;
  --slate-200: #e2e8f0;
  --slate-700: #334155;
  --slate-900: #0f172a;

  /* spacing, a consistent scale */
  --space-2: 0.5rem;
  --space-3: 0.75rem;
  --space-4: 1rem;

  /* shape */
  --radius-2: 8px;
}

Notice that nothing here mentions "background" or "text". These are paint colors on a shelf, not decisions yet.

Step 2: semantic tokens

Now give the colors jobs. The default (light) theme goes on :root as well:

CSS
:root {
  --color-bg:       var(--slate-50);
  --color-surface:  white;
  --color-text:     var(--slate-900);
  --color-muted:    var(--slate-700);
  --color-border:   var(--slate-200);
  --color-action:   var(--indigo-600);
  --color-on-action: white;
}

A second theme only redefines the semantic names, and only the ones that change. A theme is a scoped override, usually on a data-theme attribute:

CSS
[data-theme="midnight"] {
  --color-bg:       var(--slate-900);
  --color-surface:  #1e293b;
  --color-text:     var(--slate-50);
  --color-muted:    #94a3b8;
  --color-border:   #334155;
  --color-action:   #818cf8;
  --color-on-action: var(--slate-900);
}

Because custom properties inherit, setting data-theme on the <html> element themes the whole page, and setting it on a <div> themes just that region. A dark panel on a light page needs no extra CSS.

Step 3: components use semantic tokens only

Here is a complete example with three themes and one component. Click the buttons to switch the theme, and read the console for what changed. The CSS for .card is identical in all themes:

Switching between three themes with one attribute

The component never mentions indigo, forest or midnight. Adding a fourth theme later is a block of ten lines, with zero changes to components. That separation is the whole point.

Component tokens: a private API for each component

For components with several states or variants, give them local tokens that default to semantic ones:

CSS
.btn {
  --btn-bg: var(--color-action);
  --btn-fg: var(--color-on-action);
  background: var(--btn-bg);
  color: var(--btn-fg);
}
.btn--danger  { --btn-bg: var(--color-danger); }
.toolbar .btn { --btn-bg: transparent; --btn-fg: var(--color-text); }

Now anyone can restyle a button in a given context by setting --btn-bg, without overriding the rule or raising specificity. This is the "public API" idea: the variables are the component's knobs.

More than colors: density and typography themes

Tokens are not only colors. A density theme changes spacing tokens, so the same markup becomes compact or spacious:

CSS
:root              { --density: 1; }
[data-density="compact"] { --density: 0.75; }

.list-item { padding-block: calc(var(--space-3) * var(--density)); }

You can do the same for font families (a "reading" theme with a serif), corner radii (square versus pill) or motion (--duration: 0ms for people who prefer reduced motion, combined with a media query).

Density and radius as themeable tokens

Combining themes with the user's system preference

A good setup respects the operating system until the user chooses. Use color-scheme so form controls and scrollbars follow, and the system preference as the default for the semantic layer:

CSS
:root { color-scheme: light dark; }

@media (prefers-color-scheme: dark) {
  :root:not([data-theme]) {
    --color-bg: #0f172a;
    --color-surface: #1e293b;
    --color-text: #f1f5f9;
  }
}
[data-theme="midnight"] { color-scheme: dark; /* plus the same tokens */ }

The :not([data-theme]) guard means: follow the system only when no explicit theme is set. For two-theme setups, light-dark() is shorter. For three or more, the attribute approach scales better. Many sites save the user's choice in localStorage and set the attribute from a tiny inline script in <head> to avoid a flash of the wrong theme. The editors here run in a sandbox without storage, so that part is read-only.

Naming and housekeeping

  • Prefix by category so autocomplete helps: --color-*, --space-*, --radius-*, --font-*, --shadow-*.
  • Name semantic tokens by role, not by look. --color-danger survives a rebrand; --color-red does not.
  • Keep primitives and semantics in separate files or cascade layers so it is obvious which is which.
  • Add a fallback only where a token may be missing: var(--color-border, currentColor). Do not hide typos behind fallbacks everywhere.
  • Do not create a token for every value. A token with one user is just indirection. Tokens are for decisions that repeat or may change.
  • Test every theme with real components. Contrast between text and surface must hold in each theme (see Accessibility).

A bonus: tokens can come from design tools as JSON and be turned into CSS by a build script, which keeps designers and developers working from the same source. The CSS side stays exactly what you saw here.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. In a three-layer token system, which layer do themes normally change?

    Themes repoint semantic tokens such as --color-surface at different primitives, so components don't change.
  2. 2. Why should a component use --color-action instead of --indigo-600?

    A primitive stays the same in every theme. A semantic token is redefined per theme, so the component adapts.
  3. 3. What happens if you set data-theme="midnight" on a single <section>?

    Custom properties inherit, so a scoped override themes just that subtree.
  4. 4. What does :root:not([data-theme]) achieve in a prefers-color-scheme rule?

    The guard lets an explicit choice override the system preference.
  5. 5. Which token name is better for long-term maintenance?

    Role-based names remain true when the actual color changes.

Summary

  • A design token is a named design decision stored in a custom property.
  • Use three layers: primitives (raw values), semantic tokens (roles) and optional component tokens (a component's knobs).
  • A theme is a scoped override of the semantic layer, switched with an attribute such as data-theme.
  • Components use semantic tokens only, so adding a theme never touches component rules.
  • Tokens can express density, shape, typography and motion as well as color.
  • Follow the system preference by default with :root:not([data-theme]) and color-scheme, and test contrast in every theme.

Next: @property and Typed Custom Properties.