Dark Mode Design: Beyond Inverting Colors
Dark mode is a separate theme, not a color inversion. Surface elevation, desaturated accents, halation, media handling, and the CSS to ship it.
By Velloreth
Inverting a light theme is a one-line transform, and it produces a theme that technically passes a screenshot review and fails in use. The colors are all “dark”, the hierarchy is gone, the brand accent vibrates against the background, and nothing has any depth.
Dark mode is a second theme that shares your type scale and spacing tokens and disagrees with your palette on nearly everything else. The inversion shortcut fails because a light interface communicates hierarchy through shadow, saturation, and surface lightness — three signals that all invert wrong.
Why naive inversion breaks
Take a typical light theme and negate each channel. What you get:
| Light theme element | Inverted result | What actually happened |
|---|---|---|
White card #ffffff on #f5f5f5 page | Near-black card on white-ish page | Elevation flipped; card now reads as a hole |
Shadow rgba(0,0,0,0.08) | Shadow rgba(255,255,255,0.92) | A white glow around every element |
Brand blue #2563eb | #da9c14 amber | Wrong hue, and still too saturated for dark |
Body text #111827 | #eee7d8 cream | Fine, but now 15% too bright for long reading |
Success green #16a34a | Magenta-ish | Semantic colors break, not just decorative ones |
The deeper issue is that light and dark themes do not use the same physics. In light mode, elevation is expressed by shadow: a raised surface casts a darker area below it, and it sits lighter than the page. In dark mode a black shadow on a dark background is invisible, so elevation has to be expressed the other way — an elevated surface becomes lighter than the background it sits on.
Material Design’s dark theme documents this directly: use dark grey rather than black to express elevation, because shadows are visible on grey and not on black, and because a lighter surface at higher elevation is the readable version of depth in a dark environment.
Start at #121212, not #000000
Pure black fails on three counts.
No elevation range. If your background is #000000, every surface above it must be lighter — so you can never go darker, and you only have one direction to express depth. With #121212 you can step to #1a1a1a, #222222, #2a2a2a and still read a clear ladder.
OLED smearing. On an OLED panel, a black pixel is a pixel that is switched off. Scrolling white text over true black forces pixels to cycle from fully off to fully on every frame, and the panel’s response time shows up as a grey ghost trail behind the text. Material Design flags this explicitly as a blur artifact during scroll.
Halation. Pure white text on pure black is a 21:1 contrast ratio — the maximum possible, and the most uncomfortable. Bright text on a dark background appears to glow and blur for readers with astigmatism, which is a large share of any adult audience.
A practical surface ramp:
page #0e0e0e
surface-1 #161616 cards
surface-2 #1e1e1e raised cards, popovers
surface-3 #262626 modals, menus
border #2e2e2e
text-primary #ededed
text-secondary #a8a8a8
Notice the gaps are small — 6 to 8 points of lightness per step. On a dark background, large jumps between surfaces look like separate unrelated panels. Small steps read as depth.
And notice text-primary is #ededed, not #ffffff. That lands around 14:1 against #0e0e0e: far above AA, below the halation threshold. Full white is a tool for headings and active states where you want the contrast to bite.
Desaturate your accents
Saturation reads differently against dark backgrounds. A blue at #2563eb looks confident on white; the same chroma on #0e0e0e looks like it is emitting light, and adjacent saturated colors appear to shimmer where they meet — an effect caused by how the eye focuses different wavelengths.
The fix is systematic, not a per-color eyeball:
- Move the accent lighter so it clears contrast against the dark surface (4.5:1 for anything used as text, 3:1 for UI component boundaries).
- Reduce chroma by roughly 15–25% at the same time.
- Keep the hue family intact so the brand stays recognizable.
Doing this by hand in HSL gives uneven results, because HSL lightness does not track perceived lightness. Working in oklch makes the operation predictable: raise L until contrast passes, pull C down until it stops glowing, leave H alone.
:root {
--accent: oklch(0.62 0.19 255);
}
:root[data-theme="dark"] {
--accent: oklch(0.78 0.13 255);
}
The same treatment applies to semantic colors. Error red, warning amber, and success green all get lighter and less chromatic. A #16a34a success green that passes on white will fail contrast on a dark surface — verify it, do not assume.
Type behaves differently in the light
Light text on a dark background is optically heavier than dark text on light. The same face at the same size and weight looks bolder, which is why dark themes often feel cramped and shouty even when nothing changed.
Three adjustments:
- Drop a weight step. If body copy is 400 in light mode, try 400 still — but if your light mode uses 500 for body, dark mode at 400 is usually correct. Headings at 700 in light often read as 600 in dark.
- Open the line height slightly.
1.6in light becoming1.65in dark is subtle and helps. - Never letterspace body text tighter to compensate for the added apparent weight. It hurts word shape.
Separately, long-form reading in dark mode has a lower comfortable ceiling than light mode. If you are shipping a reading app, test an actual article at your chosen contrast for a few minutes rather than judging a settings screen.
Media, shadows, and the things nobody re-designs
Images and video are authored against light assumptions. A product screenshot with a white background becomes a glaring rectangle in a dark interface.
[data-theme="dark"] img:not([data-no-dim]) {
filter: brightness(0.85) contrast(1.05);
}
[data-theme="dark"] video {
filter: brightness(0.9);
}
Apply this with intent — dimming a photo gallery or a hero image is usually wrong, and an opt-out attribute is cheaper than arguing about it later.
Shadows need rewriting rather than removal:
[data-theme="dark"] .card {
background: var(--surface-2);
border: 1px solid var(--border);
box-shadow: 0 1px 2px rgb(0 0 0 / 0.4);
}
A dark theme’s shadows are mostly separators. The visible signal is the border plus the lighter surface; the shadow just stops the card from floating in a vacuum. Note what this means for your border token — light themes often have no visible borders at all, so the dark theme introduces a border color that has no light-mode counterpart. That is normal, and it is a token, not a hack.
Charts need attention too. A categorical palette picked for a white canvas will have several series that collapse into each other on dark. Re-check that every series clears 3:1 against the new plot background, and consider whether your gridlines went from invisible to too loud.
A dark theme as a token block
The concrete shape most teams settle on: a small set of surfaces, one text ramp, one border, and repointed semantics.
:root {
--bg: #0e0e0e;
--surface-1: #161616;
--surface-2: #1e1e1e;
--surface-3: #262626;
--border: #2e2e2e;
--border-strong: #3d3d3d;
--text-1: #ededed;
--text-2: #b4b4b4;
--text-3: #8a8a8a;
--accent: oklch(0.78 0.13 255);
--accent-contrast: #0e0e0e;
--danger: oklch(0.7 0.16 25);
--success: oklch(0.75 0.15 150);
--shadow-1: 0 1px 2px rgb(0 0 0 / 0.4);
--shadow-2: 0 8px 24px rgb(0 0 0 / 0.5);
}
Three things to notice. text-1 is not white — it is the halation ceiling discussed above. accent-contrast exists because an accent light enough to read on a dark surface is too light for white text on top of it, so the button label needs its own token rather than a hardcoded #fff. And the shadows are shallow: on dark surfaces their job is separation, not simulated light.
If you find yourself wanting a fourth text color, you probably have a hierarchy problem rather than a palette problem.
Testing under real conditions
A dark theme reviewed in a design tool at midday on a calibrated display is not the theme anyone will use. Test it the way it will be consumed:
| Condition | What to look for |
|---|---|
| Lowest screen brightness you use | Text-2 and text-3 disappearing entirely |
| Phone at 1% brightness, night | Minimum viable contrast, not nominal contrast |
| Scroll a text-heavy page | OLED ghosting behind bright glyphs |
| Screenshot and view on a light theme device | Whether the hierarchy still reads |
| Full white page in a dark UI | Whether it feels like an alarm |
| Long article, 5 minutes | Halation, squinting, rereading lines |
Also verify the cases that do not appear in a component gallery: browser autofill backgrounds, native select dropdowns, the default color of a scrollbar, ::-webkit-scrollbar if you styled it, PDFs and embedded iframes that cannot follow your tokens, and the caret color in a text field.
Shipping it without a flash
The failure mode everyone has seen: page loads white, then snaps dark. That happens when the theme is applied by JavaScript after first paint.
Do it in the head, before any content:
<script>
(() => {
const stored = localStorage.getItem("theme");
const dark = matchMedia("(prefers-color-scheme: dark)").matches;
const theme = stored ?? (dark ? "dark" : "light");
document.documentElement.dataset.theme = theme;
document.documentElement.style.colorScheme = theme;
})();
</script>
Then declare color-scheme in CSS as well so scrollbars, form controls, and the caret follow:
:root { color-scheme: light; }
:root[data-theme="dark"] { color-scheme: dark; }
The rules for the toggle are simple. Absent an explicit choice, follow prefers-color-scheme and keep following it live — use addEventListener on the media query, do not cache the first reading. Store an override only when the user actually makes one, and give them a third option in longer-lived products: system, light, dark. A user who set their phone to dark three years ago has not necessarily told you that your app should be dark.
Contrast checks in both directions
The most common dark mode accessibility bug is reusing a light theme’s muted gray. #6b7280 sits around 4.8:1 on white, which passes. The same hex on #0e0e0e is roughly 4.0:1 — a failure that no design review caught, because the light theme was the one under review.
Check every text token against every surface it can appear on, in both themes. Specifically:
- Secondary and tertiary text, which is almost always the offender.
- Placeholder text, which is often a token nobody audited.
- Disabled states — they still need to be legible enough to read, even though they are intentionally de-emphasized.
- Border and focus ring colors, which need 3:1 against adjacent colors (SC 1.4.11) and a focus indicator that meets SC 2.4.13 in WCAG 2.2.
- Link text at rest, not just hovered.
Automate it. A contrast check in CI against the built stylesheet catches this class of regression permanently; reviewing screenshots catches it once.
The pass/fail for a dark theme
Four questions, answerable in five minutes on any screen of your product:
- Can I see depth? Cards, sheets, and menus should be distinguishable from the page without borders doing all the work.
- Does anything glow? Saturated fills, focus rings, and primary buttons should look painted, not backlit.
- Can I read the quiet text? Placeholders, metadata, timestamps — the stuff nobody demos.
- Did anything flash? Hard-reload the page and watch the first 300ms.
If those four hold, the theme is real. Everything past that is refinement, and refinement is where you spend time after the fundamentals — not before.