CSS Accessibility
CSS Theming
Build light and dark themes that work with browser controls, user preferences, and forced colors. You will coordinate system preferences, color-scheme, light-dark(), custom-property tokens, explicit overrides, and forced-color behavior.
A CSS theme is a coordinated set of semantic color and presentation tokens. color-scheme also tells the browser how built-in controls and default surfaces should be rendered.
Changing a page background is not enough to create a dark theme. Text, borders, focus indicators, form controls, shadows, images, and code surfaces must remain legible together. Semantic tokens reduce that work by naming roles such as surface, text, border, and action instead of duplicating raw color values. This topic also connects with Modern Colors and CSS Variables.
Declare supported schemes
Example
css
:root {
color-scheme: light dark;
--surface: light-dark(#ffffff, #111827);
--text: light-dark(#172033, #e5e7eb);
}
body {
background: var(--surface);
color: var(--text);
}color-scheme lets the browser choose appropriate colors for built-in controls, scrollbars, and canvas defaults. The light-dark() function chooses a value from the active scheme.
Offer an explicit theme override
Example
css
html[data-theme="dark"] {
color-scheme: dark;
--surface: #111827;
--text: #e5e7eb;
}Forced colors
Example
css
@media (forced-colors: active) {
.button {
border: 2px solid ButtonText;
forced-color-adjust: auto;
}
}Theming Reference
| Syntax | Purpose | Example |
|---|---|---|
| color-scheme | Declares supported schemes for browser-provided UI. | color-scheme: light dark |
| prefers-color-scheme | Reads the user's preferred scheme. | @media (prefers-color-scheme: dark) |
| light-dark() | Selects a color according to the used scheme. | color: light-dark(#111, #eee) |
| forced-color-adjust | Controls forced-color adjustments in exceptional cases. | forced-color-adjust: auto |
Complete Example
Run the complete document below in the Try It editor. Resize the preview or interact with the controls where the example calls for it.
Complete runnable example
html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>CSS Theming example</title>
<style>
* { box-sizing: border-box; }
body {
margin: 0;
padding: 2rem;
font-family: system-ui, sans-serif;
line-height: 1.5;
}
main { max-width: 70rem; margin-inline: auto; }
article, section, aside, form, .card, .panel {
padding: 1rem;
border: 1px solid #cbd5e1;
border-radius: 0.6rem;
}
:root {
color-scheme: light dark;
--surface: light-dark(#ffffff, #111827);
--text: light-dark(#172033, #e5e7eb);
}
body {
background: var(--surface);
color: var(--text);
}
html[data-theme="dark"] {
color-scheme: dark;
--surface: #111827;
--text: #e5e7eb;
}
@media (forced-colors: active) {
.button {
border: 2px solid ButtonText;
forced-color-adjust: auto;
}
}
</style>
</head>
<body>
<main><article class="card"><h1>System-aware theme</h1><p>This surface follows the active color scheme.</p><button onclick="document.documentElement.dataset.theme=document.documentElement.dataset.theme==='dark'?'':'dark'">Toggle explicit dark theme</button></article></main>
</body>
</html>Browser Support
Feature | Chrome | Edge | Firefox | Safari |
|---|---|---|---|---|
| color-scheme | 81 | 81 | 96 | 13 |
| light-dark() | 123 | 123 | 120 | 17.5 |
Versions show the first stable desktop release with unprefixed support. Data source: MDN Browser Compatibility Data 8.0.8. A partial-support note is included where it changes how the example behaves.
Notes
- Avoid opting out with
forced-color-adjust: noneunless a small visual element genuinely requires its authored colors and remains understandable. - Test the example with real content, keyboard input, browser zoom, and the narrowest layout your project supports.
- Use a fallback when the support table shows that one of your required browsers predates the feature.
Conclusion
A reliable theme coordinates authored tokens with the browser’s active color scheme and forced colors.
Respect the system preference as a useful default and preserve an explicit user selection when the product offers one. Test every theme independently for contrast, then test forced colors without attempting to repaint the entire system-controlled palette.