WCAG 2.2 AA accessibility audit for all role UI components
epic-role-based-access-control-ui-and-navigation-task-012 — Conduct a full WCAG 2.2 AA accessibility audit across all role-driven UI components: Role-Based Home Screen variants, Role Switch Widget, Role-Aware Bottom Navigation, No-Access Screen, and Route Guard redirect targets. Verify semantic labels, focus management, contrast ratios, touch target sizes (minimum 44x44dp), and screen reader announcement flows using flutter_test accessibility matchers.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 6 - 158 tasks
Can start after Tier 5 completes
Implementation Notes
Start with a Semantics audit pass using Flutter's built-in SemanticsDebugger widget in a debug build to visually inspect the semantics tree before writing automated tests. Pay special attention to the Role Switch Widget: role changes are asynchronous (BLoC state transition), so ensure the Semantics announcement fires after the new state is emitted, not before. For the No-Access Screen, wrap the admin portal link in an ExcludeSemantics/MergeSemantics pair if needed to avoid double-reading icon + label. For contrast ratio: do not hardcode color values in tests — read from design tokens (AppColors / ThemeData) so tests remain valid if tokens change.
Touch target enforcement: prefer wrapping small icons with a SizedBox of at least 44×44 and using GestureDetector's HitTestBehavior.opaque. Document all WCAG criterion codes (e.g., 1.4.3, 2.4.3) in test comments for traceability. This is especially critical given that Blindeforbundet (screen reader users) and NHF (cognitive accessibility for stroke survivors) are key user groups.
Testing Requirements
Use flutter_test with tester.getSemantics() and SemanticsFlag assertions to validate each component. Write one test group per component covering: (1) contrast ratio via design token verification, (2) touch target size via tester.getSize(), (3) Semantics label presence and correctness, (4) focus traversal order using FocusTraversalGroup assertions, (5) screen reader announcement on state change. Run tests on both iOS (VoiceOver) and Android (TalkBack) simulator configurations. Produce a CI-compatible report; audit must pass before the task is marked complete.
Minimum coverage: all 5 audited component groups, all role variants.
Combining GoRouter's declarative redirect logic in the route guard with StatefulShellRoute's stateful branch management is known to produce subtle bugs where the shell rebuilds unnecessarily on role switches, losing tab state or causing double-navigation events.
Mitigation & Contingency
Mitigation: Implement the route guard as a GoRouter redirect callback that only evaluates role from an already-resolved Riverpod provider (not async). Use a dedicated ShellRoute navigator key per tab branch to anchor state independently of role-driven rebuilds. Write integration tests for the full navigation graph.
Contingency: If StatefulShellRoute state loss is confirmed during QA, fall back to a manual tab state preservation approach using a TabStateManager service that caches the last route per tab and restores it after role switches, decoupling tab state from the shell lifecycle.
The role-based home screen must render three significantly different layouts (coordinator dashboard, peer mentor activity summary, org admin overview). If these variants are implemented as a single widget with conditionals, the file will become unmaintainable and difficult to test in isolation, especially as each variant grows with downstream feature additions.
Mitigation & Contingency
Mitigation: Design the role-based home screen as a router/dispatcher widget that delegates to three separate variant widgets (CoordinatorHomeView, PeerMentorHomeView, OrgAdminHomeView). Each variant is independently testable and can be developed by separate team members in parallel.
Contingency: If variant coupling has already occurred before this risk is addressed, refactor to the dispatcher pattern in a dedicated cleanup task before feature handoff. The dispatcher pattern is a straightforward extraction that carries low refactoring risk.
The no-access screen must link global admin users to the correct admin portal URL, which may differ per organization (NHF, HLF, Blindeforbundet each have their own admin portals). Hardcoding a single URL will result in wrong or broken links for some global admin users.
Mitigation & Contingency
Mitigation: Source the admin portal URL from the organization's configuration record in Supabase rather than hardcoding it. The no-access screen reads the active org context and resolves the portal URL dynamically. Provide a safe fallback to a generic Norse Digital Products support page if the URL is not configured.
Contingency: If dynamic URL resolution is not ready when the no-access screen ships, display a static instruction to contact the organization's administrator along with a support email address as an interim measure, and track the URL configuration task as a follow-up.