Initial curated itworx-knowledge-hub source from 3b1751d0d9dee551aa6994eee0093704dc334817

docs/21-accessibility.md

@@ -0,0 +1,106 @@
+# Accessibility
+
+## Standard
+
+Target WCAG 2.2 AA for all implemented user flows.
+
+Automated tests are necessary but not sufficient. Each milestone with UI changes includes
+manual keyboard review; M8 includes representative screen-reader checks.
+
+## Global requirements
+
+- Semantic HTML first.
+- One logical `h1` per page view.
+- Landmarks for header, navigation, main and complementary content.
+- Skip link.
+- Visible focus meeting contrast/area requirements.
+- Logical DOM and tab order.
+- No keyboard trap.
+- 200% zoom without loss of function.
+- Reflow at 320 CSS px width except genuinely two-dimensional content.
+- Minimum target size or adequate spacing.
+- Text contrast and non-text contrast.
+- Status not conveyed by color alone.
+- Accessible names for icon-only controls.
+- Form labels, instructions and error association.
+- Live regions only for concise relevant updates.
+- Reduced motion.
+- Language set to `nl-BE`, with code/foreign fragments where appropriate.
+
+## Navigation tree
+
+Implement the WAI-ARIA tree pattern only if the team can meet its complete keyboard model.
+A nested disclosure/list pattern is acceptable and often simpler.
+
+Required operations:
+
+- Tab enters/leaves the tree predictably.
+- Arrow or disclosure controls expand/collapse.
+- Current page is announced.
+- Actions are reachable without context menu/right-click.
+- Drag-and-drop has move-dialog/keyboard equivalent.
+- Loading more children is announced.
+
+## Editor
+
+- Text area/editor exposes a usable label and instructions.
+- Toolbar controls have names and pressed state.
+- Shortcuts do not conflict with browser/assistive technology and are documented.
+- Preview mode is a distinct region.
+- Heading outline is navigable.
+- Autosave and publish state are announced without excessive interruption.
+- Validation errors link to the relevant metadata/editor location.
+- Conflict UI explains versions and preserves text.
+- Markdown source remains available; no inaccessible rich-editor-only content.
+
+## Markdown rendering
+
+- Heading hierarchy is validated/warned.
+- Tables have accessible overflow and author guidance for headers.
+- Code blocks have language labels where known.
+- Copy action is labeled and reports success.
+- Images require alt text or explicit decorative status.
+- Mermaid diagrams require an author-provided text description or alternative.
+- Link text must be understandable in context.
+- Deprecated/warning notices use semantic status patterns.
+
+## Dialogs and sheets
+
+- Initial focus is intentional.
+- Focus is trapped only while modal.
+- Escape closes when safe.
+- Focus returns to trigger.
+- Title/description relationships are correct.
+- Destructive confirmation names the target and consequence.
+- Token/recovery secret dialogs prevent accidental loss and provide copy confirmation.
+
+## Search and dynamic results
+
+- Search input has label and clear action.
+- Result count/loading changes are announced politely.
+- Keyboard focus does not jump on every keystroke.
+- Filters are reachable and stateful.
+- Highlighting is not the only relevance cue.
+- Empty/no-results states are announced.
+
+## Testing matrix
+
+Automated:
+
+- axe-core on primary routes and important dialogs;
+- eslint accessibility rules;
+- component semantics where stable;
+- Playwright keyboard flows;
+- color-token contrast tests where practical.
+
+Manual at M8:
+
+- keyboard-only complete journeys;
+- Chromium with a screen reader on login, tree, page read/edit, search, project, import
+  report and backup status;
+- 200% zoom;
+- reduced motion;
+- dark/light mode;
+- mobile touch and software keyboard.
+
+Every exception requires documented user impact and an accepted remediation plan.