Theme Toggling Approaches
Most dark mode work starts from a light theme that serves as the default, plus a switch to reach a darker counterpart. Several implementation strategies exist, and each carries different trade-offs.
Body Class Swapping
Define the default light styles as usual, then write a second complete set of color rules scoped under a class on the <body> element. A button handler in JavaScript adds or removes that class, and the cascade and specificity take care of overriding the light values.
<body>
<button class="btn-toggle">Toggle Dark Mode</button>
<h1>Hey there! This is just a title</h1>
<p>I am just a boring text, existing here solely for the purpose of this demo</p>
<p>And I am just another one like the one above me, because two is better than having only one</p>
<a href="#">I am a link, don't click me!</a>
</body>
Separate Stylesheets
Keep each theme in its own file — light-theme.css and dark-theme.css — and link both in the <head>, with the light file first since it's the default. Toggling means selecting the theme link by ID (#theme-link) and swapping its href rather than swapping classes.
CSS Custom Properties
Custom properties remove the need to duplicate whole rulesets per theme, which speeds up authoring and simplifies later edits. Default values live on the body; a .dark-theme class re-sets them, and the element rules reference the variables rather than literal colors. Putting the variables in :root is equally valid and common, with dark values under something like :root.dark-mode { }.
body {
color: var(--text-color);
background: var(--bkg-color);
}
a {
color: var(--anchor-color);
}
Server-Side Scripts
If a server-side language is already in play, it can apply the body class — for example via a GET (URL params) or POST request — whenever the page reloads; it can also swap stylesheets. The obvious downside is that a refresh is required for the toggle to apply, but this makes it useful for persisting a user's choice across reloads and visits.
Choosing a Method
Project requirements drive the decision: custom properties help manage a large codebase, while legacy browser support may force a different route. Methods can also be combined, and other approaches may exist.
Following the Operating System
Users can already pick light or dark in system settings, and the prefers-color-scheme media query exposes that preference to the page with three possible values: no preference, light and dark.
In pure CSS, dark styles go inside the media query, so dark-mode users get them by default — no JavaScript, no server-side script, no button.
@media (prefers-color-scheme: dark) {
body {
color: #eee;
background: #121212;
}
a {
color: #809fff;
}
}
JavaScript can detect the same signal through matchedMedia(), but scripts run after CSS, so a brief flash of the light theme is likely and may read as a bug. Linking both stylesheets and letting the media query decide which applies is another option.
Letting Users Override the System
A system-wide preference doesn't mean a user wants dark mode on every site, so a manual override is worth providing. The custom-properties pattern works well: define both sets of variables, wrap dark styles in the media query, and add a .light-theme class inside that can override the dark values. The toggle button then respects the OS choice by default while still permitting a manual switch.
Support
prefers-color-scheme is supported by Chrome 76+, Firefox 67+, Chrome Android 76+, Safari 12.5+ (13+ on iOS) and Samsung Internet Browser, but not IE. Can I Use estimates 80.85% user coverage. Dark-mode-capable operating systems include MacOS (Mojave or later), iOS (13.0+), Windows (10+) and Android (10+).
Persisting a Theme Choice
A toggle alone doesn't survive reloads or navigation; the choice has to be stored. localStorage and cookies both fit, as do user accounts.
With localStorage, the script saves the selected theme on toggle and reads it back on load. Since JavaScript executes after CSS, this risks a flash of incorrect theme (FOIT).
A server-side script like PHP can avoid that flash. JavaScript writes the theme to a cookie, and PHP reads the cookie and applies the matching body class — provided the project already has a server-side language. Cookies also pair naturally with the separate-stylesheet method.
Sites with accounts can store the preference in the database and fetch it at login, keeping it in a session variable. PHP's null coalesce operator (??) can pick the session value when the user is logged in and fall back to the cookie otherwise.
Informing the UA Stylesheet
The color-scheme meta tag tells the browser which schemes the page supports; list both, space-separated, or just "light" if only that one is offered. With it, the browser renders user-agent-controlled elements — form controls, root background colors, spell-check styles — according to the user's preference. Because themes are mostly styled by hand and override UA styles, this mainly guards against a flash in cases where HTML has rendered but CSS hasn't loaded yet.
The equivalent CSS property also exists. At time of writing, the property lacks broad browser support, though Safari and Chrome both support it.
Design Considerations
Swap light values for dark ones, then attend to the elements that need more nuance.
Images
Bright images on dark backgrounds are jarring; reducing their brightness and contrast slightly is easier on the eyes. The CSS filter() function handles this, or the <picture> element can load a separate version via markup — at the cost of shipping two files and not fully accounting for on-site toggling.
/* Apply the filter directly on the body tag */
body.dark-theme img {
filter: brightness(.8) contrast(1.2);
}
/* Or apply it via media query */
@media (prefers-color-scheme: dark) {
img {
filter: brightness(.8) contrast(1.2);
}
}
Shadows and Typography
Inverted shadows look wrong. A dark shadow works in dark mode only if the background is light enough (such as a dark gray) for contrast. Rather than naively inverting the light scheme and discarding its visual cues, use opacity to convey depth: higher-elevation elements get lower opacity than those closer to the background.
Typography follows the same balance principle as images. Too heavy a weight glares; too light strains. The sweet spot is in between, and variable fonts can help with legibility.
Icons
Icons sit between text and images. SVG icons can have their fill changed with CSS; font icons can simply have their color changed. The text guidance applies here too — avoid full white and heavy outlines.
Colors and Palettes
Pure white on pure black is harsh. Use off-white text and off-black backgrounds; Material Design Guidelines, for instance, recommend #121212 for the background.
Contrast drives the rest. Run palettes through a contrast checker and target at least WCAG AA, a ratio of 4.5:1. Desaturated colors are helpful in dark themes — they avoid overbright surfaces while leaving room for adequate contrast. Accent colors are enhancements: they're usually brighter than the background, so using them as a primary or large container color is as grating as heavy white text.
Dark mode isn't only blacks and grays. Dark blue with pale yellow text, or dark brown with tan, are viable, and colors like #232B32, #152028 and #202945 are dark without being fully black. Material Design's dark mode guidelines are a useful additional reference.
How Popular Sites Do It
The custom-properties route appears most popular: Dropbox Paper, Slack and Facebook use it. YouTube is a notable example — all colors are defined as variables under the html selector, dark values live under html:not(.style-scope)[dark], and a dark="true" attribute on the <html> tag activates the override. Simplenote uses class swapping, with light rules under a .theme-light parent and dark under .theme-dark, applying the right class to the <body> on toggle. Twitter offers several themes: "Default," "Dim" (a dark blue background) and "Lights out" (a stark black).
Should You Build One?
Valid arguments exist on both sides, including timing, budget and resources. Reasons in favor:
- It supports users who experience eye strain with bright themes, improving accessibility.
- It lets users choose how to consume content while you keep control of the look and feel — better than ceding the job to a Reader Mode button.
- On OLED screens, brighter colors consume more energy, so dark themes can help preserve battery life.
- It's popular enough that some users will expect it.
Trendiness alone is not a reason to implement it.



