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 VisitedTeg 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.
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.
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