A checklist that can be filtered by A / AA level, with a short description and links to the related "Understanding" and "How to Meet" articles that accompany each criterion.
- WAI-ARIA A guide for understanding how to use WAI-ARIA 1.1 to create an accessible Rich Internet Application. It provides guidance on the appropriate application of WAI-ARIA, describes recommended WAI-ARIA usage patterns, and explains concepts behind them.
The volume of information on the WCAG 2.0 website can be disorienting. We keep the following links handy for quick reference:
-
-
-
-
-
-
-
-
WCAG 2.0: the W3C standard, includes principles, guidelines and success criteria
-
Understanding WCAG 2.0: detailed reference, includes intent, benefits to people with disabilities, examples, resources and techniques
-
How to Meet WCAG 2.0: a customisable quick reference, includes guidelines, success criteria and techniques
-
Techniques for WCAG 2.0: instructions for developers, includes browser and assistive technology support notes, examples, code, resources and test procedures
-
-
-
-
-
-
-
-
-
-
-
-
Useful tools
-
The web is abundant in tools that help to create and test for accessible sites. We find the following particularly useful:
If you spot an accessibility problem in Vanilla, let us know by filing an issue on GitHub.
-
-
-{% endblock %}
diff --git a/templates/docs/accessibility.md b/templates/docs/accessibility.md
new file mode 100644
index 000000000..3075fd3f5
--- /dev/null
+++ b/templates/docs/accessibility.md
@@ -0,0 +1,477 @@
+---
+wrapper_template: '_layouts/docs.html'
+context:
+ title: 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](https://www.w3.org/TR/WCAG22/), 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](https://www.w3.org/WAI/WCAG22/Understanding/intro#understanding-the-four-principles-of-accessibility).
+
+
+## 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](https://wave.webaim.org/) and [PageSpeed Insights](https://pagespeed.web.dev/), or Lighthouse within Google Chrome's developer tools. Note that [a score of 100 doesn't mean your page is accessible](https://savvasstephanides.hashnode.dev/my-lighthouse-accessibility-score-is-100-does-that-mean-my-website-is-100-accessible).
+- **Browser extensions**:
+ * [Axe DevTools browser extension](https://www.deque.com/axe/browser-extensions/) 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](https://wave.webaim.org/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](https://www.deque.com/axe/devtools/linter/)
+- **CLI tools**: [Pa11y](https://pa11y.org/) and [Axe](https://www.npmjs.com/package/@axe-core/cli) offer similar functionality by detecting issues. Both can be used for continuous integration (check also [axe Linter GitHub action](https://github.com/marketplace/axe-linter))
+
+
+## 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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
High contrast mode
+
Go to Settings > Accessibility > Seeing, enable High Contrast.
+
You can also enable High Contrast in the Accessibility menu.
+
Dark theme
+
Go to Settings > Appearance > Style, select Dark.
+
Large text
+
Go to Settings > Accessibility > Seeing, enable Large Text.
+
You can also enable Large Text in the Accessibility menu.
+
Reduced motion
+
Go to Settings > Accessibility > Seeing, disable Animation Effects.
+
+
+
+
+
+
High contrast mode
+
Go to Settings > Accessibility > Contrast themes (or "High contrast" on Windows 10). Select a theme from the drop-down menu and click Apply.
+
Shortcut: Press Left Alt + Left Shift + Print Screen to toggle High Contrast on or off.
+
Dark theme
+
Go to Settings > Personalization > Colors. Under "Choose your mode," select Dark.
+
Large text
+
Go to Settings > Accessibility > Text size. Drag the slider to your desired size and click Apply.
+
To make everything bigger (apps and text), go to Settings > System > Display and adjust the "Scale" percentage.
Go to System Settings > Accessibility > Display. Toggle the switch for Increase contrast.
+
For a more drastic effect, you can also toggle "Invert colours" in the same menu.
+
Dark theme
+
Go to System Settings > Appearance. Select Dark.
+
Large text
+
Option 1 (System-wide scaling): Go to System Settings > Displays. Select a resolution option closer to "Larger Text."
+
Option 2 (Text only): Go to System Settings > Accessibility > Display > Text Size. Use the slider to adjust the preferred reading size for supported apps.
+
Reduced motion
+
System Settings > Accessibility > Display > Reduce motion
+
+
+
+
+
+### 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](#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](https://css-irl.info/testing-colour-accessibility-with-dev-tools/) and [Chrome](https://developer.chrome.com/docs/devtools/accessibility/contrast), 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](https://snapcraft.io/kontrast) or [Contrast](https://flathub.org/en/apps/org.gnome.design.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:
+
+| Action | Shortcut |
+|--------|----------|
+| Move to next interactive item | Tab |
+| Move to previous interactive item | Shift+Tab |
+| Interact with an item or group | Enter |
+| Exit a group | Esc |
+
+
+### 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](/docs/patterns/links#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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Orca is the default screen reader in Ubuntu Desktop and other Linux distributions. It can be enabled in Settings > Accessibility > Seeing. You can also enable Screen Reader in the Accessibility menu.
+
+
Note that some Orca features don't work with certain combinations of Ubuntu releases and application toolkits. Read Improve screen reader usability.
+
+
You need to become familiar with keyboard shortcuts to use the screen reader. Modifier keys are used in the shortcuts:
+
+
+
Super
+
Generally mapped to the Windows key on Windows computers, and the Command key on Macs.
+
Orca
+
By default, the Orca key is CapsLock for the Laptop layout, and the Insert key for the Desktop layout. You can set the layout in the Orca settings by typing orca -s in the terminal.
For testing on Windows, we recommend NVDA (NonVisual Desktop Access), a free, open-source screen reader. Once installed, you can start it via the desktop shortcut or by pressing Ctrl + Alt + N.
+
+
You need to become familiar with keyboard shortcuts to use the screen reader. By default, the NVDA key is mapped to the Insert key (Desktop) or Caps Lock (Laptop), depending on how you configured it during setup.
+
+
NVDA uses "Browse Mode" (for reading web pages) and "Focus Mode" (for typing in forms). It usually switches automatically, but knowing this distinction is vital for testing.
+
+
+
+
+
Action
+
Shortcut
+
+
+
+
+
Turn NVDA on
+
Ctrl + Alt + N
+
+
+
Turn NVDA off
+
NVDA + Q
+
+
+
Input Help (Learn mode)
+
NVDA + 1 (Press again to exit)
+
+
+
NVDA Menu (Preferences)
+
NVDA + N
+
+
+
Read all (from current position)
+
NVDA + Down Arrow
+
+
+
Read current line
+
NVDA + Up Arrow
+
+
+
Read next line
+
Down Arrow
+
+
+
Read previous line
+
Up Arrow
+
+
+
Pause Speech
+
Control
+
+
+
+
+
+
VoiceOver is the default screen reader in macOS. Go to System Settings > Accessibility > VoiceOver to toggle it on. You can also quickly toggle it using the shortcut Command + F5 (or Command + Triple-press Touch ID on laptops with Touch ID).
+
+
You need to become familiar with keyboard shortcuts to use the screen reader. The VO key is the modifier key used for almost all commands. It is mapped to Control + Option pressed together. You can also configure Caps Lock to act as the VO key in settings.
+
+
VoiceOver has a feature called "Quick nav" (toggle with Left Arrow + Right Arrow) that allows you to navigate using single arrow keys without holding the VO keys.
+
+
+
+
+
Action
+
Shortcut
+
+
+
+
+
Turn VoiceOver on
+
Command + F5
+
+
+
Turn VoiceOver off
+
Command + F5
+
+
+
Keyboard Help (Learn mode)
+
VO + K (Press Esc to exit)
+
+
+
VoiceOver Utility (Preferences)
+
VO + F8
+
+
+
Read all (from current position)
+
VO + A
+
+
+
Read current item/line
+
VO + F3 (Description)
+
+
+
Move to next item
+
VO + Right Arrow
+
+
+
Move to previous item
+
VO + Left Arrow
+
+
+
Interact with group/web area
+
VO + Shift + Down Arrow
+
+
+
Stop Interacting (Exit group)
+
VO + Shift + Up Arrow
+
+
+
Pause Speech
+
Control
+
+
+
+
+
+
+### Screen reading checklist
+
+- All interactive elements (buttons, fields, links…) have a label and a role that is read out loud by the screen reader
+ * Use the right HTML elements so screen readers can rely on their implied roles. Check [W3C documentation on roles](https://www.w3.org/WAI/ARIA/apg/practices/structural-roles/).
+ * You may use the [off-screen Vanilla utility](/docs/utilities/off-screen) (`.u-off-screen`) to make a label readable only for screen reader.
+- The HTML document has an appropriate `lang` attribute on the root element (e.g., ``)
+- HTML5 semantic elements (``, `