Dark Mode Implementation: A Complete Developer's Guide
Implement dark mode properly with CSS custom properties, system preference detection, user toggle persistence, and smooth transitions.
· 3 min read
In this article7 sections
Why Dark Mode Matters
Dark mode is no longer a nice-to-have. Over 80% of users prefer dark mode for at least some of their apps. It reduces eye strain in low-light environments, can save battery on OLED screens, and many users simply prefer the aesthetic.
But implementing dark mode properly is more complex than just swapping black and white. Poor dark mode implementations cause readability issues, lose brand identity, and create jarring transitions.
The CSS Custom Properties Approach
The foundation of any good dark mode implementation is CSS custom properties (variables). Define all your colors as variables in :root for light mode and override them in a dark class or attribute:
:root contains --background: 0 0% 100% and --foreground: 0 0% 3.9% for light mode.
.dark contains --background: 0 0% 3.9% and --foreground: 0 0% 98% for dark mode.
Use HSL values for maximum flexibility. HSL makes it easy to create variations by adjusting lightness or saturation without changing the hue.
Detecting System Preferences
The prefers-color-scheme media query detects the user's operating system preference. Use it as the default, but always let users override it with a manual toggle.
In JavaScript, use window.matchMedia('(prefers-color-scheme: dark)') to check the current preference and add a change event listener to react when users change their system settings.
The Toggle with Persistence
Build a three-state toggle: Light, Dark, and System. Store the user's choice in localStorage and apply it before the page renders to prevent a flash of the wrong theme. The "System" option follows the OS preference, while Light and Dark override it.
To prevent the flash of wrong theme (FOWT), add a small inline script in your HTML head that reads the preference from localStorage and applies the correct class before any content renders.
Color Palette Design
Do not just invert your light mode colors. Dark mode needs its own carefully designed palette:
- Use dark grays (#121212 to #1E1E1E) instead of pure black (#000000) for backgrounds
- Reduce the contrast slightly. Pure white text on dark backgrounds is harsh. Use #E0E0E0 instead
- Desaturate brand colors slightly for dark backgrounds
- Increase the lightness of accent colors to maintain sufficient contrast
- Test contrast ratios for accessibility. WCAG requires 4.5:1 for normal text
Handling Images and Media
Images designed for light mode can look jarring on dark backgrounds. Consider:
- Adding subtle dark borders or rounded corners to images
- Using CSS filter: brightness(0.8) on decorative images in dark mode
- Providing alternate logo versions for dark backgrounds
- Using transparent PNGs with appropriate contrasting text
Smooth Transitions
Add a CSS transition on the color-related properties to prevent harsh flashing when toggling: transition: background-color 0.3s, color 0.3s. Apply this to the body element and key layout components.
But disable this transition on page load. You do not want the entire page to animate from one theme to another when the user first arrives.
- Dark Mode
- CSS
- UX

Written by Pontus Henriksson
Co-founder and CEO of Walldy in Sundsvall. I have built for the web since I was fourteen, tested games for studios like Netflix and Bungie since 2021, and write about what I use in real projects.
Liked this? Get the next one.
New Claude skills, kits and what I learn building AI for small businesses. Not often, only when it is worth sending. Unsubscribe with one click.