CSS Dark Mode Implementation — System Detection, Toggle, and Flash Prevention

Modern CSS dark mode is built on two browser features: the prefers-color-scheme media query and CSS custom properties. The media query reports the user's OS-level preference (dark or light), and custom properties serve as the color tokens that switch between the two themes. Understanding which layer controls what is essential for building a reliable implementation.

The prefers-color-scheme media query is purely declarative and requires no JavaScript. It fires whenever the OS color scheme changes, including dynamically when a user switches between light and dark in their system settings. This makes it the correct foundation for a base implementation — any user who has set their OS to dark mode will see dark colors without any JavaScript running.

The second layer is the in-page toggle. Most modern sites offer a button that lets users override the OS preference. This requires JavaScript because CSS cannot write to localStorage or toggle DOM attributes. The toggle needs to be coordinated with the media query: if the OS is dark and the user switches to light in the page, the page should stay light even if the OS later changes back to dark. This state is typically stored in localStorage.

The flash-of-incorrect-theme problem arises at the intersection of these two layers. If a React, Next.js, or Astro site reads the saved theme preference during JavaScript hydration — which happens after the first HTML paint — the page will flash the wrong theme for a fraction of a second before correcting itself. The only reliable solution is an inline script in the HTML head that reads localStorage and sets the data attribute synchronously before any paint occurs.

Chrome DevTools can emulate prefers-color-scheme without changing your OS settings. Open DevTools, go to the Rendering tab (More tools → Rendering), and set Emulate CSS media feature prefers-color-scheme to dark or light. This lets you test the media query path without toggling your OS theme, which is especially useful on Windows where the OS toggle requires navigating through several settings screens.

To check whether the flash-of-wrong-theme problem exists, open the Network tab and set the throttle to Slow 3G. Reload the page without cache. Watch the first few hundred milliseconds — if the page loads white before switching to dark, the theme is being applied after the first paint. The fix must be an inline script in the head, not a useEffect hook or a DOMContentLoaded listener.

For the color-scheme property check, inspect the html element in the Elements panel and look for color-scheme in the Computed styles. If it is not present or shows light, native browser elements like scrollbars and form inputs will not adopt dark mode appearance. Add color-scheme: light dark to :root and color-scheme: dark to the [data-theme='dark'] or the prefers-color-scheme dark block.

For the localStorage persistence issue, open the Application tab in DevTools and look at Local Storage for your domain. The theme key should be set to either 'dark' or 'light' after the user toggles. If it is missing or set to an unexpected value, the JavaScript event handler is not calling localStorage.setItem correctly, or the key name differs between the script that writes and the script that reads.

Start by tokenizing all colors into CSS custom properties on :root. Every hardcoded hex value for background, text, border, surface, and shadow needs a corresponding token. The tokens form the theming API — instead of changing colors in dozens of rules, you change only the token declarations. This step cannot be skipped; without token-based colors, every dark mode selector must duplicate every color-using rule.

With tokens in place, add the media query block that overrides the token values for dark mode. Use :root inside the media query to match the specificity of the light-mode declarations. Override only the tokens that need to change — primary action colors like --accent or --brand often look fine without a dark-mode variant if they are chosen with sufficient contrast for both themes.

Add the [data-theme='dark'] selector with the same token overrides as the media query. This is what your JavaScript toggle will control. Guard the media query block with :root:not([data-theme='light']) so that a user who explicitly chose light mode stays light even if their OS switches to dark. This three-way state (OS dark, user override dark, user override light) is the complete model.

For the flash prevention script, place a small inline script immediately after the opening head tag. The script must be synchronous — no async or defer — so it runs before the browser paints. The script reads localStorage for a saved preference, reads window.matchMedia for the OS preference as a fallback, and calls document.documentElement.setAttribute('data-theme', 'dark') if either condition is true. This runs in under 1ms and makes the correct theme available before any CSS is applied.

Server-side rendering frameworks like Next.js and Astro generate HTML before the browser has read localStorage, which means the server cannot know the user's saved preference. The standard solution is to render the page in a neutral state (or the light state as the default) and rely on the inline flash-prevention script to immediately set the correct data attribute before the CSS cascade runs. Some frameworks offer a cookies-based approach where the theme preference is sent with every request, allowing the server to render the correct theme without any flash.

Images and videos are a common oversight in dark mode implementations. Photographs rendered in full brightness against a very dark background create extreme contrast that feels jarring and causes eye strain. A subtle filter: brightness(0.85) contrast(1.05) on img and video elements reduces this glare while preserving color fidelity. SVG icons that are designed with dark strokes on transparent backgrounds may need an alternative version for dark mode, either via a media query inside the SVG or by switching the fill color through a custom property.

Third-party component libraries that use hardcoded colors are the most difficult dark mode challenge. Libraries like React Select, Date Pickers, or rich text editors often apply inline styles or component-scoped styles that cannot be overridden by custom properties on :root. The options are to override specific component styles with !important (fragile), to use a library version that supports custom property tokens (ideal), or to apply a filter: invert(1) hue-rotate(180deg) to the component as a last resort (approximate and not always accurate).

Mobile browsers on iOS and Android expose the OS color scheme through the same prefers-color-scheme API, but there are quirks. On iOS Safari, the browser chrome (status bar, tab bar) can be themed using the meta name='theme-color' tag with a media attribute: one for light and one for dark. Without this, the browser chrome stays white even when your page's background is dark, breaking the illusion of a seamless dark mode experience.

Not adding color-scheme: light dark to :root is the most common omission. Without it, the browser renders all native UI elements — scrollbars, text selection highlight, input backgrounds, checkbox ticks, select dropdown arrows — in light mode even when the page is visually dark. The fix is adding color-scheme: light dark to :root and color-scheme: dark to the dark theme selector. This one declaration makes native browser elements match the theme without any additional CSS.

Applying the theme class to body instead of html is a specificity trap. Custom properties cascade down the DOM tree from the element where they are declared. Declaring them on body instead of html (document.documentElement) means any content outside body — rare but possible in edge case layouts — will not receive the theme tokens. Using html (document.documentElement) as the theming root is the universal convention.

Adding transition: all to the root element creates performance problems. transition: all means every CSS property, including layout properties, will be animated when they change. This turns simple layout reflows into expensive animated transitions. Instead, explicitly list only the color-related properties: transition: background-color 0.25s, color 0.25s, border-color 0.25s, box-shadow 0.25s. Some developers also scope the transition to just body to avoid transitioning layout containers.

Not testing with real OS dark mode in addition to DevTools emulation. The DevTools emulation changes only the prefers-color-scheme media feature, but actual OS dark mode also changes system colors, native element appearances, and on macOS may affect certain WebKit-specific rendering behaviors. Test with the OS toggle at least once before shipping, particularly on iOS Safari where certain behaviors differ from desktop Chrome.

Design your token set with dark mode in mind from the start. Tokens named --bg-primary, --text-primary, --surface-elevated, --border-subtle, and --shadow-md are neutral names that can be redefined for any theme. Token names that embed their value — --white, --gray-100, --midnight-800 — break down when the theme changes because the name no longer accurately describes the token's role in the dark theme.

Limit the number of dark-mode-specific token overrides. A common mistake is to create entirely separate light and dark token sets with dozens of different values. Most interfaces only need four to eight token swaps to achieve a good dark mode: background, surface, text primary, text secondary, border, link color, and one or two semantic feedback colors. Minimize the override set and test each one for sufficient contrast against WCAG AA minimums (4.5:1 for normal text, 3:1 for large text).

Handle the no-JS case explicitly. If JavaScript is disabled or fails to load, the inline flash-prevention script will not run and the data attribute will never be set. The @media prefers-color-scheme path covers this case for users whose OS is set to dark mode, but a user who previously chose dark mode in your page toggle will see light mode with no JS. Either accept this tradeoff and document it, or use server-side preference storage via cookies to make the server-rendered HTML theme-aware.

Document the dark mode architecture in your CSS file with a short comment block. Explain the three-way state model (OS dark, user-override dark, user-override light), the data-theme attribute, the localStorage key, and which token set is the theming API. This reduces onboarding time for new developers and prevents well-intentioned changes from breaking the theme system. A clear comment on the :root rule pointing to the token override block is often enough.