Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .storybook/preview.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,7 @@ const preview: Preview = {
"Helpers",
"Theme",
"Theme/Logos",
"Accessibility",
"MUI",
"Components",
],
Expand Down
189 changes: 189 additions & 0 deletions src/storybook/accessibility/00-overview.mdx
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>
Comment thread
zoharma marked this conversation as resolved.
Resolved

## ✅ 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>&lt;Tooltip /&gt;</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>
108 changes: 108 additions & 0 deletions src/storybook/accessibility/01-colour-contrast.mdx
Comment thread
zoharma marked this conversation as resolved.
Resolved
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>
72 changes: 72 additions & 0 deletions src/storybook/accessibility/02-cognitive-a11y.mdx
Comment thread
zoharma marked this conversation as resolved.
Resolved
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>
Loading