Windows High Contrast Themes

Supporting Windows 11 High Contrast Desktop Themes

High-contrast themes in Windows 11 are crucial for accessibility. High contrast themes overwrite CSS colors including color, backgroundColor, and boxShadow, while border and outline properties retain their settings. To ensure your UI is compatible, follow these best practices for improved visibility.

Further reading: Change color contrast in Windows 

Focus Indicators:

Since Canvas Kit components rely on boxShadow for the keyboard focus state, it won’t be visible in high contrast themes. We’ve added a 2px solid transparent CSS outline to ensure a focus indicator remains visible. Use outlineOffset to add space between the element and the outline for aesthetics. We’ve used a 2px offset on components like BaseButton  to match the visual design of the boxShadow in the system. A -2px negative offset is used for focusable components inside popup containers like the <Menu> component to ensure the focus indicator isn’t clipped off the edge. (For example: MenuItem .)

Boundary Borders and Outlines:

If content needs to be grouped with a boundary in high contrast themes, using a transparent CSS outline can be useful because it won’t cause alignment problems on the page. We’ve done this to draw boundaries in components that don’t have any focus state like ModalCard  and TooltipContainer .

Images:

<img> elements, which are for images like JPEGs or PNGs, are not affected by high contrast themes. If you use a meaningful image with a transparent background, it could become difficult to see against some background colors. Be careful when using such images for conveying information to users.

SVG Icons

The colors inside <svg> elements usually don’t change with high contrast themes, which can make them hard to see on some backgrounds. We’ve used a media query to set the icon fill and color properties to currentColor ensuring the icon uses the correct color from the user’s preferred high contrast theme.

// for Windows high contrast desktop themes
'@media (prefers-contrast: more)': {
  '.wd-icon-fill, .wd-icon-accent': {
    color: 'currentColor',
    fill: 'currentColor',
  },
},