Implement WCAG 2.2 AA accessibility across all widgets
epic-periodic-summaries-ui-task-011 — Audit and remediate all three widgets (PeriodicSummaryCard, CoordinatorTeamSummaryView, PeriodComparisonWidget) for WCAG 2.2 AA compliance. Add Semantics wrappers with meaningful labels for all interactive elements, delta indicators, and outlier badges. Verify VoiceOver (iOS) and TalkBack (Android) read content in logical order. Ensure all touch targets meet minimum 44x44pt requirement. Validate contrast ratios for all text and badge colors.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 6 - 158 tasks
Can start after Tier 5 completes
Implementation Notes
Start with an audit pass: run the app on a simulator with Accessibility Inspector (Xcode) enabled and note all elements lacking labels or with insufficient touch targets. Common Flutter accessibility pitfalls to fix: (1) Icon buttons without Tooltip or Semantics(label:...) — always add; (2) Row widgets mixing text and icons where VoiceOver reads them in wrong order — use MergeSemantics; (3) Color-only status indicators (green dot, red badge) — always add a text label in the Semantics tree even if visually hidden; (4) ListTile onTap without a semantic label — add Semantics(label: 'Mentor: ${name}, tap to view details'). For the 44×44 requirement: wrap icon buttons in SizedBox(width: 44, height: 44, child: IconButton(...)) and verify InkWell tap areas. Document all contrast ratio checks as a markdown table in a comment on the PR for reviewer verification.
The project is used by Blindeforbundet members who rely on VoiceOver — this task has real user impact.
Testing Requirements
Automated accessibility tests using flutter_test with SemanticsHandle: verify semantic labels exist on all interactive elements; verify delta indicators have non-empty label strings; verify touch targets are at least 44×44 by asserting widget constraints. Manual QA on a physical iOS device with VoiceOver enabled: record navigation order through the mentor list and compare against visual order. Manual QA on a physical Android device with TalkBack enabled. Use a color contrast analyzer tool (e.g., Colour Contrast Analyser desktop app) to verify all design token color pairs used for badges and text against WCAG 2.2 AA thresholds — document results.
Run flutter test --verbose and check for AccessibilityGuideline violations using AccessibilityGuideline.androidScrollable.
If the cached summary is from a prior period (e.g., previous quarter's card is still cached), the digest card could appear on the home screen with outdated numbers after a new period begins, confusing users who have already seen that data.
Mitigation & Contingency
Mitigation: In the SummaryCacheRepository, store the period_start and period_end alongside cached data. In the PeriodicSummaryCard BLoC, compare the cached record's period against the current date using PeriodCalculatorService. Only render the card if the cached summary belongs to the active period.
Contingency: If stale cards appear in production, push a hotfix that adds the period validity check to the BLoC and clears all cached summaries older than the current period boundary via a forced cache flush on next app launch.
Using colour alone to distinguish underactive from overloaded mentors in the coordinator view would fail WCAG 1.4.1 (use of colour). This is especially critical for organisations serving users with colour vision deficiency.
Mitigation & Contingency
Mitigation: Always pair colour indicators with a text label or icon (e.g., a downward arrow + 'Underactive' text alongside the amber colour). Use the contrast-safe-color-palette design tokens throughout. Run the contrast-ratio-validator on all new colour combinations in CI.
Contingency: If an accessibility audit flags colour-only indicators post-launch, introduce icon-based indicators as a patch release and update the design token definitions to enforce the paired-indicator pattern going forward.
Inserting a new card into the role-based home screen requires changes to shared home screen widget composition, which may conflict with parallel feature branches also modifying the home screen layout, causing merge conflicts and integration delays.
Mitigation & Contingency
Mitigation: Implement the PeriodicSummaryCard as a fully self-contained widget that the home screen conditionally renders based on a BLoC state flag. Minimise changes to the home screen itself to a single conditional insertion point, reducing the surface area for merge conflicts.
Contingency: If integration conflicts block the PR, isolate the card behind the organisation-scoped feature flag so it can be toggled independently and merged without affecting other home screen changes.