Light and Dark Theming with CSS

CSS accepts color values in several notations. The most common is hexadecimal, which encodes the RGB (red, green, blue) color model: a # followed by six characters, each consecutive pair giving the intensity of red, green, and blue respectively, from 00 to ff.

The same RGB model is also available as a function, rgb(red, green, blue), with each channel given as an integer from 0 to 255 (or, in modern CSS, a percentage) instead of a hex pair — useful when a value is computed or needs an alpha channel via rgb(red green blue / alpha).

Neither hex nor rgb() is convenient when you need to derive a related but different color, such as a complementary color for a dark theme, because red/green/blue channels don’t map intuitively onto "the same hue, darker" or "the same hue, opposite." The hsl() function solves this by describing a color as hue, saturation, and lightness instead of raw color channels:

Because hue is just an angle and lightness is just a percentage, hsl() makes it straightforward to derive a dark counterpart of a light palette (or vice versa) by adjusting those two numbers directly, as the next section shows.

Hue is easiest to reason about when visualized as a wheel of angles, since it makes complementary (opposite) colors easy to spot — for example red and cyan, or green and magenta:

The wheel above is drawn with 0deg at the top and hue increasing clockwise, which is exactly how CSS’s own conic-gradient() walks a set of colors — so background: conic-gradient(in hsl longer hue, hsl(0 100% 50%), hsl(360 100% 50%)) paints this same ring.

The complementary color of any hue is found by adding 180 degrees to it; if the result exceeds 360, it simply wraps back around to the start of the wheel. Applying this to a light theme’s palette produces a plausible starting point for a dark theme:

Rotating the hue alone is rarely enough to produce a convincingly dark theme, though: the saturation and lightness percentages carried over unchanged still describe a light, high-lightness background and a low-lightness (dark) text color. A real dark theme also needs those two swapped — pushing the background’s lightness down toward 0% and the text’s lightness up toward 100%:

The simplest way to ship a light and a dark theme is to keep each palette’s custom properties in its own stylesheet — light.css and dark.css — both defining the same set of --variable names under :root, and to link only one of the two <link> elements in at a time:

Because both files declare the same variable names, every other stylesheet that consumes them via var() (see CSS Custom Properties and Media Queries) needs no change at all when the theme is switched — only the <link> (or, as the next sections show, a media query) selecting which palette file applies needs to change.

Rather than maintaining a second palette by hand, the invert() CSS filter function can flip an element’s rendered colors to their opposites on the fly. It takes a percentage: 0% leaves colors unchanged, 100% fully inverts them, and 50% is the neutral midpoint that cancels out all color, effectively rendering pure gray:

Applying invert(100%) to the whole page’s root element is the fastest way to bolt a "dark mode" onto an existing light-only stylesheet, with no palette duplication and no need to touch existing color declarations. The trade-off is precision: invert() flips hue, saturation, and lightness of everything it’s applied to, including images and photos, which usually look wrong inverted. In practice this means scoping invert() to specific text/background containers rather than :root, or excluding image elements with a second, counter- inverting rule.

Since 2022, CSS can react to the user’s operating-system light/dark preference without any JavaScript, through two cooperating pieces:

color-scheme accepts:

Declare it once on :root to opt the whole page into both schemes:

Or scope it per element, including forcing a specific section to ignore the user’s preference entirely:

color-scheme alone only affects browser-drawn chrome, though — it does not, by itself, change any author colors. Pairing it with prefers-color-scheme and the custom properties from CSS Custom Properties and Media Queries lets a single stylesheet carry both palettes and switch between them automatically:

This collapses the separate light.css / dark.css files from the previous section into one stylesheet, switched automatically by the operating system’s setting rather than by which <link> happens to be present in the page. Because only one branch of the media query ever matches at a time, there’s also no need to layer invert() on top — there’s nothing left over from the other theme for it to invert.

light-dark() compresses the prefers-color-scheme pattern above into a single property value. It takes two colors — one for light mode, one for dark — and resolves to whichever one matches the current color-scheme:

light-dark() still depends on color-scheme: light dark being set on an ancestor (typically :root) — without it, the browser has no signal for which of the two values currently applies. It replaces the @media (prefers-color-scheme: …​) blocks entirely for simple value swaps, at the cost of only working inside property values rather than letting you branch on arbitrary CSS structure the way a media query block can.