Repository navigation
Docs: Add accessibility documentation structure and guidance pages #286
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
zoharma
wants to merge
5
commits into
main
Choose a base branch
from
zma/docs-a11y-guidelines
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
3b6a618
Add accessibility documentation structure and guidance pages
zoharma 868a72d
Fix Meta import in accessibility docs
zoharma 02f7c63
Refine accessibility overview page
zoharma 071ad7e
Trim accessibility docs to practical guidance
zoharma 08819eb
Updated accessibility docs
zoharma File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,189 @@ | ||
| import { Meta } from "@storybook/addon-docs/blocks"; | ||
|
|
||
| <Meta title="Accessibility/Overview" /> | ||
|
|
||
| <div className="ds-docs"> | ||
|
|
||
| # Accessibility (a11y) | ||
|
|
||
| Our goal is to make interfaces that are understandable, predictable, and | ||
| usable across a wide range of abilities, environments, and levels of fatigue. | ||
|
|
||
| ## Standards and approach | ||
|
|
||
| We follow WCAG 2.2 as the compliance baseline, and use APCA (Advanced | ||
| Perceptual Contrast Algorithm) to keep text readable and comfortable in | ||
| real-world conditions. See [Colour contrast and | ||
| vision](?path=/docs/accessibility-colour-contrast-and-vision--docs) for | ||
| details. | ||
|
|
||
| ## Core principles | ||
|
|
||
| <ul> | ||
| <li> | ||
| <strong>Clarity over cleverness</strong>: interfaces should explain | ||
| themselves. | ||
| </li> | ||
| <li> | ||
| <strong>Predictable behaviour</strong>: similar things behave in similar | ||
| ways. | ||
| </li> | ||
| <li> | ||
| <strong>Multiple ways to perceive information</strong>: never rely on one | ||
| signal alone. | ||
| </li> | ||
| <li> | ||
| <strong>Low cognitive effort by default</strong>: minimise mental overhead. | ||
| </li> | ||
| </ul> | ||
|
|
||
| ## ✅ Do | ||
|
|
||
| ### Interactive elements | ||
|
|
||
| <ul> | ||
| <li>Ensure every interactive control has an accessible name.</li> | ||
| <li> | ||
| Provide this via a visible label, <code>aria-label</code>, or{" "} | ||
| <code>aria-labelledby</code>. | ||
| </li> | ||
| <li>Make keyboard focus clearly visible at all times.</li> | ||
| <li> | ||
| Use a consistent focus indicator (outline) rather than transient effects | ||
| such as ripples. | ||
| </li> | ||
| <li> | ||
| Ensure disabled states are clearly distinguishable from enabled and default. | ||
| </li> | ||
| </ul> | ||
|
|
||
| ### Keyboard navigation | ||
|
|
||
| <ul> | ||
| <li> | ||
| All interactive elements must be reachable and usable using a keyboard | ||
| alone. | ||
| </li> | ||
| <li>Follow a logical tab order that matches the visual and reading order.</li> | ||
| <li> | ||
| Do not trap focus. Users must be able to move in and out of components using | ||
| standard keyboard interactions. | ||
| </li> | ||
| <li> | ||
| Ensure focus is always visible and moves predictably between elements. | ||
| </li> | ||
| <li> | ||
| Support standard keyboard interactions (e.g. Enter or Space to activate | ||
| controls). | ||
| </li> | ||
| </ul> | ||
|
|
||
| For overlays such as menus and dialogs, manage focus intentionally: | ||
|
|
||
| <ul> | ||
| <li>Move focus into the component when it opens.</li> | ||
| <li> | ||
| Keep focus within modal dialogs while they are open. Non-modal menus and | ||
| popovers should close on Escape or when focus leaves. | ||
| </li> | ||
| <li>Return focus to the triggering element when it closes.</li> | ||
| </ul> | ||
|
|
||
| ### Icons and icon-only actions | ||
|
|
||
| <ul> | ||
| <li> | ||
| Icon-only controls must include an accessible name that describes the action | ||
| (e.g. “Delete sample”), using <code>aria-label</code> or{" "} | ||
| <code>aria-labelledby</code>. | ||
| </li> | ||
| <li> | ||
| Tooltips support discoverability, but do not replace accessible names. | ||
| </li> | ||
| <li> | ||
| Decorative icons should be hidden from assistive technologies using{" "} | ||
| <code>aria-hidden="true"</code>. | ||
| </li> | ||
| <li>Do not rely on an icon alone to communicate critical meaning.</li> | ||
| <li> | ||
| If an icon represents a toggle or state, expose the state using appropriate | ||
| ARIA attributes (e.g. <code>aria-pressed</code>). | ||
| </li> | ||
| </ul> | ||
|
|
||
| For interactive icons, ensure both an accessible name and a visible affordance | ||
| such as a tooltip or label. | ||
|
|
||
| In MUI, use <code>aria-label</code> on <code>IconButton</code>. Tooltips (e.g. <code><Tooltip /></code>) should be used in addition to, not instead of, | ||
| accessible labelling. | ||
|
|
||
| ### Forms and inputs | ||
|
|
||
| <ul> | ||
| <li>Always associate inputs with labels (even if visually hidden).</li> | ||
| <li> | ||
| Do not show validation errors while a user is actively typing. Validate on | ||
| blur or submission. | ||
| </li> | ||
| <li>Make error messages clear, specific, and actionable.</li> | ||
| <li>Associate errors programmatically with the relevant field.</li> | ||
| </ul> | ||
|
|
||
| ### Content and layout | ||
|
|
||
| <ul> | ||
| <li>Do not rely on colour alone to convey meaning.</li> | ||
| <li>Do not rely on icons alone to convey critical meaning.</li> | ||
| <li>Use a logical, predictable reading order.</li> | ||
| </ul> | ||
|
|
||
| ## ❌ Don’t | ||
|
|
||
| <ul> | ||
| <li>Don’t use placeholder text as a replacement for labels.</li> | ||
| <li>Don’t hide important information in faint or decorative text.</li> | ||
| <li>Don’t introduce unexpected interaction patterns.</li> | ||
| <li>Don’t create dense, unbroken blocks of content.</li> | ||
| </ul> | ||
|
|
||
| ## Storybook guidance | ||
|
|
||
| <ul> | ||
| <li> | ||
| Simple component stories may be visually minimal, but should still expose an | ||
| accessible name, or be documented as intentionally incomplete. | ||
| </li> | ||
| </ul> | ||
|
|
||
| ## Quick sense check | ||
|
|
||
| <ul> | ||
| <li>Can this be used with a keyboard only?</li> | ||
| <li>Is its purpose clear without colour or icons?</li> | ||
| <li>Would it still make sense when someone is tired or distracted?</li> | ||
| </ul> | ||
|
|
||
| ## Learn more: | ||
|
|
||
| <ul> | ||
| <li> | ||
| <a | ||
| href="https://www.w3.org/TR/WCAG22/" | ||
| target="_blank" | ||
| rel="noopener noreferrer" | ||
| > | ||
| WCAG 2.2 | ||
| </a> | ||
| </li> | ||
| <li> | ||
| <a | ||
| href="https://git.apcacontrast.com/documentation/APCAeasyIntro" | ||
| target="_blank" | ||
| rel="noopener noreferrer" | ||
| > | ||
| APCA (Advanced Perceptual Contrast Algorithm) | ||
| </a> | ||
| </li> | ||
| </ul> | ||
|
|
||
| </div> | ||
|
zoharma marked this conversation as resolved.
Resolved
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,108 @@ | ||
| import { Meta } from "@storybook/addon-docs/blocks"; | ||
|
|
||
| <Meta title="Accessibility/Colour contrast and vision" /> | ||
|
|
||
| <div className="ds-docs"> | ||
|
|
||
| # Colour contrast and vision | ||
|
|
||
| Poor contrast slows decisions and raises error rates, especially in dense, | ||
| data-heavy interfaces. Colour choices also need to work for people with colour | ||
| vision deficiency (CVD). | ||
|
|
||
| ## How we judge contrast | ||
|
|
||
| <ul> | ||
| <li> | ||
| <strong>APCA</strong> is the primary tool for tuning colours. It accounts | ||
| for font size, weight, and light or dark polarity. | ||
| </li> | ||
| <li> | ||
| <strong>WCAG 2.2</strong> is the compliance floor. If it fails, the colour | ||
| must change. | ||
| </li> | ||
| <li> | ||
| If WCAG 2.2 passes but APCA still shows poor readability, improve the | ||
| colour rather than treating compliance as enough. | ||
| </li> | ||
| </ul> | ||
|
|
||
| ## Do | ||
|
|
||
| <ul> | ||
| <li> | ||
| Use the theme tokens and roles (<code>--ds-*</code>) rather than picking | ||
| colours by hand. | ||
| </li> | ||
| <li>Test text across sizes, weights, and both light and dark modes.</li> | ||
| <li> | ||
| Pair colour with text, an icon, or a label. Icons should differ in shape, | ||
| not just colour. | ||
| </li> | ||
| <li> | ||
| Keep disabled states distinguishable without making them unreadable. WCAG | ||
| 2.2 exempts disabled controls from contrast minimums, but we still aim for | ||
| legible text. | ||
| </li> | ||
| <li>Use subtle text only for non-essential information.</li> | ||
| </ul> | ||
|
|
||
| ## Watch out for | ||
|
|
||
| <ul> | ||
| <li> | ||
| Status colours (<code>--ds-success</code>, <code>--ds-warning</code>,{" "} | ||
| <code>--ds-danger</code>). Saturated colours can pass WCAG and still vibrate | ||
| or feel muddy, and they fall in the red-green range that the most common | ||
| types of CVD compress together. | ||
| </li> | ||
| <li> | ||
| Status colours placed side by side, such as a legend or results table. | ||
| Check them in a CVD simulator, not just by eye. | ||
| </li> | ||
| <li>Reducing contrast for visual subtlety where meaning is still needed.</li> | ||
| <li>Assuming light and dark mode need the same values.</li> | ||
| </ul> | ||
|
|
||
| Learn more: | ||
|
|
||
| <ul> | ||
| <li> | ||
| <a | ||
| href="https://git.apcacontrast.com/documentation/APCAeasyIntro" | ||
| target="_blank" | ||
| rel="noopener noreferrer" | ||
| > | ||
| APCA (Advanced Perceptual Contrast Algorithm) | ||
| </a> | ||
| </li> | ||
| <li> | ||
| <a | ||
| href="https://www.w3.org/TR/WCAG22/" | ||
| target="_blank" | ||
| rel="noopener noreferrer" | ||
| > | ||
| WCAG 2.2 | ||
| </a> | ||
| </li> | ||
| <li> | ||
| <a | ||
| href="https://www.color-blindness.com/coblis-color-blindness-simulator/" | ||
| target="_blank" | ||
| rel="noopener noreferrer" | ||
| > | ||
| Coblis (colour blindness simulator) | ||
| </a> | ||
| </li> | ||
| <li> | ||
| <a | ||
| href="https://www.w3.org/TR/wcag-3.0/" | ||
| target="_blank" | ||
| rel="noopener noreferrer" | ||
| > | ||
| WCAG 3 (W3C Working Draft) | ||
| </a> | ||
| </li> | ||
| </ul> | ||
|
|
||
| </div> |
|
zoharma marked this conversation as resolved.
Resolved
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,72 @@ | ||
| import { Meta } from "@storybook/addon-docs/blocks"; | ||
|
|
||
| <Meta title="Accessibility/Cognitive accessibility" /> | ||
|
|
||
| <div className="ds-docs"> | ||
|
|
||
| # Cognitive accessibility and usability | ||
|
|
||
| People differ in how they process information, maintain focus, and recover from | ||
| errors. In scientific software, users may work for long periods or run live | ||
| experiments where mistakes are costly. The goal is not to simplify the science, | ||
| but to remove cognitive load the interface adds. | ||
|
|
||
| ## Design objectives | ||
|
|
||
| <ul> | ||
| <li> | ||
| <strong>Be understandable</strong>: use familiar patterns and terminology, | ||
| and make state visible at a glance. | ||
| </li> | ||
| <li> | ||
| <strong>Reduce memory burden</strong>: keep important information visible | ||
| and favour recognition over recall. | ||
| </li> | ||
| <li> | ||
| <strong>Support focus</strong>: avoid competing emphasis and keep | ||
| navigation consistent. | ||
| </li> | ||
| <li> | ||
| <strong>Prevent and recover from errors</strong>: show consequences before | ||
| actions, and make recovery obvious and forgiving. | ||
| </li> | ||
| <li> | ||
| <strong>Design for long sessions</strong>: assume users are tired, | ||
| interrupted, or multitasking. | ||
| </li> | ||
| </ul> | ||
|
|
||
| ## Quick sense check | ||
|
|
||
| <ul> | ||
| <li>Is it understandable without prior knowledge?</li> | ||
| <li>Does it rely on memory or hidden behaviour?</li> | ||
| <li>Is important state clearly visible?</li> | ||
| <li>Is error recovery clear and forgiving?</li> | ||
| <li>Would it still be clear at the end of a long experiment session?</li> | ||
| </ul> | ||
|
|
||
| Learn more: | ||
|
|
||
| <ul> | ||
| <li> | ||
| <a | ||
| href="https://www.w3.org/TR/coga-usable/" | ||
| target="_blank" | ||
| rel="noopener noreferrer" | ||
| > | ||
| Making Content Usable for People with Cognitive and Learning Disabilities | ||
| </a> | ||
| </li> | ||
| <li> | ||
| <a | ||
| href="https://www.w3.org/WAI/fundamentals/accessibility-usability-inclusion/" | ||
| target="_blank" | ||
| rel="noopener noreferrer" | ||
| > | ||
| W3C: Accessibility, Usability, and Inclusion | ||
| </a> | ||
| </li> | ||
| </ul> | ||
|
|
||
| </div> |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.