Windows High Contrast Mode (WHCM) Support

[pwolfert]

RFC: Windows High Contrast Mode (WHCM) Support

Date: November 29, 2021
Author: @zarahzachz
Original PR: #1298
Status: Ready for review

Background

Windows High Contrast Mode (WHCM) is a unique accessibility feature originally designed for Windows users with contrast sensitivity and low vision issues. Other reasons a user might enable WHCM include:

• Reducing visual noise to improve focus
• Easing eye strain, migraines, or light sensitivity
• Preferring a specific color scheme

With WHCM, users can select a theme of colors for a scoped number of semantic elements. These colors are mapped to a subset of CSS2 System Color keywords, which is then applied to user interfaces and applications.

Windows provides a handful of preexisting themes, which can be customized to the user's preference. The WHCM color palette consists of the following colors:

• Text (foreground) color
• Hyperlink color
• Disabled text color
• Selected text color
  • Text (foreground) color
  • Background color
• Button text
  • Text (foreground) color
  • Background color
• Background color

Problem

Our Design System was built primarily by developers using macOS, so it wasn't as apparent how our UI library looked or behaved when WHCM was enabled. As a result, many of our more complex UI components range from difficult to impossible to use.

This initial full audit captures how these components appear/behave in WHCM.

The bulk of the outages can be categorized as follows (number doesn't denote priority):

1. Inconsistent disabled states across the system.
   1. All disable states should be mapped to WHCM's "disabled text color," which is GrayText.
   2. For additional context, the not-allowed cursor should be implemented on disabled states.
2. Form fields should have consistent and usable states and hint text.
   1. Default form fields look indistinguishable from success and error states (i.e., when red/green borders on inputs denote error/success).
      1. It may be worth exploring different border treatments to show that a field has a non-default state.
   2. Hint text looks identical to error text.
      1. Error text should be prepended with an error icon.
   3. Most issues appear to be inherited from the <FormLabel /> component.
3. Components that rely on color alone to denote meaning need to be reconsidered.
   1. <Alert />, form fields, <Badge />, and <Button /> to some extent rely only on color, which can make it difficult to know the difference between a "success" and default variety component.
4. Borders are either non-existant or are too thin in a high contrast setting.
   1. <Badge />, <FilterChip />, <HelpDrawerToggle />, <Tooltip />, and the <Modal /> close button are the biggest offenders when it comes to border issues.
   2. Consider making borders thicker, maybe 2-3px?
   3. Content within <Accordion /> and <Tabs /> aren't visually grouped together and borders are missing.
5. SVGs vary in visibility.
   1. SVGs include icons and logos.
   2. SVGs that don't use system colors can be difficult to see.
   3. Consider using currentColor for SVG fill to ensure they receive some kind of contrast with the background.
6. Buttons.
   1. When ghost style buttons are used within components (i.e., <Pagination />), there's an issue with padding/margin, or the button's borders are broken.
   2. Links styled as buttons look visually different from buttons - is this OK?

Proposal

CSS media queries exist to detect if WHCM is enabled and can help developers modify how styles are applied to specific elements. These queries provide both guidance for the browser on how a web element should appear when WHCM is enabled and contain any necessary style overrides so they're applied only when WHCM is enabled (meaning high contrast styles won't bleed out into non-high contrast scenarios).

-ms-high-contrast is a Microsoft extension that targets WHCM for IE and older versions of Edge. It supports none, active, black-on-white, and white-on-black as values, but it's recommended at this point to only use the active value.

forced-colors is a new media query supported by Chrome, Edge, and Firefox and is considered the standard for browsers moving forward. It supports none and active as values.

Windows recommends using both media queries (aka "The Frankenquery") to guarantee adequate support for those using WHCM. This would look something like:

@media (-ms-high-contrast: active), (forced-colors: active) {
  /* CSS overrides here */
}

Examples

Ex. 1: Specifying custom style rules on an element

Both -ms-high-contrast and forced-colors queries behave like your average run-of-the-mill queries in that they scope their defined styles to a specific condition (high contrast, in this case).

For example, if we wanted to increase the border-width on <FilterChip />, you could write the following code:

@media (-ms-high-contrast: active), (forced-colors: active) {
  .ds-c-filter-chip__button {
    border-width: 2px;
  }
}

In this example, a 2px border would be applied to the <FilterChip />, but only when WHCM is enabled.

⚠️ It's worth noting that while you can apply specific color values (i.e., hex values) using this query, it's recommended you avoid using static colors in forced colors mode due to the risk of introducing a visual contrast bug.

To implement colors, it's recommended you use CSS System Colors, which will automatically pick up whichever color the user specified. See Ex. 2 for more details about CSS System Colors.

Ex. 2: Overriding an element's style rules using CSS System Colors

For instances where the color of an element needs to be adjusted, it's recommended you use CSS System Colors. These colors are basically a limited set of variables a user sets to define their contrast theme. You can find a list of available colors in the link above.

Using system colors in lieu of static colors is preferred because a static color, like #ff0000, may have unexpected and severe contrast issues for your user.

For example, because we've implemented custom checkbox and radio buttons, these elements don't receive all the styles a native checkbox or radio button would normally receive. So when a checkbox or radio button is disabled, that style isn't apparent at all in WHCM. To fix something like this, you'd implement the following:

@media (-ms-high-contrast: active), (forced-colors: active) {
  .ds-c-choice:disabled + label {
    color: GrayText; /* `GrayText` is the CSS System Colors name for disabled text */
  }
  .ds-c-choice:disabled + label:before {
    border-color: GrayText;
  }
}

Ex. 3: Making sure an element's style persists, regardless of contrast mode

There are some scenarios where you may want to force an element to appear the same in WHCM as you would in any non-WHCM environment. For our purposes, we may want to use this approach for sections of our documentation site, like our color swatches, which have visual meaning but don't appear in WHCM due to the limited WHCM color palette.

To preserve the original appearance of an element in WHCM, you could write the following:

@media (-ms-high-contrast: active), (forced-colors: active) {
  .c-swatch__preview {
    -ms-high-contrast-adjust: none; /* For IE */
    forced-color-adjust: none; /* For everything else * /
  }
}

Recommendation

1. WHCM updates should support IE in addition to modern browsers.

While our design system no longer technically supports IE (as it falls below our 2% support threshold), a good percentage of those who rely on WHCM continue to use it. And because the effort to support IE is low, I agree with Microsoft's recommendation - just be certain your system color keywords work across both queries and the cascade doesn't impact how those styles render (meaning, test the changes). If more targeted styles are needed between IE and Edge, the Frankenquery may need to be split.

2. New and refactored components should be checked in WHCM as part of our "definition of done".

We have access to a SauceLabs account and they have good documentation for how to do local testing, so we should use it.

3. Collaboration between developer and designer may be needed for some issues, but probably not all.

There are some issues in WHCM that I would consider low severity and I'd think design could trust development to implement a good solution. I'm thinking border-widths, margin/padding on our buttons, and ensuring System Colors are being implemented correctly (like in the disabled state mentioned above). For these kinds of issues, I can envision a developer making an adequate fix and maybe sharing a screenshot with design if needed.

Designer/developer collaboration is probably needed for moderate-to-severe issues.

A moderate concern might be how our error states look on form fields, or how SVGs should look in certain context (to currentColor or not to currentColor?).

A severe concern is when a component doesn't work correctly or fails to convey its messaging. Think <Alert /> (they all look the same, without indication of severity) or <Tabs />/<VerticalNav /> (where the active state is difficult to see or not apparent).

Depending on the issue, this collaboration might be able to happen asynchronously or require a meeting. Asynchronous communication could be as simple as sharing screenshots, or even sharing Storybook links so each party can test the component in WHCM themselves.

🗣 I believe most of our WHCM issues fall under low or moderate severity, with the bulk being how our SVGs (icons and logos) should look on their own and within certain contexts.

Before any work begins:

It's not the intention of this work to create a separate design for WHCM users. If semantic HTML is used correctly, there should be very little need to overwrite styles. The overall recommendation is to use a light touch when applying fixes. As Adrian Roselli writes:

You should only ever use these feature queries to spackle over gaps (found in most libraries / frameworks) or enhance an experience that may be lacking.

And as MSN says:

[...] its intended usage is to make small tweaks to improve usability or legibility when the default application of forced colors does not work well for a given portion of a page.

I believe the outages identified (with maybe the exception of Buttons) fall into this definition.

Benefits

• We get to be Good Guy Gregs by supporting a widely used accessibility feature
• Our design system delivers a consistent experience regardless of user setting
• Current unusable components will be usable to our users and the end users

Risks

• Overrides between the media queries outlined may not be a perfect 1:1 match - visual testing will be required
• Support for forced-colors exists in all modern browsers, but the spec is still in draft mode so the spec may change
• There isn't a way to automate testing, so visual regressions within WHCM could potentially exist for awhile without detection

Questions and Requested Feedback

We'll need to codify some kind of workflow to ensure WHCM is being accounted for.

If a light or dark theme is introduced to our system, we'll need to reevaluate our WHCM solutions to best account for those preferences. prefers-color-scheme is a query that can be used in combination with the contrast queries mentioned above to accommodate WHCM users with a light or dark theme preference. But because our system doesn't currently accommodate a light/dark themes, I don't think this is something we need to pursue at this time.