Accessibility Audit and WCAG 2.2 AA Remediation
epic-admin-portal-dashboard-ui-task-018 — Run flutter_accessibility_lint and manual screen-reader testing (TalkBack/VoiceOver) across all admin portal screens and panels. Ensure all interactive elements have semantic labels, the RoleAssignmentPanel confirmation dialog is fully keyboard and screen-reader navigable, stat widgets announce values correctly via live regions, and all color combinations meet WCAG 2.2 AA contrast ratios using the contrast-safe design token palette.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 7 - 84 tasks
Can start after Tier 6 completes
Implementation Notes
In Flutter, use the Semantics widget or the semanticsLabel property to add labels. For live regions, wrap stat value Text widgets with Semantics(liveRegion: true, child: ...) — this maps to ARIA live regions on web and announces value changes to screen readers. For the RoleAssignmentPanel dialog, use Flutter's AlertDialog which has built-in focus trapping; verify the dialog's actions array places the destructive action last. For color contrast, audit the design token palette file and map every token used in admin portal widgets — if any token fails 4.5:1, create a contrast-safe override token rather than hardcoding a fix.
Use MediaQuery.textScaleFactorOf(context) in widget tests to simulate large text. When adding semantic labels to icon buttons, prefer Tooltip + semanticsLabel over a raw Semantics wrapper as Tooltip automatically provides both visual and semantic labels. The flutter_accessibility_lint package must be added to dev_dependencies in pubspec.yaml and configured via analysis_options.yaml.
Testing Requirements
Three layers of testing required: (1) Automated — run flutter_accessibility_lint as a CI step; add widget tests using tester.getSemantics(find.byType(ElevatedButton)) to assert non-empty labels; use SemanticsController to verify live region properties; (2) Semi-automated — use Flutter's Semantics debugger (showSemanticsDebugger: true) to visually inspect semantic tree on device/emulator; (3) Manual — test each screen with VoiceOver on iOS 17+ and TalkBack on Android 13+, following WCAG 2.2 success criteria 1.3.1, 1.4.3, 2.1.1, 2.4.3, 4.1.2; document each test in an audit spreadsheet with status (pass/fail/N/A) and screenshot evidence. Contrast ratios must be verified with a contrast checker tool (e.g., Colour Contrast Analyser) against the design token hex values.
If org node selection in AdminStateBLoC does not correctly propagate to all dependent data streams (statistics, activity log, user list, certification panel), some panels may show data from the previously selected org scope, creating a confusing and potentially dangerous mixed-scope view.
Mitigation & Contingency
Mitigation: Model org node selection as a single source of truth in AdminStateBLoC. All downstream providers derive their query parameters from this single stream via Riverpod's watch pattern. Write integration tests that verify every data stream emits a reload event when the selected node changes.
Contingency: If scope propagation bugs are detected in QA, add an explicit full-state reset on org node change (clear all cached data and refetch from scratch) as a safe but less efficient fallback until the targeted propagation is fixed.
The Admin Dashboard Screen must adapt its layout for Flutter Web (wider viewports, mouse interaction, larger grid) and mobile embedding. Flutter Web responsive layout support has historically required non-trivial workarounds, and the adaptive grid may introduce significant additional development time.
Mitigation & Contingency
Mitigation: Define breakpoints and grid behaviour in the design system before implementation. Use LayoutBuilder with explicit breakpoint constants rather than MediaQuery scattered across widgets. Prototype the web layout with a skeleton screen before implementing live data binding.
Contingency: If web layout proves intractable within sprint, deliver a mobile-first layout for all platforms initially and track a dedicated web-optimisation task for the next sprint.
A bug in the Role Assignment Panel's permission scope validation could allow an org_admin to assign roles beyond their authority (e.g., assigning super_admin to a user), representing a serious privilege escalation vulnerability.
Mitigation & Contingency
Mitigation: Enforce role assignment scope on both the client (disable unavailable roles in the panel UI) and the server (UserManagementService validates the target role is within the admin's permitted scope before persisting). Write security-focused tests that attempt out-of-scope role assignments and assert rejection.
Contingency: If an escalation vulnerability is discovered, immediately disable the role assignment panel via feature flag, revoke any incorrectly assigned roles, and deploy a server-side fix before re-enabling.