Implementing Dark Mode: A Complete Developer Guide
Dark mode has moved from a niche preference to an expected feature. Users on every platform — macOS, Windows, Android, iOS — can set a system-wide dark appearance, and they expect websites and apps to honor it. Implementing dark mode correctly requires more than swapping white for black: it demands a systematic approach to color, contrast, and user control. This guide walks through the complete process, from CSS architecture through JavaScript toggle mechanics to testing both themes thoroughly.
CSS Custom Properties for Themes
The most maintainable way to handle dark mode in CSS is through custom properties (also called CSS variables). Instead of scattering color values throughout your stylesheets, you define every color as a variable on :root and then redefine those variables for dark mode. Component styles reference only the variables — never raw hex codes.
Defining Your Light and Dark Palettes
Start with a light-mode palette as your default. A clean starting point might look like this:
:root {
/* Backgrounds */
--color-bg-base: #FFFFFF;
--color-bg-elevated: #F8F9FA;
--color-bg-overlay: #F1F3F5;
/* Text */
--color-text-primary: #1A1A2E;
--color-text-secondary: #4A4A6A;
--color-text-muted: #6C757D;
/* Borders */
--color-border: #DEE2E6;
--color-border-strong: #ADB5BD;
/* Brand / accent */
--color-accent: #3B82F6;
--color-accent-hover: #2563EB;
/* Feedback */
--color-success: #22C55E;
--color-warning: #F59E0B;
--color-danger: #EF4444;
}
Then define overrides for dark mode in a separate block. The key insight is that you are not just inverting colors — you are choosing a different, purpose-built palette for a dark surface:
[data-theme="dark"] {
/* Backgrounds */
--color-bg-base: #0F0F17;
--color-bg-elevated: #1A1A2E;
--color-bg-overlay: #252540;
/* Text */
--color-text-primary: #E8E8F0;
--color-text-secondary: #A8A8C0;
--color-text-muted: #6A6A88;
/* Borders */
--color-border: #2E2E4A;
--color-border-strong: #4A4A6A;
/* Brand / accent — often slightly lighter for legibility on dark bg */
--color-accent: #60A5FA;
--color-accent-hover: #93C5FD;
/* Feedback — slightly desaturated to avoid harshness */
--color-success: #4ADE80;
--color-warning: #FCD34D;
--color-danger: #F87171;
}
Notice that the accent #3B82F6 in light mode becomes #60A5FA in dark mode. The hue is the same but the lightness increases — this is necessary because the contrast context has flipped. A color that passes WCAG AA against a white background will almost always fail against a near-black background unless you adjust it. The Shade Generator lets you explore the full 50–950 range of any color, making it easy to pick the appropriate shade for each theme.
Using Variables in Components
With the palette established, every component references variables rather than raw values:
.card {
background-color: var(--color-bg-elevated);
border: 1px solid var(--color-border);
color: var(--color-text-primary);
}
.btn-primary {
background-color: var(--color-accent);
color: #FFFFFF;
}
.btn-primary:hover {
background-color: var(--color-accent-hover);
}
When the [data-theme="dark"] attribute is present on the <html> element, all variables update simultaneously, and every component that references them changes appearance — zero additional CSS required.
The prefers-color-scheme Media Query
Before the user ever interacts with a toggle, you can honor their operating system preference using the prefers-color-scheme media query. This media query fires when the OS is set to dark appearance.
@media (prefers-color-scheme: dark) {
:root {
--color-bg-base: #0F0F17;
--color-bg-elevated: #1A1A2E;
--color-bg-overlay: #252540;
--color-text-primary: #E8E8F0;
--color-text-secondary: #A8A8C0;
--color-text-muted: #6A6A88;
--color-border: #2E2E4A;
--color-border-strong: #4A4A6A;
--color-accent: #60A5FA;
--color-accent-hover: #93C5FD;
--color-success: #4ADE80;
--color-warning: #FCD34D;
--color-danger: #F87171;
}
}
This approach works without any JavaScript, is zero-layout-shift, and respects the user's declared preference immediately on page load. It is the right baseline. The limitation is that users cannot override it in your app — if the OS is dark, the site is dark, with no escape. That is why most production implementations layer a JavaScript toggle on top of the media query.
Combining Both Approaches
The recommended pattern uses the media query as a default and the data-theme attribute as an explicit override. You can handle this with a CSS specificity trick or by ordering your rules correctly:
/* 1. Light mode default */
:root {
--color-bg-base: #FFFFFF;
/* ... */
}
/* 2. OS dark mode override (when no explicit preference set) */
@media (prefers-color-scheme: dark) {
:root:not([data-theme="light"]) {
--color-bg-base: #0F0F17;
/* ... */
}
}
/* 3. Explicit dark mode (user toggled via JS) */
[data-theme="dark"] {
--color-bg-base: #0F0F17;
/* ... */
}
The :not([data-theme="light"]) selector in the media query means the OS dark preference only applies when the user has not explicitly chosen light mode. Once they toggle, their explicit choice wins.
Toggle Mechanism with JavaScript
A well-implemented toggle does three things: it changes the current appearance immediately, it persists the preference in localStorage, and it reads the saved preference on page load before the first paint.
Reading Preference on Load
This script must run in <head> — before the page renders — to prevent a flash of the wrong theme:
<head>
<script>
(function() {
const stored = localStorage.getItem('theme');
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
const theme = stored ?? (prefersDark ? 'dark' : 'light');
document.documentElement.setAttribute('data-theme', theme);
})();
</script>
</head>
This immediately sets data-theme on <html> before any styles are applied. The browser computes the correct custom property values from the first paint — no flash.
The Toggle Function
function toggleTheme() {
const current = document.documentElement.getAttribute('data-theme');
const next = current === 'dark' ? 'light' : 'dark';
document.documentElement.setAttribute('data-theme', next);
localStorage.setItem('theme', next);
}
// Hook it up to a button
document.getElementById('theme-toggle').addEventListener('click', toggleTheme);
Syncing the Toggle Button State
The toggle button should visually reflect the current mode. A simple approach uses icons:
<button id="theme-toggle" aria-label="Toggle dark mode">
<span class="icon-light">☀️</span>
<span class="icon-dark">🌙</span>
</button>
[data-theme="dark"] .icon-light { display: none; }
[data-theme="dark"] .icon-dark { display: inline; }
[data-theme="light"] .icon-light { display: inline; }
[data-theme="light"] .icon-dark { display: none; }
Because the icon visibility is controlled by CSS variables tied to data-theme, the button state updates automatically whenever the attribute changes — no additional JavaScript needed.
Color Adaptation Strategies
Choosing dark-mode colors is not as simple as inverting your light palette. Several principles guide good dark color choices.
Reduce Contrast, Not Just Flip It
Pure white text on a pure black background (#FFFFFF on #000000) is technically maximum contrast — 21:1 — but it is cognitively tiring for extended reading. Reduce both extremes: use an off-white like #E8E8F0 for body text and a very dark navy like #0F0F17 for the page background. This preserves ample contrast (still above 15:1) while reducing visual fatigue.
Use the Contrast Checker to verify that every text/background combination in your dark theme meets at least WCAG AA (4.5:1 for normal text, 3:1 for large text). Common failure points include:
- Placeholder text in form fields
- Disabled button labels
- Secondary metadata text (timestamps, bylines)
- Icon-only buttons without visible labels
Layered Elevation with Dark Surfaces
In light mode, elevation is typically expressed by drop shadows. In dark mode, shadows become invisible against dark backgrounds. The Material Design 3 specification introduced a more effective approach: lighter surfaces feel higher. Use subtly lighter backgrounds for elevated components:
/* Dark mode elevation scale */
--color-bg-base: #0F0F17; /* Page background */
--color-bg-elevated: #1A1A2E; /* Cards, sidebars */
--color-bg-overlay: #252540; /* Modals, dropdowns */
--color-bg-tooltip: #2E2E4A; /* Tooltips */
#0F0F17 as the base, #1A1A2E for cards, #252540 for modals — each step is about 8–10% lighter in HSL lightness terms. This creates a clear visual hierarchy without relying on shadows.
Desaturate Dark Mode Colors Slightly
Highly saturated colors look harsh and neon-like on dark backgrounds. When adapting your brand colors for dark mode, reduce saturation by 10–20% alongside increasing lightness. Instead of a vivid #22C55E success green, prefer #4ADE80 — lighter and slightly less saturated, which reads as success without eye strain.
The Shade Generator is ideal here: enter your brand's primary green or blue and explore the 300–400 range for dark-mode text and icon uses, versus the 500–600 range for interactive elements.
Images and Media
Images with white backgrounds look jarring in dark mode. CSS can help:
/* Reduce harshness of images in dark mode */
[data-theme="dark"] img:not([src*=".svg"]) {
filter: brightness(0.9) contrast(1.05);
}
/* Or allow images to blend slightly with the background */
[data-theme="dark"] img {
mix-blend-mode: luminosity;
opacity: 0.9;
}
For SVG icons that need to adapt, using currentColor as the fill value means they automatically adopt the current text color:
.icon { color: var(--color-text-secondary); }
<svg fill="currentColor" viewBox="0 0 24 24">...</svg>
Testing Both Modes
Thorough testing prevents dark-mode regressions from slipping into production.
Browser DevTools Emulation
Chrome and Firefox both offer dark-mode emulation in DevTools without changing your OS setting. In Chrome: open DevTools, click the three-dot menu, go to More Tools → Rendering, and set "Emulate CSS media feature prefers-color-scheme" to "dark." This lets you compare both modes side by side.
Automated Contrast Testing
Manual spot-checking is error-prone. Integrate automated contrast auditing into your development workflow. Use tools like Axe or Lighthouse in CI to catch new color additions that fail WCAG thresholds. The Contrast Checker lets you quickly verify a foreground/background pair against all WCAG levels — paste in any hex pair and see the ratio instantly.
Test with Real Content
Dark-mode bugs often appear on pages with dynamic content: user-uploaded images, third-party embeds, charts, and maps. Test against a realistic content sample, not just your design system's component library in isolation.
OS-Level Testing
After verifying via DevTools emulation, test with your OS actually set to dark mode. The prefers-color-scheme media query fires based on the OS setting, and some browsers behave slightly differently depending on whether the setting is real vs. emulated. Also test the transition: switch modes while a page is open and confirm no layout shifts or rendering artifacts occur.
Common Pitfalls Checklist
- Hardcoded hex values in component CSS instead of variables — search your stylesheets for raw hex codes and replace with variables
- SVG icons with hardcoded
fill="#000000"— change tofill="currentColor" - Third-party components that do not respect
data-theme— wrap them in a scoped CSS layer color-schemeproperty not set — addcolor-scheme: light darkto:rootso browser chrome (scrollbars, form controls) also adapts<meta name="color-scheme">missing from<head>— add it so the browser can apply the right background color before CSS loads
<meta name="color-scheme" content="light dark">
:root {
color-scheme: light dark;
}
This small addition makes native scrollbars, date pickers, and other OS-rendered form controls automatically switch to their dark variants — a detail many implementations overlook.
Key Takeaways
- Define all colors as CSS custom properties on
:rootand override them for dark mode using[data-theme="dark"]. Component styles reference only variables, making theme switching zero-effort once the palette is established. - Use
prefers-color-scheme: darkas the automatic default for users who have set their OS to dark appearance. Layer a JavaScript toggle withlocalStoragepersistence on top for users who want to override. - Run the anti-flash script in
<head>before CSS loads to prevent the first-paint flash of the wrong theme. - Dark mode colors are not inverted light colors — reduce extreme contrast, use lighter backgrounds to convey elevation, and desaturate brand accents slightly to avoid neon harshness.
- Verify every text/background pair with the Contrast Checker and use the Shade Generator to find the right shade of each brand color for both themes.
- Add
color-scheme: light darkand the corresponding<meta>tag so native browser UI elements (scrollbars, inputs) also switch automatically.
