Accessibility

Accessible design allows users with disabilities to easily interact with products, while also providing a better experience for everyone. The following guidelines emphasize component and text contrast requirements consistent with the accessibility requirements outlined in Section 508 of the WCAG 2.1.

For a comprehensive list of accessibility requirements, including details on illustration, motion, sound, and engineering best practices, visit w3.org.

Contrast requirements

Contrast requirements help low vision and/or colorblind users navigate our products. You can download the Stark plugin for a quick, easy way to check the contrast between different elements in your Figma file.

Contrast for text elements

Text elements should meet a minimum of 4.5:1 contrast between the text and background color. For text 18px or greater, the required contrast drops to 3:1. Disabled text is exempt from contrast requirements.

As shown below, MongoDB’s lightest gray that still meets contrast requirements for text on a white background is Gray: Dark 1.

The 4.5:1 contrast standard also applies to text within components.

Contrast for components

Any visual information that is necessary for a user to identify and operate a control must meet 3:1 contrast. This contrast requirement also applies to active states, focus states, and hover states.

Inactive and disabled portions of a component are exempt from these contrast requirements. Similarly, if a component is not actually a control (for example, a tooltip) or if the fill or border is stylistic, these contrast requirements do not apply.

Required Contrast

If the green fill of this button indicating hit area is necessary for a user to identify and operate the control, then the green must meet 3:1 contrast with the adjacent white background.

Because contrast requirements apply to the edge of a component where it meets adjacent colors, a component with a border that meets 3:1 is accessible. The fill color and the contrast between the border and fill is not relevant.

Exceptions to contrast requirements

Components that are not controls with distinct functions do not need to meet 3:1 contrast requirements. These include tooltips, banners, notifications, modals, and toasts. All text and actionable elements within components must still meet contrast requirements.

For example, in the toast below, the contrast between the border and the background is only 1.34:1. Since the light green visual container itself is not essential information, the low contrast still meets accessibility requirements. The close icon is an actionable element and must meet the 3:1 contrast requirement.

Similarly, in the example below, the clickable area of the button can be determined from its context and copy. The button does not need to meet a fill area that meets contrast with the surrounding white. The close icon and text must still meet contrast requirements.

Component states

All actionable components should have a focus state. The active state, hover state, and focus state of a component need to meet 3:1 contrast requirements with adjacent colors.

The contrast between different states does not have a requirement. For example, the color difference between how a component appears in its active state compared to its hover state is not important to meet requirements.

Icon contrast

Product icons should also meet 3:1 contrast requirements, however decorative marketing icons do not need to meet requirements.

Color

Avoid relying on color

Color should not be used as the only means of communicating information. Consider adding a pattern, icon, or text to increase accessibility.

For example, consider an input field: if this element only uses the color red to show that it’s invalid, a user who is unable to perceive red may not be able to detect that change. Adding a warning icon helps signal that the input is invalid.

Keyboard navigation

Many users including those with vision impairments rely on keyboard navigation to use our products. For this reason, all components should be accessible via keyboard including links, buttons, and form controls.

Tab order should follow predictable, sequential hierarchy. Important screens should be annotated with tab order, direction, and any additional notes needed for developers and engineers to reference.

Aria labels

Ensure all inputs have an Accessible Rich Internet Applications (ARIA) label. You can do this by either having a visible label, by using the aria-label attribute, or by having the aria-labelledby attribute for the element associated with the input. Inputs without aria-labels can be hard for users to understand, especially for those who use a screen-reader.

Focus states

For all dropdowns that have a list, we highlight the first menu item.

Same applies to our Menu component.

For Search we break the pattern because we need to allow the user to search exactly what the user typed in versus just the list items that get surfaced — it’s a rare case where dropdown items are not necessarily an exhaustive list.

In general, the browser focus (i.e. document.activeElement) should be on the triggering element (input or button), unless there are focusable elements within the dropdown, like DatePicker where there are buttons inside the dropdown.

For DatePicker and UserMenu that have actionable items with their dropdown, the focus will stay on the input itself. An element within the dropdown will be highlighted, and then hitting tab will move to the next trigger in the Menu/dropdown.

A browser focus and highlighted element are distinct.

Further information on focus states can be found here.