Skip to main content
HTML5ANDCSS3 logoHTML5ANDCSS3Tools and Tutorials

CSS Accessibility

CSS Theming

Written by Published

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

SyntaxPurposeExample
color-schemeDeclares supported schemes for browser-provided UI.color-scheme: light dark
prefers-color-schemeReads 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-adjustControls 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-scheme81819613
light-dark()12312312017.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: none unless 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.

PreviousAccessible CSSNextModern Form Styling