a11y: establish cross-surface accessibility acceptance matrix for editor, PWA and native renderers

[qnbs]

Context

ROADMAP.md includes an Accessibility deep-dive in the v2.0 Foundation. Existing issues are more narrowly scoped:

• [Bug]: AI Writing Studio text is unreadable #341 tracks a concrete readability/theme regression and its current closure evidence;
• pwa(first-class): harden offline reliability, lifecycle, performance, install/update UX & browser-native AI #478 owns PWA-specific accessibility, theme, mobile and VRT acceptance;
• [Desktop/Tauri→Qt]: Linux responsiveness, Alt-Tab hang & memory — cross-renderer acceptance baseline #332 owns cross-renderer desktop/Tauri→Qt acceptance where renderer-specific defects are relevant.

There is currently no durable cross-surface acceptance owner for the product-wide accessibility contract itself.

Goal

Define and enforce one accessibility acceptance matrix for the core writing experience while allowing renderer-specific implementation details to remain in their proper issues/adapters.

This issue is not a generic bug bucket. Concrete defects should still receive focused issues. This tracker owns shared acceptance/evidence and cross-surface parity.

Core user journeys

At minimum audit and test:

• first launch / Welcome Portal;
• open/create/import project;
• project navigation/sidebar/binder;
• editor writing/selection/formatting;
• dialogs, menus, command palette and settings;
• save/autosave/offline/recovery/update status;
• character/world/outline/manuscript navigation;
• export/backup flows;
• AI/local-model state where status/action is user-visible;
• collaboration/local-first state where enabled.

Keyboard and focus

Require deterministic keyboard-only operation for primary workflows:

• logical tab order;
• visible focus;
• no keyboard traps;
• Escape/close behavior;
• focus restoration after dialogs, popovers, navigation and destructive-confirmation flows;
• editor shortcuts do not consume navigation keys unexpectedly;
• skip/navigation affordances where the shell benefits from them.

Focus behavior must be tested after asynchronous UI transitions, not only static render.

Screen-reader semantics

Audit:

• landmark/navigation structure;
• names/roles/values;
• form labels/descriptions/errors;
• dynamic save/recovery/offline/update/model status announcements;
• dialogs and modal ownership;
• editor semantics and selected/current state;
• loading/progress/busy states;
• tables/lists/trees where used;
• icon-only controls.

Avoid duplicate live-region announcements and role="alert" overuse.

Visual/readability acceptance

Coordinate with #341 rather than duplicating its specific regression:

• text/background contrast for supported themes;
• placeholder/disabled/secondary text;
• editor caret/selection/focus indicators;
• forced/high-contrast modes where supported;
• reduced transparency;
• reduced motion;
• zoom/text scaling;
• font-size/line-height controls;
• no content/action loss at large text/zoom.

Use deterministic contrast/readability oracles where possible, not screenshots alone.

Responsive / mobile / virtual keyboard

PWA-specific details remain in #478, but shared acceptance should include:

• viewport resize without inaccessible hidden actions;
• virtual keyboard/editor coexistence;
• touch target sizing;
• safe-area behavior;
• orientation changes;
• zoom without horizontal traps where avoidable.

Native / Qt admission

Do not start Qt implementation from this issue.

When Qt is admitted by the native roadmap, require the same semantic acceptance for:

• keyboard/focus behavior;
• accessible names/roles/states through Qt accessibility APIs;
• screen-reader operation on supported desktop OSes;
• high-contrast/system settings;
• reduced-motion/system preference mapping where applicable.

Qt is allowed native implementation strengths; parity is behavioral, not DOM-equivalent markup.

Automated and manual evidence

Use a layered evidence model:

STATIC/UNIT ARIA CONTRACT
KEYBOARD INTEGRATION
AXE/AUTOMATED RULES
CONTRAST/READABILITY ORACLES
E2E FOCUS/STATUS FLOWS
REPRESENTATIVE SCREEN-READER MANUAL CHECK
NATIVE PLATFORM CHECK WHEN ADMITTED

Automated scanners are necessary but not sufficient for editor/screen-reader usability.

Acceptance criteria

• A current accessibility support/acceptance matrix exists for major product workflows.
• Primary writing workflows are keyboard-operable with deterministic focus restoration.
• Dynamic save/offline/recovery/update/model states have correct non-duplicative announcements.
• Supported themes and accessibility presets pass deterministic readability/contrast acceptance.
• Zoom/text scaling/reduced-motion/high-contrast behavior is documented and tested where supported.
• PWA-specific acceptance reconciles pwa(first-class): harden offline reliability, lifecycle, performance, install/update UX & browser-native AI #478 instead of duplicating it.
• Known readability defect tracking remains in [Bug]: AI Writing Studio text is unreadable #341.
• Renderer-specific desktop defects remain linked to [Desktop/Tauri→Qt]: Linux responsiveness, Alt-Tab hang & memory — cross-renderer acceptance baseline #332 where appropriate.
• Qt admission includes equivalent semantic accessibility acceptance before stable native release.
• Remaining concrete defects are split into focused issues with reproducible user impact.

Non-goals

• treating every accessibility defect as one mega-ticket;
• closing [Bug]: AI Writing Studio text is unreadable #341 by declaration;
• forcing Qt to copy DOM implementation details;
• adding arbitrary ARIA solely to satisfy static tooling;
• making accessibility evidence dependent on one browser only.

[qnbs]

Focused defect split created as #565 from PR #564 CI/CD #2571 (0865895f...): Welcome/Home Axe contrast failures persist across retries with serious WCAG-AA violations (observed ratios down to 1.14:1). This is independent of the R-15 docs diff and is now tracked separately per this umbrella's policy. #565 owns the concrete remediation; #557 remains the cross-surface acceptance/evidence owner.