High Contrast Mode: Supporting Forced Colors

1. What forced-colors mode is and who relies on it

Forced-colors mode is an operating system setting, best known as Windows High Contrast Mode, where the operating system instructs the browser to replace nearly all developer-defined colors with a fixed, user-selectable system palette. This mode is used above all by people with severely limited vision or contrast perception disorders, for whom a low-contrast default rendering is simply unreadable.

Unlike a plain dark color scheme, forced-colors mode digs considerably deeper into rendering: it removes not only background colors but often also shadows, gradients, and custom border colors, replacing them with a radically reduced palette, typically fewer than ten colors, guaranteed to offer sufficient contrast between one another.

2. Detecting the forced-colors media query

Whether the mode is active can be determined both in CSS via @media (forced-colors: active) and in JavaScript via window.matchMedia('(forced-colors: active)').matches, structurally identical to the already familiar prefers-reduced-motion query. Inside an Alpine component, the same matchMedia technique works to capture the state as a reactive property and adjust component-specific behavior when needed.

In practice, the plain JavaScript detection gets needed less often than for prefers-reduced-motion, because forced-colors mode is primarily handled through CSS, with the browser doing most of the color replacement automatically. A JavaScript check pays off mainly when a component deliberately needs to show a different structure or extra text labels under forced colors, not just different colors.

3. system-color keywords: CanvasText, ButtonFace, LinkText and more

Inside a forced-colors media query, special CSS keywords are available that the operating system fills with the currently active system color, such as Canvas for the default background, CanvasText for default text, ButtonFace and ButtonText for controls, and LinkText for links. These keywords guarantee that a custom component uses the same color palette as native browser elements under the same mode.

It matters to use these keywords deliberately only inside the forced-colors media query, not as a general replacement for the actual color palette, since outside forced-colors mode the real brand and Tailwind colors should of course still apply. The keywords serve purely as a targeted override for the special case of forced system color replacement.

@media (forced-colors: active) {
  .btn-primary {
    background-color: ButtonFace;
    color: ButtonText;
    border: 1px solid ButtonText;
  }

  .badge-highlight {
    background-color: Canvas;
    color: LinkText;
    border: 1px solid CanvasText;
  }
}

4. How Alpine-generated classes and inline styles behave under forced colors

An Alpine component that sets colors dynamically through :class or :style, for example a status color for an availability indicator, largely gets overridden by the browser under forced-colors mode, since the mode explicitly ignores set background-color and color values to enforce the fixed system palette. That affects Tailwind utility classes and inline styles set through x-bind equally.

What generally does not get overridden is borders, as long as they are set through an explicit border property with a visible width, along with the component's underlying structure and text content. An Alpine component that relies purely on background color for meaning, for example a colored dot with no text as a status indicator, loses that information entirely under forced-colors mode if no extra border or text is present.

5. Practical example: testing a custom dropdown under forced colors

A custom dropdown built with Alpine that normally uses a subtle gray background and a colored border on hover can suddenly render with no visible separation between individual options under forced-colors mode, if only background colors were used for distinction. The browser replaces those backgrounds with a single uniform system color, and the visual separation gets lost.

The robust solution is defining an explicit border for every interactive option in addition to background colors, one that stays visible via the border property even after the color replacement under forced colors, and signaling the currently focused or selected state through a structural change like a thicker border rather than exclusively through a color change.

<div x-data="dropdown()" class="relative">
  <button @click="open = !open" class="border border-gray-300 rounded px-4 py-2">
    <span x-text="selected || 'Please select'"></span>
  </button>

  <ul x-show="open" class="absolute mt-1 border border-gray-300 bg-white">
    <template x-for="option in options" :key="option">
      <li
        @click="select(option)"
        :class="{ 'border-2 border-blue-600': option === selected, 'border border-transparent': option !== selected }"
        class="px-4 py-2 cursor-pointer"
        x-text="option"
      ></li>
    </template>
  </ul>
</div>

6. Using forced-color-adjust: none deliberately

For rare cases where a component absolutely must keep its own coloring even under forced-colors mode, for example a color picker widget whose entire purpose is exact color representation, the CSS property forced-color-adjust: none offers a targeted opt-out from automatic color replacement for exactly that element. The browser then respects the actually defined colors again.

This opt-out should be used with considerable restraint, since any element with forced-color-adjust: none automatically loses the guaranteed contrast ratios that forced-colors mode is meant to ensure, and responsibility for sufficient contrast then falls entirely back onto the development team. For the vast majority of UI components, forced-color-adjust: none is not the right solution but rather a deliberate exception.

7. Pitfall: disappearing focus indicators with custom styles

By far the most common pitfall under forced-colors mode is a focus indicator built purely through a custom outline color or a box-shadow, since box-shadow gets ignored entirely under forced colors and an outline color gets replaced by the system color, which in unfavorable combinations can result in a barely visible indicator if outline color and background happen to resolve to the same system color.

The most reliable solution is relying primarily on the native outline property with a sufficient outline-width and outline-offset for focus indicators, instead of box-shadow, since outline gets replaced by default under forced-colors mode with the system color designated for focus rings, staying guaranteed visible without the component itself needing any forced-colors-specific code at all.

8. Testing in the browser: Windows High Contrast and Chrome emulation

The most reliable test happens on a real Windows system through the Ease of Access and Contrast themes settings, where several predefined contrast themes such as Black on White or White on Black can be switched between, to check whether a component works consistently across multiple variants, not just in a single randomly tested combination.

For a quick interim check without a Windows system, the developer tools in Chrome and Edge offer emulation through the Rendering tab with the Emulate CSS media feature forced-colors option, which is not one hundred percent identical to real Windows rendering, but already reliably surfaces most structural problems like disappearing borders or focus indicators.

9. A checklist for forced-colors-ready Alpine components

Before shipping a new interactive Alpine component, a short, fixed checklist pays off: are all interactive boundaries marked through visible border properties instead of relying purely on background colors, is the focus indicator implemented through outline instead of box-shadow, and does no piece of information get conveyed exclusively through a color with no accompanying text or icon.

In addition, every component should get checked at least once under Chrome emulation and, for larger, frequently used components such as header navigation or the checkout form, additionally on a real Windows system with high contrast mode enabled, before the component counts as fully tested, since emulation does not capture every quirk of real operating system rendering.

10. Summary

11. FAQ: Forced Colors With Alpine: Key Takeaways