crumbs/docs/ACCESSIBILITY.md

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).

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.