diff --git a/.github/workflows/deploy-storybook.yaml b/.github/workflows/deploy-storybook.yaml
index 5ae937fc..cda7c81b 100644
--- a/.github/workflows/deploy-storybook.yaml
+++ b/.github/workflows/deploy-storybook.yaml
@@ -25,10 +25,8 @@ jobs:
steps:
- uses: actions/checkout@v4
- - uses: pnpm/action-setup@v4
- with:
- run_install: |
- args: [ --force ]
+ - name: Setup pnpm
+ uses: pnpm/action-setup@v4
- name: Set Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v4
@@ -36,6 +34,9 @@ jobs:
node-version: ${{ matrix.node-version }}
cache: pnpm
+ - name: Install dependencies
+ run: pnpm install --frozen-lockfile
+
- name: Build and publish
id: build-publish
uses: bitovi/github-actions-storybook-to-github-pages@v1.0.3
diff --git a/.github/workflows/npm-publish-pre-release.yaml b/.github/workflows/npm-publish-pre-release.yaml
index ca76aefb..e71cc402 100644
--- a/.github/workflows/npm-publish-pre-release.yaml
+++ b/.github/workflows/npm-publish-pre-release.yaml
@@ -19,9 +19,6 @@ jobs:
- name: Setup pnpm
uses: pnpm/action-setup@v4
- with:
- run_install: |
- args: [ --force ]
- name: Setup node
uses: actions/setup-node@v4
diff --git a/.github/workflows/npm-publish.yaml b/.github/workflows/npm-publish.yaml
index 478cb2b3..e9cb93ba 100644
--- a/.github/workflows/npm-publish.yaml
+++ b/.github/workflows/npm-publish.yaml
@@ -20,9 +20,6 @@ jobs:
- name: Setup pnpm
uses: pnpm/action-setup@v4
- with:
- run_install: |
- args: [ --force ]
- name: Setup node
uses: actions/setup-node@v4
diff --git a/.github/workflows/test-build.yaml b/.github/workflows/test-build.yaml
index afe814d2..48e9a519 100644
--- a/.github/workflows/test-build.yaml
+++ b/.github/workflows/test-build.yaml
@@ -20,17 +20,16 @@ jobs:
steps:
- uses: actions/checkout@v4
- - name: Install dependencies
+ - name: Setup pnpm
uses: pnpm/action-setup@v4
- with:
- run_install: |
- args: [ --force ]
- name: Set Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
- cache: pnpm
+
+ - name: Install dependencies
+ run: pnpm install --frozen-lockfile
- name: Audit packages, run Typescript tests and lint client code
run: |
diff --git a/.npmrc b/.npmrc
index c14db4af..390b0c46 100644
--- a/.npmrc
+++ b/.npmrc
@@ -1,3 +1,2 @@
publish-branch=main
access=public
-ignore-scripts=true
\ No newline at end of file
diff --git a/.storybook/ThemeSwapper.tsx b/.storybook/ThemeSwapper.tsx
index efd541cc..280ff099 100644
--- a/.storybook/ThemeSwapper.tsx
+++ b/.storybook/ThemeSwapper.tsx
@@ -18,18 +18,35 @@ export interface ThemeSwapperProps {
export const TextLight = "Mode: Light";
export const TextDark = "Mode: Dark";
+export const TextSystem = "Mode: System";
const ThemeSwapper = ({ context, children }: ThemeSwapperProps) => {
- const { mode, setMode } = useColorScheme();
- //if( !mode ) return
+ const { mode, systemMode, setMode } = useColorScheme();
useEffect(() => {
- const selectedThemeMode = context.globals.themeMode || TextLight;
- setMode(selectedThemeMode == TextLight ? "light" : "dark");
- }, [context.globals.themeMode]);
+ const selectedThemeMode = context.globals.themeMode ?? TextSystem;
+
+ if (selectedThemeMode === TextLight) {
+ setMode("light");
+ return;
+ }
+
+ if (selectedThemeMode === TextDark) {
+ setMode("dark");
+ return;
+ }
+
+ setMode("system");
+ }, [context.globals.themeMode, setMode]);
+
+ const resolvedMode = mode === "system" ? systemMode : mode;
return (
-
+
{children}
);
diff --git a/.storybook/preview.tsx b/.storybook/preview.tsx
index 4de2bdc4..f5c6190d 100644
--- a/.storybook/preview.tsx
+++ b/.storybook/preview.tsx
@@ -3,12 +3,32 @@ import { CssBaseline } from "@mui/material";
import type { Preview } from "@storybook/react";
import { ThemeProvider } from "../src";
-import { GenericTheme, DiamondTheme } from "../src";
-
-import { Context, ThemeSwapper, TextLight, TextDark } from "./ThemeSwapper";
+import { GenericTheme, DiamondTheme, DiamondDSTheme } from "../src";
+import { ThemeSwapper, TextLight, TextDark, TextSystem } from "./ThemeSwapper";
+import "../src/styles/diamondDS/diamond-ds-roles.css";
const TextThemeBase = "Theme: Generic";
const TextThemeDiamond = "Theme: Diamond";
+const TextThemeDiamondDS = "Theme: DiamondDS";
+
+function resolveTheme(selectedTheme: string) {
+ switch (selectedTheme) {
+ case TextThemeBase:
+ return GenericTheme;
+ case TextThemeDiamond:
+ return DiamondTheme;
+ case TextThemeDiamondDS:
+ default:
+ return DiamondDSTheme;
+ }
+}
+
+function resolveDefaultMode(selectedThemeMode: string) {
+ if (selectedThemeMode === TextLight) return "light";
+ if (selectedThemeMode === TextDark) return "dark";
+
+ return "system";
+}
export const decorators = [
(StoriesWithPadding: React.FC) => {
@@ -18,24 +38,21 @@ export const decorators = [
+
+# 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
+
+
+
+
{mode}
;
+}
+
+it("switches to dark mode", async () => {
+ render(
+
+
+ ,
+ );
+
+ await waitFor(() => {
+ expect(screen.getByTestId("mode").textContent).toBe("dark");
+ expect(document.documentElement.getAttribute("data-mode")).toBe("dark");
+ });
+});
+
+it("switches to light mode", async () => {
+ render(
+
+
+ ,
+ );
+
+ await waitFor(() => {
+ expect(screen.getByTestId("mode").textContent).toBe("light");
+ expect(document.documentElement.getAttribute("data-mode")).toBe("light");
+ });
+});
diff --git a/tsconfig.json b/tsconfig.json
index beb704da..bdf6a6a5 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -1,11 +1,7 @@
{
"compilerOptions": {
"target": "esnext",
- "lib": [
- "dom",
- "dom.iterable",
- "esnext"
- ],
+ "lib": ["dom", "dom.iterable", "esnext"],
"allowJs": true,
"skipLibCheck": true,
"esModuleInterop": true,
@@ -22,14 +18,8 @@
"emitDeclarationOnly": true,
"jsx": "react-jsx",
"baseUrl": "src",
- "types": [
- "vitest/globals",
- "@testing-library/jest-dom"
- ]
+ "types": ["vitest/globals", "@testing-library/jest-dom"]
},
- "include": [
- "src",
- "src/types"
- ],
+ "include": ["src", "src/types"],
"rootDir": "src"
-}
\ No newline at end of file
+}