Design Systems · Step 2 · 7 min read
Themes and modes
Light and dark, comfortable and compact: a mode is a second set of answers for the same semantic tokens. How Harbour switches modes and density without touching a component, the exact CSS behind a live demo, why dark mode is measured and not inverted, and how Figma and the DTCG resolver handle the same idea.
A mode doesn't change your components. It changes what your tokens point to. If dark mode means editing the button, the card, the table and forty others, the system has a hole in it. If dark mode means re-pointing a dozen semantic tokens, the system is working. That's what the tiers from the start of this step were for, and this is where they pay off.
What you'll be able to do after reading:
- Tell themes, modes and density apart
- Switch modes by re-pointing semantic tokens, with no component changes
- Read and reuse the CSS behind a live mode switch
- Design dark mode by measuring, not inverting
1. Themes, modes, density
The words overlap, so here's how this course uses them:
- Mode: a context the same product runs in. Light and dark are modes; so is high contrast.
- Density: how tightly the interface is spaced. Harbour has comfortable (default) and compact, for the staff console, where port staff want more rows on screen.
- Theme or brand: a different look for a different product or company. Tidewater and Skiff, in Step 7 (Multi-brand and multi-product systems).
Atlassian puts them all under one idea: "Light mode, dark mode, and high-contrast mode are all examples of theming", and "non-color themes are also possible: think cozy/comfortable/compact views, reduced motion, or custom typography styles" (Atlassian, Design tokens). Carbon ships four colour themes, White, Gray 10, Gray 90 and Gray 100, and its rule is the one to remember: "Each theme shares the same variables and roles, with only the value changing for each individual theme" (Carbon, Themes).
2. Try it
Porto → Vigo · 09:40
Delayed 15 min
Check in passengercolor.→surface. default color.sand.50color.ink.900color.→text. default color.ink.900color.sand.50color.→action. primary color.blue.600color.blue.400color.→feedback. danger color.coral.600color.coral.400space.→inset. md space.4 (16 px)space.3 (12 px)button.→primary. padding-inline space.5 (24 px)space.4 (16 px)button.→primary. background color., in every modeaction. primary
:has(:checked); colour changes fade in 0.2 s, and not at all with reduced motion. Demo: Marcus Andrey, CC BY 4.0.The card never changes its CSS. It reads --hb-color-surface-default, --hb-button-primary-background, --hb-space-inset-md and so on. The mode and density switches only change where those semantic tokens point. The list beside the card shows each link as it is right now.
3. The CSS, exactly as it runs
This is the whole token part of the demo above, copied from its stylesheet:
.ds-a-live {
/* primitives: raw values, never used by components directly */
--hb-color-blue-400: #5B95DB;
--hb-color-blue-600: #1F5FAE;
--hb-color-sand-50: #FBF8F2;
--hb-color-sand-300: #CFC6B6;
--hb-color-ink-600: #4A5A69;
--hb-color-ink-900: #14202B;
--hb-color-coral-400: #E8735F;
--hb-color-coral-600: #C2412D;
--hb-space-2: 8px;
--hb-space-3: 12px;
--hb-space-4: 16px;
--hb-space-5: 24px;
--hb-radius-md: 8px;
/* semantic: light mode and comfortable density are the defaults */
--hb-color-surface-default: var(--hb-color-sand-50);
--hb-color-text-default: var(--hb-color-ink-900);
--hb-color-text-subtle: var(--hb-color-ink-600);
--hb-color-action-primary: var(--hb-color-blue-600);
--hb-color-text-on-action: var(--hb-color-sand-50);
--hb-color-feedback-danger: var(--hb-color-coral-600);
--hb-space-inset-md: var(--hb-space-4);
--hb-radius-control: var(--hb-radius-md);
/* component: points at semantic tokens only */
--hb-button-primary-background: var(--hb-color-action-primary);
--hb-button-primary-padding-inline: var(--hb-space-5);
}
/* dark mode: only semantic tokens change, components follow */
.ds-a-live:has([value="dark"]:checked) {
--hb-color-surface-default: var(--hb-color-ink-900);
--hb-color-text-default: var(--hb-color-sand-50);
--hb-color-text-subtle: var(--hb-color-sand-300);
--hb-color-action-primary: var(--hb-color-blue-400);
--hb-color-text-on-action: var(--hb-color-ink-900);
--hb-color-feedback-danger: var(--hb-color-coral-400);
}
/* compact density, for the staff console */
.ds-a-live:has([value="compact"]:checked) {
--hb-space-inset-md: var(--hb-space-3);
--hb-button-primary-padding-inline: var(--hb-space-4);
}
/* the card only ever reads semantic and component tokens */
.ds-a-card {
padding: var(--hb-space-inset-md);
border-radius: var(--hb-radius-control);
background: var(--hb-color-surface-default);
color: var(--hb-color-text-default);
}
.ds-a-card__meta { color: var(--hb-color-text-subtle); }
.ds-a-card__late { color: var(--hb-color-feedback-danger); }
.ds-a-card__btn {
padding-block: var(--hb-space-2);
padding-inline: var(--hb-button-primary-padding-inline);
border-radius: var(--hb-radius-control);
background: var(--hb-button-primary-background);
color: var(--hb-color-text-on-action);
}
Three things to notice:
- Only semantic tokens appear in the mode blocks. Primitives never change; component tokens never change. Dark mode is six lines; compact density is two.
- The two switches are independent. Mode only touches colour; density only touches space. That's why dark plus compact works without a fourth block. Keep your axes separate like this, or the combinations multiply.
- Aliases are declared on the same element as the switch. In CSS, a custom property that says
var(--hb-color-action-primary)is resolved on the element where it's declared. If--hb-button-primary-backgroundwere declared on:rootand dark mode re-pointed--hb-color-action-primaryonly on a child, the button would keep the light blue. Declare the whole chain where the mode is set, or lower (MDN, Using CSS custom properties).
The demo switches with :has(:checked) because it's a lesson (MDN, :has()). In a product you'd put the same blocks on :root, chosen by the system setting and by a choice the user saves:
@media (prefers-color-scheme: dark) {
:root:not([data-mode="light"]) { /* the dark block */ }
}
:root[data-mode="dark"] { /* the dark block */ }
CSS also has light-dark(), which picks between two values from the used colour scheme, once color-scheme: light dark is set; MDN lists it as Baseline 2024 (MDN, light-dark()). It's handy for two modes, but it only handles light and dark, so for density and brands you still need the re-pointing approach.
4. Dark mode is measured, not inverted
Harbour's dark mode isn't "swap black and white". Every semantic pair was measured again (Colour, type and spacing as tokens):
color.action.primarymoves fromblue.600toblue.400, becauseblue.600on the dark surface is only 2.6 to 1.blue.400gives 5.3 to 1.color.text.on-actionflips from sand to ink, because a light label on a lighter blue would fail.color.feedback.dangermoves fromcoral.600tocoral.400: 5.5 to 1 on the dark surface.
The surface isn't pure black either: ink.900 is a very dark blue that keeps the brand feel. Images need their own care in dark mode; see Images in dark mode.
Respect the system setting by default (MDN, prefers-color-scheme), and let people override it. Port staff on a night shift might want dark even if the shared computer is set to light.
5. The same idea in Figma and in the token format
Figma variables hold one value per mode: "each mode stores one value per variable". Layers are set to Auto by default and "take on the mode of their parent container", so you set Dark on a frame and everything inside follows. If no parent sets a mode, objects fall back to the collection's default, the left-most mode (Figma Help, Modes for variables). Put light and dark in a Semantic collection, and comfortable and compact in a separate Density collection, so the axes stay independent, just like the CSS.
The DTCG Resolver Module 2025.10 describes "a method to work with design tokens in multiple contexts (such as "light mode" and "dark mode" color themes)". It warns that such contexts "are susceptible to combinatorial explosion", and solves it with modifiers: each modifier, like mode or density, has its own contexts and files, merged in order (DTCG, Resolver Module 2025.10). Same idea again: separate axes, one set of names.
6. Common mistakes
- Components with their own dark mode styles, outside the tokens.
- Inverting colours and calling it dark mode, without measuring.
- Mixing axes: a "dark-compact" mode, then "dark-comfortable", then "light-compact"…
- Ignoring the system setting, or giving people no way to override it.
- Declaring aliases on
:rootand switching modes lower down, so the chain doesn't update.
7. Vocabulary
| Term | Meaning |
|---|---|
| Mode | A context with its own token values, like light, dark or high contrast |
| Density | A spacing context, like comfortable or compact |
| Theme | A full set of values for a product or brand |
| Axis | One independent kind of mode: colour mode, density, brand |
| Modifier | The DTCG resolver's name for an axis, with one context per value |
prefers-color-scheme |
The CSS media feature that reads the system's light or dark setting |
8. Try it (no tools needed)
- In the demo, switch to dark and compact together. Write down every token that changed.
- Now imagine a high-contrast mode. Which semantic tokens would it re-point? Would it touch spacing?
- Sketch the extra CSS block it would need, using only semantic tokens.
Reflection questions: How many lines would your current product need to change for dark mode? What does that number tell you about its tiers?
9. If you already practise
- Count the tokens each mode re-points. If it's hundreds, your semantic tier is probably too thin or your components read primitives.
- Generate screenshots of key screens in every mode combination in CI, so a broken pair shows up in review.
- Store the user's choice, apply it before first paint, and test the switch with a screen reader: nothing should be announced as changed except the setting itself.
Checklist
Learn more
- MDN: Using CSS custom properties · prefers-color-scheme · light-dark() · color-scheme · :has()
- Figma Help: Modes for variables
- Design Tokens Community Group: Resolver Module 2025.10
- IBM Carbon: Themes · Atlassian: Design tokens
Books, courses and videos to go deeper
- Expressive Design SystemsYesenia Perez-CruzBook · A Book Apart, 2019 (Amazon)
- Design SystemsAlla KholmatovaBook · Smashing Media, 2017 (Amazon)
Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.
Related
Token tiers · Colour, type and spacing as tokens · Tokens from Figma to code · Build a token set with modes · Images in dark mode · Multi-brand and multi-product systems · Colour and contrast