WCAG 2.2 AA audit and accessibility pass for all cert screens
epic-certification-management-ui-task-011 — Run a full WCAG 2.2 AA accessibility audit across CertificationStatusScreen, RecordRenewalScreen, and CertificationsExpiringWidget. Verify contrast ratios meet 4.5:1 for normal text and 3:1 for large text using the contrast-safe color palette. Add semantics labels to all interactive elements, fix focus order on RecordRenewalScreen form, and add live region announcements for status changes and form submission feedback.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 5 - 253 tasks
Can start after Tier 4 completes
Implementation Notes
Start by running Flutter's built-in accessibility checker: wrap each screen's test with `expect(tester, meetsGuideline(textContrastGuideline))` to get an automated baseline. For live regions, use `SemanticsService.announce(message, textDirection)` inside BLoC state listeners — avoid announcing on every rebuild, only on meaningful state transitions (idle→loading→success/error). Fix focus order on RecordRenewalScreen by wrapping the form in a FocusTraversalGroup with an OrderedTraversalPolicy, assigning FocusTraversalOrder widgets to each label+field pair. For the CertificationsExpiringWidget, expiry urgency (e.g., 'expires in 3 days') should be encoded in the Semantics label string directly so color-blind and screen reader users get the same information.
Use MergeSemantics around icon+label pairs to prevent double-reading. Avoid ExcludeSemantics on decorative elements that happen to carry state information — audit each exclusion manually. All contrast values should be pulled from the AccessibilityDesignTokenEnforcer (task epic-cognitive-accessibility-foundation-task-005) once available; until then, assert against hardcoded WCAG thresholds.
Testing Requirements
Unit tests: write flutter_test widget tests for each screen asserting semantics tree structure — use tester.getSemantics() to verify labels, roles, and live region flags on key nodes. Contrast tests: write a helper that reads design token color pairs and asserts minimum contrast ratios using the WCAG relative luminance formula; run it as a unit test to prevent regressions. Integration tests: perform a full screen traversal simulation using AccessibilityGuideline assertions (meetsGuideline(androidTapTargetGuideline), meetsGuideline(iOSTapTargetGuideline), meetsGuideline(labeledTapTargetGuideline)). Manual tests: conduct a full VoiceOver walkthrough on a physical iOS device covering all three screens, including form submission and expiry state changes; document findings in a checklist.
Regression: add these tests to CI so any future widget change that breaks semantics is caught before merge.
Flutter date pickers have historically poor screen reader support (VoiceOver/TalkBack), which is especially critical for this feature given that HLF peer mentors may have hearing impairment and the broader user base includes people with visual impairments. An inaccessible date picker on RecordRenewalScreen could block coordinator workflows entirely.
Mitigation & Contingency
Mitigation: Evaluate and adopt a third-party accessible date picker widget with verified WCAG 2.2 AA support, or build a custom picker using Flutter Semantics wrappers following the pattern established by the accessibility epic. Test all date pickers against VoiceOver on iOS and TalkBack on Android before UI sign-off.
Contingency: If no accessible date picker is available in time, provide a manual text field fallback for date entry (ISO format with clear labelling) alongside the picker, ensuring keyboard and screen reader users are never blocked.
Course enrolment initiation may redirect the user to the external HLF course portal (deep link or browser), which breaks the in-app flow and may confuse users expecting a seamless experience. The course data structure from Dynamics may also not be available in a machine-readable format in time for the initial release.
Mitigation & Contingency
Mitigation: Agree with HLF on whether enrolment is in-app or via deep link before UI design begins. If course data is not available from Dynamics at launch, design the enrolment prompt as a placeholder CTA that links to the HLF course portal homepage with a clear label indicating the user is leaving the app.
Contingency: Ship the course enrolment prompt as a configurable deep link per org. If Dynamics integration is delayed, the feature flag for the enrolment section can be disabled without affecting the rest of the certification status screen.
Coordinators may attempt to record a renewal with an expiry date earlier than the previous certification's expiry (e.g., data entry error), or attempt to back-date a renewal. Without strict validation, the renewal history timeline could become chronologically inconsistent and mislead peer mentors about their coverage.
Mitigation & Contingency
Mitigation: CertificationManagementService validates that new expiry_date > current date and new issue_date >= previous renewal's issue_date before persisting. Surface validation errors as plain-language messages on RecordRenewalScreen using the error_message_registry pattern.
Contingency: If invalid renewal entries are discovered in production (from pre-validation data), provide a coordinator-only correction flow (edit renewal entry) behind an admin feature flag to fix historical records without requiring a full reset.