Book a call

WritingFoundations & tokensPart 4 of 6 in Tokens in practice

Dark mode with design tokens: a step-by-step guide using semantic tokens

Dark mode isn't a second design. It's a second set of answers to the same questions: what's the background, what's the text, what's the action? Set those answers up as semantic tokens and the whole product switches at once.

On this pageWhy dark mode breaks without semantic tokens
  1. Why dark mode breaks without semantic tokens
  2. Primitive vs semantic colour tokens
  3. Step 1: Name colours by their job
  4. Step 2 and 3: Map light mode, then dark mode
  5. Step 4: Check every pair for contrast
  6. Step 5: Ship it as modes
  7. Things that break in dark mode
  8. Beyond dark mode: brands, density and white-label
  9. The short version
  10. Frequently asked questions
  11. Further reading

The short answer

To build dark mode with design tokens, name every colour by its job (bg.canvas, text.primary, action.primary.bg) as semantic tokens, make every component use only those names, then give each name a second value for dark mode. Check every text and background pair for contrast in both modes. The components don't change at all; only the token values do.

  • Dark mode is not inverted light mode. Surfaces get lighter as they rise, and accents usually move to lighter, softer steps.
  • Avoid pure black backgrounds and pure white text; both make reading harder.
  • The bug you'll hit first is a component that used a raw colour or a primitive. Lint for it.

Why dark mode breaks without semantic tokens

Most teams discover their colour problem the day someone asks for dark mode. The estimate is "two sprints". Then engineering searches the code and finds hundreds of colour values typed directly into styles, many of them nearly identical greys. Nothing says which grey is text and which is a border, so nothing can be switched. Two sprints become two quarters.

The fix is a layer of names between the colours and the components. If a card's background is bg.surface rather than #F3F7FE, then dark mode only has to answer one question: what should bg.surface be in the dark? Answer that for every semantic token, and every screen switches at once.

Primitive vs semantic colour tokens

Two tiers of colour tokens do two different jobs. (The full explanation, with a third optional tier, is in our design tokens guide.)

PRIMITIVE

The paint

Every step of every colour ramp, named by what it is: neutral.50, neutral.950, brand.700. These never change between modes. Components never use them.

SEMANTIC

The job

Names for purposes: bg.canvas, text.secondary, feedback.danger.bg. Each points to a primitive, and that pointer is what changes between light and dark.

Step 1: Name colours by their job

List every distinct job colour does in your interface. Most products need a surprisingly small set, grouped by role:

BACKGROUNDS

bg.canvas, bg.surface, bg.subtle: the page, raised surfaces, quiet fills.

TEXT

text.primary, text.secondary, text.disabled, text.link.

BORDERS & FOCUS

border.default, border.strong, focus.ring.

ACTION & FEEDBACK

action.primary.*, feedback.danger.*, feedback.success.*.

Resist creating a semantic token for every screen ("checkout header background"). If a new name doesn't describe a job that several components share, it's a component token or a one-off, not a semantic token.

Step 2 and 3: Map light mode, then dark mode

For each semantic token, choose a primitive for light mode and a primitive for dark mode. Here's the full set from our playbook, built on an OKLCH palette:

Semantic tokenLight modeDark mode
bg.canvasneutral.50neutral.950
bg.surfaceneutral.50neutral.900
bg.subtleneutral.100neutral.800
border.defaultneutral.200neutral.700
border.strongneutral.500neutral.500
text.primaryneutral.950neutral.50
text.secondaryneutral.700neutral.300
text.disabledneutral.400neutral.600
text.linkblue.700blue.300
action.primary.bgbrand.700brand.400
action.primary.bg-hoverbrand.800brand.300
action.primary.textneutral.50neutral.950
feedback.danger.textred.700red.300
feedback.danger.bgred.100red.900
feedback.success.textgreen.700green.300
feedback.success.bggreen.100green.900
focus.ringblue.600blue.400
Seventeen semantic colour tokens and the primitive each one points to in light and dark mode. Components only ever use the left column.

Read down the dark column and you'll see the rules most good dark themes follow:

  1. Don't use pure black

    The dark canvas is neutral.950 (#1E232C), not #000000. Pure black makes light text appear to glow and smear, especially for people with astigmatism, and leaves no room below it for shadows or depth.

  2. Raise surfaces by making them lighter

    In light mode, shadows show elevation. In the dark, shadows barely show, so raised surfaces get lighter instead: canvas neutral.950, surface neutral.900, subtle neutral.800. Material Design uses the same idea.

  3. Soften the text

    Primary text is neutral.50, a very light, slightly cool grey, rather than pure white. Contrast stays very high (14.67:1) without the glare.

  4. Move accents to lighter steps

    The primary action moves from brand.700 to brand.400, and links from blue.700 to blue.300. Dark accents that work on white disappear into a dark background.

  5. Flip feedback fills

    Error and success backgrounds move from pale tints (red.100) to deep tones (red.900), and their text from dark to light, so alerts stay readable without glowing.

Here's what that does to a real piece of interface. Same component, same code, two sets of answers:

light mode

Invoice #2041

Due 12 March · 3 items

Payment overdue by 4 days
Pay nowView details

dark mode

Invoice #2041

Due 12 March · 3 items

Payment overdue by 4 days
Pay nowView details
The same card, the same component code, two sets of answers. Only the semantic tokens change between the two.

Step 4: Check every pair for contrast

A dark theme is only finished when every text and background pairing passes, in both modes. WCAG 2.2 asks for 4.5:1 for body text (1.4.3) and 3:1 for meaningful non-text elements like input borders and focus rings (1.4.11). Check pairs, not colours: a token is only "accessible" in relation to what it sits on.

UsePairNeedsLightDark
Body texttext.primary on bg.canvas4.5:114.67:1 Pass14.67:1 Pass
Secondary texttext.secondary on bg.canvas4.5:15.99:1 Pass8.89:1 Pass
Linkstext.link on bg.canvas4.5:16.05:1 Pass8.76:1 Pass
Primary button labelaction.primary.text on action.primary.bg4.5:16.44:1 Pass6.09:1 Pass
Error messagefeedback.danger.text on feedback.danger.bg4.5:15.74:1 Pass6.68:1 Pass
Success messagefeedback.success.text on feedback.success.bg4.5:15.02:1 Pass6.81:1 Pass
Input border (non-text)border.strong on bg.canvas3:13.07:1 Pass4.77:1 Pass
Focus ring (non-text)focus.ring on bg.canvas3:14.28:1 Pass6.51:1 Pass
Disabled text (exempt)text.disabled on bg.canvasexempt2.23:1 3.45:1
Every pairing that matters, checked in both modes against WCAG 2.2: 4.5:1 for text (1.4.3) and 3:1 for borders and focus rings (1.4.11). Disabled text is exempt under WCAG, but we still keep it readable.
In practice

Put the pairs table in your documentation and in an automated test. When someone proposes a new token value, the test tells them which pairs would fail before the change ships. The Lab has a free contrast checker with a pair matrix if you want to try this on your own palette.

Step 5: Ship it as modes

On the web, the cleanest implementation is CSS custom properties with the semantic layer overridden per theme. Let users choose, default to their system setting, and remember the choice:

:root {
  --bg-canvas: var(--neutral-50);
  --text-primary: var(--neutral-950);
  --action-primary-bg: var(--brand-700);
  color-scheme: light;
}
/* Follow the system unless the user picked a theme */
@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    --bg-canvas: var(--neutral-950);
    --text-primary: var(--neutral-50);
    --action-primary-bg: var(--brand-400);
    color-scheme: dark;
  }
}
[data-theme="dark"] { /* the same overrides, for an explicit choice */ }

Setting color-scheme matters more than it looks: it tells the browser to draw scrollbars, form controls and the default page background in the matching theme, so there's no white flash while the page loads.

In Figma, the same structure becomes a semantic variable collection with two modes, light and dark. Designers switch a whole frame between modes to check their work, exactly as the product will.

Things that break in dark mode

One component that used a primitive

Every screen switches except the date picker, whose selected day stays bright orange on white, because it used brand.700 directly. Lint for primitives and raw values in component code.

Images and illustrations

Logos, illustrations with white backgrounds and screenshots need dark variants or a transparent background. Plan them as assets, not afterthoughts.

Charts

Data colours tuned for white often lose contrast on dark. Give charts their own semantic tokens (chart.series.1…) with dark values checked against the dark surface.

Shadows

Dark shadows on dark surfaces vanish. Use lighter surfaces for elevation, and a subtle border where separation matters.

Third-party embeds

Maps, payment forms and chat widgets often ignore your theme. Check whether they support a dark mode parameter, and test them.

Hard-coded colours in content

Rich text from a CMS with inline colours will fight your theme. Strip inline colours or map them to tokens on the way in.

Beyond dark mode: brands, density and white-label

Once your components only use semantic tokens, dark mode is just the first theme. The same structure supports:

  • High contrast: stronger borders and text, for users who need them.
  • Multiple brands: a different primitive palette behind the same semantic names.
  • White-labelled products: a client's palette mapped into your semantic layer, with contrast checks run on their values before release.
  • Density: the same trick for spacing and control heights.

At IBM, the Riyadh Air design system drew 71 components in English and Arabic, light and dark: four versions of every component, all from one set of semantic decisions. See the case study.

The short version

  • Name colours by job as semantic tokens; components use only those names.
  • Give each semantic token a dark value. Don't invert: lighter surfaces for elevation, lighter accents, softer text, no pure black.
  • Check every pair for contrast in both modes, and automate the check.
  • Ship as CSS custom properties with prefers-color-scheme, an explicit user choice and color-scheme.
  • The same structure gives you high contrast, brands and white-label for free.

Frequently asked questions

Should dark mode just invert colours?

No. Inverting turns shadows into glows, makes accents too dark to read, and flips the logic of elevation. Dark mode is a separate set of choices for the same jobs.

How many semantic colour tokens do I need?

Fewer than you think. The set in this article has 17 and covers most of a typical product. Large systems often have 40–60, mostly for feedback states, data visualisation and specific surfaces.

How do I handle elevation in dark mode?

Make raised surfaces lighter rather than relying on shadows: canvas, then surface, then subtle, each a step lighter. Add a faint border where two surfaces at similar levels meet.

Do images and charts need dark tokens?

Charts, yes: give each data series a semantic token with a checked dark value. Images need dark-friendly variants or transparent backgrounds, managed as assets.

Should dark mode follow the system setting?

Yes by default, using prefers-color-scheme, with an explicit choice in settings that overrides it and is remembered.

Further reading