Marcus Andrey Study
Ler em português Library

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

Mode
Density

Porto → Vigo · 09:40

Pier 2 · 184 of 220 passengers checked in

Delayed 15 min

Check in passenger
  • color.surface.default → color.sand.50color.ink.900
  • color.text.default → color.ink.900color.sand.50
  • color.action.primary → color.blue.600color.blue.400
  • color.feedback.danger → color.coral.600color.coral.400
  • space.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.action.primary, in every mode
A sailing card from the staff console, styled only with Harbour's semantic and component tokens. Switch the mode or the density: the card's CSS never changes, only what the tokens point to. The token list shows each link as it is now.Live CSS: custom properties re-declared under :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-background were declared on :root and dark mode re-pointed --hb-color-action-primary only 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.primary moves from blue.600 to blue.400, because blue.600 on the dark surface is only 2.6 to 1. blue.400 gives 5.3 to 1.
  • color.text.on-action flips from sand to ink, because a light label on a lighter blue would fail.
  • color.feedback.danger moves from coral.600 to coral.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 :root and 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)

  1. In the demo, switch to dark and compact together. Write down every token that changed.
  2. Now imagine a high-contrast mode. Which semantic tokens would it re-point? Would it touch spacing?
  3. 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

Books, courses and videos to go deeper

Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.

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

Saved only on this device.

↑ ↓ to move · Enter to open · Esc to close