From 642c5b73222816dc31b6ee231f00c4933dc28775 Mon Sep 17 00:00:00 2001
From: Ilia Denisov <evilcart@gmail.com>
Date: Fri, 22 May 2026 08:25:14 +0200
Subject: [PATCH 1/3] =?UTF-8?q?feat(ui):=20accessibility=20pass=20?=
 =?UTF-8?q?=E2=80=94=20WCAG=202.2=20AA=20for=20login/lobby/shell=20(F2)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add the a11y foundation and bring login, lobby, and the in-game shell to
WCAG 2.2 AA:

- Primitives: .sr-only + .skip-link (base.css), trapFocus (modal focus
  trap + restore) and restoreFocus (menu focus restore) actions, the
  --color-focus visible ring.
- In-game shell: skip link + focusable main landmark; WAI-ARIA sidebar
  tabs (roving tabindex, arrow/Home/End, tabpanel wiring); menu Escape +
  focus restore (account / view / turn-navigator / map-toggles /
  bottom-tabs); mail compose as a role=dialog modal with a focus trap.
- login / lobby / lobby-create: skip link + main landmark, field labels,
  role=alert / role=status live regions.
- Map canvas: aria-label naming it a visual overview, with its data
  reachable by keyboard via the sidebar inspector and tables (accessible
  alternative; in-canvas keyboard nav deferred).

Gates (chromium-desktop): tests/e2e/a11y-axe.spec.ts scans every
top-level view for WCAG 2.2 AA violations (zero); a11y-keyboard.spec.ts
covers the skip link, menu Escape+restore, and tab roving. Adds
@axe-core/playwright. Docs: ui/docs/a11y.md (+ index). Marks F1 and F2
done in ui/PLAN-finalize.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 ui/PLAN-finalize.md                           | 22 ++++-
 ui/docs/README.md                             |  3 +
 ui/docs/a11y.md                               | 77 +++++++++++++++++
 ui/frontend/package.json                      |  1 +
 ui/frontend/src/lib/a11y/focus-trap.ts        | 70 +++++++++++++++
 ui/frontend/src/lib/a11y/restore-focus.ts     | 34 ++++++++
 .../src/lib/active-view/mail/compose.svelte   | 39 ++++++---
 .../src/lib/active-view/map-toggles.svelte    |  8 +-
 ui/frontend/src/lib/active-view/map.svelte    |  7 +-
 .../src/lib/header/account-menu.svelte        |  8 +-
 .../src/lib/header/turn-navigator.svelte      |  8 +-
 ui/frontend/src/lib/header/view-menu.svelte   |  8 +-
 ui/frontend/src/lib/i18n/locales/en.ts        |  3 +
 ui/frontend/src/lib/i18n/locales/ru.ts        |  3 +
 .../src/lib/sidebar/bottom-tabs.svelte        |  8 +-
 ui/frontend/src/lib/sidebar/sidebar.svelte    |  8 +-
 ui/frontend/src/lib/sidebar/tab-bar.svelte    | 47 +++++++++-
 ui/frontend/src/lib/theme/base.css            | 38 ++++++++
 .../src/routes/games/[id]/+layout.svelte      | 11 ++-
 ui/frontend/src/routes/lobby/+page.svelte     | 11 +--
 .../src/routes/lobby/create/+page.svelte      |  3 +-
 ui/frontend/src/routes/login/+page.svelte     | 17 +---
 ui/frontend/tests/e2e/a11y-axe.spec.ts        | 86 +++++++++++++++++++
 ui/frontend/tests/e2e/a11y-keyboard.spec.ts   | 66 ++++++++++++++
 ui/pnpm-lock.yaml                             | 19 ++++
 25 files changed, 559 insertions(+), 46 deletions(-)
 create mode 100644 ui/docs/a11y.md
 create mode 100644 ui/frontend/src/lib/a11y/focus-trap.ts
 create mode 100644 ui/frontend/src/lib/a11y/restore-focus.ts
 create mode 100644 ui/frontend/tests/e2e/a11y-axe.spec.ts
 create mode 100644 ui/frontend/tests/e2e/a11y-keyboard.spec.ts

diff --git a/ui/PLAN-finalize.md b/ui/PLAN-finalize.md
index c40f2bc..251d640 100644
--- a/ui/PLAN-finalize.md
+++ b/ui/PLAN-finalize.md
@@ -19,7 +19,15 @@ being marked done.
 
 ---
 
-## F1 — Visual design system
+## F1 — Visual design system — done
+
+Merged to `development` via PR #26 (2026-05-22): a shared design-token
+system (`ui/frontend/src/lib/theme/`), light/dark theming with a picker
+and pre-paint guard, and the whole UI migrated onto the tokens.
+Documented literal exceptions: the battle-scene data-viz palette, overlay
+scrims, and directional/deliberate drop shadows. The default theme is
+dark; flipping it to `system` is an available follow-up. Tokens and
+conventions live in `ui/docs/design-system.md`.
 
 Goal: replace the ad-hoc per-component styling (inline hex colors like
 `#0a0e1a`, one-off spacing) with a shared design language so every view
@@ -36,7 +44,17 @@ Acceptance: no literal theme colors left in component `<style>` blocks
 (spot-checked); a single token change restyles the app coherently.
 Consider the `frontend-design` skill for the palette/spacing pass.
 
-## F2 — Accessibility (WCAG 2.2 AA)
+## F2 — Accessibility (WCAG 2.2 AA) — done
+
+Shared a11y primitives (`.sr-only`, `.skip-link`, `trapFocus`,
+`restoreFocus`, the `--color-focus` ring), keyboard paths and ARIA across
+login / lobby / in-game shell (skip links + landmarks, WAI-ARIA sidebar
+tabs with roving + arrow keys, menu Escape + focus restore, the mail
+compose modal dialog with a focus trap), and the map canvas handled as a
+labelled accessible-alternative surface (data via the sidebar/tables).
+Gated by `tests/e2e/a11y-axe.spec.ts` (axe WCAG 2.2 AA scan of every
+top-level view, chromium-desktop, zero violations) and
+`tests/e2e/a11y-keyboard.spec.ts`. Documented in `ui/docs/a11y.md`.
 
 (From Phase 35.) Goal: the whole client is usable by keyboard and
 assistive tech.
diff --git a/ui/docs/README.md b/ui/docs/README.md
index 44c00c4..01650ca 100644
--- a/ui/docs/README.md
+++ b/ui/docs/README.md
@@ -12,6 +12,9 @@ lives in [`../PLAN.md`](../PLAN.md), the active web finalization in
 - [design-system.md](design-system.md) — the design tokens (colour /
   spacing / typography), the light/dark theming mechanism, and the
   component migration conventions.
+- [a11y.md](a11y.md) — the WCAG 2.2 AA approach: axe + keyboard test
+  gates, the shared a11y primitives, coverage by area, and the map-canvas
+  alternative.
 - [navigation.md](navigation.md) — routes, the sidebar tabs, and the
   state-preservation rules across view/tab switches.
 - [storage.md](storage.md) — the `KeyStore` and `Cache` abstractions and
diff --git a/ui/docs/a11y.md b/ui/docs/a11y.md
new file mode 100644
index 0000000..03475cc
--- /dev/null
+++ b/ui/docs/a11y.md
@@ -0,0 +1,77 @@
+# Accessibility
+
+The client targets **WCAG 2.2 AA**. This doc records how accessibility is
+built in, what is verified automatically, and the deliberate boundaries.
+
+## Tooling & gates
+
+- **axe-core via Playwright** (`@axe-core/playwright`):
+  [`tests/e2e/a11y-axe.spec.ts`](../frontend/tests/e2e/a11y-axe.spec.ts)
+  scans every top-level view — login, lobby, lobby/create, and the
+  in-game map / report / mail / battle / science-designer / table — with
+  the `wcag2a wcag2aa wcag21a wcag21aa wcag22aa` rule tags and asserts
+  zero violations. It runs once, on the `chromium-desktop` project (axe's
+  contrast and computed-role checks need one real engine; the
+  webkit/mobile projects add cost without new signal).
+- **Keyboard navigation** (Playwright):
+  [`tests/e2e/a11y-keyboard.spec.ts`](../frontend/tests/e2e/a11y-keyboard.spec.ts)
+  covers the skip link, Escape-closes-and-restores-focus on menus, and
+  the sidebar tab arrow-key pattern.
+- **Svelte compiler a11y lint** is on (no suppressions); `pnpm check`
+  fails on a11y warnings, so basic role/label/structure issues are caught
+  at build time.
+
+## Shared primitives
+
+- `.sr-only` (in [`base.css`](../frontend/src/lib/theme/base.css)) —
+  visually hidden, available to assistive tech.
+- `.skip-link` — visible only on focus; each layout renders one as its
+  first focusable element, pointing at a `tabindex="-1"` main region.
+- [`trapFocus`](../frontend/src/lib/a11y/focus-trap.ts) — Svelte action
+  for modal dialogs: moves focus in (to `[data-autofocus]`), cycles
+  Tab/Shift+Tab within, restores focus on close.
+- [`restoreFocus`](../frontend/src/lib/a11y/restore-focus.ts) — Svelte
+  action for non-modal popovers/menus: returns focus to the trigger when
+  the surface closes, without trapping.
+- `--color-focus` token drives a single visible focus ring app-wide
+  (`:where(*):focus-visible` in `base.css`).
+
+## Coverage by area
+
+- **Landmarks.** The in-game shell is `header` (banner) + `main` +
+  `aside` (complementary); login/lobby/create each wrap content in a
+  `main#main-content`. Every layout has a skip link to its main.
+- **Forms** (login, lobby, create). Every control has an associated
+  label; submit/validation errors use `role="alert"`, async status uses
+  `role="status"`, so they are announced.
+- **Sidebar tabs** follow the WAI-ARIA tabs pattern: `role="tablist"` /
+  `tab` / `tabpanel`, roving `tabindex`, arrow + Home/End keys with
+  automatic activation, `aria-controls` / `aria-labelledby` linking tabs
+  to the panel.
+- **Menus & popovers** (account, view, turn navigator, map toggles,
+  mobile "more"): `aria-haspopup` / `aria-expanded` triggers, Escape and
+  outside-click dismissal, and `restoreFocus` so focus is never dropped
+  to `<body>`.
+- **Modal dialog** (mail compose): `role="dialog"` + `aria-modal` +
+  `aria-labelledby`, `trapFocus`, Escape to close.
+
+## The map canvas
+
+The PixiJS/WebGL map is a visual surface that cannot be made keyboard- or
+screen-reader-navigable without a bespoke effort. It is therefore handled
+as an **accessible alternative**: the `<canvas>` carries an `aria-label`
+naming it and pointing to where the same information lives, and every
+datum it shows — planets, ship groups, routes — is reachable by keyboard
+through the sidebar inspector and the tables view. In-canvas keyboard
+navigation (cursoring between planets) is intentionally out of scope; it
+is noted as a future enhancement in [`ROADMAP.md`](../ROADMAP.md).
+
+## Boundaries / future work
+
+- The deep AA pass focuses on login, lobby, and the in-game shell
+  (acceptance surfaces). Secondary views pass the axe structural scan;
+  exhaustive keyboard/SR polish of every view interaction is incremental.
+- The battle scene (`battle-player/battle-scene.svelte`) is a data-viz
+  surface (see [`design-system.md`](design-system.md)); its content is
+  summarised by the adjacent text protocol log.
+- In-canvas keyboard navigation for the map (deferred, above).
diff --git a/ui/frontend/package.json b/ui/frontend/package.json
index 4ec205b..d4b1341 100644
--- a/ui/frontend/package.json
+++ b/ui/frontend/package.json
@@ -18,6 +18,7 @@
     "pixi.js": "^8.18.1"
   },
   "devDependencies": {
+    "@axe-core/playwright": "4.11.3",
     "@bufbuild/protobuf": "^2.12.0",
     "@bufbuild/protoc-gen-es": "^2.12.0",
     "@connectrpc/connect": "^2.1.1",
diff --git a/ui/frontend/src/lib/a11y/focus-trap.ts b/ui/frontend/src/lib/a11y/focus-trap.ts
new file mode 100644
index 0000000..85a500b
--- /dev/null
+++ b/ui/frontend/src/lib/a11y/focus-trap.ts
@@ -0,0 +1,70 @@
+/**
+ * Focus management for modal dialogs.
+ *
+ * `trapFocus` is a Svelte action for an element with `role="dialog"` and
+ * `aria-modal="true"`. On mount it remembers the currently-focused
+ * element, moves focus into the dialog, and keeps Tab / Shift+Tab cycling
+ * within it; on destroy it restores focus to the original element. ESC
+ * handling stays with the component (it owns the open/close state).
+ *
+ * Initial focus goes to the element marked `data-autofocus`, else the
+ * first focusable element, else the dialog node itself.
+ */
+
+const FOCUSABLE_SELECTOR = [
+	"a[href]",
+	"button:not([disabled])",
+	"input:not([disabled])",
+	"select:not([disabled])",
+	"textarea:not([disabled])",
+	'[tabindex]:not([tabindex="-1"])',
+].join(",");
+
+function focusableWithin(node: HTMLElement): HTMLElement[] {
+	return Array.from(
+		node.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),
+	).filter((el) => el.offsetParent !== null || el === document.activeElement);
+}
+
+/** Svelte action: trap and restore focus for a modal dialog node. */
+export function trapFocus(node: HTMLElement): { destroy(): void } {
+	const previouslyFocused =
+		document.activeElement instanceof HTMLElement
+			? document.activeElement
+			: null;
+
+	function onKeydown(event: KeyboardEvent): void {
+		if (event.key !== "Tab") return;
+		const items = focusableWithin(node);
+		if (items.length === 0) {
+			event.preventDefault();
+			node.focus();
+			return;
+		}
+		const first = items[0];
+		const last = items[items.length - 1];
+		const active = document.activeElement;
+		if (event.shiftKey && active === first) {
+			event.preventDefault();
+			last.focus();
+		} else if (!event.shiftKey && active === last) {
+			event.preventDefault();
+			first.focus();
+		}
+	}
+
+	const initial =
+		node.querySelector<HTMLElement>("[data-autofocus]") ??
+		focusableWithin(node)[0] ??
+		node;
+	initial.focus();
+
+	node.addEventListener("keydown", onKeydown);
+
+	return {
+		destroy(): void {
+			node.removeEventListener("keydown", onKeydown);
+			previouslyFocused?.focus();
+		},
+	};
+}
diff --git a/ui/frontend/src/lib/a11y/restore-focus.ts b/ui/frontend/src/lib/a11y/restore-focus.ts
new file mode 100644
index 0000000..a0079c6
--- /dev/null
+++ b/ui/frontend/src/lib/a11y/restore-focus.ts
@@ -0,0 +1,34 @@
+/**
+ * Focus restoration for transient popovers and menus.
+ *
+ * `restoreFocus` is a Svelte action for a surface that is rendered only
+ * while open (an `{#if open}` popover/menu/drawer). On mount it records
+ * the element that had focus — the trigger that opened it — and on
+ * destroy it returns focus there, so dismissing the surface (Escape,
+ * outside click, or selecting an item) never drops keyboard focus to the
+ * document body.
+ *
+ * Unlike `trapFocus`, it neither traps focus nor moves it into the
+ * surface: menus are non-modal, so the user tabs in only if they want.
+ * Focus is restored only when it would otherwise be lost (it is inside
+ * the closing surface or already on `<body>`); if the user has
+ * deliberately moved focus to another control, that choice is left
+ * alone.
+ */
+export function restoreFocus(node: HTMLElement): { destroy(): void } {
+	const trigger =
+		document.activeElement instanceof HTMLElement
+			? document.activeElement
+			: null;
+
+	return {
+		destroy(): void {
+			const active = document.activeElement;
+			const lost =
+				active === null ||
+				active === document.body ||
+				node.contains(active);
+			if (lost) trigger?.focus();
+		},
+	};
+}
diff --git a/ui/frontend/src/lib/active-view/mail/compose.svelte b/ui/frontend/src/lib/active-view/mail/compose.svelte
index 4fa7ba2..ae9f5f8 100644
--- a/ui/frontend/src/lib/active-view/mail/compose.svelte
+++ b/ui/frontend/src/lib/active-view/mail/compose.svelte
@@ -10,6 +10,7 @@ surfaces the resulting 403 inline.
 	import { getContext } from "svelte";
 
 	import { i18n } from "$lib/i18n/index.svelte";
+	import { trapFocus } from "$lib/a11y/focus-trap";
 	import { mailStore } from "$lib/mail-store.svelte";
 	import {
 		RENDERED_REPORT_CONTEXT_KEY,
@@ -51,6 +52,10 @@ surfaces the resulting 403 inline.
 		}
 	});
 
+	function onWindowKeydown(event: KeyboardEvent): void {
+		if (event.key === "Escape") onClose();
+	}
+
 	async function submit(event: SubmitEvent): Promise<void> {
 		event.preventDefault();
 		error = null;
@@ -84,16 +89,30 @@ surfaces the resulting 403 inline.
 	}
 </script>
 
-<div class="overlay" data-testid="mail-compose">
+<svelte:window onkeydown={onWindowKeydown} />
+
+<div
+	class="overlay"
+	data-testid="mail-compose"
+	role="dialog"
+	aria-modal="true"
+	aria-labelledby="mail-compose-title"
+	use:trapFocus
+>
 	<form class="dialog" onsubmit={submit}>
 		<header>
-			<h3>{i18n.t("game.mail.compose_action")}</h3>
-			<button type="button" class="close" onclick={onClose}>×</button>
+			<h3 id="mail-compose-title">{i18n.t("game.mail.compose_action")}</h3>
+			<button
+				type="button"
+				class="close"
+				aria-label={i18n.t("common.dismiss")}
+				onclick={onClose}>×</button
+			>
 		</header>
 
 		<label>
 			{i18n.t("game.mail.compose.target_label")}
-			<select bind:value={kind} data-testid="mail-compose-kind">
+			<select bind:value={kind} data-testid="mail-compose-kind" data-autofocus>
 				<option value="personal">{i18n.t("game.mail.compose.target_personal")}</option>
 				<option value="broadcast">{i18n.t("game.mail.compose.target_broadcast")}</option>
 			</select>
@@ -111,7 +130,7 @@ surfaces the resulting 403 inline.
 		{/if}
 
 		<label>
-			<span class="visually-hidden">{i18n.t("game.mail.subject_placeholder")}</span>
+			<span class="sr-only">{i18n.t("game.mail.subject_placeholder")}</span>
 			<input
 				type="text"
 				bind:value={subject}
@@ -121,7 +140,7 @@ surfaces the resulting 403 inline.
 		</label>
 
 		<label>
-			<span class="visually-hidden">{i18n.t("game.mail.body_placeholder")}</span>
+			<span class="sr-only">{i18n.t("game.mail.body_placeholder")}</span>
 			<textarea
 				bind:value={body}
 				placeholder={i18n.t("game.mail.body_placeholder")}
@@ -229,12 +248,4 @@ surfaces the resulting 403 inline.
 		font-size: 0.85rem;
 		margin: 0;
 	}
-	.visually-hidden {
-		position: absolute;
-		clip: rect(0 0 0 0);
-		clip-path: inset(50%);
-		height: 1px;
-		width: 1px;
-		overflow: hidden;
-	}
 </style>
diff --git a/ui/frontend/src/lib/active-view/map-toggles.svelte b/ui/frontend/src/lib/active-view/map-toggles.svelte
index 9e01036..2b61bda 100644
--- a/ui/frontend/src/lib/active-view/map-toggles.svelte
+++ b/ui/frontend/src/lib/active-view/map-toggles.svelte
@@ -14,6 +14,7 @@ bottom-tabs bar.
 <script lang="ts">
 	import { onMount } from "svelte";
 	import { i18n } from "$lib/i18n/index.svelte";
+	import { restoreFocus } from "$lib/a11y/restore-focus";
 	import type { MapToggles, GameStateStore } from "$lib/game-state.svelte";
 	import type { WrapMode } from "../../map/world";
 
@@ -83,7 +84,12 @@ bottom-tabs bar.
 		<span aria-hidden="true">⚙</span>
 	</button>
 	{#if open}
-		<div class="surface" role="menu" data-testid="map-toggles-surface">
+		<div
+			class="surface"
+			role="menu"
+			data-testid="map-toggles-surface"
+			use:restoreFocus
+		>
 			<fieldset>
 				<legend>{i18n.t("game.map.toggles.section.objects")}</legend>
 				<label>
diff --git a/ui/frontend/src/lib/active-view/map.svelte b/ui/frontend/src/lib/active-view/map.svelte
index c015db4..04070b5 100644
--- a/ui/frontend/src/lib/active-view/map.svelte
+++ b/ui/frontend/src/lib/active-view/map.svelte
@@ -706,7 +706,12 @@ preference the store already manages.
 		data-planet-count={store?.report?.planets.length ?? 0}
 		bind:this={containerEl}
 	>
-		<canvas bind:this={canvasEl}></canvas>
+		<canvas
+			bind:this={canvasEl}
+			aria-label={i18n.t("game.map.aria_label", {
+				count: String(store?.report?.planets.length ?? 0),
+			})}
+		></canvas>
 		{#if store !== undefined && store.status === "ready"}
 			<MapTogglesControl {store} />
 		{/if}
diff --git a/ui/frontend/src/lib/header/account-menu.svelte b/ui/frontend/src/lib/header/account-menu.svelte
index b5173d4..576b18b 100644
--- a/ui/frontend/src/lib/header/account-menu.svelte
+++ b/ui/frontend/src/lib/header/account-menu.svelte
@@ -15,6 +15,7 @@ Sessions and Theme) take over.
 	} from "$lib/i18n/index.svelte";
 	import { session } from "$lib/session-store.svelte";
 	import { theme, type ThemeChoice } from "$lib/theme/theme.svelte";
+	import { restoreFocus } from "$lib/a11y/restore-focus";
 
 	const THEME_CHOICES: ReadonlyArray<{ id: ThemeChoice; key: TranslationKey }> = [
 		{ id: "system", key: "game.shell.menu.theme_system" },
@@ -79,7 +80,12 @@ Sessions and Theme) take over.
 		⚙
 	</button>
 	{#if open}
-		<div class="surface" role="menu" data-testid="account-menu-list">
+		<div
+			class="surface"
+			role="menu"
+			data-testid="account-menu-list"
+			use:restoreFocus
+		>
 			<button type="button" role="menuitem" data-testid="account-menu-settings" disabled>
 				{i18n.t("game.shell.menu.settings")}
 			</button>
diff --git a/ui/frontend/src/lib/header/turn-navigator.svelte b/ui/frontend/src/lib/header/turn-navigator.svelte
index 6381eaa..6a85e20 100644
--- a/ui/frontend/src/lib/header/turn-navigator.svelte
+++ b/ui/frontend/src/lib/header/turn-navigator.svelte
@@ -17,6 +17,7 @@ Selecting a row calls `gameState.viewTurn(N)`; the row that matches
 <script lang="ts">
 	import { getContext, onMount } from "svelte";
 	import { i18n } from "$lib/i18n/index.svelte";
+	import { restoreFocus } from "$lib/a11y/restore-focus";
 	import {
 		GAME_STATE_CONTEXT_KEY,
 		type GameStateStore,
@@ -139,7 +140,12 @@ Selecting a row calls `gameState.viewTurn(N)`; the row that matches
 		→
 	</button>
 	{#if open}
-		<div class="surface" role="menu" data-testid="turn-navigator-list">
+		<div
+			class="surface"
+			role="menu"
+			data-testid="turn-navigator-list"
+			use:restoreFocus
+		>
 			{#each turns as turn (turn)}
 				<button
 					type="button"
diff --git a/ui/frontend/src/lib/header/view-menu.svelte b/ui/frontend/src/lib/header/view-menu.svelte
index 3eaaf76..8b4115e 100644
--- a/ui/frontend/src/lib/header/view-menu.svelte
+++ b/ui/frontend/src/lib/header/view-menu.svelte
@@ -16,6 +16,7 @@ polishes microcopy.
 	import { goto } from "$app/navigation";
 	import { i18n, type TranslationKey } from "$lib/i18n/index.svelte";
 	import { mailStore } from "$lib/mail-store.svelte";
+	import { restoreFocus } from "$lib/a11y/restore-focus";
 
 	type Props = { gameId: string };
 	let { gameId }: Props = $props();
@@ -81,7 +82,12 @@ polishes microcopy.
 		<span class="icon-hamburger" aria-hidden="true">☰</span>
 	</button>
 	{#if open}
-		<div class="surface" role="menu" data-testid="view-menu-list">
+		<div
+			class="surface"
+			role="menu"
+			data-testid="view-menu-list"
+			use:restoreFocus
+		>
 			<button
 				type="button"
 				role="menuitem"
diff --git a/ui/frontend/src/lib/i18n/locales/en.ts b/ui/frontend/src/lib/i18n/locales/en.ts
index 65cfcb9..915209d 100644
--- a/ui/frontend/src/lib/i18n/locales/en.ts
+++ b/ui/frontend/src/lib/i18n/locales/en.ts
@@ -8,6 +8,7 @@ const en = {
 	"common.language": "language",
 	"common.loading": "loading…",
 	"common.dismiss": "dismiss",
+	"common.skip_to_content": "skip to main content",
 	"common.browser_not_supported_title": "browser not supported",
 	"common.browser_not_supported_body":
 		"Galaxy requires Ed25519 in WebCrypto. See supported browsers.",
@@ -117,6 +118,8 @@ const en = {
 	"game.shell.history.current_badge": "current",
 	"game.view.map": "map",
 	"game.map.toggles.open": "open map visibility menu",
+	"game.map.aria_label":
+		"galaxy map ({count} planets) — a visual overview; planet, ship-group and route details are available in the sidebar inspector and the tables view",
 	"game.map.toggles.close": "close map visibility menu",
 	"game.map.toggles.section.objects": "Objects",
 	"game.map.toggles.section.planets": "Planets",
diff --git a/ui/frontend/src/lib/i18n/locales/ru.ts b/ui/frontend/src/lib/i18n/locales/ru.ts
index b774a7b..ab394a2 100644
--- a/ui/frontend/src/lib/i18n/locales/ru.ts
+++ b/ui/frontend/src/lib/i18n/locales/ru.ts
@@ -9,6 +9,7 @@ const ru: Record<keyof typeof en, string> = {
 	"common.language": "язык",
 	"common.loading": "загрузка…",
 	"common.dismiss": "закрыть",
+	"common.skip_to_content": "к основному содержимому",
 	"common.browser_not_supported_title": "браузер не поддерживается",
 	"common.browser_not_supported_body":
 		"Galaxy требует поддержки Ed25519 в WebCrypto. См. список поддерживаемых браузеров.",
@@ -118,6 +119,8 @@ const ru: Record<keyof typeof en, string> = {
 	"game.shell.history.current_badge": "текущий",
 	"game.view.map": "карта",
 	"game.map.toggles.open": "открыть меню видимости карты",
+	"game.map.aria_label":
+		"карта галактики ({count} планет) — визуальный обзор; детали планет, групп кораблей и маршрутов доступны в инспекторе сайдбара и в таблицах",
 	"game.map.toggles.close": "закрыть меню видимости карты",
 	"game.map.toggles.section.objects": "Объекты",
 	"game.map.toggles.section.planets": "Планеты",
diff --git a/ui/frontend/src/lib/sidebar/bottom-tabs.svelte b/ui/frontend/src/lib/sidebar/bottom-tabs.svelte
index 1a1e3f5..8c083b1 100644
--- a/ui/frontend/src/lib/sidebar/bottom-tabs.svelte
+++ b/ui/frontend/src/lib/sidebar/bottom-tabs.svelte
@@ -16,6 +16,7 @@ destinations beats the duplication.
 	import { onMount } from "svelte";
 	import { goto } from "$app/navigation";
 	import { i18n, type TranslationKey } from "$lib/i18n/index.svelte";
+	import { restoreFocus } from "$lib/a11y/restore-focus";
 	import type { MobileTool } from "./types";
 
 	type Props = {
@@ -131,7 +132,12 @@ destinations beats the duplication.
 		</button>
 	</div>
 	{#if moreOpen}
-		<div class="drawer" role="menu" data-testid="bottom-tabs-more-drawer">
+		<div
+			class="drawer"
+			role="menu"
+			data-testid="bottom-tabs-more-drawer"
+			use:restoreFocus
+		>
 			<button
 				type="button"
 				role="menuitem"
diff --git a/ui/frontend/src/lib/sidebar/sidebar.svelte b/ui/frontend/src/lib/sidebar/sidebar.svelte
index c67587a..3b3b3c3 100644
--- a/ui/frontend/src/lib/sidebar/sidebar.svelte
+++ b/ui/frontend/src/lib/sidebar/sidebar.svelte
@@ -91,7 +91,13 @@ through the binding without extra plumbing.
 			✕
 		</button>
 	</div>
-	<div class="content" data-testid="sidebar-content">
+	<div
+		class="content"
+		role="tabpanel"
+		id="sidebar-panel"
+		aria-labelledby="sidebar-tab-{activeTab}"
+		data-testid="sidebar-content"
+	>
 		{#if activeTab === "calculator"}
 			<Calculator />
 		{:else if activeTab === "inspector"}
diff --git a/ui/frontend/src/lib/sidebar/tab-bar.svelte b/ui/frontend/src/lib/sidebar/tab-bar.svelte
index 5bb56f5..03a788c 100644
--- a/ui/frontend/src/lib/sidebar/tab-bar.svelte
+++ b/ui/frontend/src/lib/sidebar/tab-bar.svelte
@@ -29,17 +29,60 @@ flips it on.
 	const tabs = $derived(
 		hideOrder ? allTabs.filter((t) => t.id !== "order") : allTabs,
 	);
+
+	let tablistEl: HTMLDivElement | undefined = $state();
+
+	// WAI-ARIA tabs keyboard pattern: arrows move between tabs (with
+	// wrap-around), Home/End jump to the ends. Activation is automatic —
+	// moving focus also selects the tab — and focus follows to the
+	// newly-active tab button.
+	function onKeydown(event: KeyboardEvent, index: number): void {
+		const ids = tabs.map((t) => t.id);
+		let next = index;
+		switch (event.key) {
+			case "ArrowRight":
+			case "ArrowDown":
+				next = (index + 1) % ids.length;
+				break;
+			case "ArrowLeft":
+			case "ArrowUp":
+				next = (index - 1 + ids.length) % ids.length;
+				break;
+			case "Home":
+				next = 0;
+				break;
+			case "End":
+				next = ids.length - 1;
+				break;
+			default:
+				return;
+		}
+		event.preventDefault();
+		onSelect(ids[next]);
+		tablistEl
+			?.querySelector<HTMLElement>(`[data-testid="sidebar-tab-${ids[next]}"]`)
+			?.focus();
+	}
 </script>
 
-<div class="tab-bar" role="tablist" data-testid="sidebar-tab-bar">
-	{#each tabs as tab (tab.id)}
+<div
+	class="tab-bar"
+	role="tablist"
+	data-testid="sidebar-tab-bar"
+	bind:this={tablistEl}
+>
+	{#each tabs as tab, i (tab.id)}
 		<button
 			type="button"
 			role="tab"
+			id="sidebar-tab-{tab.id}"
 			data-testid="sidebar-tab-{tab.id}"
 			aria-selected={tab.id === activeTab}
+			aria-controls="sidebar-panel"
+			tabindex={tab.id === activeTab ? 0 : -1}
 			class:active={tab.id === activeTab}
 			onclick={() => onSelect(tab.id)}
+			onkeydown={(e) => onKeydown(e, i)}
 		>
 			{i18n.t(tab.key)}
 		</button>
diff --git a/ui/frontend/src/lib/theme/base.css b/ui/frontend/src/lib/theme/base.css
index fe31674..44e5fb4 100644
--- a/ui/frontend/src/lib/theme/base.css
+++ b/ui/frontend/src/lib/theme/base.css
@@ -27,3 +27,41 @@ body {
 ::selection {
 	background: var(--color-accent-subtle);
 }
+
+/*
+ * Visually-hidden content that stays available to assistive tech. Use
+ * for labels/announcements a sighted user gets from layout or icons.
+ */
+.sr-only {
+	position: absolute;
+	width: 1px;
+	height: 1px;
+	padding: 0;
+	margin: -1px;
+	overflow: hidden;
+	clip: rect(0, 0, 0, 0);
+	white-space: nowrap;
+	border: 0;
+}
+
+/*
+ * Skip link: visually hidden until focused, then slides into the
+ * top-left so a keyboard user can jump straight to the main content.
+ * Each layout renders one as its first focusable element, targeting a
+ * `tabindex="-1"` main region.
+ */
+.skip-link {
+	position: absolute;
+	left: var(--space-2);
+	top: -4rem;
+	z-index: 100;
+	padding: var(--space-2) var(--space-3);
+	background: var(--color-surface-overlay);
+	color: var(--color-text);
+	border: 1px solid var(--color-border);
+	border-radius: var(--radius-sm);
+	transition: top 120ms ease;
+}
+.skip-link:focus-visible {
+	top: var(--space-2);
+}
diff --git a/ui/frontend/src/routes/games/[id]/+layout.svelte b/ui/frontend/src/routes/games/[id]/+layout.svelte
index 591ab86..c2ad782 100644
--- a/ui/frontend/src/routes/games/[id]/+layout.svelte
+++ b/ui/frontend/src/routes/games/[id]/+layout.svelte
@@ -46,6 +46,7 @@ fresh.
 	import { onDestroy, onMount, setContext, untrack } from "svelte";
 	import { goto } from "$app/navigation";
 	import { page } from "$app/state";
+	import { i18n } from "$lib/i18n/index.svelte";
 	import Header from "$lib/header/header.svelte";
 	import HistoryBanner from "$lib/header/history-banner.svelte";
 	import Sidebar from "$lib/sidebar/sidebar.svelte";
@@ -528,6 +529,9 @@ fresh.
 </script>
 
 <div class="game-shell" data-testid="game-shell">
+	<a class="skip-link" href="#active-view-host">
+		{i18n.t("common.skip_to_content")}
+	</a>
 	<Header
 		{gameId}
 		{sidebarOpen}
@@ -535,7 +539,12 @@ fresh.
 	/>
 	<HistoryBanner />
 	<div class="body">
-		<main class="active-view-host" data-testid="active-view-host">
+		<main
+			class="active-view-host"
+			id="active-view-host"
+			tabindex="-1"
+			data-testid="active-view-host"
+		>
 			{#if effectiveTool === "calc"}
 				<Calculator />
 			{:else if effectiveTool === "order"}
diff --git a/ui/frontend/src/routes/lobby/+page.svelte b/ui/frontend/src/routes/lobby/+page.svelte
index 35f198f..77cd66d 100644
--- a/ui/frontend/src/routes/lobby/+page.svelte
+++ b/ui/frontend/src/routes/lobby/+page.svelte
@@ -265,7 +265,8 @@
 	});
 </script>
 
-<main>
+<a class="skip-link" href="#main-content">{i18n.t("common.skip_to_content")}</a>
+<main id="main-content" tabindex="-1">
 	<header>
 		<h1>{i18n.t("lobby.title")}</h1>
 		<p>
@@ -297,7 +298,7 @@
 	<section data-testid="lobby-my-games-section">
 		<h2>{i18n.t("lobby.section.my_games")}</h2>
 		{#if listsLoading}
-			<p>{i18n.t("lobby.list_loading")}</p>
+			<p role="status">{i18n.t("lobby.list_loading")}</p>
 		{:else if myGames.length === 0}
 			<p data-testid="lobby-my-games-empty">{i18n.t("lobby.my_games.empty")}</p>
 		{:else}
@@ -323,7 +324,7 @@
 	<section data-testid="lobby-invitations-section">
 		<h2>{i18n.t("lobby.section.invitations")}</h2>
 		{#if listsLoading}
-			<p>{i18n.t("lobby.list_loading")}</p>
+			<p role="status">{i18n.t("lobby.list_loading")}</p>
 		{:else if invitations.length === 0}
 			<p data-testid="lobby-invitations-empty">{i18n.t("lobby.invitations.empty")}</p>
 		{:else}
@@ -357,7 +358,7 @@
 	<section data-testid="lobby-applications-section">
 		<h2>{i18n.t("lobby.section.applications")}</h2>
 		{#if listsLoading}
-			<p>{i18n.t("lobby.list_loading")}</p>
+			<p role="status">{i18n.t("lobby.list_loading")}</p>
 		{:else if applications.length === 0}
 			<p data-testid="lobby-applications-empty">{i18n.t("lobby.applications.empty")}</p>
 		{:else}
@@ -416,7 +417,7 @@
 	<section data-testid="lobby-public-games-section">
 		<h2>{i18n.t("lobby.section.public_games")}</h2>
 		{#if listsLoading}
-			<p>{i18n.t("lobby.list_loading")}</p>
+			<p role="status">{i18n.t("lobby.list_loading")}</p>
 		{:else if publicGames.length === 0}
 			<p data-testid="lobby-public-games-empty">{i18n.t("lobby.public_games.empty")}</p>
 		{:else}
diff --git a/ui/frontend/src/routes/lobby/create/+page.svelte b/ui/frontend/src/routes/lobby/create/+page.svelte
index 9b169d1..0aa13d0 100644
--- a/ui/frontend/src/routes/lobby/create/+page.svelte
+++ b/ui/frontend/src/routes/lobby/create/+page.svelte
@@ -125,7 +125,8 @@
 	});
 </script>
 
-<main>
+<a class="skip-link" href="#main-content">{i18n.t("common.skip_to_content")}</a>
+<main id="main-content" tabindex="-1">
 	<h1>{i18n.t("lobby.create.title")}</h1>
 	{#if configError !== null}
 		<p role="alert" data-testid="lobby-create-config-error">{configError}</p>
diff --git a/ui/frontend/src/routes/login/+page.svelte b/ui/frontend/src/routes/login/+page.svelte
index 482c5b5..23bacd3 100644
--- a/ui/frontend/src/routes/login/+page.svelte
+++ b/ui/frontend/src/routes/login/+page.svelte
@@ -133,7 +133,8 @@
 	}
 </script>
 
-<main>
+<a class="skip-link" href="#main-content">{i18n.t("common.skip_to_content")}</a>
+<main id="main-content" tabindex="-1">
 	<header>
 		<h1>{i18n.t("login.title")}</h1>
 		<div class="language-picker">
@@ -166,7 +167,7 @@
 					stroke-width="1.5"
 				/>
 			</svg>
-			<label class="visually-hidden" for="login-language-select">
+			<label class="sr-only" for="login-language-select">
 				{i18n.t("common.language")}
 			</label>
 			<select
@@ -303,18 +304,6 @@
 		padding: 0.25rem 0.5rem;
 	}
 
-	.visually-hidden {
-		position: absolute;
-		width: 1px;
-		height: 1px;
-		padding: 0;
-		margin: -1px;
-		overflow: hidden;
-		clip: rect(0, 0, 0, 0);
-		white-space: nowrap;
-		border: 0;
-	}
-
 	form {
 		display: flex;
 		flex-direction: column;
diff --git a/ui/frontend/tests/e2e/a11y-axe.spec.ts b/ui/frontend/tests/e2e/a11y-axe.spec.ts
new file mode 100644
index 0000000..cf1b51f
--- /dev/null
+++ b/ui/frontend/tests/e2e/a11y-axe.spec.ts
@@ -0,0 +1,86 @@
+// F2 — automated WCAG 2.2 AA scans with axe-core across every
+// top-level view. Runs only on chromium-desktop (axe's colour-contrast
+// and computed-role checks need one real engine; repeating across the
+// webkit/mobile projects adds cost without new signal).
+//
+// Auth is bootstrapped through `/__debug/store` exactly as the
+// game-shell specs do; the in-game layout tolerates a missing gateway
+// (ECONNREFUSED) and still renders the chrome + view shells, which is
+// what the structural a11y scan needs.
+
+import AxeBuilder from "@axe-core/playwright";
+import { expect, test, type Page } from "@playwright/test";
+
+const SESSION_ID = "f2-a11y-axe-session";
+// A real UUID — the layout's auto-sync calls `uuidToHiLo` on it.
+const GAME_ID = "10101010-1010-1010-1010-101010101010";
+
+const WCAG_TAGS = ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa"];
+
+async function authenticate(page: Page): Promise<void> {
+	await page.goto("/__debug/store");
+	await expect(page.getByTestId("debug-store-ready")).toBeVisible();
+	await page.waitForFunction(() => window.__galaxyDebug?.ready === true);
+	await page.evaluate(() => window.__galaxyDebug!.clearSession());
+	await page.evaluate(
+		(id) => window.__galaxyDebug!.setDeviceSessionId(id),
+		SESSION_ID,
+	);
+}
+
+async function expectNoViolations(page: Page): Promise<void> {
+	const results = await new AxeBuilder({ page }).withTags(WCAG_TAGS).analyze();
+	// Surface the rule ids in the assertion message for a fast triage.
+	expect(
+		results.violations,
+		results.violations.map((v) => `${v.id} (${v.nodes.length})`).join(", "),
+	).toEqual([]);
+}
+
+test.describe("axe WCAG 2.2 AA", () => {
+	test.beforeEach(({}, testInfo) => {
+		test.skip(
+			testInfo.project.name !== "chromium-desktop",
+			"axe scan runs once, on chromium-desktop",
+		);
+	});
+
+	test("login", async ({ page }) => {
+		await page.goto("/login");
+		await expect(page.locator("#main-content")).toBeVisible();
+		await expectNoViolations(page);
+	});
+
+	test("lobby", async ({ page }) => {
+		await authenticate(page);
+		await page.goto("/lobby");
+		await expect(page.locator("#main-content")).toBeVisible();
+		await expectNoViolations(page);
+	});
+
+	test("lobby create", async ({ page }) => {
+		await authenticate(page);
+		await page.goto("/lobby/create");
+		await expect(page.locator("#main-content")).toBeVisible();
+		await expectNoViolations(page);
+	});
+
+	const inGameViews: Array<[string, string]> = [
+		["map", "active-view-map"],
+		["report", "active-view-report"],
+		["mail", "active-view-mail"],
+		["battle", "active-view-battle"],
+		["designer/science", "active-view-designer-science"],
+		["table/planets", "active-view-table"],
+	];
+
+	for (const [path, testId] of inGameViews) {
+		test(`in-game: ${path}`, async ({ page }) => {
+			await authenticate(page);
+			await page.goto(`/games/${GAME_ID}/${path}`);
+			await expect(page.getByTestId("game-shell")).toBeVisible();
+			await expect(page.getByTestId(testId)).toBeVisible();
+			await expectNoViolations(page);
+		});
+	}
+});
diff --git a/ui/frontend/tests/e2e/a11y-keyboard.spec.ts b/ui/frontend/tests/e2e/a11y-keyboard.spec.ts
new file mode 100644
index 0000000..084f82e
--- /dev/null
+++ b/ui/frontend/tests/e2e/a11y-keyboard.spec.ts
@@ -0,0 +1,66 @@
+// F2 — keyboard-only navigation coverage for the in-game shell.
+// Runs on chromium-desktop (a stable ≥1024px viewport where the sidebar
+// is visible); the behaviours under test are engine-independent.
+
+import { expect, test, type Page } from "@playwright/test";
+
+const SESSION_ID = "f2-a11y-keyboard-session";
+const GAME_ID = "10101010-1010-1010-1010-101010101010";
+
+async function bootShell(page: Page): Promise<void> {
+	await page.goto("/__debug/store");
+	await expect(page.getByTestId("debug-store-ready")).toBeVisible();
+	await page.waitForFunction(() => window.__galaxyDebug?.ready === true);
+	await page.evaluate(() => window.__galaxyDebug!.clearSession());
+	await page.evaluate(
+		(id) => window.__galaxyDebug!.setDeviceSessionId(id),
+		SESSION_ID,
+	);
+	await page.goto(`/games/${GAME_ID}/map`);
+	await expect(page.getByTestId("game-shell")).toBeVisible();
+	await expect(page.getByTestId("active-view-map")).toBeVisible();
+}
+
+test.describe("keyboard navigation", () => {
+	test.beforeEach(({}, testInfo) => {
+		test.skip(
+			testInfo.project.name !== "chromium-desktop",
+			"keyboard specs run on chromium-desktop",
+		);
+	});
+
+	test("skip link is the first focusable and jumps to main content", async ({
+		page,
+	}) => {
+		await bootShell(page);
+		await page.keyboard.press("Tab");
+		await expect(page.locator(".skip-link")).toBeFocused();
+		await page.keyboard.press("Enter");
+		await expect(page.locator("#active-view-host")).toBeFocused();
+	});
+
+	test("Escape closes the account menu and returns focus to its trigger", async ({
+		page,
+	}) => {
+		await bootShell(page);
+		await page.getByTestId("account-menu-trigger").click();
+		await expect(page.getByTestId("account-menu-list")).toBeVisible();
+		// Move focus into the menu, then dismiss with Escape.
+		await page.getByTestId("account-menu-theme-select").focus();
+		await page.keyboard.press("Escape");
+		await expect(page.getByTestId("account-menu-list")).toBeHidden();
+		await expect(page.getByTestId("account-menu-trigger")).toBeFocused();
+	});
+
+	test("sidebar tabs move with the arrow keys (roving)", async ({ page }) => {
+		await bootShell(page);
+		const calculator = page.getByTestId("sidebar-tab-calculator");
+		const inspector = page.getByTestId("sidebar-tab-inspector");
+		await calculator.click();
+		await expect(calculator).toHaveAttribute("aria-selected", "true");
+		await calculator.focus();
+		await page.keyboard.press("ArrowRight");
+		await expect(inspector).toBeFocused();
+		await expect(inspector).toHaveAttribute("aria-selected", "true");
+	});
+});
diff --git a/ui/pnpm-lock.yaml b/ui/pnpm-lock.yaml
index 7ea412a..f78bbde 100644
--- a/ui/pnpm-lock.yaml
+++ b/ui/pnpm-lock.yaml
@@ -21,6 +21,9 @@ importers:
         specifier: ^8.18.1
         version: 8.18.1
     devDependencies:
+      '@axe-core/playwright':
+        specifier: 4.11.3
+        version: 4.11.3(playwright-core@1.59.1)
       '@bufbuild/protobuf':
         specifier: ^2.12.0
         version: 2.12.0
@@ -90,6 +93,11 @@ packages:
   '@asamuzakjp/css-color@3.2.0':
     resolution: {integrity: sha512-K1A6z8tS3XsmCMM86xoWdn7Fkdn9m6RSVtocUrJYIwZnFVkng/PvkEoWtOWmP+Scc6saYWHWZYbndEEXxl24jw==}
 
+  '@axe-core/playwright@4.11.3':
+    resolution: {integrity: sha512-h/kfksv4F0cVIDlKpT4700OehdRgpvuVskuQ2nb7/JmtWUXpe9ftHAPtwyXGvVSsa6SJ64A9ER7Zrzc/sIvC4w==}
+    peerDependencies:
+      playwright-core: '>= 1.0.0'
+
   '@babel/code-frame@7.29.0':
     resolution: {integrity: sha512-9NhCeYjq9+3uxgdtp20LSiJXJvN0FeCtNGpJxuMFZ1Kv3cWUNb6DOhJwUvcVCzKGR66cw4njwM6hrJLqgOwbcw==}
     engines: {node: '>=6.9.0'}
@@ -462,6 +470,10 @@ packages:
   asynckit@0.4.0:
     resolution: {integrity: sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==}
 
+  axe-core@4.11.4:
+    resolution: {integrity: sha512-KunSNx+TVpkAw/6ULfhnx+HWRecjqZGTOyquAoWHYLRSdK1tB5Ihce1ZW+UY3fj33bYAFWPu7W/GRSmmrCGuxA==}
+    engines: {node: '>=4'}
+
   axobject-query@4.1.0:
     resolution: {integrity: sha512-qIj0G9wZbMGNLjLmg1PT6v2mE9AH2zlnADJD/2tC6E00hgmhUOfEB6greHPAfLRSufHqROIUTkw6E+M3lH0PTQ==}
     engines: {node: '>= 0.4'}
@@ -1152,6 +1164,11 @@ snapshots:
       '@csstools/css-tokenizer': 3.0.4
       lru-cache: 10.4.3
 
+  '@axe-core/playwright@4.11.3(playwright-core@1.59.1)':
+    dependencies:
+      axe-core: 4.11.4
+      playwright-core: 1.59.1
+
   '@babel/code-frame@7.29.0':
     dependencies:
       '@babel/helper-validator-identifier': 7.28.5
@@ -1480,6 +1497,8 @@ snapshots:
 
   asynckit@0.4.0: {}
 
+  axe-core@4.11.4: {}
+
   axobject-query@4.1.0: {}
 
   call-bind-apply-helpers@1.0.2:
-- 
2.52.0


From e193f3ca888143c8e09a2b2531796a82f694d7ef Mon Sep 17 00:00:00 2001
From: Ilia Denisov <evilcart@gmail.com>
Date: Fri, 22 May 2026 08:36:17 +0200
Subject: [PATCH 2/3] feat(ui): default theme to system (follow OS light/dark)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Light has been signed off, so the theme store's default choice is now
`system` (it was `dark` during the incremental migration). This matches
the app.html pre-paint guard, which already resolved an unset choice via
prefers-color-scheme — removing the brief boot-time mismatch where the
store re-pinned dark. Users still pin light/dark via the account-menu
picker. Updates the store default + its test and the design-system /
finalize-plan docs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 ui/PLAN-finalize.md                       | 6 +++---
 ui/docs/design-system.md                  | 8 ++++----
 ui/frontend/src/lib/theme/theme.svelte.ts | 4 ++--
 ui/frontend/tests/theme.test.ts           | 9 +++++----
 4 files changed, 14 insertions(+), 13 deletions(-)

diff --git a/ui/PLAN-finalize.md b/ui/PLAN-finalize.md
index 251d640..2e1dfed 100644
--- a/ui/PLAN-finalize.md
+++ b/ui/PLAN-finalize.md
@@ -25,9 +25,9 @@ Merged to `development` via PR #26 (2026-05-22): a shared design-token
 system (`ui/frontend/src/lib/theme/`), light/dark theming with a picker
 and pre-paint guard, and the whole UI migrated onto the tokens.
 Documented literal exceptions: the battle-scene data-viz palette, overlay
-scrims, and directional/deliberate drop shadows. The default theme is
-dark; flipping it to `system` is an available follow-up. Tokens and
-conventions live in `ui/docs/design-system.md`.
+scrims, and directional/deliberate drop shadows. The default theme
+follows the OS (`system`); the account-menu picker pins light or dark.
+Tokens and conventions live in `ui/docs/design-system.md`.
 
 Goal: replace the ad-hoc per-component styling (inline hex colors like
 `#0a0e1a`, one-off spacing) with a shared design language so every view
diff --git a/ui/docs/design-system.md b/ui/docs/design-system.md
index 81b090a..736c743 100644
--- a/ui/docs/design-system.md
+++ b/ui/docs/design-system.md
@@ -72,7 +72,8 @@ the colour block in `tokens.css`.
   persists the choice, applies `data-theme`, and — while the choice is
   `system` — follows OS theme changes via `matchMedia`.
 - The account menu (`account-menu.svelte`) exposes the picker. The
-  default is `dark`; `system` follows the OS.
+  default is `system` (it follows the OS preference); `light` / `dark`
+  pin a theme.
 
 The `app.html` guard and the store deliberately duplicate the
 resolution logic (one runs before modules load, the other after) — keep
@@ -115,6 +116,5 @@ The only remaining literal colours are the documented exceptions above:
 the battle-scene data-viz palette, the overlay scrims, and the
 directional / deliberate drop shadows.
 
-The default theme is **dark** while light coherence is being verified
-across the migrated views; once the owner signs off on light, the
-default can flip to `system`.
+The default theme is **`system`** — it follows the OS light/dark
+preference; users can pin light or dark via the account-menu picker.
diff --git a/ui/frontend/src/lib/theme/theme.svelte.ts b/ui/frontend/src/lib/theme/theme.svelte.ts
index 7ce5a26..f9598ef 100644
--- a/ui/frontend/src/lib/theme/theme.svelte.ts
+++ b/ui/frontend/src/lib/theme/theme.svelte.ts
@@ -24,11 +24,11 @@ export const THEME_STORAGE_KEY = "galaxy-theme";
 const SYSTEM_LIGHT_QUERY = "(prefers-color-scheme: light)";
 
 function readStoredChoice(): ThemeChoice {
-	if (typeof localStorage === "undefined") return "dark";
+	if (typeof localStorage === "undefined") return "system";
 	const value = localStorage.getItem(THEME_STORAGE_KEY);
 	return value === "light" || value === "dark" || value === "system"
 		? value
-		: "dark";
+		: "system";
 }
 
 function systemTheme(): ResolvedTheme {
diff --git a/ui/frontend/tests/theme.test.ts b/ui/frontend/tests/theme.test.ts
index d963fe0..4eafc21 100644
--- a/ui/frontend/tests/theme.test.ts
+++ b/ui/frontend/tests/theme.test.ts
@@ -42,9 +42,10 @@ describe("theme store", () => {
 		vi.restoreAllMocks();
 	});
 
-	it("defaults to dark and applies it to the document", async () => {
+	it("defaults to system and applies the resolved theme", async () => {
 		const { theme } = await freshStore();
-		expect(theme.choice).toBe("dark");
+		expect(theme.choice).toBe("system");
+		// freshStore() leaves the OS at dark (prefersLight = false).
 		expect(theme.resolved).toBe("dark");
 		expect(document.documentElement.dataset.theme).toBe("dark");
 	});
@@ -80,9 +81,9 @@ describe("theme store", () => {
 		expect(document.documentElement.dataset.theme).toBe("light");
 	});
 
-	it("falls back to dark for an unrecognised stored value", async () => {
+	it("falls back to system for an unrecognised stored value", async () => {
 		localStorage.setItem(STORAGE_KEY, "neon");
 		const { theme } = await freshStore();
-		expect(theme.choice).toBe("dark");
+		expect(theme.choice).toBe("system");
 	});
 });
-- 
2.52.0


From 70f29733961dd9161b5a781d4a4fcd0c3835c3a5 Mon Sep 17 00:00:00 2001
From: Ilia Denisov <evilcart@gmail.com>
Date: Fri, 22 May 2026 08:40:38 +0200
Subject: [PATCH 3/3] fix(ui): darken light-theme danger to meet AA contrast
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

With the default theme now following the OS, Playwright renders the light
theme, where the previous light `--color-danger` (#c84d4d, ~3.9:1 on a
near-white surface) failed WCAG 1.4.3 on error text — caught by the axe
scan of the science designer's empty-name error. Darken light
`--color-danger` to #c0392b (~5.5:1 on white; white-on-danger fills stay
≥5:1). Dark theme unchanged.
---
 ui/frontend/src/lib/theme/tokens.css | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/ui/frontend/src/lib/theme/tokens.css b/ui/frontend/src/lib/theme/tokens.css
index 25c8a35..13fcdd3 100644
--- a/ui/frontend/src/lib/theme/tokens.css
+++ b/ui/frontend/src/lib/theme/tokens.css
@@ -121,9 +121,9 @@
 	--color-accent-contrast: #ffffff;
 	--color-accent-subtle: rgba(74, 99, 216, 0.1);
 
-	--color-danger: #c84d4d;
+	--color-danger: #c0392b;
 	--color-danger-contrast: #ffffff;
-	--color-danger-subtle: rgba(200, 77, 77, 0.1);
+	--color-danger-subtle: rgba(192, 57, 43, 0.1);
 
 	--color-success: #2f8f63;
 	--color-success-subtle: rgba(47, 143, 99, 0.12);
-- 
2.52.0