Browser controls and your own colours are separate jobs
The color-scheme property tells the browser which schemes an element can support. The browser may then adjust built-in surfaces and controls such as form fields and scrollbars. It does not automatically design every background, heading and border in your page. You must supply suitable author colours for those elements.
The prefers-color-scheme media feature responds to a user or system light/dark preference. Give the page a readable default first, then override author colours for dark mode. A website can also offer its own theme switch; that requires application state and should not silently override a user’s explicit choice.
Give a small page two readable palettes
The example declares that the root supports both schemes, sets explicit light colours and changes them when a dark preference matches. The card uses inherited text colour. A button would also receive browser-supplied control styling appropriate to the scheme, but its contrast should still be checked in both modes.
Change your operating system or browser preference and reload. If the page does not change, verify the environment’s preference and inspect the matching media query in DevTools. Test both palettes rather than assuming dark mode is simply inverted light mode.
HTML
<main class="page"><h1>Study notes</h1><p>Save a short summary after each lesson.</p><button>Save note</button></main>CSS
:root { color-scheme: light dark; }
body { margin: 0; background: #ffffff; color: #182334; }
.page { max-width: 36rem; margin: 2rem auto; padding: 1.5rem; border: 1px solid #c7d2e0; }
@media (prefers-color-scheme: dark) {
body { background: #101820; color: #edf3f8; }
.page { border-color: #526276; }
}Check colour and browser behaviour
Test text, borders, links, focus indicators and controls in both schemes. A CSS colour that works on white may disappear on a dark background. The user preference can change while the page is open, and different browsers can render native controls differently. Provide a sensible default even when the preference query does not match.
color-scheme: light dark is an opt-in for browser-owned rendering, not a promise that your custom colours have sufficient contrast. Use DevTools to emulate schemes and inspect the resulting computed colours.
Scope a scheme to a component when needed
You can set color-scheme on an individual component when it supports a particular scheme. For example, a dark code panel within a light page can opt into dark browser-controlled UI inside that panel. The rest of the page may keep a light scheme. Be careful with embedded controls and transparent backgrounds; explicitly style the surfaces around them.
Syntax
:root { color-scheme: light dark; }
@media (prefers-color-scheme: dark) { /* dark colours */ }Examples
A two-scheme study page
The page follows the light or dark preference without JavaScript.
:root { color-scheme: light dark; }
body { background: #ffffff; color: #182334; }
.page { border: 1px solid #c7d2e0; }
@media (prefers-color-scheme: dark) {
body { background: #101820; color: #edf3f8; }
.page { border-color: #526276; }
}- :root advertises support for both schemes to the browser’s built-in UI.
- The normal body and card rules define the light default.
- The media query replaces author colours when the environment requests dark mode. Check contrast in both modes.
HTML used by this example
<main class="page"><h2>Study notes</h2><p>This page follows your colour preference.</p></main>Best practices
- Supply explicit readable palettes; color-scheme alone does not style your whole page.
- Test links, focus indicators and form controls in both modes.
- Keep an explicit user-selected theme separate from the system preference when adding a theme switch.
Runtime & versions
Web browsers. Feature availability depends on the language and runtime version used by your project; consult the official reference below.
CSS specifications (modules)