diff --git a/apps/backoffice/src/main.tsx b/apps/backoffice/src/main.tsx index 5d991e0df..e85c16aba 100644 --- a/apps/backoffice/src/main.tsx +++ b/apps/backoffice/src/main.tsx @@ -4,6 +4,10 @@ import '@mantine/core/styles.css'; import '@mantine/notifications/styles.css'; import '@mantine/dates/styles.css'; import '@mantine/spotlight/styles.css'; +// After Mantine's CSS (it defines the variables these tokens resolve to), +// before the app's own, which may override them. Relative because the +// @ema-platform aliases are tsconfig paths, which do not carry subpaths. +import '../../../libs/shared/src/lib/theme/semantic.css'; import './styles.css'; import './app/i18n/config'; import { App } from './app/app'; diff --git a/apps/e2e/visual/theme.spec.ts b/apps/e2e/visual/theme.spec.ts index eee86e15f..0618fa396 100644 --- a/apps/e2e/visual/theme.spec.ts +++ b/apps/e2e/visual/theme.spec.ts @@ -58,4 +58,43 @@ for (const app of APPS) { }); } } + + /** + * The focus ring, captured while actually focused. + * + * The full-page shots above can't show this: nothing is focused in them, so + * a regression that removed the ring entirely would leave them all green. + * Keyboard focus specifically, because `:focus-visible` deliberately does + * not match a mouse click. + */ + test(`${app.name} — focus ring is visible`, async ({ page }) => { + await page.setViewportSize({ width: 1440, height: 900 }); + await gotoGallery(page, app.url, 'light'); + + const section = page.locator('section, div').filter({ hasText: 'Focus states' }).last(); + await section.scrollIntoViewIfNeeded(); + + const button = page.getByRole('button', { name: 'Button', exact: true }); + await button.focus(); + await expect(button).toBeFocused(); + + // Assert the ring in computed styles as well as pixels. A screenshot alone + // would still pass if the outline came from somewhere unintended, and a + // token that failed to resolve leaves an empty string rather than an error. + const ring = await button.evaluate((el) => { + const s = getComputedStyle(el); + return { + width: s.outlineWidth, + style: s.outlineStyle, + token: getComputedStyle(document.documentElement) + .getPropertyValue('--ema-focus-ring') + .trim(), + }; + }); + expect(ring.style).toBe('solid'); + expect(ring.width).toBe('2px'); + expect(ring.token).not.toBe(''); + + await expect(button).toHaveScreenshot(`${app.name}-focus-ring.png`); + }); } diff --git a/apps/e2e/visual/theme.spec.ts-snapshots/backoffice-focus-ring-chromium-win32.png b/apps/e2e/visual/theme.spec.ts-snapshots/backoffice-focus-ring-chromium-win32.png new file mode 100644 index 000000000..434007dca Binary files /dev/null and b/apps/e2e/visual/theme.spec.ts-snapshots/backoffice-focus-ring-chromium-win32.png differ diff --git a/apps/e2e/visual/theme.spec.ts-snapshots/portal-focus-ring-chromium-win32.png b/apps/e2e/visual/theme.spec.ts-snapshots/portal-focus-ring-chromium-win32.png new file mode 100644 index 000000000..9271b168c Binary files /dev/null and b/apps/e2e/visual/theme.spec.ts-snapshots/portal-focus-ring-chromium-win32.png differ diff --git a/apps/portal/src/main.tsx b/apps/portal/src/main.tsx index 1297bc950..56a6956cd 100644 --- a/apps/portal/src/main.tsx +++ b/apps/portal/src/main.tsx @@ -3,6 +3,10 @@ import { createRoot } from 'react-dom/client'; import '@mantine/core/styles.css'; import '@mantine/dates/styles.css'; import '@mantine/notifications/styles.css'; +// After Mantine's CSS (it defines the variables these tokens resolve to), +// before the app's own, which may override them. Relative because the +// @ema-platform aliases are tsconfig paths, which do not carry subpaths. +import '../../../libs/shared/src/lib/theme/semantic.css'; import './app/theme/portal.css'; import './app/i18n/config'; diff --git a/libs/shared/src/index.ts b/libs/shared/src/index.ts index 040d0f5ff..ce06ea28f 100644 --- a/libs/shared/src/index.ts +++ b/libs/shared/src/index.ts @@ -2,6 +2,7 @@ export * from './lib/theme/palettes'; export * from './lib/theme/base-theme'; export * from './lib/theme/ema-theme'; export * from './lib/theme/portal-theme'; +export * from './lib/theme/status-tone'; export * from './lib/date/date-displayer'; export * from './lib/date/use-date-displayer'; export * from './lib/date/ethiopic'; diff --git a/libs/shared/src/lib/theme/semantic.css b/libs/shared/src/lib/theme/semantic.css new file mode 100644 index 000000000..f40f547e6 --- /dev/null +++ b/libs/shared/src/lib/theme/semantic.css @@ -0,0 +1,178 @@ +/* ============================================================================ + Semantic tokens. + + These name a *role* — "the page background", "a subtle border", "danger" — + rather than a colour. Feature code should reach for these instead of a hex, + because a hex cannot follow the colour scheme and a Mantine shade index + (`gray.5`) says nothing about why that shade was chosen. + + Every token resolves to a Mantine variable rather than a literal. That is + deliberate: Mantine already recomputes its own variables under + [data-mantine-color-scheme], so tokens defined in terms of them switch for + free and can never drift from the theme. A parallel palette of raw hexes + would recreate exactly the problem this layer exists to fix. + + Loaded once per app, after Mantine's CSS. + ============================================================================ */ + +:root { + /* --- Surfaces ---------------------------------------------------------- */ + /* The page itself, a raised card, and a recessed well. */ + --ema-surface-page: var(--mantine-color-gray-0); + --ema-surface-raised: var(--mantine-color-white); + --ema-surface-sunken: var(--mantine-color-gray-1); + + /* --- Borders ----------------------------------------------------------- */ + /* Subtle separates rows; strong outlines an input or a focused container. */ + --ema-border-subtle: var(--mantine-color-gray-2); + --ema-border-strong: var(--mantine-color-gray-4); + + /* --- Text -------------------------------------------------------------- */ + /* Secondary must stay a *text* colour: it has to clear 4.5:1, not 3:1, so + it deliberately sits darker than the gray-5 that reads as "dimmed". */ + --ema-text-primary: var(--mantine-color-gray-9); + --ema-text-secondary: var(--mantine-color-gray-7); + --ema-text-disabled: var(--mantine-color-gray-5); + + /* --- Status ------------------------------------------------------------ + Six tones, which is the entire vocabulary a status needs. Domain statuses + map onto these rather than each picking their own colour. + + `-fg` is text on the app background; `-bg` is a tint to sit that text on. + Both are needed because a badge and a label have different contrast + requirements against the same surface. */ + --ema-status-success-fg: var(--mantine-color-green-8); + --ema-status-success-bg: var(--mantine-color-green-0); + --ema-status-warning-fg: var(--mantine-color-yellow-8); + --ema-status-warning-bg: var(--mantine-color-yellow-0); + --ema-status-danger-fg: var(--mantine-color-red-8); + --ema-status-danger-bg: var(--mantine-color-red-0); + --ema-status-info-fg: var(--mantine-color-blue-8); + --ema-status-info-bg: var(--mantine-color-blue-0); + --ema-status-pending-fg: var(--mantine-color-orange-8); + --ema-status-pending-bg: var(--mantine-color-orange-0); + --ema-status-neutral-fg: var(--mantine-color-gray-7); + --ema-status-neutral-bg: var(--mantine-color-gray-1); + + /* --- Focus ------------------------------------------------------------- + One ring for the whole platform. Sized to stay visible against both a + white card and a tinted surface. */ + --ema-focus-ring: var(--mantine-primary-color-filled); + --ema-focus-ring-width: 2px; + --ema-focus-ring-offset: 2px; +} + +[data-mantine-color-scheme='dark'] { + /* Dark is not light inverted. Surfaces lift with elevation rather than + dropping, and text steps down from white rather than up from black. */ + --ema-surface-page: var(--mantine-color-dark-8); + --ema-surface-raised: var(--mantine-color-dark-7); + --ema-surface-sunken: var(--mantine-color-dark-9); + + --ema-border-subtle: var(--mantine-color-dark-4); + --ema-border-strong: var(--mantine-color-dark-3); + + --ema-text-primary: var(--mantine-color-gray-0); + --ema-text-secondary: var(--mantine-color-gray-4); + --ema-text-disabled: var(--mantine-color-dark-2); + + /* Saturated mid-shades go muddy on a dark ground; these step lighter so the + foreground still clears 4.5:1 and the tint stays distinguishable. */ + --ema-status-success-fg: var(--mantine-color-green-4); + --ema-status-success-bg: var(--mantine-color-green-9); + --ema-status-warning-fg: var(--mantine-color-yellow-4); + --ema-status-warning-bg: var(--mantine-color-yellow-9); + --ema-status-danger-fg: var(--mantine-color-red-4); + --ema-status-danger-bg: var(--mantine-color-red-9); + --ema-status-info-fg: var(--mantine-color-blue-4); + --ema-status-info-bg: var(--mantine-color-blue-9); + --ema-status-pending-fg: var(--mantine-color-orange-4); + --ema-status-pending-bg: var(--mantine-color-orange-9); + --ema-status-neutral-fg: var(--mantine-color-gray-4); + --ema-status-neutral-bg: var(--mantine-color-dark-5); +} + +/* ============================================================================ + Focus. + + The codebase had no :focus-visible rule anywhere, which is the single + largest accessibility gap in it. :focus-visible rather than :focus so a + mouse click does not leave a ring behind — that is the behaviour that gets + focus rings deleted from designs in the first place. + ============================================================================ */ + +/* Mantine already rings its own controls (`.mantine-focus-auto:focus-visible` + resolves to the same 2px solid primary). This rule is the safety net for + everything it does not own: plain anchors, custom elements, and the + UnstyledButtons this codebase uses for its own controls. + + Note there is deliberately no `outline: none` opt-out for the Mantine + classes. An earlier attempt at one suppressed Mantine's working ring and + left portal buttons with no focus indicator at all — which of the two rules + won came down to stylesheet order, and that differs between the apps. + Matching values mean overlap is invisible, so overlap is the safe default. */ +:focus-visible { + outline: var(--ema-focus-ring-width) solid var(--ema-focus-ring); + outline-offset: var(--ema-focus-ring-offset); +} + +/* ============================================================================ + Screen-reader-only utility. + + No equivalent existed anywhere in the codebase, so anything needing a text + alternative had nowhere to put it. + ============================================================================ */ + +.ema-sr-only { + position: absolute; + width: 1px; + height: 1px; + padding: 0; + margin: -1px; + overflow: hidden; + /* clip-path rather than the legacy clip: it does not force a layer and is + not deprecated. */ + clip-path: inset(50%); + white-space: nowrap; + border: 0; +} + +/* A skip link is sr-only until focused, then must be plainly visible. */ +.ema-skip-link { + position: absolute; + top: 0; + left: 0; + z-index: 9999; + padding: 0.75rem 1.25rem; + background: var(--ema-surface-raised); + color: var(--ema-text-primary); + border: 1px solid var(--ema-border-strong); + border-radius: 0 0 var(--mantine-radius-md) 0; + font-weight: 600; + text-decoration: none; + /* Off-screen rather than display:none, so it stays focusable. */ + transform: translateY(-150%); +} + +.ema-skip-link:focus-visible { + transform: translateY(0); +} + +/* ============================================================================ + Reduced motion. + + Honour the OS setting globally. Animation is not removed outright — a + near-instant transition still conveys that something changed, without the + movement that triggers vestibular symptoms. + ============================================================================ */ + +@media (prefers-reduced-motion: reduce) { + *, + *::before, + *::after { + animation-duration: 0.01ms !important; + animation-iteration-count: 1 !important; + transition-duration: 0.01ms !important; + scroll-behavior: auto !important; + } +} diff --git a/libs/shared/src/lib/theme/status-tone.ts b/libs/shared/src/lib/theme/status-tone.ts new file mode 100644 index 000000000..4d68cf716 --- /dev/null +++ b/libs/shared/src/lib/theme/status-tone.ts @@ -0,0 +1,51 @@ +/** + * The platform's status vocabulary. + * + * There are 48 separate status→colour maps across the codebase, each deciding + * independently what "pending" looks like. They disagree. The fix is not one + * bigger map — domain statuses genuinely differ per feature — but one small set + * of *tones* that every domain maps onto, so the colour decision is made six + * times instead of forty-eight. + * + * `semantic.css` carries the CSS-variable form of these for stylesheet use. + * This module is for the many places that need a Mantine `color` prop instead. + */ + +export type StatusTone = + | 'success' + | 'warning' + | 'danger' + | 'info' + | 'pending' + | 'neutral'; + +/** + * Tone → Mantine colour name. + * + * Deliberately the only place a tone becomes a colour. Changing the platform's + * idea of "warning" is an edit here, not a sweep through 48 files. + */ +export const STATUS_TONE_COLOR: Record = { + success: 'green', + warning: 'yellow', + danger: 'red', + info: 'blue', + pending: 'orange', + neutral: 'gray', +}; + +/** + * Tone → CSS custom properties, for inline styles and stylesheets. + * + * Returns variable references rather than resolved colours so the values keep + * following the active colour scheme. + */ +export function statusToneVars(tone: StatusTone): { + color: string; + background: string; +} { + return { + color: `var(--ema-status-${tone}-fg)`, + background: `var(--ema-status-${tone}-bg)`, + }; +}