Codectionary / Developer documentation / CSS

Supporting Forced-Colors Mode

Forced-colors mode lets a browser replace many author colours with a user-selected palette.

What it is and why to use it

Forced-colors mode lets a browser replace many author colours with a user-selected palette. It is useful for people who need particular contrast settings. Components should remain understandable when backgrounds, shadows and ordinary colour distinctions are changed by that mode.

Common mistakes and limitations

Avoid forced-color-adjust:none on entire components unless a specific exception is justified and tested. Shadows may disappear, so provide structural cues such as borders where needed. Forced-colors is not identical to a normal dark theme.

Try the example

The example pairs editable CSS with its own HTML preview. Run it, then change one declaration at a time and compare the result. Locally, put the CSS in a style element in the document head or in an external stylesheet linked from the HTML. Feature support varies by browser and version; use the linked reference and a useful fallback where needed.

HTML used by this example

<div class="notice"><strong>Saved.</strong> Your progress is available.</div>

Syntax

@media (forced-colors: active) { ... }

Examples

Supporting Forced-Colors Mode

Run the CSS against the supplied HTML, then experiment with the values.

.notice { padding: 1rem; border: 2px solid #2563eb; background: #dbeafe; color: #172b4d; }
@media (forced-colors: active) {
  .notice { border-color: CanvasText; background: Canvas; color: CanvasText; }
}
  1. The default notice uses both text and a border, rather than colour alone.
  2. When forced colours are active, system colours adapt the component to the user’s palette.
  3. Test with the operating system setting or DevTools emulation. The semantic saved message remains available even if the normal blue styling changes.
HTML used by this example
<div class="demo"><div class="notice"><strong>Saved.</strong> Your progress is available.</div></div>

Best practices

  • Avoid forced-color-adjust:none on entire components unless a specific exception is justified and tested. Shadows may disappear, so provide structural cues such as borders where needed. Forced-colors is not identical to a normal dark theme.
  • Inspect the relevant browser reference and test the browsers used by your audience.

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)

Specifications & further reading