v145 · CSS · Forced Colors Context

Forced Colors Context

How forced-colors mode works, which CSS properties are overridden, how to detect it, and the system color keywords available for writing high-contrast-aware styles.

Forced colors mode is activated by the user via OS settings (Windows High Contrast mode, macOS Increase Contrast + Differentiate Without Color) or by CSS forced-colors: active in DevTools emulation. Authors cannot activate it — only detect it.

CSS properties overridden

Property Override behaviour
color Replaced with CanvasText or ButtonText depending on context
background-color Replaced with Canvas or ButtonFace
border-color Replaced with ButtonText
outline-color Replaced with ButtonText
box-shadow Removed (set to none)
text-shadow Removed
Background images on text Removed unless forced-color-adjust: none

system color keywords

Keyword Represents Typical use
Canvas Background of page/app Container backgrounds
CanvasText Foreground text color Body text, labels
ButtonFace Button background Interactive elements
ButtonText Button foreground text Button labels, borders
LinkText Unvisited link color Anchor elements
Highlight Selected item background Selection, focus rings
HighlightText Selected item text Selected text color

author best practices

/* Detect forced-colors and adjust styles */
@media (forced-colors: active) {
  /* Use system color keywords for forced-colors-safe colours */
  .my-badge {
    background: ButtonFace;
    color: ButtonText;
    border: 1px solid ButtonText;
  }

  /* Icons that rely on fill color need special handling */
  svg.icon {
    fill: ButtonText;
  }

  /* Preserve forced-color adjustments for specific elements */
  .image-text-overlay {
    forced-color-adjust: none; /* opt out — use with care */
  }
}

/* Skip box shadows and text shadows — removed in forced colors anyway */
/* They add visual complexity with no benefit in high-contrast mode */

see also

scenario focus

Select a scenario to focus its rendered example and summary.