

Dark mode sounds simple until you try to implement it properly. The first instinct (invert the colors, darken the backgrounds, lighten the text) produces something that looks wrong in ways that are hard to articulate. Shadows disappear or become garish. Surfaces lose their sense of depth. Colors that worked perfectly in light mode feel harsh or muddy in dark.
The reason is that dark mode isn't a color transformation. It's a different color system, designed for a different ambient context. Done well, it requires rethinking how color communicates depth, hierarchy, and state, not just flipping values.
This article covers the structural and practical requirements for implementing dark mode with design tokens: why inversion fails, how to structure your semantic color tokens to support both modes from the start, how to handle elevation, and how to test dark mode properly.
The inversion approach treats dark mode as a mathematical operation: take every light-mode color, invert it, and you have a dark mode. The problem is that color doesn't carry meaning in isolation. It carries meaning relative to the surface it's on and the other colors around it.
A few specific ways inversion breaks down:
Brand colors don't invert well. A vivid brand blue at full saturation reads as energetic on a white surface. The same blue on a near-black surface can feel aggressive, radioactive, or simply out of place. Dark mode often requires desaturating or lightening brand colors slightly (sometimes significantly) to maintain the same perceptual weight they have in light mode.
Shadows become meaningless. In light mode, shadows work by adding darkness below an element to create the impression of elevation. In a dark environment, adding more darkness to an already-dark background produces no perceptual separation. Dark mode elevation needs a completely different mechanism: lighter surfaces for higher elevation, or subtle color overlays, rather than shadows.
Depth and hierarchy collapse. Light-mode interfaces use lightness to communicate depth: lighter backgrounds are further back, darker elements are closer or interactive. In dark mode this relationship often needs to reverse, but it doesn't do so cleanly through inversion. You need deliberate semantic decisions about which surfaces sit at which elevation level.
Contrast arithmetic changes. A color that passes WCAG contrast requirements against a white background will almost certainly fail against a dark background, and vice versa. Every foreground-background pair needs to be re-evaluated for dark mode, not assumed to work from the light-mode values.
The upshot: dark mode requires deliberate design, token by token, not a transformation of existing values.
The best time to design for dark mode is before you build your first component. The structure that makes dark mode possible (a semantic alias layer where each token describes a role rather than a value) is the same structure that makes all theming possible. If you build it in from the start, adding dark mode is a matter of supplying a second set of alias values. If you retrofit it later, you're restructuring your entire token system.
The key principle is that every color token a component uses should be a semantic alias, never a global value. And every semantic alias should be named for its role, not its current value.
A well-structured set of semantic color tokens for a UI surface might look like:
color-surface-default → the default page/panel background
color-surface-raised → elevated surface (card, popover)
color-surface-overlay → modal or drawer backdrop
color-surface-inset → recessed surface (input, well)
color-text-primary → primary body text
color-text-secondary → supporting or label text
color-text-disabled → non-interactive text
color-text-on-action → text on interactive surfaces (button label)
color-action-primary → primary interactive color
color-action-primary-hover → hover state
color-action-primary-active → pressed/active state
color-action-primary-disabled → disabled interactive state
color-border-default → standard borders and dividers
color-border-focus → keyboard focus indicator
color-border-disabled → disabled input borders
color-feedback-success → success states
color-feedback-warning → warning states
color-feedback-error → error states
color-feedback-info → informational states
In light mode, color-surface-default might resolve to neutral-50 (#FAFAFA). In dark mode, it resolves to neutral-950 (#0A0A0A). The token name stays the same; the component that uses it stays the same; only the value changes when the mode switches.
The discipline is consistency: every color decision in every component must go through this semantic layer. A single component that uses a hardcoded hex value or a direct global token reference will fail to respond to the mode switch, producing a broken hybrid that mixes light and dark values.
Elevation is where dark mode most visibly diverges from its light-mode counterpart, and where inversion most clearly fails.
In light mode, elevation is typically communicated through shadows: a card sits above the page background because it casts a shadow beneath it. The higher the elevation, the more prominent the shadow. This works because shadows add darkness, and darkness reads as depth against a light background.
In dark mode, the same shadow tokens produce little or no perceptual separation. A dark shadow on a dark background is nearly invisible. Two approaches replace shadows as the primary elevation signal:
The most widely used approach for dark mode elevation is the "light on dark" principle: higher elevation surfaces are lighter, not darker. The page background is the darkest surface; cards and panels are slightly lighter; modals and popovers are lighter still.
This requires a dedicated set of surface tokens for each elevation level:
Light mode Dark mode
color-surface-default: #FAFAFA color-surface-default: #121212
color-surface-raised: #FFFFFF color-surface-raised: #1E1E1E
color-surface-overlay: #FFFFFF color-surface-overlay: #2C2C2C
The light-mode values may differ only slightly (white vs near-white); the dark-mode values use progressively lighter neutrals to signal elevation. The key is that the semantic token names remain stable: color-surface-raised always means "a surface that sits above the default level", while the values express that relationship differently in each mode.
An alternative used by Material Design and similar systems applies a semi-transparent white overlay on elevated surfaces in dark mode, with the overlay opacity increasing with elevation level. This produces a consistent visual system without needing a separate color value for every elevation level:
css
/* Elevation level 1 */
.surface-elevated-1 {
background-color: var(--color-surface-default);
background-image: linear-gradient(
rgba(255, 255, 255, 0.05),
rgba(255, 255, 255, 0.05)
);
}
/* Elevation level 3 */
.surface-elevated-3 {
background-image: linear-gradient(
rgba(255, 255, 255, 0.11),
rgba(255, 255, 255, 0.11)
);
}
The overlay approach is more systematic and easier to extend, but requires either CSS or component-level implementation. It can't be expressed purely as a token value in most formats.
In practice, many systems use a hybrid: semantic surface tokens for the most common elevation levels, with overlay-based elevation for components that need finer granularity.
A well-implemented dark mode respects the user's operating system preference by default and allows them to override it explicitly.
The CSS media query for system preference is:
css
@media (prefers-color-scheme: dark) {
:root {
--color-surface-default: #121212;
--color-text-primary: #F5F5F5;
/* ... full dark mode token set */
}
}
This alone gives you automatic dark mode support. The interface switches when the OS switches, with no JavaScript required.
For products that want to offer a manual toggle, the typical pattern is:
js
const stored = localStorage.getItem('theme-preference');
const systemDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
const theme = stored ?? (systemDark ? 'dark' : 'light');
document.documentElement.setAttribute('data-theme', theme);
The data-theme attribute then drives the CSS custom property overrides, as covered in Article 08.
One important consideration: when using prefers-color-scheme alongside a manual toggle, make sure the specificity of your manual override is higher than the media query. A common mistake is to define dark mode values in a media query and then find that a data-theme="light" attribute on the root element doesn't override them because the media query has equal or higher specificity.
Dark mode is one of the most undertested parts of most interfaces. The visual complexity of verifying two complete sets of color values across every component and state means testing is often cursory: a quick visual scan rather than a systematic check.
A more reliable approach:
Every foreground-background pairing in dark mode needs to be tested for WCAG contrast compliance independently from its light-mode equivalent. A color pair that meets AA requirements in light mode will not automatically meet them in dark mode. Tools like the APCA contrast checker or browser DevTools' accessibility inspector can surface failures quickly.
Pay particular attention to:
Every interactive state (hover, active, focus, disabled, loading, error) needs to be verified in dark mode, not just the default state. State colors are the most common source of dark mode bugs because they're often defined as modifiers on the base color rather than as independent semantic tokens.
A few specific situations that produce dark mode failures even in otherwise well-implemented systems:
Images and illustrations: Photographic images and some illustrations can feel uncomfortably bright in a dark interface. Consider whether image containers need a subtle overlay or opacity reduction in dark mode.
Third-party content: Embedded maps, charts, iframes, and other third-party components often don't respond to your dark mode token system. Document these gaps and handle them explicitly, either with a wrapper overlay or by surfacing them as known limitations.
Transparent elements: Components that use transparency to blend with their background (frosted glass effects, semi-transparent overlays) may need different opacity values in dark mode to achieve the intended visual result.
High-contrast mode interaction: If you're also supporting a high-contrast mode, verify that dark mode and high-contrast mode can be applied simultaneously and produce a coherent result.
Automated accessibility testing tools can catch contrast failures across your component library in both modes simultaneously, making it practical to run contrast checks as part of a CI pipeline rather than relying on manual review.
The next article in this series is Article 10 — Tokens vs CSS custom properties: what's the difference?, which covers how design tokens and CSS custom properties relate to each other, where they overlap, and where they diverge — including what tokens can express that CSS variables alone cannot.
Dark mode is a specific application of the modes mechanism covered in Article 06 — Token modes: handling variation in your token system, which explains how mode inheritance, fallback behavior, and mode stacking work at the token level.
For the broader theming system that dark mode sits within — CSS implementation patterns, scoping, and non-color token theming — Article 08 — Theming with design tokens covers those foundations in full.
For the Figma side — setting up light and dark as variable modes and testing them in your designs — Article 16 — Figma variable modes in depth covers that workflow specifically.
