Check your web interface for accessibility

This guide will help you address common accessibility pitfalls in web applications and content websites.

We aim to comply with the Web Content Accessibility Guidelines (WCAG) 2.2, level AA. WCAG has been adopted as the standard for accessibility legislation around the world.

Why accessibility is important

Designing and coding for accessibility helps everyone. People with disabilities or age-related challenges that affect seeing, hearing, moving, speaking, or understanding information need accessible design. But disabilities can also be temporary or situational, like having an injury, being in a noisy place, or dealing with glare.

The Web Content Accessibility Guidelines (WCAG) ensure that interfaces are perceivable, operable, understandable and robust.

When using Vanilla

Components, styles and documentation for Vanilla are written with accessibility in mind, but do not guarantee an accessible experience for your website or web application.

When you use Vanilla, check the Accessibility tab in each component's documentation. We also suggest that you check the code examples, which follow best practices.

Whether you are using Vanilla or not, make sure to use correct HTML markup and semantics to make the most of browsers' built-in accessibility features.

Automated tools

Automated tools can identify many issues with markup and styles. However, they are not sufficient for conducting a comprehensive accessibility audit. Use them mindfully, and do rely as well on manual reviews.

Here are some tools that may help you:

• Online validators: for an initial assessment, you may use tools such as WAVE and PageSpeed Insights, or Lighthouse within Google Chrome's developer tools. Note that a score of 100 doesn't mean your page is accessible.
• Browser extensions:
  • Axe DevTools browser extension can scan any given page for accessibility issues, providing guidance on how to fix them. Paid version also provides guided tests and testing full flows.
  • WAVE browser extension: flags issues but also lets you visually check the accessibility tree, focus order and labels.
• Code editor linters: check Axe Linter for Visual Studio Code
• CLI tools: Pa11y and Axe offer similar functionality by detecting issues. Both can be used for continuous integration (check also axe Linter GitHub action)

Check visual accessibility

These checks support people with low vision (cataracts), color vision deficiencies (color blindness), photosensitivity, or reading difficulties by ensuring clear contrast, readable text at any size, no reliance on color alone, and safe, non-distracting visuals.

Enable the visual features

Visual accessibility checklist

• All elements are visible and all text is legible in all themes
  • If your framework supports dark theme or high contrast mode, check all possible combinations.
• All text wraps instead of overflowing/cropping when enabling large text mode
• All text wraps instead of overflowing/cropping when zooming 200%
• All text wraps instead of overflowing/cropping when the window is resized
• Meaning is conveyed through text or icons, not by color alone.
  • For example: for errors, an error message is shown in addition to a red border.
• Animations are disabled or reduced when reduced motion is enabled in the system settings
  • Large positional shifts, parallax scrolling, sliding panels, carousels, rotating spinners, or auto-playing loops are problematic and should be disabled.
  • Subtle opacity fades, color changes, shadows, or small local micro-interactions are OK.
  • Use CSS's prefers-reduced-motion to honour system settings.
• No flashing (there should not be more than 3 flashes per second)
• All elements have enough contrast with their background
  • Read contrast checks for further guidance.

Contrast checks

Default styles from Vanilla already provide sufficient contrast out of the box, but you should double check elements have enough color contrast so all content is perceivable:

• For text: 4.5:1 or higher contrast with background
• For everything else (for instance, icons on background): 3:1 or higher contrast with background

No minimum contrast is required for inactive components, decorative images or graphics, or logos.

You should be particularly cautious in the following cases:

• Check how any local style overrides affect states like hover or focus
• Check light colors, such as light gray for secondary text or yellow
• Check semantic colors for text, such as red for errors or yellow for warnings
• Check how colors change on light and dark theme, and high contrast mode

For checking color contrast:

• On most browsers, including Firefox and Chrome, you can check contrast ratio by inspecting an element and clicking on the colour swatch next to the CSS value. Remember we are aiming at level AA at least.
• Install a checker, such as Kontrast or Contrast in Ubuntu, and pick the foreground and background colors.

Be mindful of text on images, and the use of transparency: some automatic tests may evaluate contrast incorrectly in those cases. Common sense may help flag up problems too: if text looks unreadable to you, it's not accessible no matter what the contrast checker says.

Check keyboard navigation

These checks ensure a good experience for keyboard-only users, including people with motor disabilities that cannot use a mouse or trackpad, blind users who rely on screen readers, and power users who just prefer to use their keyboard.

Try keyboard shortcuts

For a simple test, select the window you want to test. Then hit the Tab key repeatedly and check how focus moves through all interactive elements.

For a more thorough test, you need these shortcuts:

Keyboard navigation checklist

• All interactive elements (for example, buttons, fields, links) can be focused using the Tab key
• All interactive elements have a visible focus state (ideally a focus ring)
• There are no focus traps: it is possible to escape all loops, for instance by pressing the Esc key
• Focus moves from one element to the next in a logical order
  • In most of our apps, that usually means sidebar (if open), then body; and top to bottom, left to right (or right to left for RTL languages such as Arabic or Hebrew).
• A skip link is provided at the beginning of the page to bypass navigation
  • Check skip link in Vanilla
• When a dialog opens, focus moves to the dialog
• When a dialog closes, focus moves back to the element that triggered the dialog
• Dialogs close by hitting the Escape key
• If an element doesn't have a visible label but does have a tooltip on hover, the tooltip should also be visible on focus

Check screen reading

All graphical interfaces should be readable with common screen readers. Screen readers benefit blind and visually impaired users who rely on audio feedback to navigate interfaces. To work properly, screen readers require good markup, labelling, and logical content structure.

Use the screen reader