Dark mode

In practice

It arrives two ways, and the media query is only half the machinery. The query reports the preference, which the visitor can set in the browser as well as in the operating system. A separate CSS property tells the browser which schemes your page supports, and that is what makes native form controls, scrollbars and the page canvas follow the theme instead of staying stubbornly white. The query now has two values rather than three, and light also means the person never expressed a preference, so write light as the default and treat dark as the override.

Building it as an inversion is the common mistake, and there is a formula behind why it fails. Relative luminance weights the channels unequally, and blue contributes only 7.22% of it, so a saturated brand blue is a very dark colour by the numbers. On a light background it has contrast to spare. On a dark one it has almost none. Brand blues and purples are usually the first casualties of a dark palette, and inverting the greys produces a set of values nobody chose. Measure the pairs rather than trusting the pattern, because the numbers are what the rule reads.

Focus indicators are the next thing to go, and they answer to three rules rather than one. They have to be visible, and they have to clear 3:1 against what sits next to them. At Level AAA the measurement changes again, to the contrast between the same pixels in the focused and unfocused states, which is the one most likely to break when a palette flips. The preference reaches inside cross-origin embeds too, so the video player, the map and the logo stranded white in the middle of a dark page can follow it. Can, not will. The embedded document has to have been built to respond, and where it was not, nothing you write on the outside restyles it for you.

Why it matters

A palette that passes in light mode is not a palette that passes. It is one of two, and the second one is usually the one nobody measured, because a scan reports whichever scheme it happened to load in and most runs never say which that was. Automation can emulate the preference and test both, so ask what the run actually covered rather than assuming either answer. There is one argument here that runs the other way and is worth knowing. WCAG encourages authors to offer colour adjustment mechanisms even where the combinations somebody picks fall below the thresholds, as long as a mechanism brings them back. So a theme toggle is something the standard wants rather than a risk to conformance, and a toggle producing a conforming version can even be the mechanism that reaches a conforming alternate version. That only holds if the toggle itself is operable by keyboard and named for a screen reader.

Where this shows up on the site

• Colour and contrast
• Check a colour pair
• Why an untested theme stays untested

Related terms

• Contrast ratioA contrast ratio is a number from 1:1 to 21:1 measuring how far apart two colors are in brightness, computed from a formula rather than judged by eye.
• High contrast modeHigh contrast mode is an operating-system setting that throws away most of a site's colours and paints the page in a palette the user chose.
• Focus visibleFocus visible is two things with nearly the same name, and keeping them apart settles an argument.
• Low visionLow vision is sight loss that ordinary glasses cannot correct, and it covers far more ground than a single blurred-vision picture suggests.
• prefers-reduced-motionprefers-reduced-motion is a preference people set in their operating system or their browser, and it reaches your CSS as a media query and your JavaScript as a check you can read.
• Forced colorsForced colors is what the web platform calls it when somebody's operating system throws your palette away and repaints the page in colors they chose.