Codectionary / Developer documentation / CSS

Responding to prefers-contrast

prefers-contrast reports a user preference for a different level of contrast.

What it is and why to use it

prefers-contrast reports a user preference for a different level of contrast. It can enhance an already accessible baseline with clearer borders or stronger distinctions. It is a preference signal rather than an automatic contrast checker or a promise that every platform exposes the same settings.

Common mistakes and limitations

Do not make the default state deliberately low contrast. Values such as less and custom have different meanings; forced-colors can also interact with preferences. Verify support and test the actual palette rather than assuming the query guarantees accessibility.

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="note">Lesson ready to review.</div>

Syntax

@media (prefers-contrast: more) { ... }

Examples

Responding to prefers-contrast

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

.note { padding: 1rem; border: 1px solid #64748b; color: #1e293b; background: white; }
@media (prefers-contrast: more) {
  .note { border: 3px solid black; color: black; }
}
  1. The default foreground and border are readable before any query matches.
  2. A more-contrast preference increases border emphasis and uses a darker foreground.
  3. Compare the two states with emulation where available. This is useful for making component boundaries easier to identify without changing content.
HTML used by this example
<div class="demo"><div class="note">Lesson ready to review.</div></div>

Best practices

  • Do not make the default state deliberately low contrast. Values such as less and custom have different meanings; forced-colors can also interact with preferences. Verify support and test the actual palette rather than assuming the query guarantees accessibility.
  • 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