diff --git a/src/storybook/accessibility/00-overview.mdx b/src/storybook/accessibility/00-overview.mdx
new file mode 100644
index 00000000..627f44f2
--- /dev/null
+++ b/src/storybook/accessibility/00-overview.mdx
@@ -0,0 +1,198 @@
+import { Meta } from "@storybook/blocks";
+
+
+
+
+
+
+
+# Accessibility
+
+
+ Accessibility (a11y) in the Diamond Design System is a baseline for quality,
+ clarity, and usability in complex scientific tools, not a checklist or a
+ separate mode.
+
+
+
+ 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 baseline for accessibility compliance.
+
+
+ We also use APCA (Advanced Perceptual Contrast Algorithm) to design for
+ perceived readability. Unlike WCAG contrast ratios, APCA accounts for font
+ size, weight, and light/dark conditions.
+
+
+
+ WCAG defines minimum thresholds. APCA is used to ensure interfaces remain
+ readable, comfortable, and usable in real-world conditions.
+
+
+
This reflects the direction of emerging standards such as WCAG 3.
+
+## Core principles
+
+
+ -
+ Clarity over cleverness: interfaces should explain
+ themselves.
+
+ -
+ Predictable behaviour: similar things behave in similar
+ ways.
+
+ -
+ Multiple ways to perceive information: never rely on one
+ signal alone.
+
+ -
+ Low cognitive effort by default: minimise mental overhead.
+
+
+
+## Do
+
+### Interactive elements
+
+
+ - Ensure every interactive control has an accessible name.
+ -
+ Provide this via a visible label,
aria-label, or{" "}
+ aria-labelledby.
+
+ - Make keyboard focus clearly visible at all times.
+ -
+ Use a consistent focus indicator (outline) rather than transient effects
+ such as ripples.
+
+ -
+ Ensure disabled states are clearly distinguishable from enabled and default.
+
+
+
+### Keyboard navigation
+
+
+ -
+ All interactive elements must be reachable and usable using a keyboard
+ alone.
+
+ - Follow a logical tab order that matches the visual and reading order.
+ -
+ Do not trap focus. Users must be able to move in and out of components using
+ standard keyboard interactions.
+
+ -
+ Ensure focus is always visible and moves predictably between elements.
+
+ -
+ Support standard keyboard interactions (e.g. Enter or Space to activate
+ controls).
+
+
+
+
+ For composite components (e.g. menus, dialogs, tables), manage focus
+ intentionally:
+
+
+
+ - Move focus into the component when it opens.
+ - Keep focus within the component while it is active.
+ - Return focus to the triggering element when it closes.
+
+
+### Icons and icon-only actions
+
+
+ -
+ Icon-only controls must include an accessible name that describes the action
+ (e.g. “Delete sample”), using
aria-label or{" "}
+ aria-labelledby.
+
+ -
+ Tooltips support discoverability, but do not replace accessible names.
+
+ -
+ Decorative icons should be hidden from assistive technologies using{" "}
+
aria-hidden="true".
+
+ - Do not rely on an icon alone to communicate critical meaning.
+ -
+ If an icon represents a toggle or state, expose the state using appropriate
+ ARIA attributes (e.g.
aria-pressed).
+
+
+
+
+ For interactive icons, ensure both an accessible name and a visible affordance
+ such as a tooltip or label.
+
+
+
+ In MUI, use aria-label on IconButton. Tooltips (e.g.
+ <Tooltip />) should be used in addition to, not instead of,
+ accessible labelling.
+
+
+### Forms and inputs
+
+
+ - Always associate inputs with labels (even if visually hidden).
+ -
+ Do not show validation errors while a user is actively typing. Validate on
+ blur or submission.
+
+ - Make error messages clear, specific, and actionable.
+ - Associate errors programmatically with the relevant field.
+
+
+### Content and layout
+
+
+ - Do not rely on colour alone to convey meaning.
+ - Do not rely on icons alone to convey critical meaning.
+ - Use a logical, predictable reading order.
+
+
+## Don’t
+
+
+ - Don’t use placeholder text as a replacement for labels.
+ - Don’t hide important information in faint or decorative text.
+ - Don’t introduce unexpected interaction patterns.
+ - Don’t create dense, unbroken blocks of content.
+
+
+## Storybook guidance
+
+
+ -
+ Simple component stories may be visually minimal, but should still expose an
+ accessible name, or be documented as intentionally incomplete.
+
+ -
+ Accessibility warnings in Storybook are signals, not noise. Either resolve
+ them or document why they exist.
+
+
+
+## Quick sense check
+
+
+ - Can this be used with a keyboard only?
+ - Is its purpose clear without colour or icons?
+ - Would it still make sense when someone is tired or distracted?
+
+
+
+
+# Colour contrast
+
+
+ Colour contrast directly affects readability, speed, and error rate. In dense,
+ data-heavy scientific interfaces, poor contrast increases cognitive load and
+ slows decision-making.
+
+
+
+ We prioritise perceptual contrast using APCA when defining colour choices,
+ while maintaining WCAG 2.2 as the compliance baseline.
+
+
+## Why contrast needs a modern approach
+
+
+ Traditional WCAG 2.x contrast ratios are useful, but they are based on
+ luminance ratios rather than perceived readability. In practice, some
+ combinations can technically pass while still feel strained or unstable in
+ real UI.
+
+
+
+ This becomes more visible across different font sizes, weights, and light or
+ dark environments.
+
+
+
This leads to common issues:
+
+
+ - Combinations that pass but still feel hard to read.
+ - Overly strong contrast that causes glare or eye strain in dark mode.
+ -
+ Poor readability with saturated colours such as success, warning, and
+ danger.
+
+
+
+
+ APCA helps address these limitations by modelling perceived readability rather
+ than relying only on raw luminance difference.
+
+
+## APCA contrast (primary)
+
+
+ APCA reflects how contrast is actually experienced by users more closely than
+ older ratio-based methods.
+
+
+
+ - Accounts for font size, weight, and polarity.
+ - Handles light-on-dark and dark-on-light differently.
+ - Produces more reliable results for real UI text.
+ - Helps reduce strain in long-running workflows.
+
+
+
+ We use APCA to tune token values, component defaults, and interaction states.
+
+
+## WCAG 2.2 contrast (baseline)
+
+
WCAG 2.2 remains the current compliance baseline for text contrast.
+
+
+ - Defines minimum acceptable contrast thresholds.
+ - Used as a strict floor we do not go below.
+ - Required for accessibility reviews and audits.
+
+
+
+ WCAG 2.2 is necessary, but on its own it is not enough to judge readability
+ quality.
+
+
+## How we use them together
+
+
Contrast decisions follow a clear order:
+
+
+ -
+ 1. Design using APCA for perceptual readability.
+
+ -
+ 2. Validate against WCAG 2.2 for compliance.
+
+ -
+ 3. Adjust only if required, without degrading usability.
+
+
+
+
This helps keep interfaces both compliant and genuinely usable.
+
+## Colour-specific considerations
+
+
+ Some hues behave less predictably for perceived contrast, even when WCAG 2.x
+ ratios look acceptable.
+
+
+
+ In DiamondDS this matters most for status colours: --ds-success,
+ --ds-warning, and --ds-danger.
+
+
+
+ A common issue in real interfaces is that black text on a saturated colour may
+ look mathematically strong, but visually feel unstable, vibrating, or tiring,
+ especially for smaller or denser text.
+
+
+
APCA is better at exposing these perception problems.
+
+
+ -
+ Success: can feel muddy or uneven with dark text,
+ especially in small labels.
+
+ -
+ Warning: often looks shallower than expected, reducing
+ clarity on both light and dark surfaces.
+
+ -
+ Danger: more prone to vibration and reduced legibility,
+ particularly in error messaging.
+
+
+
+
When using these colours:
+
+
+ - Use APCA to judge readability, not just WCAG 2.2 ratios.
+ - Test across sizes, weights, and both themes.
+ - Always pair colour with text, icons, or labels.
+
+
+### WCAG 2.2 vs APCA: why passes can still fail users
+
+
+ WCAG 2.2 is a useful baseline, but it does not always predict comfort or
+ readability in real interfaces. APCA tracks perceived readability more closely.
+
+
+
+
+
+
Light
+
+
+
Success
+
+ --ds-success
+ #1B8834
+
+
+
+
WCAG 2.2 ✅
+
+ Experiment complete · 12 files processed
+
+
+
+
APCA ✅
+
+ Experiment complete · 12 files processed
+
+
+
+
+
+
+
Warning
+
+ --ds-warning
+ #e97b12
+
+
+
+
WCAG 2.2
+
+ Beamline temperature near limit
+
+
+
+
APCA ✅
+
+ Beamline temperature near limit
+
+
+
+
+
+
+
Danger
+
+ --ds-danger
+ #d63c41
+
+
+
+
WCAG 2.2 ✅
+
+ Connection failed · retry required
+
+
+
+
APCA ✅
+
+ Connection failed · retry required
+
+
+
+
+
+
+
+
Dark
+
+
+
Success
+
+ --ds-success
+ #23913C
+
+
+
+
WCAG 2.2
+
+ Experiment complete · 12 files processed
+
+
+
+
APCA ✅
+
+ Experiment complete · 12 files processed
+
+
+
+
+
+
+
Warning
+
+ --ds-warning
+ #f07a13
+
+
+
+
WCAG 2.2
+
+ Beamline temperature near limit
+
+
+
+
APCA ✅
+
+ Beamline temperature near limit
+
+
+
+
+
+
+
Danger
+
+ --ds-danger
+ #d63c41
+
+
+
+
WCAG 2.2 ✅
+
+ Connection failed · retry required
+
+
+
+
APCA ✅
+
+ Connection failed · retry required
+
+
+
+
+
+
+
+
+
How to use this
+
+ - Use WCAG 2.2 as the baseline check, especially for smaller text.
+ -
+ Use APCA to validate perceived readability and comfort, particularly for
+ saturated status colours.
+
+ - Always pair colour with icons or text. Never rely on colour alone.
+
+
+
+
+
+## Practical guidance
+
+
+ -
+ Body text: optimise for perceptual readability first, then
+ confirm WCAG 2.2 compliance.
+
+ -
+ UI chrome: maintain clear separation and predictable
+ hierarchy through surface and border roles.
+
+ -
+ Subtle text: only use for non-essential information.
+
+ -
+ Disabled states: must remain distinguishable without
+ becoming unreadable.
+
+
+
+## Common pitfalls
+
+
+ - Relying on WCAG ratios alone to judge readability.
+ -
+ Reducing contrast for visual subtlety where meaning is still required.
+
+ - Using saturated colours without perceptual validation.
+ - Ignoring polarity differences between light and dark mode.
+
+
+## When WCAG and APCA disagree
+
+
+ - If WCAG 2.2 fails, the colour must change.
+ -
+ If WCAG 2.2 passes but APCA still indicates poor readability, improve the
+ colour choice rather than treating compliance as enough.
+
+ -
+ In critical workflows, readability and accuracy take precedence over visual
+ subtlety.
+
+
+
+## Future: WCAG 3 and APCA
+
+
+ WCAG 3 is still evolving, but perceptual contrast models such as APCA are
+ influencing the direction of accessibility guidance.
+
+
+
+ Our approach reflects that direction while staying grounded in current
+ compliance requirements:
+
+
+
+ - Use perceptual contrast thinking to design and tune colour choices.
+ - Validate text contrast against WCAG 2.2 today.
+ -
+ Reduce future rework by avoiding colour decisions that are only
+ mathematically compliant.
+
+
+
+
Learn more:
+
+
+
+
+
+# Cognitive accessibility and usability
+
+
+ Accessibility is not only about vision, hearing, or motor input. People also
+ differ in how they process information, maintain focus, recover from errors,
+ and work under pressure or fatigue.
+
+
+
+ In scientific environments, these differences matter. Users may work for long
+ periods, switch between multiple tools and data sources, or operate systems
+ during live experiments where mistakes can be costly.
+
+
+
+ This page focuses on cognitive accessibility and practical usability within
+ complex scientific software.
+
+
+## Designing for cognitive accessibility
+
+
+ Good accessibility and usability often come from the same decisions:
+ interfaces that are clear, predictable, consistent, and forgiving.
+
+
+
+ The goal is not to simplify scientific work itself, but to reduce unnecessary
+ cognitive load created by the interface.
+
+
+## Design objectives
+
+### Help users understand what things are
+
+
+ - Use familiar patterns, terminology, and behaviours.
+ - Avoid inventing new interaction models without strong justification.
+ - Make purpose and state visible at a glance.
+ - Ensure actions and outcomes feel predictable.
+
+
+### Reduce memory burden
+
+
+ - Do not rely on users remembering hidden rules or previous states.
+ - Keep important information visible where possible.
+ - Use clear labels, grouping, and hierarchy.
+ - Support recognition over recall.
+
+
+### Help users maintain focus
+
+
+ - Avoid unnecessary distractions or competing emphasis.
+ - Use layout and spacing to separate concerns clearly.
+ - Keep navigation and interaction patterns consistent.
+ - Help users re-orient when context is lost.
+
+
+### Help users avoid and recover from errors
+
+
+ - Prevent errors where possible rather than reacting to them later.
+ - Make system status and consequences visible before actions occur.
+ - Provide clear, actionable error messages.
+ - Make recovery paths obvious and forgiving.
+
+
+### Design for long-running workflows
+
+
+ - Assume users may be tired, interrupted, or multitasking.
+ - Reduce ambiguity in high-pressure or operational situations.
+ - Keep interfaces calm, stable, and predictable.
+ - Design interactions that still make sense at the end of a long day.
+
+
+## Applying this in Storybook
+
+When reviewing components and patterns, ask:
+
+
+ - Is the interface understandable without prior knowledge?
+ - Does it rely on memory or hidden behaviour?
+ - Is important state clearly visible?
+ - Is error recovery understandable and forgiving?
+ - Would this remain clear during a long experiment session?
+
+
+## Further reading
+
+
+
+