From c6c875e6dee69bf0f65bdccc0dcdb73b84fe6c46 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Ruiti=C3=B1a?= Date: Mon, 2 Feb 2026 15:20:42 +0100 Subject: [PATCH 1/4] Add web accessibility review guide --- side-navigation.yaml | 2 + templates/_layouts/docs.html | 1 + templates/docs/accessibility.md | 444 ++++++++++++++++++++++++++++++++ 3 files changed, 447 insertions(+) create mode 100644 templates/docs/accessibility.md diff --git a/side-navigation.yaml b/side-navigation.yaml index ec3d3dd25..dd26c9443 100644 --- a/side-navigation.yaml +++ b/side-navigation.yaml @@ -243,6 +243,8 @@ - heading: Resources ordering: alphabetical subheadings: + - title: Check accessibility + url: /docs/accessibility - title: Component examples url: /docs/examples - title: Release notes for {version} diff --git a/templates/_layouts/docs.html b/templates/_layouts/docs.html index 3103e2922..d476f357e 100644 --- a/templates/_layouts/docs.html +++ b/templates/_layouts/docs.html @@ -135,5 +135,6 @@

On this page:

+ {% endblock %} diff --git a/templates/docs/accessibility.md b/templates/docs/accessibility.md new file mode 100644 index 000000000..188d8b36c --- /dev/null +++ b/templates/docs/accessibility.md @@ -0,0 +1,444 @@ +--- +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. + + +## Why accessibility is important + +Designing and coding for accessibility helps everyone, not just a specific group. 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. + +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. The guidelines ensure that the interface is: + +
+
Perceivable
+
All users can perceive it
+
Operable
+
All users can interact with it
+
Understandable
+
All users can comprehend it
+
Robust
+
The interface is compatible with accessibility features (also called assistive technologies)
+
+ + +## Automated tools + +Automated tools can identify many issues with markup and styles. However, they are not sufficient for doing a full accessibility audit. For instance, they will generally fail to evaluate the quality of labels and may throw false positives for contrast. + +- **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 a score of 100 doesn't mean your page is 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.
+
+
+ + + + +
+ + +### 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 + +Contrast is usually properly handled by Vanilla, but you should ensure all elements have enough color contrast so all text and controls are 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 that will mean 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). +- 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 in Ubuntu Desktop should be readable with the built-in [Orca screen reader](https://documentation.ubuntu.com/desktop/en/latest/how-to/accessibility/orca/read-screen-aloud/). 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.
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ActionLaptop layoutDesktop layout
Enable screen readerSuper+Alt+SSuper+Alt+S
Quit screen readerSuper+Alt+SSuper+Alt+S
Learn modeOrca+H (exit with Esc)Insert+H (exit with Esc)
Orca preferencesCapsLock+SpaceInsert+Space
Toggle flat reviewCapsLock+PInsert+- on the numeric keypad
Say all (in flat review)CapsLock and double-press ;Double-press + on the numeric keypad
Read current lineCapsLock+I8 on the numeric keypad
Read next lineCapsLock+O9 on the numeric keypad
Read previous lineCapsLock+U7 on the numeric keypad
+ +

You can find further guidance in the screen reader documentation.

+
+ + + + + + +### 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](https://vanillaframework.io/docs/utilities/off-screen) (`.u-off-screen`) to make a label readable only for screen reader. +- All labels are descriptive, meaningful and concise +- All labels are unique, unless they trigger the exact same action. + * For example, if there's more than one share button, each label should mention what it refers to ("Share [item name 1]", "Share [item name 2]") +- All pages have a meaningful title or main heading +- All headings are unique and meaningful +- Headings follow a sequential order, without skipping any levels. + * For example, H3 headings are always under an H1 and an H2 heading. + * Use the right markup for heading levels regardless of how they are styled. You can achieve this by using heading styles, for example: `

` +- When changing to a new page, either the page title or the main heading is announced (whichever is more meaningful) +- Errors are announced and readable with the screen reader + * Check the [aria-live](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-live) attribute +- For images that are not strictly decorative, provide alternative text that can be read out loud by the screen reader + * Get guidance on how to write good alternative text in the [Vanilla content guidelines](https://vanillaframework.io/docs/content-guidelines#alt-text-for-images) +- All visual content in videos is [described](https://www.w3.org/WAI/media/av/description/) by a narrator, in the transcript, or in adjacent text. + + +## Check additional accessibility + +Besides the more common checks above, you should also keep in mind these: + +- All UI text is reasonably short and easy to understand + * Check the [Vanilla content guidelines](https://vanillaframework.io/docs/content-guidelines) for guidance. +- When there's an error submitting data or in a flow, a meaningful error message is shown + * Good error messages explain to the user how to avoid them, or at least explain the cause of the error. +- Search functionality is provided whenever possible so users have an alternative way to find the page or section they are looking for +- All interactive elements have a width and height of at least 24px, or have [sufficient space around them](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html). +- Large interactive elements have at least 24px of either vertical or horizontal spacing + * If interactive elements are too close, users might activate them by accident, for example when [scrolling on touch screens](https://axesslab.com/hand-tremors/). +- Audio or video that lasts more than 3 seconds does not play automatically +- Audio or video that lasts more than 3 seconds can be paused or muted +- Provide text alternatives (for instance, transcriptions or captions) for audio and video content + + +## Look for user feedback + +When auditing an app, check any outstanding accessibility issues in the app repository. Actual users are the best source for accessibility issues. + + +## Report accessibility issues + +If you found an accessibility issue, please open an issue in the relevant repository. Repositories for Canonical products are generally hosted on [GitHub](https://github.com/canonical). Describe the issue in as much detail as you can, and provide instructions to test it. Screenshots and screen recordings also help. You can propose a fix for the issue, but it's not strictly necessary. \ No newline at end of file From eba31a43a6a0f15374903749cc79fb55293728f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Ruiti=C3=B1a?= Date: Mon, 2 Feb 2026 16:01:19 +0100 Subject: [PATCH 2/4] Iterate accessibility guide Add guidance for Vanilla users Integrate advice, references from previous checklist Clean links --- templates/docs/accessibility.md | 59 +++++++++++++++++++++++++++++---- 1 file changed, 52 insertions(+), 7 deletions(-) diff --git a/templates/docs/accessibility.md b/templates/docs/accessibility.md index 188d8b36c..60002d43e 100644 --- a/templates/docs/accessibility.md +++ b/templates/docs/accessibility.md @@ -6,12 +6,14 @@ context: 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, not just a specific group. 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. -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. The guidelines ensure that the interface is: +The [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/) ensure that the interface is:
Perceivable
@@ -25,11 +27,20 @@ We aim to comply with the [Web Content Accessibility Guidelines (WCAG) 2.2](http
+## 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. + +To make the most of 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, using correct HTML markup and semantics already go a long way into making your website or application more accessible. + + ## Automated tools Automated tools can identify many issues with markup and styles. However, they are not sufficient for doing a full accessibility audit. For instance, they will generally fail to evaluate the quality of labels and may throw false positives for contrast. -- **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 a score of 100 doesn't mean your page is accessible. +- **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 [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. @@ -173,6 +184,8 @@ For a more thorough test, you need these shortcuts: - 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 @@ -400,20 +413,26 @@ All graphical interfaces in Ubuntu Desktop should be readable with the built-in - 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](https://vanillaframework.io/docs/utilities/off-screen) (`.u-off-screen`) to make a label readable only for screen reader. + * 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 a `lang` attribute on the root element (e.g., ``) +- HTML5 semantic elements (`
`, `