Color-scheme metadata tells the browser which light and dark color schemes a document can handle. Theme-color is a separate hint for browser interface areas around the page.
Make this comfortable
HTML color-scheme metadata: declare supported UI schemes separately from browser chrome
Use the contract
An incident console offers both light and dark presentation. Declare that support in the head, then supply actual CSS colors for the document and controls. A matching theme-color may tint parts of the browser interface where the browser supports it; it does not paint the page or guarantee exact chrome colors. The dark and light theme-color entries use different media conditions, so one can match each scheme. Keep text, controls, focus indicators, and images readable in both. If the site only styles one scheme, claiming both support can produce an awkward mix of browser controls and page colors.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="color-scheme" content="light dark">
<meta name="theme-color" content="#f4f1e8" media="(prefers-color-scheme: light)">
<meta name="theme-color" content="#18232a" media="(prefers-color-scheme: dark)">
<title>Incident queue</title>
<style>
body { background: #f4f1e8; color: #18232a; }
@media (prefers-color-scheme: dark) {
body { background: #18232a; color: #f4f1e8; }
}
</style>
</head>
<body><main><h1>Incident queue</h1><p>47 records await review.</p></main></body>
</html>Behavior and cost
These declarations are tiny; the cost is testing two complete visual states. A browser may adjust or ignore theme-color when painting its own interface. Test native inputs, system contrast settings, images with transparent backgrounds, and the first paint before CSS finishes loading. Color-scheme metadata can help the browser choose an appropriate early rendering mode, but a correct page still depends on a complete stylesheet. If a future design removes dark support, update the metadata as well as the CSS rather than leaving a false promise in head.
Common Mistakes
- Do not confuse theme-color with a CSS background declaration.
- Do not claim dark support until every meaningful surface has been checked.
- Do not assume all browsers render browser chrome from the hint identically.
Connected lessons
- HTML viewport metadata: let a mobile layout use device width
- HTML title and metadata: distinguish document identity from page copy
- HTML print stylesheet: declare a separate rendering context
Form and type styling
- CSS forced-color-adjust: preserve a color only for a narrow reason
- CSS prefers-contrast: strengthen an already readable interface
Related CSS decisions
html