From 71892e729372cea73ad96a4523515e30a983ffef Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Sat, 25 Apr 2026 01:03:43 +0200
Subject: [PATCH 01/13] feat(tokens): add --color-parchment design token for
 warm example-block surfaces

Adds --c-parchment (#faf8f1 light / #041828 dark) to :root and both
dark-mode blocks, exposed as --color-parchment via @theme inline.
Prerequisite for replacing bg-[#FAF8F1] raw-hex in RichtlinienRuleCard
and TranscribeDragDemo.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 frontend/src/routes/layout.css | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/frontend/src/routes/layout.css b/frontend/src/routes/layout.css
index 0f93fa13..ef368838 100644
--- a/frontend/src/routes/layout.css
+++ b/frontend/src/routes/layout.css
@@ -66,6 +66,9 @@
 	/* Focus ring — keyboard focus indicator, mode-aware (navy in light, mint in dark) */
 	--color-focus-ring: var(--c-focus-ring);
 
+	/* Parchment — warm background for code/example blocks inside cards */
+	--color-parchment: var(--c-parchment);
+
 	/* Danger — destructive action color */
 	--color-danger: var(--c-danger);
 	--color-danger-fg: var(--c-danger-fg);
@@ -122,6 +125,9 @@
 	--c-danger: #c0392b;
 	--c-danger-fg: #ffffff;
 
+	/* Parchment — warm near-white for example blocks (light mode: cream #FAF8F1) */
+	--c-parchment: #faf8f1;
+
 	/* Tag color tokens — decorative dot colors on tag chips */
 	--c-tag-sage: #5a8a6a;
 	--c-tag-sienna: #a0522d;
@@ -203,6 +209,9 @@
 		--c-danger: #e55347;
 		--c-danger-fg: #ffffff;
 
+		/* Parchment — subtle surface shift for example blocks on dark navy */
+		--c-parchment: #041828;
+
 		/* Tag color tokens — lighter for visibility on dark backgrounds */
 		--c-tag-sage: #7abf8a;
 		--c-tag-sienna: #cc7050;
@@ -267,6 +276,9 @@
 	--c-danger: #e55347;
 	--c-danger-fg: #ffffff;
 
+	/* Parchment — subtle surface shift for example blocks on dark navy */
+	--c-parchment: #041828;
+
 	/* Tag color tokens — lighter for visibility on dark backgrounds */
 	--c-tag-sage: #7abf8a;
 	--c-tag-sienna: #cc7050;
-- 
2.49.1


From 82af3f85a2bad3b4a02a0c2532ed58cb8e2befc6 Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Sat, 25 Apr 2026 01:06:52 +0200
Subject: [PATCH 02/13] fix(HelpPopover): role=region, 44px touch target,
 counter-based ID
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- role="tooltip" → role="region" + aria-label={label}: tooltip semantics
  are wrong for a click-triggered panel (Nora/Sara)
- expand button to 44×44px with inner visual <span>: WCAG 2.5.8 touch
  target for 60+ transcriber audience (Sara/Leonie)
- replace Math.random() with module-level counter: SSR/hydration mismatch
  when server and client generate different IDs (Felix)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../src/lib/components/HelpPopover.svelte     | 25 +++++++++++++---
 .../lib/components/HelpPopover.svelte.spec.ts | 29 ++++++++++++++-----
 2 files changed, 42 insertions(+), 12 deletions(-)

diff --git a/frontend/src/lib/components/HelpPopover.svelte b/frontend/src/lib/components/HelpPopover.svelte
index e1d118ca..f6ff984f 100644
--- a/frontend/src/lib/components/HelpPopover.svelte
+++ b/frontend/src/lib/components/HelpPopover.svelte
@@ -1,3 +1,10 @@
+<script module>
+// Module-level counter produces stable, predictable IDs across SSR + hydration.
+// Math.random() would generate different values server-side vs client-side,
+// causing a hydration mismatch on first render.
+let _counter = 0;
+</script>
+
 <script lang="ts">
 import type { Snippet } from 'svelte';
 
@@ -11,8 +18,9 @@ type Props = {
 
 let { label, placement = 'bottom', children }: Props = $props();
 
+const popoverId = `help-popover-${_counter++}`;
+
 let open = $state(false);
-const popoverId = `help-popover-${Math.random().toString(36).slice(2)}`;
 let triggerEl: HTMLButtonElement | null = $state(null);
 
 function toggle() {
@@ -58,6 +66,10 @@ const placementClass: Record<Placement, string> = {
 </script>
 
 <div class="relative inline-block">
+	<!--
+		Outer button is 44×44px for WCAG 2.5.8 touch-target compliance (our transcriber
+		audience is 60+). The inner <span> carries the visual 20×20px circle.
+	-->
 	<button
 		bind:this={triggerEl}
 		type="button"
@@ -65,15 +77,20 @@ const placementClass: Record<Placement, string> = {
 		aria-expanded={open}
 		aria-controls={popoverId}
 		onclick={toggle}
-		class="flex h-5 w-5 items-center justify-center rounded-full border border-line bg-muted font-sans text-[10px] font-bold text-ink-3 transition-colors hover:border-brand-navy hover:text-brand-navy"
+		class="flex h-[44px] w-[44px] items-center justify-center"
 	>
-		?
+		<span
+			class="flex h-5 w-5 items-center justify-center rounded-full border border-line bg-muted font-sans text-[10px] font-bold text-ink-3 transition-colors hover:border-brand-navy hover:text-brand-navy"
+		>
+			?
+		</span>
 	</button>
 
 	{#if open}
 		<div
 			id={popoverId}
-			role="tooltip"
+			role="region"
+			aria-label={label}
 			class="absolute z-50 w-64 rounded-sm border border-line bg-white p-3 font-sans text-sm text-ink shadow-md {placementClass[placement]}"
 		>
 			{#if children}
diff --git a/frontend/src/lib/components/HelpPopover.svelte.spec.ts b/frontend/src/lib/components/HelpPopover.svelte.spec.ts
index b2e5ae16..b22d1ab9 100644
--- a/frontend/src/lib/components/HelpPopover.svelte.spec.ts
+++ b/frontend/src/lib/components/HelpPopover.svelte.spec.ts
@@ -20,7 +20,7 @@ describe('HelpPopover — initial state', () => {
 		renderPopover();
 		const btn = page.getByRole('button', { name: /Help/ });
 		await expect.element(btn).toHaveAttribute('aria-expanded', 'false');
-		expect(document.querySelector('[role="tooltip"]')).toBeNull();
+		expect(document.querySelector('[role="region"]')).toBeNull();
 	});
 });
 
@@ -30,37 +30,37 @@ describe('HelpPopover — open / close interactions', () => {
 		await page.getByRole('button', { name: /Help/ }).click();
 		const btn = page.getByRole('button', { name: /Help/ });
 		await expect.element(btn).toHaveAttribute('aria-expanded', 'true');
-		expect(document.querySelector('[role="tooltip"]')).not.toBeNull();
+		expect(document.querySelector('[role="region"]')).not.toBeNull();
 	});
 
 	it('closes on Esc key', async () => {
 		renderPopover();
 		await page.getByRole('button', { name: /Help/ }).click();
-		expect(document.querySelector('[role="tooltip"]')).not.toBeNull();
+		expect(document.querySelector('[role="region"]')).not.toBeNull();
 
 		document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
-		await vi.waitFor(() => expect(document.querySelector('[role="tooltip"]')).toBeNull());
+		await vi.waitFor(() => expect(document.querySelector('[role="region"]')).toBeNull());
 	});
 
 	it('closes on outside click', async () => {
 		renderPopover();
 		await page.getByRole('button', { name: /Help/ }).click();
-		expect(document.querySelector('[role="tooltip"]')).not.toBeNull();
+		expect(document.querySelector('[role="region"]')).not.toBeNull();
 
 		document.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }));
-		await vi.waitFor(() => expect(document.querySelector('[role="tooltip"]')).toBeNull());
+		await vi.waitFor(() => expect(document.querySelector('[role="region"]')).toBeNull());
 	});
 
 	it('opens on Enter key (button is keyboard-reachable, Enter fires click)', async () => {
 		renderPopover();
 		await page.getByRole('button', { name: /Help/ }).click();
-		expect(document.querySelector('[role="tooltip"]')).not.toBeNull();
+		expect(document.querySelector('[role="region"]')).not.toBeNull();
 	});
 
 	it('opens on Space key (button is keyboard-reachable, Space fires click)', async () => {
 		renderPopover();
 		await page.getByRole('button', { name: /Help/ }).click();
-		expect(document.querySelector('[role="tooltip"]')).not.toBeNull();
+		expect(document.querySelector('[role="region"]')).not.toBeNull();
 	});
 });
 
@@ -74,4 +74,17 @@ describe('HelpPopover — aria wiring', () => {
 		const popover = document.getElementById(controls!);
 		expect(popover).not.toBeNull();
 	});
+
+	it('two renders produce different, predictable IDs (no Math.random — SSR safe)', async () => {
+		const { container: c1 } = render(HelpPopover, { props: { label: 'A' } });
+		const { container: c2 } = render(HelpPopover, { props: { label: 'B' } });
+		const id1 = c1.querySelector('button[aria-controls]')?.getAttribute('aria-controls');
+		const id2 = c2.querySelector('button[aria-controls]')?.getAttribute('aria-controls');
+		expect(id1).toBeTruthy();
+		expect(id2).toBeTruthy();
+		expect(id1).not.toBe(id2);
+		// IDs must be deterministic (counter-based), not random hex
+		expect(id1).toMatch(/^help-popover-\d+$/);
+		expect(id2).toMatch(/^help-popover-\d+$/);
+	});
 });
-- 
2.49.1


From bdd91aa165f7f727fb41839dfcec483dc8151760 Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Sat, 25 Apr 2026 01:16:00 +0200
Subject: [PATCH 03/13] fix(TranscribeDragDemo): reactive prefersReducedMotion
 + bg-parchment token

- Replace one-shot $derived(.matches) snapshot with $state + addEventListener
  so the static/animated branch reacts when the user toggles OS reduced-motion
  at runtime (Felix: non-reactive media query)
- Replace bg-[#FAF8F1] raw hex with bg-parchment design token so the SVG
  background remaps correctly in dark mode (Felix/Markus)

Also update TranscriptionPanelHeader.svelte.test.ts to expect role="region"
after the HelpPopover ARIA fix.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../lib/components/TranscribeDragDemo.svelte   | 18 +++++++++++++++---
 .../TranscriptionPanelHeader.svelte.test.ts    |  2 +-
 2 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/frontend/src/lib/components/TranscribeDragDemo.svelte b/frontend/src/lib/components/TranscribeDragDemo.svelte
index d2c5753f..c0fde0b2 100644
--- a/frontend/src/lib/components/TranscribeDragDemo.svelte
+++ b/frontend/src/lib/components/TranscribeDragDemo.svelte
@@ -1,7 +1,19 @@
 <script lang="ts">
-const prefersReducedMotion = $derived(
+// $derived from .matches is a one-shot snapshot — it doesn't react when the
+// user toggles the OS setting at runtime. Use $state + addEventListener instead.
+let prefersReducedMotion = $state(
 	typeof window !== 'undefined' && window.matchMedia('(prefers-reduced-motion: reduce)').matches
 );
+
+$effect(() => {
+	if (typeof window === 'undefined') return;
+	const mql = window.matchMedia('(prefers-reduced-motion: reduce)');
+	const handler = (e: MediaQueryListEvent) => {
+		prefersReducedMotion = e.matches;
+	};
+	mql.addEventListener('change', handler);
+	return () => mql.removeEventListener('change', handler);
+});
 </script>
 
 {#if prefersReducedMotion}
@@ -10,7 +22,7 @@ const prefersReducedMotion = $derived(
 		role="img"
 		aria-label="Eine gestrichelte Umrandung markiert eine Zeile Kurrentschrift auf dem Dokument."
 		viewBox="0 0 600 180"
-		class="border-brand-sand block w-full rounded-sm border bg-[#FAF8F1]"
+		class="border-brand-sand block w-full rounded-sm border bg-parchment"
 	>
 		<g
 			stroke="#2a2a2a"
@@ -61,7 +73,7 @@ const prefersReducedMotion = $derived(
 		role="img"
 		aria-label="Animation: Ein Cursor zieht einen gestrichelten Rahmen um eine Zeile Kurrentschrift. Beim Loslassen wird der Rahmen durchgehend und ein Häkchen erscheint."
 		viewBox="0 0 600 180"
-		class="border-brand-sand block w-full rounded-sm border bg-[#FAF8F1]"
+		class="border-brand-sand block w-full rounded-sm border bg-parchment"
 	>
 		<!-- Kurrent writing (static) -->
 		<g
diff --git a/frontend/src/lib/components/TranscriptionPanelHeader.svelte.test.ts b/frontend/src/lib/components/TranscriptionPanelHeader.svelte.test.ts
index 4084aba1..d60b5e60 100644
--- a/frontend/src/lib/components/TranscriptionPanelHeader.svelte.test.ts
+++ b/frontend/src/lib/components/TranscriptionPanelHeader.svelte.test.ts
@@ -177,6 +177,6 @@ describe('TranscriptionPanelHeader', () => {
 
 		const helpBtn = document.querySelector('button[aria-expanded]') as HTMLButtonElement;
 		helpBtn.dispatchEvent(new MouseEvent('click', { bubbles: true }));
-		await vi.waitFor(() => expect(document.querySelector('[role="tooltip"]')).not.toBeNull());
+		await vi.waitFor(() => expect(document.querySelector('[role="region"]')).not.toBeNull());
 	});
 });
-- 
2.49.1


From 77bd005df72c450709a1b033dcf5dfa726b5b622 Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Sat, 25 Apr 2026 01:17:06 +0200
Subject: [PATCH 04/13] =?UTF-8?q?fix(RichtlinienRuleCard):=20bg-[#FAF8F1]?=
 =?UTF-8?q?=20=E2=86=92=20bg-parchment=20design=20token?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Raw hex bypassed the token system and wouldn't remap in dark mode.
Now uses --color-parchment which has a proper dark-mode counterpart.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 frontend/src/lib/components/RichtlinienRuleCard.svelte | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/frontend/src/lib/components/RichtlinienRuleCard.svelte b/frontend/src/lib/components/RichtlinienRuleCard.svelte
index cbf9b163..1d9e8a7c 100644
--- a/frontend/src/lib/components/RichtlinienRuleCard.svelte
+++ b/frontend/src/lib/components/RichtlinienRuleCard.svelte
@@ -18,7 +18,7 @@ let { icon, title, body, beispielOutput, beispielLabel = 'Beispiel' }: Props = $
 	<p class="font-serif text-sm leading-relaxed text-ink-2">{body}</p>
 
 	{#if beispielOutput !== undefined}
-		<div class="border-brand-sand mt-4 rounded-sm border bg-[#FAF8F1] px-4 py-3">
+		<div class="border-brand-sand mt-4 rounded-sm border bg-parchment px-4 py-3">
 			<p class="font-sans text-xs font-semibold tracking-wider text-ink-3 uppercase">
 				{beispielLabel}
 			</p>
-- 
2.49.1


From 1715ceb53e3fee1441e02a47432b249945284d13 Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Sat, 25 Apr 2026 01:19:42 +0200
Subject: [PATCH 05/13] fix(TranscribeCoachEmptyState): Tailwind grid instead
 of inline styles; step aria-labels

- Replace style="grid-template-columns: 34px 1fr; align-items: start;"
  with Tailwind grid-cols-[34px_1fr] items-start (Felix: inline styles)
- Add aria-label="Schritt N von 3" on each <li> so screen readers announce
  step position when the numeric badge is aria-hidden (Nora/Sara)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../src/lib/components/TranscribeCoachEmptyState.svelte     | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/frontend/src/lib/components/TranscribeCoachEmptyState.svelte b/frontend/src/lib/components/TranscribeCoachEmptyState.svelte
index 8bb18705..26b31f8d 100644
--- a/frontend/src/lib/components/TranscribeCoachEmptyState.svelte
+++ b/frontend/src/lib/components/TranscribeCoachEmptyState.svelte
@@ -13,7 +13,7 @@ import TranscribeDragDemo from './TranscribeDragDemo.svelte';
 
 	<ol class="m-0 flex list-none flex-col gap-[18px] p-0">
 		<!-- Step 1 -->
-		<li class="grid gap-3.5" style="grid-template-columns: 34px 1fr; align-items: start;">
+		<li aria-label="Schritt 1 von 3" class="grid grid-cols-[34px_1fr] items-start gap-3.5">
 			<span
 				aria-hidden="true"
 				class="flex h-7 w-7 flex-shrink-0 items-center justify-center rounded-full bg-ink font-sans text-sm font-bold text-white"
@@ -27,7 +27,7 @@ import TranscribeDragDemo from './TranscribeDragDemo.svelte';
 		</li>
 
 		<!-- Step 2 -->
-		<li class="grid gap-3.5" style="grid-template-columns: 34px 1fr; align-items: start;">
+		<li aria-label="Schritt 2 von 3" class="grid grid-cols-[34px_1fr] items-start gap-3.5">
 			<span
 				aria-hidden="true"
 				class="flex h-7 w-7 flex-shrink-0 items-center justify-center rounded-full bg-ink font-sans text-sm font-bold text-white"
@@ -40,7 +40,7 @@ import TranscribeDragDemo from './TranscribeDragDemo.svelte';
 		</li>
 
 		<!-- Step 3 -->
-		<li class="grid gap-3.5" style="grid-template-columns: 34px 1fr; align-items: start;">
+		<li aria-label="Schritt 3 von 3" class="grid grid-cols-[34px_1fr] items-start gap-3.5">
 			<span
 				aria-hidden="true"
 				class="flex h-7 w-7 flex-shrink-0 items-center justify-center rounded-full bg-ink font-sans text-sm font-bold text-white"
-- 
2.49.1


From 0b1d67ca96d0c9890aaf630a03f8fb59d79979b2 Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Sat, 25 Apr 2026 01:21:29 +0200
Subject: [PATCH 06/13] =?UTF-8?q?fix(richtlinien):=20<main>=20landmark=20+?=
 =?UTF-8?q?=20closing=20card=20h2=20=E2=86=92=20h3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Wrap page content in <main> so AT users can jump to main content (Nora)
- Closing card "Fehlt eine Regel?" was <h2> after two existing <h2> siblings
  but styled like a card title, not a section label; downgrade to <h3> to
  fix the heading hierarchy (Sara/Leonie)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 frontend/src/routes/hilfe/transkription/+page.svelte | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/frontend/src/routes/hilfe/transkription/+page.svelte b/frontend/src/routes/hilfe/transkription/+page.svelte
index af42eb9c..61cdecc6 100644
--- a/frontend/src/routes/hilfe/transkription/+page.svelte
+++ b/frontend/src/routes/hilfe/transkription/+page.svelte
@@ -46,7 +46,7 @@ const klaerungChips = [
 	<title>{m.richtlinien_title()} — Familienarchiv</title>
 </svelte:head>
 
-<div class="mx-auto max-w-2xl px-4 py-10 font-serif">
+<main class="mx-auto max-w-2xl px-4 py-10 font-serif">
 	<!-- Title -->
 	<h1 class="mb-4 text-3xl font-bold text-ink">{m.richtlinien_title()}</h1>
 
@@ -102,10 +102,10 @@ const klaerungChips = [
 
 	<!-- Closing card -->
 	<div class="border-brand-sand rounded-sm border bg-white p-6 shadow-sm">
-		<h2 class="mb-2 font-serif text-lg font-bold text-ink">{m.richtlinien_closing_title()}</h2>
+		<h3 class="mb-2 font-serif text-lg font-bold text-ink">{m.richtlinien_closing_title()}</h3>
 		<p class="font-serif text-sm leading-relaxed text-ink-2">{m.richtlinien_closing_body()}</p>
 	</div>
-</div>
+</main>
 
 <style>
 @media print {
-- 
2.49.1


From d2cee2a5b401d6dc3c337d55b7c15e83fa3d0850 Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Sat, 25 Apr 2026 01:22:33 +0200
Subject: [PATCH 07/13] docs(richtlinien): document why prerender=true is
 auth-safe

handleAuth in hooks.server.ts is in the sequence() chain and redirects
unauthenticated users at runtime regardless of prerender. Adding a comment
so the next reader doesn't mistake this for a security hole. (Markus/Nora)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 frontend/src/routes/hilfe/transkription/+page.ts | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/frontend/src/routes/hilfe/transkription/+page.ts b/frontend/src/routes/hilfe/transkription/+page.ts
index 189f71e2..3bead06e 100644
--- a/frontend/src/routes/hilfe/transkription/+page.ts
+++ b/frontend/src/routes/hilfe/transkription/+page.ts
@@ -1 +1,6 @@
+// prerender = true is safe here: hooks.server.ts exports
+//   handle = sequence(userGroup, handleAuth, ...)
+// where handleAuth redirects all non-public paths to /login at runtime.
+// Prerendered HTML is served, but the browser still hits handleAuth on
+// every navigation — unauthenticated users are redirected before seeing content.
 export const prerender = true;
-- 
2.49.1


From 10768937ba213b11771e8e595440f5619e63971e Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Sat, 25 Apr 2026 01:23:54 +0200
Subject: [PATCH 08/13] chore(i18n): remove dead transcription_empty_draw_hint
 key

The key was orphaned when TranscriptionEditView's empty state was replaced
by TranscribeCoachEmptyState. Removed from de/en/es to avoid accumulating
unreferenced strings. (Felix)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 frontend/messages/de.json | 1 -
 frontend/messages/en.json | 1 -
 frontend/messages/es.json | 1 -
 3 files changed, 3 deletions(-)

diff --git a/frontend/messages/de.json b/frontend/messages/de.json
index 1b90d913..9824ccee 100644
--- a/frontend/messages/de.json
+++ b/frontend/messages/de.json
@@ -515,7 +515,6 @@
 	"scan_collapse": "Scan verkleinern",
 	"transcription_empty_title": "Noch keine Transkription",
 	"transcription_empty_desc": "Zeichne Bereiche auf dem Scan und tippe den Text ab, um eine Transkription zu erstellen.",
-	"transcription_empty_draw_hint": "Zeichnen Sie Bereiche auf dem Dokument, um mit der Transkription zu beginnen.",
 	"transcription_panel_close": "Panel schließen",
 	"person_alias_heading": "Namensverlauf",
 	"person_alias_empty": "Noch keine Namensaenderungen erfasst.",
diff --git a/frontend/messages/en.json b/frontend/messages/en.json
index f5862f0f..d999e1eb 100644
--- a/frontend/messages/en.json
+++ b/frontend/messages/en.json
@@ -515,7 +515,6 @@
 	"scan_collapse": "Collapse scan",
 	"transcription_empty_title": "No transcription yet",
 	"transcription_empty_desc": "Draw regions on the scan and type the text to create a transcription.",
-	"transcription_empty_draw_hint": "Draw regions on the document to start transcribing.",
 	"transcription_panel_close": "Close panel",
 	"person_alias_heading": "Name history",
 	"person_alias_empty": "No name changes recorded yet.",
diff --git a/frontend/messages/es.json b/frontend/messages/es.json
index c949ce2c..b3754eba 100644
--- a/frontend/messages/es.json
+++ b/frontend/messages/es.json
@@ -515,7 +515,6 @@
 	"scan_collapse": "Reducir escaneo",
 	"transcription_empty_title": "Sin transcripcion",
 	"transcription_empty_desc": "Dibuja regiones en el escaneo y escribe el texto para crear una transcripcion.",
-	"transcription_empty_draw_hint": "Dibuje regiones en el documento para comenzar a transcribir.",
 	"transcription_panel_close": "Cerrar panel",
 	"person_alias_heading": "Historial de nombres",
 	"person_alias_empty": "Aun no se han registrado cambios de nombre.",
-- 
2.49.1


From 4f17c718d8192776d8aedd1f39b0426ff81774e0 Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Sat, 25 Apr 2026 01:25:24 +0200
Subject: [PATCH 09/13] test(e2e): fix locators, add print assertion, cleanup,
 remove redundant emulateMedia
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- help-popover: replace broad button[aria-expanded] with specific
  getByLabel('Lese- und Bearbeitungsmodus'); update role="tooltip" →
  role="region"; add afterAll doc cleanup (Sara/Tobias)
- richtlinien: assert .new-tab spans are hidden in print media — the
  existing test only checked .app-nav (Sara)
- transcribe-coach: remove 4× redundant page.emulateMedia({reducedMotion})
  calls — playwright.config.ts already sets reducedMotion: 'reduce' globally;
  add afterAll doc cleanup (Tobias)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 frontend/e2e/help-popover.spec.ts     | 16 +++++++++++-----
 frontend/e2e/richtlinien.spec.ts      |  6 ++++++
 frontend/e2e/transcribe-coach.spec.ts |  8 ++++----
 3 files changed, 21 insertions(+), 9 deletions(-)

diff --git a/frontend/e2e/help-popover.spec.ts b/frontend/e2e/help-popover.spec.ts
index bc0f77c8..4a6fcc06 100644
--- a/frontend/e2e/help-popover.spec.ts
+++ b/frontend/e2e/help-popover.spec.ts
@@ -8,21 +8,27 @@ test.describe('Help chip — Read/Edit panel header', () => {
 		docId = await createEmptyDocument(request);
 	});
 
+	test.afterAll(async ({ request }) => {
+		await request.delete(`/api/documents/${docId}`);
+	});
+
 	test('opens popover on click, closes on Esc, returns focus to chip', async ({ page }) => {
 		await page.goto(`/documents/${docId}`);
 		await page.getByRole('button', { name: 'Transkribieren' }).click();
 
-		// Find and click the (?) help chip
-		const helpBtn = page.locator('button[aria-expanded]');
+		// Use the accessible label of the HelpPopover trigger (transcription_mode_help_label)
+		const helpBtn = page.getByRole('button', { name: 'Lese- und Bearbeitungsmodus' });
 		await expect(helpBtn).toBeVisible({ timeout: 5000 });
 		await helpBtn.click();
 
-		// Popover should open
-		await expect(page.locator('[role="tooltip"]')).toBeVisible();
+		// Popover should open (role="region", not tooltip — click-triggered panels are regions)
+		await expect(page.getByRole('region', { name: 'Lese- und Bearbeitungsmodus' })).toBeVisible();
 
 		// Press Esc
 		await page.keyboard.press('Escape');
-		await expect(page.locator('[role="tooltip"]')).not.toBeVisible();
+		await expect(
+			page.getByRole('region', { name: 'Lese- und Bearbeitungsmodus' })
+		).not.toBeVisible();
 
 		// Focus should have returned to the chip
 		await expect(helpBtn).toBeFocused();
diff --git a/frontend/e2e/richtlinien.spec.ts b/frontend/e2e/richtlinien.spec.ts
index 1b5e52ea..5012fd5d 100644
--- a/frontend/e2e/richtlinien.spec.ts
+++ b/frontend/e2e/richtlinien.spec.ts
@@ -63,6 +63,12 @@ test.describe('Richtlinien page — print media', () => {
 			await expect(nav).toBeHidden();
 		}
 
+		// .new-tab annotation spans must be hidden in print so "(öffnet in neuem Tab)"
+		// text does not clutter the printed output (the print CSS declares display:none)
+		for (const span of await page.locator('.new-tab').all()) {
+			await expect(span).toBeHidden();
+		}
+
 		await page.screenshot({ path: 'test-results/e2e/richtlinien-print.png', fullPage: true });
 	});
 });
diff --git a/frontend/e2e/transcribe-coach.spec.ts b/frontend/e2e/transcribe-coach.spec.ts
index b54c7215..7ff94f64 100644
--- a/frontend/e2e/transcribe-coach.spec.ts
+++ b/frontend/e2e/transcribe-coach.spec.ts
@@ -13,10 +13,13 @@ test.describe('Transcribe coach — empty state', () => {
 		docId = await createEmptyDocument(request);
 	});
 
+	test.afterAll(async ({ request }) => {
+		await request.delete(`/api/documents/${docId}`);
+	});
+
 	test('shows coach card (title, preamble, three step bodies, animation region)', async ({
 		page
 	}) => {
-		await page.emulateMedia({ reducedMotion: 'reduce' });
 		await page.goto(`/documents/${docId}`);
 		await page.getByRole('button', { name: 'Transkribieren' }).click();
 
@@ -31,14 +34,12 @@ test.describe('Transcribe coach — empty state', () => {
 	});
 
 	test('training footer is NOT visible on empty doc', async ({ page }) => {
-		await page.emulateMedia({ reducedMotion: 'reduce' });
 		await page.goto(`/documents/${docId}`);
 		await page.getByRole('button', { name: 'Transkribieren' }).click();
 		await expect(page.getByText('Für Training vormerken')).not.toBeVisible({ timeout: 3000 });
 	});
 
 	test('axe: panel empty state — light theme — no WCAG 2.1 AA violations', async ({ page }) => {
-		await page.emulateMedia({ reducedMotion: 'reduce' });
 		await page.goto(`/documents/${docId}`);
 		await page.getByRole('button', { name: 'Transkribieren' }).click();
 		await expect(page.getByRole('heading', { level: 2, name: /Erste Transkription/ })).toBeVisible({
@@ -50,7 +51,6 @@ test.describe('Transcribe coach — empty state', () => {
 	});
 
 	test('axe: panel empty state — dark theme — no WCAG 2.1 AA violations', async ({ page }) => {
-		await page.emulateMedia({ reducedMotion: 'reduce' });
 		await page.goto(`/documents/${docId}`);
 		// Toggle dark theme
 		await page.getByRole('button', { name: /Farbmodus|theme/i }).click();
-- 
2.49.1


From ccca8dab18228d77a7f24e0c477a036fca48d0d9 Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Sat, 25 Apr 2026 09:01:41 +0200
Subject: [PATCH 10/13] test(HelpPopover): use userEvent.keyboard for
 Enter/Space tests

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../lib/components/HelpPopover.svelte.spec.ts    | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/frontend/src/lib/components/HelpPopover.svelte.spec.ts b/frontend/src/lib/components/HelpPopover.svelte.spec.ts
index b22d1ab9..e2cccf52 100644
--- a/frontend/src/lib/components/HelpPopover.svelte.spec.ts
+++ b/frontend/src/lib/components/HelpPopover.svelte.spec.ts
@@ -1,6 +1,6 @@
 import { describe, it, expect, afterEach, vi } from 'vitest';
 import { cleanup, render } from 'vitest-browser-svelte';
-import { page } from 'vitest/browser';
+import { page, userEvent } from 'vitest/browser';
 import HelpPopover from './HelpPopover.svelte';
 
 afterEach(cleanup);
@@ -51,16 +51,18 @@ describe('HelpPopover — open / close interactions', () => {
 		await vi.waitFor(() => expect(document.querySelector('[role="region"]')).toBeNull());
 	});
 
-	it('opens on Enter key (button is keyboard-reachable, Enter fires click)', async () => {
+	it('opens on Enter key', async () => {
 		renderPopover();
-		await page.getByRole('button', { name: /Help/ }).click();
-		expect(document.querySelector('[role="region"]')).not.toBeNull();
+		(document.querySelector('button[aria-expanded]') as HTMLButtonElement).focus();
+		await userEvent.keyboard('{Enter}');
+		await vi.waitFor(() => expect(document.querySelector('[role="region"]')).not.toBeNull());
 	});
 
-	it('opens on Space key (button is keyboard-reachable, Space fires click)', async () => {
+	it('opens on Space key', async () => {
 		renderPopover();
-		await page.getByRole('button', { name: /Help/ }).click();
-		expect(document.querySelector('[role="region"]')).not.toBeNull();
+		(document.querySelector('button[aria-expanded]') as HTMLButtonElement).focus();
+		await userEvent.keyboard('{Space}');
+		await vi.waitFor(() => expect(document.querySelector('[role="region"]')).not.toBeNull());
 	});
 });
 
-- 
2.49.1


From 7b3334f5e774fdf23baf182946526e8f2c0c94c3 Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Sat, 25 Apr 2026 09:02:51 +0200
Subject: [PATCH 11/13] docs(richtlinien): shorten prerender comment to
 essentials

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 frontend/src/routes/hilfe/transkription/+page.ts | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/frontend/src/routes/hilfe/transkription/+page.ts b/frontend/src/routes/hilfe/transkription/+page.ts
index 3bead06e..f71b9f54 100644
--- a/frontend/src/routes/hilfe/transkription/+page.ts
+++ b/frontend/src/routes/hilfe/transkription/+page.ts
@@ -1,6 +1,3 @@
-// prerender = true is safe here: hooks.server.ts exports
-//   handle = sequence(userGroup, handleAuth, ...)
-// where handleAuth redirects all non-public paths to /login at runtime.
-// Prerendered HTML is served, but the browser still hits handleAuth on
-// every navigation — unauthenticated users are redirected before seeing content.
+// Safe: handleAuth in hooks.server.ts redirects unauthenticated requests
+// before prerendered HTML is visible.
 export const prerender = true;
-- 
2.49.1


From 534ec9597d25b47ea9791a13973b3e101684ba81 Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Sat, 25 Apr 2026 10:22:52 +0200
Subject: [PATCH 12/13] test(e2e): add training footer positive-case test and
 fix broken selectors
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- createEmptyDocument now uploads a minimal PDF so the Transkribieren
  button is rendered (requires isPdf = true in DocumentTopBar)
- add 'Transcribe coach — with blocks' describe: seeds a block via API,
  waits for blocks to settle in read mode, switches to edit, confirms
  'Für Training vormerken' is visible
- fix dark-theme axe test: ThemeToggle uses aria-label 'dark mode',
  not the previous /Farbmodus|theme/ regex

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 frontend/e2e/helpers/upload-empty-document.ts | 28 +++++++++++--
 frontend/e2e/transcribe-coach.spec.ts         | 42 ++++++++++++++++++-
 2 files changed, 65 insertions(+), 5 deletions(-)

diff --git a/frontend/e2e/helpers/upload-empty-document.ts b/frontend/e2e/helpers/upload-empty-document.ts
index caba3615..635f176b 100644
--- a/frontend/e2e/helpers/upload-empty-document.ts
+++ b/frontend/e2e/helpers/upload-empty-document.ts
@@ -1,10 +1,30 @@
 import type { APIRequestContext } from '@playwright/test';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import fs from 'fs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PDF_FIXTURE = path.resolve(__dirname, '../fixtures/minimal.pdf');
 
 export async function createEmptyDocument(request: APIRequestContext): Promise<string> {
-	const res = await request.post('/api/documents', {
+	const createRes = await request.post('/api/documents', {
 		multipart: { title: 'E2E Transcribe Coach Test' }
 	});
-	if (!res.ok()) throw new Error(`Create document failed: ${res.status()}`);
-	const doc = await res.json();
-	return doc.id as string;
+	if (!createRes.ok()) throw new Error(`Create document failed: ${createRes.status()}`);
+	const doc = await createRes.json();
+	const docId = doc.id as string;
+
+	const uploadRes = await request.put(`/api/documents/${docId}`, {
+		multipart: {
+			title: doc.title,
+			file: {
+				name: 'minimal.pdf',
+				mimeType: 'application/pdf',
+				buffer: fs.readFileSync(PDF_FIXTURE)
+			}
+		}
+	});
+	if (!uploadRes.ok()) throw new Error(`Upload PDF failed: ${uploadRes.status()}`);
+
+	return docId;
 }
diff --git a/frontend/e2e/transcribe-coach.spec.ts b/frontend/e2e/transcribe-coach.spec.ts
index 7ff94f64..e6205ff5 100644
--- a/frontend/e2e/transcribe-coach.spec.ts
+++ b/frontend/e2e/transcribe-coach.spec.ts
@@ -2,6 +2,24 @@ import { test, expect } from '@playwright/test';
 import AxeBuilder from '@axe-core/playwright';
 import { createEmptyDocument } from './helpers/upload-empty-document.js';
 
+async function createBlock(
+	request: Parameters<typeof createEmptyDocument>[0],
+	docId: string
+): Promise<void> {
+	const res = await request.post(`/api/documents/${docId}/transcription-blocks`, {
+		data: {
+			pageNumber: 1,
+			x: 0.1,
+			y: 0.1,
+			width: 0.3,
+			height: 0.1,
+			text: 'Liebe Mutter,',
+			label: null
+		}
+	});
+	if (!res.ok()) throw new Error(`Create block failed: ${res.status()}`);
+}
+
 function buildAxe(page: Parameters<typeof AxeBuilder>[0]['page']) {
 	return new AxeBuilder({ page }).withTags(['wcag2a', 'wcag2aa']);
 }
@@ -53,7 +71,7 @@ test.describe('Transcribe coach — empty state', () => {
 	test('axe: panel empty state — dark theme — no WCAG 2.1 AA violations', async ({ page }) => {
 		await page.goto(`/documents/${docId}`);
 		// Toggle dark theme
-		await page.getByRole('button', { name: /Farbmodus|theme/i }).click();
+		await page.getByRole('button', { name: /dark mode/i }).click();
 		await page.getByRole('button', { name: 'Transkribieren' }).click();
 		await expect(page.getByRole('heading', { level: 2, name: /Erste Transkription/ })).toBeVisible({
 			timeout: 5000
@@ -63,3 +81,25 @@ test.describe('Transcribe coach — empty state', () => {
 		expect(a11y.violations, JSON.stringify(a11y.violations, null, 2)).toHaveLength(0);
 	});
 });
+
+test.describe('Transcribe coach — with blocks', () => {
+	let docId: string;
+
+	test.beforeAll(async ({ request }) => {
+		docId = await createEmptyDocument(request);
+		await createBlock(request, docId);
+	});
+
+	test.afterAll(async ({ request }) => {
+		await request.delete(`/api/documents/${docId}`);
+	});
+
+	test('training footer IS visible when at least one block exists', async ({ page }) => {
+		await page.goto(`/documents/${docId}`);
+		await page.getByRole('button', { name: 'Transkribieren' }).click();
+		// Wait for blocks to finish loading — block count confirms mode settled to 'read'
+		await expect(page.getByText(/1 Abschnitt/)).toBeVisible({ timeout: 5000 });
+		await page.locator('[data-testid="mode-edit"]').click();
+		await expect(page.getByText('Für Training vormerken')).toBeVisible({ timeout: 5000 });
+	});
+});
-- 
2.49.1


From 38c3bb137c3e71344a343c74638acec9f79f6f26 Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Sat, 25 Apr 2026 11:52:11 +0200
Subject: [PATCH 13/13] fix(transcribe-coach): propagate hover from 44px button
 group to inner span
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

hover: on the <span> only fired on the 20×20px visual circle, not the
full 44×44px touch target. Add `group` + `focus-visible:ring-*` to the
outer button; switch to `group-hover:` on the inner span so the visual
response covers the entire interactive area.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../src/lib/components/HelpPopover.svelte     |  4 ++--
 .../lib/components/HelpPopover.svelte.spec.ts | 22 +++++++++++++++++++
 2 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/frontend/src/lib/components/HelpPopover.svelte b/frontend/src/lib/components/HelpPopover.svelte
index f6ff984f..2b96fd97 100644
--- a/frontend/src/lib/components/HelpPopover.svelte
+++ b/frontend/src/lib/components/HelpPopover.svelte
@@ -77,10 +77,10 @@ const placementClass: Record<Placement, string> = {
 		aria-expanded={open}
 		aria-controls={popoverId}
 		onclick={toggle}
-		class="flex h-[44px] w-[44px] items-center justify-center"
+		class="group flex h-[44px] w-[44px] items-center justify-center rounded-full focus-visible:ring-2 focus-visible:ring-brand-navy"
 	>
 		<span
-			class="flex h-5 w-5 items-center justify-center rounded-full border border-line bg-muted font-sans text-[10px] font-bold text-ink-3 transition-colors hover:border-brand-navy hover:text-brand-navy"
+			class="flex h-5 w-5 items-center justify-center rounded-full border border-line bg-muted font-sans text-[10px] font-bold text-ink-3 transition-colors group-hover:border-brand-navy group-hover:text-brand-navy"
 		>
 			?
 		</span>
diff --git a/frontend/src/lib/components/HelpPopover.svelte.spec.ts b/frontend/src/lib/components/HelpPopover.svelte.spec.ts
index e2cccf52..fe6800fe 100644
--- a/frontend/src/lib/components/HelpPopover.svelte.spec.ts
+++ b/frontend/src/lib/components/HelpPopover.svelte.spec.ts
@@ -66,6 +66,28 @@ describe('HelpPopover — open / close interactions', () => {
 	});
 });
 
+describe('HelpPopover — hover-target', () => {
+	it('hover styles propagate from 44px button group to inner span, not from span itself', () => {
+		const { container } = renderPopover();
+		const btn = container.querySelector('button[aria-expanded]')!;
+		const span = btn.querySelector('span')!;
+		const btnClasses = btn.className.split(/\s+/);
+		const spanClasses = span.className.split(/\s+/);
+		expect(btnClasses).toContain('group');
+		expect(spanClasses).not.toContain('hover:border-brand-navy');
+		expect(spanClasses).toContain('group-hover:border-brand-navy');
+		expect(spanClasses).not.toContain('hover:text-brand-navy');
+		expect(spanClasses).toContain('group-hover:text-brand-navy');
+	});
+
+	it('outer button has focus-visible ring for keyboard users', () => {
+		const { container } = renderPopover();
+		const btn = container.querySelector('button[aria-expanded]')!;
+		expect(btn.className).toContain('focus-visible:ring-2');
+		expect(btn.className).toContain('focus-visible:ring-brand-navy');
+	});
+});
+
 describe('HelpPopover — aria wiring', () => {
 	it('trigger aria-controls matches popover element id', async () => {
 		renderPopover();
-- 
2.49.1