# How Dark Mode Tokens Work

> Dark mode tokens bind a second set of values to the same semantic names as light mode, so components never need to know which theme is active.

- Source: https://flashdsm.com/glossary/dark-mode-tokens
- Site: Flash DS (https://flashdsm.com)
- Updated: 2026-08-06

---

## Definition

Dark mode tokens are a second set of values bound to the same semantic token names as the light theme, so that switching modes repoints names such as `--color-surface` at different underlying colours without any component needing to know which mode is active.

Also written as: Theme tokens, Colour modes

## Why inverting does not work

The intuitive approach - flip lightness, swap black and white - produces a dark theme that looks wrong in ways that are hard to name at first.

Some concrete reasons:

**Pure black is harsh.** Most well-made dark themes use a very dark grey, often with a slight hue, rather than `#000000`. Full-contrast white text on pure black causes halation, where the text appears to bleed.

**Saturated colours read as brighter on dark.** A blue that sits comfortably on white can vibrate against a dark background. Dark-mode variants are usually desaturated and lightened, not just lightened.

**Elevation reverses.** In light themes, raised surfaces cast shadows. In dark themes, shadows are nearly invisible, so raised surfaces are usually indicated by getting *lighter*. Shadow tokens that work in one mode carry no information in the other.

**Contrast ratios do not survive the flip.** A pairing that passes AA in light mode can fail in dark. Every pairing needs rechecking, not just recomputing.

## The structure that makes it work

Dark mode is a naming problem before it is a colour problem. It only works cleanly if the semantic layer already exists.

```css
:root {
  --color-surface: var(--grey-50);
  --color-text-primary: var(--grey-900);
}

[data-theme="dark"] {
  --color-surface: var(--grey-900);
  --color-text-primary: var(--grey-50);
}
```

Components reference `--color-surface`. They never learn there is a mode. Adding a third theme later is another block of the same shape rather than a change to every component.

If components reference primitives directly, there is nothing to repoint, and dark mode becomes a conditional in every file.

## Generate both together

A dark theme retrofitted six months later is a survey of every component. Produced alongside the light theme, from the same scales, it is free.

This is the strongest argument for deciding modes at the start even if you only ship one: the structural cost is in the naming, and the naming is cheap before there are components and expensive after.

## Where this fits with Flash DS

Every generated system produces light and dark together, bound to the same semantic names, with contrast checked across pairings rather than one mode derived from the other afterwards.

## Related terms

- https://flashdsm.com/glossary/semantic-token
- https://flashdsm.com/glossary/design-token
- https://flashdsm.com/glossary/design-system