Dark Mode Implementation Patterns

Token-based theming, flash prevention, and system preference detection for robust dark mode.

Component PatternsIntermediate

Why

Users expect dark mode — 30%+ enable it system-wide. Poor implementations flash white on load, ignore OS preference, or hardcode colors that break branded themes.

A token-driven approach with no-flash hydration is table stakes.

When

Implement dark mode for any consumer-facing app, documentation site, or tool used at night. Skip for print-only or embedded kiosk UIs with fixed lighting.

How

1. Define token pairs — --bg-light / --bg-dark, never component-specific dark overrides 2. Set up CSS — :root { --bg: #fff } :root[data-theme="dark"] { --bg: #0f172a } 3. Inline script — read localStorage + matchMedia BEFORE first paint to set data-theme 4. Toggle component — sun/moon icon, updates attribute + localStorage, dispatch event 5. System sync — matchMedia("(prefers-color-scheme: dark)") listener updates if user chose "system" 6. Images — provide dark-optimized variants via <picture> or CSS filter for logos 7. Test — toggle in Storybook, screenshot both themes in Playwright CI

Example

<head> <script> (function () { var t = localStorage.getItem("theme") || "system"; var dark = t === "dark" || (t === "system" && matchMedia("(prefers-color-scheme: dark)").matches); document.documentElement.dataset.theme = dark ? "dark" : "light"; })(); </script> </head> /* tokens.css — paired tokens, components reference --bg only */ :root { --bg: #ffffff; --text: #0f172a; --surface: #f1f5f9; } :root[data-theme="dark"] { --bg: #0f172a; --text: #f1f5f9; --surface: #1e293b; } body { background: var(--bg); color: var(--text); } // ThemeToggle.tsx — updates attribute + storage + notifies function ThemeToggle() { const [theme, setTheme] = useState(localStorage.getItem("theme") || "system"); const apply = (t: string) => { localStorage.setItem("theme", t); document.documentElement.dataset.theme = t === "dark" || (t === "system" && matchMedia("(prefers-color-scheme: dark)").matches) ? "dark" : "light"; setTheme(t); }; return <button onClick={() => apply(theme === "dark" ? "light" : "dark")}> {theme === "dark" ? "☀" : "☾"} </button>; }

Common Problems

⚠FOUC (flash of unstyled content) — theme applied after hydration, users see white flash on refresh
⚠Hardcoded dark colors — .dark .btn { background: #1e293b } instead of token, breaks white-label
⚠Forgotten surfaces — bg token swapped but modals/inputs keep light surface, looks broken
⚠Logos invisible — black logo on dark bg, no <picture> variant provided

Best Practices

✓Inline the theme script in <head> before CSS — zero flash, no hydration dependency
✓Use 3 modes: light / dark / system — most apps force binary and ignore OS preference
✓Audit every surface in dark mode — use Storybook dark addon, not manual toggling
✓Provide dark-optimized logos via <picture><source media='(prefers-color-scheme: dark)'>

FAQ

How do I prevent the white flash on page load?

Inline a script in <head> before CSS that reads localStorage and matchMedia, then sets data-theme on <html>. The theme is applied before first paint, so no flash.

Should I support light/dark or also 'system'?

Three modes: light, dark, system. 'System' follows prefers-color-scheme and updates when the OS changes. Most apps force binary and ignore OS preference, which users dislike.

Why are my logos invisible in dark mode?

Black logos on dark backgrounds disappear. Provide a dark-optimized variant via <picture><source media='(prefers-color-scheme: dark)'> or invert with CSS filter.

How do I theme without hardcoding dark colors per component?

Define paired tokens (--bg, --text, --surface) and override them at :root[data-theme='dark']. Components reference var(--bg) only — never component-specific dark overrides.

How do I audit every surface in dark mode?

Use the Storybook dark-mode addon to toggle all stories, and screenshot both themes in Playwright CI. Don't manually click through — you'll miss modals and inputs.