From c1635c78d96f6f5d696b0091458a2f5d4713aa22 Mon Sep 17 00:00:00 2001 From: Zohar Manor-Abel Date: Fri, 8 May 2026 14:20:05 +0100 Subject: [PATCH] Add accessibility documentation structure and initial guidance pages Update to text and remove much of the inline styling Link in nav --- .storybook/preview.tsx | 1 + src/storybook/accessibility/00-overview.mdx | 179 +++++++ .../accessibility/01-colour-contrast.mdx | 506 ++++++++++++++++++ .../accessibility/02-cognitive-a11y.mdx | 119 ++++ 4 files changed, 805 insertions(+) create mode 100644 src/storybook/accessibility/00-overview.mdx create mode 100644 src/storybook/accessibility/01-colour-contrast.mdx create mode 100644 src/storybook/accessibility/02-cognitive-a11y.mdx diff --git a/.storybook/preview.tsx b/.storybook/preview.tsx index 9a346aa..c927e92 100644 --- a/.storybook/preview.tsx +++ b/.storybook/preview.tsx @@ -79,6 +79,7 @@ const preview: Preview = { "Helpers", "Theme", "Theme/Logos", + "Accessibility", "MUI", "Components", ], diff --git a/src/storybook/accessibility/00-overview.mdx b/src/storybook/accessibility/00-overview.mdx new file mode 100644 index 0000000..0364bbe --- /dev/null +++ b/src/storybook/accessibility/00-overview.mdx @@ -0,0 +1,179 @@ +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 + + + +## ✅ Do + +### Interactive elements + + + +### Keyboard navigation + + + +For composite components (e.g. menus, dialogs, tables), manage focus +intentionally: + + + +### Icons and icon-only actions + + + +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 + + + +### Content and layout + + + +## ❌ Don’t + + + +## Storybook guidance + + + +## Quick sense check + + + +
diff --git a/src/storybook/accessibility/01-colour-contrast.mdx b/src/storybook/accessibility/01-colour-contrast.mdx new file mode 100644 index 0000000..14e4296 --- /dev/null +++ b/src/storybook/accessibility/01-colour-contrast.mdx @@ -0,0 +1,506 @@ +import { Meta } from "@storybook/blocks"; + + + + + +
+ +# 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: + + + +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. + + + +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. + + + +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: + + + +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. + + + +When using these colours: + + + +### 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 + + + +## Common pitfalls + + + +## When WCAG and APCA disagree + + + +## 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: + + + +Learn more: + + + +
diff --git a/src/storybook/accessibility/02-cognitive-a11y.mdx b/src/storybook/accessibility/02-cognitive-a11y.mdx new file mode 100644 index 0000000..60bbc7f --- /dev/null +++ b/src/storybook/accessibility/02-cognitive-a11y.mdx @@ -0,0 +1,119 @@ +import { Meta } from "@storybook/blocks"; + + + +
+ +# 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 + + + +### Reduce memory burden + + + +### Help users maintain focus + + + +### Help users avoid and recover from errors + + + +### Design for long-running workflows + + + +## Applying this in Storybook + +When reviewing components and patterns, ask: + + + +## Further reading + + + +