Accessibility/Design Guide

Frontend Accessibility Guidelines

Without HCM enabled

Controls should, at minimum, have sufficient contrast between the control background and control content. Ideally, controls should also have sufficient contrast between their background (or border, if one exists) and the background of the component they’re embedded in. Here "sufficient" means AA rated, with AAA being ideal.
Focus rings, hover states, active states, selected states, etc. should also adhere to these contrast requirements.

With HCM enabled

Colors should be mapped semantically from the typical application palette to the reduced palette supplied by the operating system. Colors outside this palette should not be used because they will not adapt to users' preferences. Mapping should not result in a loss of information or context (eg. selected items should remain visually distinct from non-selected items, and information should not be communicated by color alone). The following are traditional foreground / background mappings given in CSS System Colors:

• Selected elements should use SelectedItemText / SelectedItem
• Controls should use ButtonText / ButtonFace
• Unvisited links should use LinkText for their foreground, background preserved
• Visited links should use VisitedText for their foreground, background preserved
• Inactive components should preserve their background, but change their foreground to GrayText
• Components not in the above categories should use CanvasText / Canvas (older implementations may use WindowText / Window)

For components which represent a combination of states, a combination of colors is necessary. For example:

• A hovered button should use SelectedItemText for its foreground and SelectedItem for its background. We don't do a simple invert here because we often place primary (ButtonFace/ButtonText) buttons next to secondary (ButtonText/ButtonFace) buttons, and inverting one would cause it to take on the same appearance as its neighbour.
• A visited link on a selected card should use VisitedText as its foreground, letting SelectedItem show through as its background.
• An inactive button should use GrayText / ButtonFace
• A selected tab should use SelectedItemText / SelectedItem with a ButtonText border

Components which require a mapping that isn't explicitly described above should have their mapping approved by the Accessibility team.

View the HCM component figma library here.

Note: The goal of HCM (though named “High contrast mode”) is to provide a user interface which respects customisations users have made in their system preferences. Users may customise their palette to adapt their system for photosensitivity, colorblindness, or other vision needs that are not strictly helped by high contrast. For this reason, we do not simply duplicate the contrast requirements set in the first section of this doc.

In addition to the color requirements described above, we enforce stylistic requirements for HCM. These styles increase component discoverabiltiy and assist users with cognative and/or motor disabilities, among others.

• Controls, sidebars, toolbars, dialogs, and other views should be bounded by a solid, 1px border at minimum. This border should inherit the component's foreground color unless the component requires a combination of colors (like the "selected tab" example above). In addition, the component should have adequate padding to ensure the border does not reduce the legibility of the component's content.A border is not necessary if the component's (semantically appropriate) background color differs from the background of its embedded component.
• With HCM enabled, the set of styles our style system will permit is reduced. Properties here with a value of `ignored_when_colors_disabled=True` may be tweaked by the style system before computed style is set. Learn more here.
• Blur effects, drop shadows, semi-opaque overlays, and other potentially distracting styles should be removed and/or replaced with their solid colour equivalent. For example, if a modal renders above content on a blurred background in non-HCM, when HCM is active it should render on a solid Canvas colour background. Drop shadows should be replaced with borders, following the guidance above. On most platforms, enabling HCM also enables "Reduce Transparency" -- we should respect this.
• SVGs should be adapted to render "reasonably" in HCM. When SVGs are decorative, or communicate information that is duplicated in a more traditional/accessible format like text, colours outside of the HCM palette may be used. The primary foreground colour for the SVG should be CanvasText and the primary background colour should be Canvas. When SVGs uniquely communicate information, or act as controls, they must be rendered using only colours from the HCM palette. You can find examples of decorative SVGs that have been adapted for HCM here.

Independent of HCM (with or without HCM enabled)

Any default text size or style set by the operating system should be respected. UI should respond to, and remain functional/legible, from 30% to 500% zoom