From 3178d65b35478d33a37c6b0f2cb99ef0d21c80d8 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 18 Sep 2026 06:08:16 +0000
Subject: [PATCH] feat(a11y): RGAA 4.1 audit report, axe e2e gate and first
 fixes

Adds docs/ACCESSIBILITY.md (findings F1-F10 mapped to RGAA 4.1 and WCAG
2.1, what passed, what tooling cannot test) and tests/e2e/accessibility.spec.ts,
which runs axe-core WCAG 2.x A/AA scans over every screen in both themes
plus scripted checks for titles, landmarks, skip link, focus visibility
and keyboard reach. The spec is red until the remaining fixes land.

Fixes that need no design sign-off:
- F1: the tooltip action now exposes its text as aria-label on icon-only
  controls; removing `title` had left ~570 buttons unnamed.
- F5/F6/F7: checklist checkboxes and inputs, the editor textbox and the
  users-page role select get accessible names.
- F8: scrollable code blocks are keyboard reachable (tabindex=0), except
  in card previews which clip instead of scroll.
- F9: each settings tab has its own page title.
- F10: skip link to main content.

Still open, pending sign-off: F2 colour tokens, F3 card structure, F4
focus-visible styling.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014u5WimmZvshm9RJSd1c6wx
---
 docs/ACCESSIBILITY.md                         | 144 ++++++++++
 package.json                                  |   1 +
 pnpm-lock.yaml                                |  19 ++
 src/lib/components/Checklist.svelte           |   5 +-
 src/lib/components/NoteCard.svelte            |   4 +-
 src/lib/components/TiptapEditor.svelte        |   2 +
 src/lib/utils/markdown.ts                     |  21 +-
 src/lib/utils/tooltip.ts                      |  11 +
 src/routes/(app)/+layout.svelte               |  10 +-
 src/routes/(app)/settings/+layout.svelte      |   3 -
 src/routes/(app)/settings/about/+page.svelte  |   4 +
 src/routes/(app)/settings/mcp/+page.svelte    |   4 +
 .../(app)/settings/preferences/+page.svelte   |   4 +
 .../(app)/settings/profile/+page.svelte       |   4 +
 src/routes/(app)/settings/users/+page.svelte  |   5 +
 tests/e2e/accessibility.spec.ts               | 252 ++++++++++++++++++
 16 files changed, 484 insertions(+), 9 deletions(-)
 create mode 100644 docs/ACCESSIBILITY.md
 create mode 100644 tests/e2e/accessibility.spec.ts

diff --git a/docs/ACCESSIBILITY.md b/docs/ACCESSIBILITY.md
new file mode 100644
index 0000000..900ea74
--- /dev/null
+++ b/docs/ACCESSIBILITY.md
@@ -0,0 +1,144 @@
+# Accessibility audit — RGAA 4.1
+
+**Date:** 2026-09-17 · **Build audited:** `main` at `7bf06ed` (before #91) · **Status:** findings open, fixes in progress on `feat/a11y-audit`
+
+RGAA 4.1 (Référentiel général d'amélioration de l'accessibilité) is the French application of WCAG 2.1 level AA: 106 criteria in 13 topics. This document records what was tested, what failed, what passed, and what has not been tested. It is **not** a compliance declaration: roughly a third of RGAA can be verified by tooling and scripted checks, and the remainder needs a manual pass with assistive technology (see [Not tested](#not-tested)).
+
+## Method
+
+| Layer | Tool | What it covers |
+|---|---|---|
+| Automated rules | axe-core 4.13 via `@axe-core/playwright`, rule tags `wcag2a`, `wcag2aa`, `wcag21a`, `wcag21aa` | Contrast, names and roles, form labels, language, nesting, scroll regions, ARIA validity |
+| Scripted checks | `tests/e2e/accessibility.spec.ts` | Page titles, landmarks, skip link, keyboard reach, visible focus, Escape handling, card action naming |
+| Manual reading | Source review of the components the scans pointed at | Root causes and fix proposals |
+
+Screens scanned, each in **light and dark** theme: notes grid seeded with all 12 note colours plus checklist, tagged and code notes; open editor; editor with colour picker; share dialog; editor on a checklist note; archive; trash; tag view; search results; settings (profile, preferences, MCP, users, about); login; public share page.
+
+The spec doubles as the CI gate: every scan asserts zero violations and writes its raw axe output to `test-results/a11y/<screen>-<theme>.json`. Run it alone with:
+
+```
+pnpm playwright test accessibility.spec.ts
+```
+
+## Findings
+
+Severity: **Blocking** = prevents a group of users from completing a core task · **Major** = criterion fails on most screens · **Minor** = localised failure.
+
+Counts are raw axe node counts across all scans; the grid repeats every card, so one root cause shows up as hundreds of nodes.
+
+### F1 · Icon buttons have no accessible name — Blocking
+
+- **RGAA 11.9** (button label relevance), **RGAA 7.1** (script compatibility with assistive tech) · WCAG 4.1.2
+- **Where:** card actions (pin, archive, trash, restore, delete) on every card; editor footer (colour picker, image, share, archive, overflow menu); new-checklist button. 574 nodes on 7 screens, both themes.
+- **Evidence:** axe `button-name`: "Element does not have inner text that is visible to screen readers; aria-label attribute does not exist or is empty".
+- **Root cause:** `src/lib/utils/tooltip.ts` was introduced as a drop-in replacement for the `title` attribute. It renders a visual tooltip but sets no `aria-label`, so every icon-only button that adopted it lost its name for screen readers.
+- **Fix:** the tooltip action sets `aria-label` from its text when the element has no accessible name of its own. One change repairs every instance.
+
+### F2 · Insufficient text contrast — Blocking (light theme), Minor (dark theme)
+
+- **RGAA 3.2** (text contrast), **RGAA 3.3** (UI component contrast) · WCAG 1.4.3, 1.4.11
+- **Where and how far off** (AA requires 4.5:1 for body text, 3:1 for large text and component boundaries):
+
+| Element | Colours | Ratio | Screens |
+|---|---|---|---|
+| Brand title "Crumbs" (18px) | `#C8860A` on `#faf5eb` | 2.81 | all app screens, login |
+| Active sidebar item | `#C8860A` on gold wash `#f3e4c9` | 2.43 | all app screens |
+| Active settings tab | `#C8860A` on `#ead8b5` | 2.18 | all settings tabs |
+| Links inside note previews | `#C8860A` on each note colour | 1.46 (peach) to 2.81 (default) | notes, archive, trash, search, editor |
+| Note preview body text | muted `#6b6272` on coral / peach / storm / dusk / sage / fog | 3.25 / 2.77 / 3.44 / 3.38 / 3.93 / 4.45 | same |
+| Primary buttons (login, save, invite, tag filter) | white on `#C8860A` | 3.05 | login, settings, tag |
+| Primary buttons, dark theme | white on `#e0a030` | 2.27 | login, settings, tag |
+
+- **What passes:** in dark mode every note colour passes for both `--text` (worst 9.3:1 on mint) and `--text-muted` (worst 4.9:1 on mint). The code-block palette added in #91 passes by construction (unit-tested). The only dark-theme failure is white text on gold buttons.
+- **Root cause:** the brand gold `--primary` is used for text, not only for accents, and it is too light on parchment. `--text-muted` was tuned for `--bg-surface` and never checked against the coloured cards.
+- **Fix (needs design sign-off, see below):**
+  1. Add `--primary-text`, a darker gold for text and icons on light chrome (`#7d5306` is already in use as the code keyword colour; it reaches 6.2:1 on `--bg-surface`, 5.5:1 on `--bg-base`, 5.4:1 on the sidebar's active wash and 4.8:1 on the settings tab wash). Dark theme keeps `#e0a030`, which passes on every dark surface (worst 5.2:1 on mint). Brand title, sidebar and settings active states switch to it. `--primary` stays for borders, shadows, washes and the checkbox accent.
+  2. Links inside note content use `--text` with an underline instead of gold. No gold passes on the coral, peach, sage, storm or dusk cards (`#7d5306` bottoms out at 3.2:1 on peach), and the underline keeps links identifiable without relying on colour (RGAA 3.1).
+  3. Primary buttons use ink text (`--text`) on gold in both themes: 5.6:1 light, 7.5:1 dark.
+  4. Note preview body text uses `--text` instead of `--text-muted`. It is the note's content, not secondary information, and `--text` passes on every card colour (worst 8.2:1 on peach).
+
+### F3 · Note cards nest interactive controls and expose two tab stops per card — Blocking
+
+- **RGAA 7.1**, **RGAA 12.8** (tab order), **RGAA 7.3** (keyboard operability) · WCAG 4.1.2, 2.1.1, 2.4.3
+- **Where:** every card on notes, archive, trash, tag and search screens. 182 axe `nested-interactive` nodes.
+- **Evidence:** the card is `<article role="button" tabindex="0">` and contains the action `<button>`s, which is invalid: a button cannot contain buttons, and screen readers flatten the card's content into the button's name ("A11y coral Body text on the coral card…"). On the main grid each card is additionally wrapped by a `svelte-dnd-action` item that has its own `tabindex="0"` and `role="listitem"`, with `outline-none`. Tabbing stops on that wrapper first, with no visible focus, and pressing **Enter** there starts keyboard drag mode instead of opening the note. The scripted "Enter opens the note" scenario failed for this reason.
+- **Fix (needs sign-off):** make the card a plain `<article>` and make its title a `<button>` that opens the note. Mouse users keep click-anywhere via the article's click handler; keyboard and screen-reader users get one clean button with the note title as its name, followed by the named action buttons. Set the drag zone's `zoneItemTabIndex: -1` so the wrapper is no longer a tab stop; keyboard reordering was unusable anyway without a visible focus and is not required by RGAA 4.1.
+
+### F4 · Focus is not visible — Major
+
+- **RGAA 10.7** · WCAG 2.4.7
+- **Where:** cards and drag wrappers use `outline-none` with no replacement; there is no `:focus-visible` style anywhere in `src/app.css`. Buttons and inputs keep the browser default ring, which is inconsistent with the design and disappears where `outline-none` is set (inputs rely on a 1px border colour change to gold, which itself fails contrast).
+- **Fix:** a global `:focus-visible` rule in the retro idiom (2px hard outline in `--primary-text`, 2px offset, no blur), and removal of `outline-none` where nothing replaces it.
+
+### F5 · Checklist checkboxes have no label — Major
+
+- **RGAA 11.1** (each field has a label) · WCAG 1.3.1, 4.1.2
+- **Where:** checklist item checkboxes in the editor (`checklist-checkbox`, `checklist-done-checkbox`) and the read-only checkboxes in card previews. 28 nodes.
+- **Fix:** associate each checkbox with its item text (`aria-labelledby` pointing at the text span, or wrap both in a `<label>`). Preview checkboxes are decorative duplicates of the text and can be `aria-hidden` instead.
+
+### F6 · The note content editor has no name — Major
+
+- **RGAA 11.1** · WCAG 4.1.2
+- **Where:** the TipTap `contenteditable` (`role="textbox"`) and the checklist item `contenteditable` inputs. 6 nodes.
+- **Fix:** `aria-label="Note content"` on the ProseMirror root via `editorProps.attributes`; checklist inputs labelled by their position or "Checklist item".
+
+### F7 · Role select on the users page has no label — Minor
+
+- **RGAA 11.1** · WCAG 1.3.1, 4.1.2
+- **Where:** `/settings/users`, the role `<select>` in the create-user form. 2 nodes.
+- **Fix:** a visible `<label for>`.
+
+### F8 · Scrollable code blocks cannot be reached by keyboard — Minor
+
+- **RGAA 7.3** · WCAG 2.1.1
+- **Where:** `<pre>` elements with `overflow-x: auto` in the editor and share page (12 nodes). After #91, card previews clip instead of scroll and drop out of this finding.
+- **Fix:** `tabindex="0"` on rendered and editor code blocks so the region can be scrolled with arrow keys.
+
+### F9 · Settings tabs share one page title — Minor
+
+- **RGAA 8.5, 8.6** (page title present and relevant) · WCAG 2.4.2
+- **Where:** profile, preferences, MCP, users and about all render `Settings - Crumbs`. Other routes are distinct (`Archive - Crumbs`, `Trash - Crumbs`, `#tag - Crumbs`).
+- **Fix:** per-tab titles (`Profile settings - Crumbs`, …).
+
+### F10 · No skip link — Minor
+
+- **RGAA 12.7** (skip link to main content) · WCAG 2.4.1
+- **Where:** the first Tab stop on every app page is the sidebar toggle; header and sidebar (up to a dozen stops) precede the content on every page. Landmarks exist (`header`, `nav`, `main`, `footer`), which satisfies **RGAA 12.6**, but RGAA 12.7 additionally requires a skip link when blocks repeat across pages.
+- **Fix:** a visually hidden "Skip to content" link as the first focusable element, revealed on focus, targeting `main`.
+
+## Passed
+
+Verified by the scans or scripted checks, on every screen unless noted:
+
+- **8.3 / 8.4** document language declared and valid.
+- **8.5** every page has a title; **8.6** titles are relevant outside settings (F9).
+- **9.2 / 12.6** header, navigation, main and footer landmarks present.
+- **1.1** no image without a text alternative on the audited screens (thumbnails carry the attachment filename).
+- **6.1** no link without a name.
+- **3.2** in dark mode for all note colours, body and muted text; code-block palette in both themes.
+- **11.1** on login, profile, preferences and MCP forms apart from F6 and F7.
+- axe reported no ARIA misuse (`aria-*` validity and allowed roles) and no duplicate ids.
+
+## Not tested
+
+These need a person with assistive technology or a manual protocol. They are listed so nobody reads the passes above as a compliance claim.
+
+- **Screen reader behaviour** (NVDA + Firefox, VoiceOver + Safari): announcement of toasts and sync status (**7.x**, WCAG 4.1.3 status messages), reading order of the editor, dialog focus trapping and restoration in the share dialog and image lightbox (**7.3**, **12.9**).
+- **Setup page** (`/setup`): redirects once an account exists, so the scans cannot reach it. It shares components with the login page, which was scanned.
+- **Information by colour alone** (**3.1**): note colours, tag chips, collaborator indicators.
+- **Reflow and zoom** at 320px width and 200% (**10.11**, **10.4**), text spacing override (**10.12**), content on hover/focus (**10.13**) for the custom tooltip.
+- **Forms**: error identification and correction guidance (**11.10**, **11.11**), autocomplete purposes (**11.13**).
+- **Time limits and motion** (**13.1**, **13.8**): auto-save, session expiry, drag animations.
+- **Alternative to drag and drop** for reordering: not required by RGAA 4.1 (WCAG 2.2 criterion), noted for the future.
+- **Heading hierarchy relevance** (**9.1**) beyond the structural check.
+- Mobile layouts and the installed PWA.
+
+## Fix plan
+
+Order reflects impact per change:
+
+1. F1 tooltip `aria-label` (one file).
+2. F2 colour tokens, F4 focus style (design sign-off first).
+3. F3 card structure and drag wrapper tab index (sign-off first).
+4. F5, F6, F7 labels; F8 `tabindex`; F9 titles; F10 skip link.
+5. Re-run `accessibility.spec.ts` until green, then it stays in CI as the gate.
diff --git a/package.json b/package.json
index 0cac5fb..aaeadde 100644
--- a/package.json
+++ b/package.json
@@ -67,6 +67,7 @@
     "zxcvbn": "^4.4.2"
   },
   "devDependencies": {
+    "@axe-core/playwright": "^4.13.0",
     "@playwright/test": "^1.62.1",
     "@sveltejs/kit": "^2.70.3",
     "@sveltejs/vite-plugin-svelte": "^6.2.4",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 21104a2..ebaf4a3 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -112,6 +112,9 @@ importers:
         specifier: ^4.4.2
         version: 4.4.2
     devDependencies:
+      '@axe-core/playwright':
+        specifier: ^4.13.0
+        version: 4.13.0(playwright-core@1.62.1)
       '@playwright/test':
         specifier: ^1.62.1
         version: 1.62.1
@@ -215,6 +218,11 @@ packages:
   '@asamuzakjp/nwsapi@2.3.9':
     resolution: {integrity: sha512-n8GuYSrI9bF7FFZ/SjhwevlHc8xaVlb/7HmHelnc/PZXBD2ZR49NnN9sMMuDdEGPeeRQ5d0hqlSlEpgCX3Wl0Q==}
 
+  '@axe-core/playwright@4.13.0':
+    resolution: {integrity: sha512-6YLx+kxXu5GJceG4ozFg+33a2EMTdjYwWGloJ3sb9Kta5pp+ZNS53uxGVog5JetIY8s++P5UrtX+cri+u0VAVg==}
+    peerDependencies:
+      playwright-core: '>= 1.0.0'
+
   '@babel/code-frame@7.29.7':
     resolution: {integrity: sha512-Aup7aUOfpbAUg2ROOJN6Iw5f9DMBlzu0mIkm/malLQFN/YQgO48wCj0Kxa3sEHJvPVFg7siR+qRInwXd2qhQKw==}
     engines: {node: '>=6.9.0'}
@@ -1918,6 +1926,10 @@ packages:
     resolution: {integrity: sha512-wvUjBtSGN7+7SjNpq/9M2Tg350UZD3q62IFZLbRAR1bSMlCo1ZaeW+BJ+D090e4hIIZLBcTDWe4Mh4jvUDajzQ==}
     engines: {node: '>= 0.4'}
 
+  axe-core@4.13.0:
+    resolution: {integrity: sha512-UzGt8zg7Ny8djbYMhxl2zuEevVa7r2gJjYY5Lwr1xM7+XU2nd6CkIWFTVcCIbAP63vSz71NaVyyuSk9lHKcy0A==}
+    engines: {node: '>=4'}
+
   axobject-query@4.1.0:
     resolution: {integrity: sha512-qIj0G9wZbMGNLjLmg1PT6v2mE9AH2zlnADJD/2tC6E00hgmhUOfEB6greHPAfLRSufHqROIUTkw6E+M3lH0PTQ==}
     engines: {node: '>= 0.4'}
@@ -4274,6 +4286,11 @@ snapshots:
 
   '@asamuzakjp/nwsapi@2.3.9': {}
 
+  '@axe-core/playwright@4.13.0(playwright-core@1.62.1)':
+    dependencies:
+      axe-core: 4.13.0
+      playwright-core: 1.62.1
+
   '@babel/code-frame@7.29.7':
     dependencies:
       '@babel/helper-validator-identifier': 7.29.7
@@ -5947,6 +5964,8 @@ snapshots:
     dependencies:
       possible-typed-array-names: 1.1.0
 
+  axe-core@4.13.0: {}
+
   axobject-query@4.1.0: {}
 
   babel-plugin-polyfill-corejs2@0.4.17(@babel/core@7.29.7):
diff --git a/src/lib/components/Checklist.svelte b/src/lib/components/Checklist.svelte
index 7ffa347..da60ca2 100644
--- a/src/lib/components/Checklist.svelte
+++ b/src/lib/components/Checklist.svelte
@@ -313,6 +313,7 @@
 					type="checkbox"
 					checked={item.checked}
 					onchange={() => toggleItem(item.id)}
+					aria-label={item.text ? `Done: ${item.text}` : 'Done'}
 					class="h-4 w-4 rounded border-[var(--border-subtle)] text-[var(--primary)] focus:ring-[var(--primary)]"
 					data-testid="checklist-checkbox"
 				/>
@@ -335,6 +336,7 @@
 					class="flex-1 min-w-0 bg-transparent text-sm outline-none break-words {item.checked ? 'text-[var(--text-muted)] line-through' : 'text-[var(--text)]'}"
 					data-placeholder="List item"
 					aria-placeholder="List item"
+					aria-label="Checklist item"
 					data-testid="checklist-input"
 					data-item-id={item.id}
 					role="textbox"
@@ -377,7 +379,7 @@
 					{#each doneSectionGroups as group}
 						{#if group.parentLabel}
 							<div class="flex items-center gap-2 py-1.5 pl-5" data-testid="checklist-done-parent-label">
-								<input type="checkbox" disabled class="h-4 w-4 rounded border-[var(--border-subtle)] opacity-50" />
+								<input type="checkbox" disabled tabindex="-1" aria-hidden="true" class="h-4 w-4 rounded border-[var(--border-subtle)] opacity-50" />
 								<span class="text-sm text-[var(--text-muted)] break-words min-w-0">{@html linkifyText(group.parentLabel.text)}</span>
 							</div>
 						{/if}
@@ -387,6 +389,7 @@
 									type="checkbox"
 									checked={item.checked}
 									onchange={() => toggleItem(item.id)}
+									aria-label={item.text ? `Done: ${item.text}` : 'Done'}
 									class="h-4 w-4 rounded border-[var(--border-subtle)] text-[var(--primary)] focus:ring-[var(--primary)]"
 									data-testid="checklist-done-checkbox"
 								/>
diff --git a/src/lib/components/NoteCard.svelte b/src/lib/components/NoteCard.svelte
index e2b72af..399c130 100644
--- a/src/lib/components/NoteCard.svelte
+++ b/src/lib/components/NoteCard.svelte
@@ -37,7 +37,7 @@
 	let lightboxSrc = $state<string | null>(null);
 	let lightboxAlt = $state('');
 
-	const renderedContent = $derived(renderMarkdown(note.content));
+	const renderedContent = $derived(renderMarkdown(note.content, { focusableCode: false }));
 
 	const checklistItems = $derived<ChecklistItem[]>(
 		note.checklistMode
@@ -143,6 +143,8 @@
 						type="checkbox"
 						checked={item.checked}
 						disabled
+						tabindex="-1"
+						aria-hidden="true"
 						class="mt-0.5 h-3.5 w-3.5 shrink-0 rounded border-[var(--border-subtle)] text-[var(--primary)]"
 						data-testid="card-checklist-checkbox"
 					/>
diff --git a/src/lib/components/TiptapEditor.svelte b/src/lib/components/TiptapEditor.svelte
index f6fadc7..731031e 100644
--- a/src/lib/components/TiptapEditor.svelte
+++ b/src/lib/components/TiptapEditor.svelte
@@ -107,6 +107,8 @@
 					Markdown
 				],
 				content,
+				// The contenteditable is exposed as role="textbox"; give it a name (RGAA 11.1).
+				editorProps: { attributes: { 'aria-label': 'Note content' } },
 				onUpdate: ({ editor: e }) => {
 					if (destroyed) return;
 					// eslint-disable-next-line @typescript-eslint/no-explicit-any
diff --git a/src/lib/utils/markdown.ts b/src/lib/utils/markdown.ts
index ff933c1..4cc7b6b 100644
--- a/src/lib/utils/markdown.ts
+++ b/src/lib/utils/markdown.ts
@@ -19,7 +19,8 @@ const SANITIZE_OPTIONS: sanitizeHtml.IOptions = {
 	allowedAttributes: {
 		...sanitizeHtml.defaults.allowedAttributes,
 		input: ['type', 'checked', 'disabled', 'class'],
-		ul: ['class']
+		ul: ['class'],
+		pre: ['tabindex']
 	},
 	// Keep markdown-it's bare void-element style (<br>, not <br />) so
 	// sanitizing doesn't change output for content that had no raw HTML to
@@ -82,8 +83,22 @@ md.core.ruler.after('task-lists', 'note-links', (state) => {
 	}
 });
 
-export function renderMarkdown(content: string): string {
-	return sanitizeHtml(md.render(content), SANITIZE_OPTIONS);
+// A <pre> that scrolls horizontally is a scrollable region and must be
+// reachable by keyboard (RGAA 7.3 / WCAG 2.1.1). Card previews clip instead of
+// scrolling and turn this off so a card does not gain a pointless tab stop.
+const defaultFence = md.renderer.rules.fence!;
+md.renderer.rules.fence = (tokens, idx, options, env, self) => {
+	const html = defaultFence(tokens, idx, options, env, self);
+	return env?.focusableCode === false ? html : html.replace(/^<pre>/, '<pre tabindex="0">');
+};
+
+export interface RenderMarkdownOptions {
+	/** Whether scrollable code blocks get `tabindex="0"`. Default true. */
+	focusableCode?: boolean;
+}
+
+export function renderMarkdown(content: string, options: RenderMarkdownOptions = {}): string {
+	return sanitizeHtml(md.render(content, { focusableCode: options.focusableCode ?? true }), SANITIZE_OPTIONS);
 }
 
 export function stripMarkdown(content: string): string {
diff --git a/src/lib/utils/tooltip.ts b/src/lib/utils/tooltip.ts
index 915ddb1..b6e5a4e 100644
--- a/src/lib/utils/tooltip.ts
+++ b/src/lib/utils/tooltip.ts
@@ -68,15 +68,26 @@ export function tooltip(node: HTMLElement, value: string | TooltipOptions) {
 	const nativeTitle = node.getAttribute('title');
 	if (nativeTitle) node.removeAttribute('title');
 
+	// Removing `title` also removed the only accessible name most icon-only
+	// buttons had (RGAA 11.9 / WCAG 4.1.2). The tooltip text is that name, so
+	// expose it to assistive tech unless the element already names itself.
+	const ownsLabel = !node.hasAttribute('aria-label') && !node.hasAttribute('aria-labelledby') && !node.textContent?.trim();
+	function syncLabel() {
+		if (ownsLabel) node.setAttribute('aria-label', opts.text);
+	}
+	syncLabel();
+
 	return {
 		update(newValue: string | TooltipOptions) {
 			opts = parseOptions(newValue);
+			syncLabel();
 		},
 		destroy() {
 			hide();
 			node.removeEventListener('mouseenter', show);
 			node.removeEventListener('mouseleave', hide);
 			node.removeEventListener('pointerdown', hide);
+			if (ownsLabel) node.removeAttribute('aria-label');
 			if (nativeTitle) node.setAttribute('title', nativeTitle);
 		}
 	};
diff --git a/src/routes/(app)/+layout.svelte b/src/routes/(app)/+layout.svelte
index d2df4b9..2a7bbea 100644
--- a/src/routes/(app)/+layout.svelte
+++ b/src/routes/(app)/+layout.svelte
@@ -33,10 +33,18 @@
 </script>
 
 <div class="flex min-h-screen flex-col bg-[var(--bg-base)] text-[var(--text)]">
+	<!-- RGAA 12.7: header and sidebar repeat on every page, so keyboard users get a way past them. -->
+	<a
+		href="#main-content"
+		class="sr-only focus:not-sr-only focus:fixed focus:left-4 focus:top-4 focus:z-50 focus:rounded-sm focus:border focus:border-[var(--border)] focus:bg-[var(--bg-surface)] focus:px-4 focus:py-2 focus:text-sm focus:text-[var(--text)] focus:shadow-[var(--card-shadow)]"
+		data-testid="skip-link"
+	>
+		Skip to content
+	</a>
 	<Header onMenuToggle={() => (sidebarOpen = !sidebarOpen)} />
 	<Sidebar open={sidebarOpen} onClose={() => (sidebarOpen = false)} />
 
-	<main class="flex-1 pt-4 transition-all {sidebarOpen ? 'lg:ml-64' : ''}">
+	<main id="main-content" tabindex="-1" class="flex-1 pt-4 outline-none transition-all {sidebarOpen ? 'lg:ml-64' : ''}">
 		<div class="mx-auto max-w-7xl px-4">
 			{@render children()}
 		</div>
diff --git a/src/routes/(app)/settings/+layout.svelte b/src/routes/(app)/settings/+layout.svelte
index 71bea8e..494b6e1 100644
--- a/src/routes/(app)/settings/+layout.svelte
+++ b/src/routes/(app)/settings/+layout.svelte
@@ -6,9 +6,6 @@
 	let pathname = $derived(page.url.pathname);
 </script>
 
-<svelte:head>
-	<title>Settings - Crumbs</title>
-</svelte:head>
 
 <div class="mx-auto max-w-4xl px-4 py-8">
 	<h1 class="mb-6 text-2xl font-bold text-[var(--text)]">Settings</h1>
diff --git a/src/routes/(app)/settings/about/+page.svelte b/src/routes/(app)/settings/about/+page.svelte
index 05cf3ca..94938d5 100644
--- a/src/routes/(app)/settings/about/+page.svelte
+++ b/src/routes/(app)/settings/about/+page.svelte
@@ -4,6 +4,10 @@
 	let appVersion = $derived($page.data.appVersion);
 </script>
 
+<svelte:head>
+	<title>About - Crumbs</title>
+</svelte:head>
+
 <div class="space-y-8">
 	<div class="flex items-center gap-3">
 		<h2 class="text-xl font-bold text-[var(--text)]">About Crumbs</h2>
diff --git a/src/routes/(app)/settings/mcp/+page.svelte b/src/routes/(app)/settings/mcp/+page.svelte
index ebdbbb7..82ccd19 100644
--- a/src/routes/(app)/settings/mcp/+page.svelte
+++ b/src/routes/(app)/settings/mcp/+page.svelte
@@ -115,6 +115,10 @@ ${mcpJsonConfig}`);
 	});
 </script>
 
+<svelte:head>
+	<title>MCP settings - Crumbs</title>
+</svelte:head>
+
 <!-- API Keys -->
 <section class="mb-6 rounded-sm border border-[var(--border-subtle)] bg-[var(--bg-surface)] p-6 shadow-[var(--card-shadow)]">
 	<div class="mb-4 flex items-center gap-2">
diff --git a/src/routes/(app)/settings/preferences/+page.svelte b/src/routes/(app)/settings/preferences/+page.svelte
index 5f24da6..ce45bfa 100644
--- a/src/routes/(app)/settings/preferences/+page.svelte
+++ b/src/routes/(app)/settings/preferences/+page.svelte
@@ -6,6 +6,10 @@
 	const prefs = $derived(getPreferences());
 </script>
 
+<svelte:head>
+	<title>Preferences - Crumbs</title>
+</svelte:head>
+
 <div class="space-y-8">
 	<h2 class="text-xl font-bold text-[var(--text)]">Preferences</h2>
 
diff --git a/src/routes/(app)/settings/profile/+page.svelte b/src/routes/(app)/settings/profile/+page.svelte
index de680f8..0dcd65d 100644
--- a/src/routes/(app)/settings/profile/+page.svelte
+++ b/src/routes/(app)/settings/profile/+page.svelte
@@ -176,6 +176,10 @@
 	});
 </script>
 
+<svelte:head>
+	<title>Profile settings - Crumbs</title>
+</svelte:head>
+
 <!-- Profile -->
 <section class="mb-6 rounded-sm border border-[var(--border-subtle)] bg-[var(--bg-surface)] p-6 shadow-[var(--card-shadow)]">
 	<h2 class="mb-4 text-lg font-semibold text-[var(--text)]">Profile</h2>
diff --git a/src/routes/(app)/settings/users/+page.svelte b/src/routes/(app)/settings/users/+page.svelte
index b7eb2cf..9d6f6bc 100644
--- a/src/routes/(app)/settings/users/+page.svelte
+++ b/src/routes/(app)/settings/users/+page.svelte
@@ -365,6 +365,10 @@
 	}
 </script>
 
+<svelte:head>
+	<title>User management - Crumbs</title>
+</svelte:head>
+
 <!-- Create User -->
 	<section class="mb-6 rounded-sm border border-[var(--border-subtle)] bg-[var(--bg-surface)] p-6 shadow-[var(--card-shadow)]">
 		<h2 class="mb-4 text-lg font-semibold text-[var(--text)]">Create User</h2>
@@ -403,6 +407,7 @@
 			{/if}
 			<select
 				bind:value={newRole}
+				aria-label="Role"
 				class="w-full rounded-sm border border-[var(--border-subtle)] bg-[var(--bg-base)] px-4 py-2 text-sm text-[var(--text)] outline-none focus:border-[var(--primary)]"
 			>
 				<option value="user">User</option>
diff --git a/tests/e2e/accessibility.spec.ts b/tests/e2e/accessibility.spec.ts
new file mode 100644
index 0000000..b0f47e9
--- /dev/null
+++ b/tests/e2e/accessibility.spec.ts
@@ -0,0 +1,252 @@
+import { test, expect, noteCard } from './helpers/fixtures.js';
+import AxeBuilder from '@axe-core/playwright';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import type { Browser, Page } from '@playwright/test';
+
+/**
+ * Automated accessibility gate. RGAA 4.1 is the French application of
+ * WCAG 2.1 AA, so the scans run axe-core's WCAG 2.x A/AA rule set over every
+ * screen in both themes, and the structural scenarios cover the RGAA
+ * criteria that tooling can prove (page titles, landmarks, keyboard reach,
+ * visible focus). Tooling covers roughly a third of RGAA; the rest needs a
+ * manual pass with assistive technology and is documented in
+ * docs/ACCESSIBILITY.md.
+ *
+ * Each scan also writes its raw violations to test-results/a11y/ so a
+ * failing run doubles as the audit's evidence.
+ */
+
+const WCAG_TAGS = ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'];
+const REPORT_DIR = 'test-results/a11y';
+const THEMES = ['light', 'dark'] as const;
+type Theme = (typeof THEMES)[number];
+
+const COLORS = ['default', 'coral', 'peach', 'sand', 'mint', 'sage', 'fog', 'storm', 'dusk', 'blossom', 'clay', 'chalk'];
+
+async function scan(page: Page, name: string, theme: Theme) {
+	const results = await new AxeBuilder({ page }).withTags(WCAG_TAGS).analyze();
+	mkdirSync(REPORT_DIR, { recursive: true });
+	writeFileSync(`${REPORT_DIR}/${name}-${theme}.json`, JSON.stringify(results.violations, null, 2));
+	const summary = results.violations
+		.map(
+			(v) =>
+				`${v.id} [${v.impact}] x${v.nodes.length}: ${v.help}\n` +
+				v.nodes
+					.slice(0, 4)
+					.map((n) => `    ${n.target.join(' ')} — ${n.failureSummary?.split('\n').slice(1).join('; ')}`)
+					.join('\n')
+		)
+		.join('\n');
+	expect(results.violations, `axe violations on "${name}" in ${theme} mode:\n${summary}`).toEqual([]);
+}
+
+/** Seed one note per colour plus checklist, tagged, code, archived and trashed notes. */
+async function seedNotes(page: Page) {
+	const existing = await (await page.request.get('/api/notes')).json();
+	if (Array.isArray(existing) && existing.some((n) => n.title === 'A11y coral')) return;
+	for (const color of COLORS) {
+		await page.request.post('/api/notes', {
+			data: { title: `A11y ${color}`, content: `Body text on the ${color} card with a [link](https://example.com) and *emphasis*.`, color }
+		});
+	}
+	await page.request.post('/api/notes', {
+		data: { title: 'A11y checklist', content: '- [ ] Open item\n- [x] Done item', checklistMode: true }
+	});
+	await page.request.post('/api/notes', { data: { title: 'A11y tagged', content: 'Filed under #audit' } });
+	await page.request.post('/api/notes', {
+		data: { title: 'A11y code', content: 'Inline `code` and a block:\n\n```ts\nconst answer: number = 42; // meaning\n```' }
+	});
+	const archived = await (await page.request.post('/api/notes', { data: { title: 'A11y archived', content: 'Archived' } })).json();
+	await page.request.patch(`/api/notes/${archived.id}`, { data: { archived: true } });
+	const trashed = await (await page.request.post('/api/notes', { data: { title: 'A11y trashed', content: 'Trashed' } })).json();
+	await page.request.patch(`/api/notes/${trashed.id}`, { data: { trashed: true } });
+}
+
+async function visit(page: Page, path: string) {
+	await page.goto(path);
+	await page.waitForLoadState('networkidle');
+}
+
+async function anonymousPage(browser: Browser, theme: Theme) {
+	const context = await browser.newContext({ colorScheme: theme, storageState: { cookies: [], origins: [] } });
+	return { context, page: await context.newPage() };
+}
+
+for (const theme of THEMES) {
+	test.describe(`WCAG 2.1 AA scan (${theme} theme)`, () => {
+		test.beforeEach(async ({ authenticatedPage: page }) => {
+			await page.emulateMedia({ colorScheme: theme });
+			await seedNotes(page);
+		});
+
+		test(`Scenario: The notes grid with every note colour has no WCAG AA violations`, async ({ authenticatedPage: page }) => {
+			await visit(page, '/');
+			await expect(noteCard(page, 'A11y chalk')).toBeVisible();
+			await scan(page, 'notes', theme);
+		});
+
+		test(`Scenario: The open editor, its colour picker and share dialog have no WCAG AA violations`, async ({
+			authenticatedPage: page
+		}) => {
+			await visit(page, '/');
+			await noteCard(page, 'A11y code').click();
+			await expect(page.getByTestId('tiptap-editor')).toBeVisible();
+			await scan(page, 'editor', theme);
+
+			await page.getByTestId('color-picker-toggle').click();
+			await expect(page.getByTestId('color-picker')).toBeVisible();
+			await scan(page, 'editor-color-picker', theme);
+			await page.keyboard.press('Escape');
+
+			await page.getByTestId('share-toggle').click();
+			await expect(page.getByTestId('share-dialog')).toBeVisible();
+			await scan(page, 'share-dialog', theme);
+		});
+
+		test(`Scenario: A checklist note open in the editor has no WCAG AA violations`, async ({ authenticatedPage: page }) => {
+			await visit(page, '/');
+			await noteCard(page, 'A11y checklist').click();
+			await expect(page.getByTestId('note-editor')).toBeVisible();
+			await scan(page, 'editor-checklist', theme);
+		});
+
+		for (const [name, path] of [
+			['archive', '/archive'],
+			['trash', '/trash'],
+			['tag', '/tag/audit'],
+			['settings-profile', '/settings/profile'],
+			['settings-preferences', '/settings/preferences'],
+			['settings-mcp', '/settings/mcp'],
+			['settings-users', '/settings/users'],
+			['settings-about', '/settings/about']
+		] as const) {
+			test(`Scenario: The ${name} page has no WCAG AA violations`, async ({ authenticatedPage: page }) => {
+				await visit(page, path);
+				await scan(page, name, theme);
+			});
+		}
+
+		test(`Scenario: Search results have no WCAG AA violations`, async ({ authenticatedPage: page }) => {
+			await visit(page, '/');
+			await page.getByTestId('search-input').fill('A11y');
+			await expect(noteCard(page, 'A11y coral')).toBeVisible();
+			await scan(page, 'search', theme);
+		});
+
+		test(`Scenario: The login page has no WCAG AA violations`, async ({ browser }) => {
+			const { context, page } = await anonymousPage(browser, theme);
+			await visit(page, '/login');
+			await expect(page.getByTestId('login-btn')).toBeVisible();
+			await scan(page, 'login', theme);
+			await context.close();
+		});
+
+		test(`Scenario: A publicly shared note has no WCAG AA violations`, async ({ authenticatedPage: page, browser }) => {
+			const notes = await (await page.request.get('/api/notes')).json();
+			const code = notes.find((n: { title: string }) => n.title === 'A11y code');
+			const { token } = await (await page.request.post(`/api/notes/${code.id}/share`)).json();
+			const { context, page: anon } = await anonymousPage(browser, theme);
+			await visit(anon, `/s/${token}`);
+			await expect(anon.getByTestId('shared-note-content')).toBeVisible();
+			await scan(anon, 'share', theme);
+			await context.close();
+		});
+	});
+}
+
+test.describe('Structure and keyboard (RGAA 8, 10, 12)', () => {
+	test.beforeEach(async ({ authenticatedPage: page }) => {
+		await seedNotes(page);
+	});
+
+	test('Scenario: Every page has a distinct, descriptive title (RGAA 8.5, 8.6)', async ({ authenticatedPage: page }) => {
+		const titles = new Map<string, string>();
+		for (const path of ['/', '/archive', '/trash', '/tag/audit', '/settings/profile', '/settings/preferences']) {
+			await visit(page, path);
+			titles.set(path, await page.title());
+		}
+		for (const [path, title] of titles) {
+			expect(title.trim(), `title of ${path}`).not.toBe('');
+		}
+		expect(new Set(titles.values()).size, `titles must differ per page: ${JSON.stringify([...titles])}`).toBe(titles.size);
+	});
+
+	test('Scenario: The app shell exposes header, navigation, main and footer landmarks (RGAA 12.6, 9.2)', async ({
+		authenticatedPage: page
+	}) => {
+		await visit(page, '/');
+		for (const selector of ['header, [role="banner"]', 'nav, [role="navigation"]', 'main, [role="main"]', 'footer, [role="contentinfo"]']) {
+			await expect(page.locator(selector).first(), selector).toBeAttached();
+		}
+	});
+
+	test('Scenario: A skip link lets keyboard users jump past the header and sidebar (RGAA 12.7)', async ({
+		authenticatedPage: page
+	}) => {
+		await visit(page, '/');
+		await page.keyboard.press('Tab');
+		const first = await page.evaluate(() => {
+			const el = document.activeElement as HTMLElement | null;
+			return { tag: el?.tagName, text: el?.textContent?.trim() ?? '', href: el?.getAttribute('href') ?? '' };
+		});
+		expect(first, 'first Tab stop should be a skip link to the main content').toMatchObject({ tag: 'A' });
+		expect(first.href).toMatch(/^#/);
+	});
+
+	test('Scenario: Every Tab stop on the notes page shows a visible focus indicator (RGAA 10.7)', async ({
+		authenticatedPage: page
+	}) => {
+		await visit(page, '/');
+		await expect(noteCard(page, 'A11y chalk')).toBeVisible();
+		const invisible: string[] = [];
+		const seen = new Set<string>();
+		for (let i = 0; i < 40; i++) {
+			await page.keyboard.press('Tab');
+			const info = await page.evaluate(() => {
+				const el = document.activeElement as HTMLElement | null;
+				if (!el || el === document.body) return null;
+				const s = getComputedStyle(el);
+				const key = el.tagName + '#' + (el.dataset.testid ?? el.getAttribute('aria-label') ?? el.textContent?.trim().slice(0, 20));
+				const hasOutline = s.outlineStyle !== 'none' && parseFloat(s.outlineWidth) > 0;
+				const hasRing = s.boxShadow !== 'none';
+				const hasBorderChange = el.matches(':focus-visible') && s.borderColor !== getComputedStyle(el.parentElement!).borderColor;
+				return { key, visible: hasOutline || hasRing || hasBorderChange };
+			});
+			if (!info || seen.has(info.key)) break;
+			seen.add(info.key);
+			if (!info.visible) invisible.push(info.key);
+		}
+		expect(seen.size, 'Tab must reach interactive elements').toBeGreaterThan(3);
+		expect(invisible, 'focused elements without a visible indicator').toEqual([]);
+	});
+
+	test('Scenario: Escape closes the editor and returns focus to the card that opened it (RGAA 7.3, 12.8)', async ({
+		authenticatedPage: page
+	}) => {
+		await visit(page, '/');
+		const card = noteCard(page, 'A11y coral');
+		await card.focus();
+		await page.keyboard.press('Enter');
+		await expect(page.getByTestId('note-editor')).toBeVisible();
+		await page.keyboard.press('Escape');
+		await expect(page.getByTestId('note-editor')).toBeHidden();
+		await expect(card).toBeFocused();
+	});
+
+	test('Scenario: Card action buttons are reachable and named for keyboard and screen-reader users (RGAA 7.1, 11.9)', async ({
+		authenticatedPage: page
+	}) => {
+		await visit(page, '/');
+		const card = noteCard(page, 'A11y coral');
+		const buttons = card.getByRole('button');
+		const count = await buttons.count();
+		expect(count, 'card should expose its actions as buttons').toBeGreaterThan(0);
+		for (let i = 0; i < count; i++) {
+			const name = await buttons.nth(i).evaluate((el) => {
+				const b = el as HTMLElement;
+				return b.getAttribute('aria-label') || b.textContent?.trim() || b.getAttribute('title') || '';
+			});
+			expect(name, `button ${i} on the card needs an accessible name`).not.toBe('');
+		}
+	});
+});