Dark Mode Implementation: The Details That Matter

Most users who prefer dark mode have already told their operating system so, via a system-wide setting. @media (prefers-color-scheme: dark) lets a site respect that existing choice automatically, providing a sensible default without requiring the user to discover and click a separate toggle on every individual site they visit.

The common, well-regarded pattern layers a manual override on top: default to the OS preference via prefers-color-scheme, but also offer an explicit toggle (persisted, typically via localStorage or a cookie) for users who want a site-specific choice different from their system-wide setting — a user might prefer their OS in dark mode generally but want one particular content-heavy reading site in light mode specifically.

Pure black against light, high-contrast text creates an unusually extreme contrast ratio. While high contrast is generally good for accessibility, an *excessive* jump — particularly on OLED displays capable of rendering true, deep black — can produce a visually uncomfortable effect for some viewers, sometimes described as text seeming to 'vibrate' or develop a halo, especially in low ambient light where the eye has adapted to darkness.

This is why the overwhelming majority of well-regarded dark mode implementations (major operating systems and popular apps among them) use a dark gray in the #121212-to-#1a1a1a range as their base background instead of literal black — dark enough to unambiguously read as 'dark mode', while meaningfully softer on the eyes over extended viewing.

A light-mode design system typically communicates that a card or modal 'floats' above the page background using box-shadow — a dark, soft shadow reads clearly against a light background. That same technique falls apart on a dark background: a dark shadow against an already-dark background has minimal visible contrast, making it an ineffective elevation cue exactly when it's needed most (modals, dropdowns, cards).

The standard solution, borrowed from Material Design and widely adopted since, is an elevation scale expressed through progressively lighter surface fills instead: the base page background is darkest, a card sitting above it gets a slightly lighter fill, and a modal appearing above that card gets lighter still — perceived depth communicated through lightness contrast, which remains clearly visible on a dark background where shadow contrast doesn't.

Dark Mode Is More Than Inverted Colors. The Theme Architecture lesson covered the general switching mechanism. Dark mode specifically has its own set of hard-won implementation details — detecting the OS preference correctly, avoiding pure black, and rethinking how elevation and depth are communicated when shadows stop working the way they do on light backgrounds.

Detecting The System Preference With prefers-color-scheme. @media (prefers-color-scheme: dark) reads the OS-level dark mode setting directly, giving a sensible default theme without requiring the user to make an explicit choice — most production dark mode implementations combine this automatic default with a manual override the user can toggle and have remembered.

prefers-color-scheme's Role. What's the typical relationship between prefers-color-scheme and a manual, user-toggleable dark mode switch?

• →A site should only ever use one or the other, never both
• →prefers-color-scheme typically provides the automatic, sensible default, while a manual toggle lets the user explicitly override it if they prefer something different from their OS setting
• →They're unrelated CSS features with no typical interaction

Why Pure Black Is Usually The Wrong Choice. #000000 against white text creates an extremely high contrast ratio that can itself cause eye strain and a distracting 'halation' effect for some users, particularly on OLED screens with true blacks; most well-regarded dark mode implementations use a dark gray (#121212-ish) instead, which still reads as 'dark mode' while being gentler on the eyes.

Avoiding Pure Black. Why do most well-designed dark mode implementations avoid pure black (#000000) as the background color?

• →Because it doesn't actually look dark enough to users
• →Because the extreme contrast against light text can cause eye strain and a distracting halation effect for some users, especially on OLED displays
• →Because pure black isn't technically supported in CSS

Elevation Via Lightness, Not Shadows. On a light background, box-shadow is an effective way to communicate that a card 'floats' above the page. On a dark background, shadows are far less visible (dark shadow on dark background has little contrast), so dark mode design systems typically communicate elevation instead through progressively lighter background shades — a card sitting 'above' the page background gets a slightly lighter fill, and a modal above that card gets lighter still.

Elevation In Dark Mode. Why do dark mode design systems typically communicate elevation through progressively lighter surface colors instead of box-shadow?

• →Because box-shadow doesn't work at all in dark mode
• →Because a dark shadow against an already-dark background has very little visible contrast, making it an ineffective elevation cue
• →Because box-shadow is a performance problem specifically in dark mode

Dark Mode Craft Mastered. You now know the specific, hard-won implementation details that separate a well-executed dark mode from a naive color inversion: reading the OS preference correctly with prefers-color-scheme, avoiding pure black in favor of a gentler dark gray, and communicating elevation through progressively lighter surfaces instead of shadows that lose their contrast on dark backgrounds.

Style A Panel For Dark Mode. A .dark ancestor class scopes an alternate color scheme to everything nested inside it.