feat(ui): accessibility pass — WCAG 2.2 AA for login/lobby/shell (F2)

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/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();
+		},
+	};
+}

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();
+		},
+	};
+}

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>

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>

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}

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>

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"

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"

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",

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": "Планеты",

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"

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"}

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>

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);
+}