In CSS, which media feature reports the user's light/dark appearance preference, and how do you use it to theme a page?

## What the feature actually reports `prefers-color-scheme` is a *user-preference media feature*: a condition you can test in an `@media` rule that describes the person and their environment rather than the screen's dimensions. It reports whether the user has asked their operating system (or, on some platforms, their browser) for a light or a dark appearance. It is not an ambient-light sensor, it does not know what time it is, and it does not know what colours your page currently uses — it is a single preference flag piped from the OS into CSS. Because it is a media feature, it is *live*. When the user flips their system appearance while your page is open, the query re-evaluates and the styles swap immediately, with no reload and no JavaScript. ## The values There are exactly two: `light` and `dark`. An earlier draft of the specification also defined `no-preference`, but it was removed, and browsers do not report it — if the user has expressed no preference, the platform simply reports `light`. So `@media (prefers-color-scheme: light)` and `@media (prefers-color-scheme: dark)` between them cover every user, which is why writing the light theme as the unconditional default and treating dark as the override is the conventional shape. ## The authoring pattern The pattern that scales is to keep every colour behind a named value and change only those values in the override block: ```css :root { color-scheme: light dark; --surface: #ffffff; --text: #101418; --border: #d8dde3; } @media (prefers-color-scheme: dark) { :root { --surface: #101418; --text: #e8ecf1; --border: #2a323b; } } body { background: var(--surface); color: var(--text); } ``` The important property of this shape is that there is exactly *one* `@media (prefers-color-scheme: dark)` block in the codebase. The alternative — a dark override next to every component — means every new component is a new opportunity to forget one, and the failure mode is dark text on a dark background. ## `color-scheme` is a separate job A very common bug is a page whose own surfaces go dark while its `<select>` dropdowns, checkboxes, scrollbars, and the blank canvas behind the page stay stubbornly light. That is because a media query only changes declarations *you* wrote; it cannot reach into user-agent-rendered widgets. The `color-scheme` property is what does that: ```css :root { color-scheme: light dark; } ``` This says "this page renders correctly in either scheme, so render your built-in UI in whichever one the user prefers." It also fixes the flash of white canvas before your stylesheet paints. ## Adding an explicit toggle If the product offers its own light/dark switch, the system preference becomes the *default* rather than the *decision*. The usual arrangement puts an attribute on the root element and lets a selector override the media query's values: ```css :root[data-theme="dark"] { --surface: #101418; --text: #e8ecf1; } ``` Because a selector on the root element wins over the same declarations set inside the media query at equal specificity by source order, placing the explicit-choice rules after the media query gives the user's choice priority while the query still handles everyone who has not chosen. ## `light-dark()` Newer stylesheets can collapse the two blocks with the `light-dark()` function, which takes two colour values and picks one according to the used colour scheme: `--surface: light-dark(#ffffff, #101418);`. It only works when `color-scheme` has been set on the element or an ancestor. It became available across the major browsers during 2024 (Firefox 120, Chrome 123, Safari 17.5), so a codebase that must support older browsers still writes the media-query form. ## What goes wrong in practice - **Only inverting background and text.** Borders, shadows, focus rings and disabled states all need attention; a pure-black shadow is invisible on a dark surface, and light-theme borders vanish. - **Images and illustrations baked for white.** Logos with white knockouts and screenshots with white chrome look broken; they need a dark counterpart or a container that keeps a light surface behind them. - **Insufficient contrast.** Pure white text on pure black is uncomfortable to read; dark themes usually use a near-black surface and a slightly dimmed foreground while still clearing contrast requirements. - **Assuming a reload is needed.** The query is live, so any state your page derives from it must be derived reactively rather than sampled once.