Apply WCAG 2.2 AA accessibility across all three screens
epic-membership-recruitment-peer-mentor-ui-task-012 — Audit ReferralCodeScreen, RecruitmentStatsWidget, and NewMemberOnboardingScreen for WCAG 2.2 AA compliance. Verify contrast ratios using design token color palette, ensure all interactive elements have 48dp touch targets, add Semantics widgets where Flutter defaults are insufficient, and test with TalkBack and VoiceOver.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 5 - 253 tasks
Can start after Tier 4 completes
Implementation Notes
Start with a systematic audit pass: (1) list all interactive elements per screen, (2) measure touch targets using Flutter Inspector, (3) compute contrast ratios for each color pair from design tokens using WCAG formula. Use the Semantics widget to override default labels where Flutter's autogenerated label is insufficient (e.g. IconButton with only an icon needs a semanticLabel). For the stats widget, wrap each stat card in Semantics(label: '${stat.label}: ${stat.value}', child: ...) to give screen reader users the full value.
Use MergeSemantics where a label + value pair should be announced together. The AccessibilityPreferences data model should inform font scale — read accessibility_preferences.font_scale_factor via a Riverpod provider and inject into MediaQuery in the onboarding flow. Avoid using Opacity widget for disabled states; use ExcludeSemantics or IgnorePointer with appropriate Semantics instead.
Testing Requirements
Automated: add widget tests using meetsGuideline(androidTapTargetGuideline) and meetsGuideline(iOSTapTargetGuideline) for each screen. Write contrast ratio verification tests using the design token color values (compute ratio in test, assert >= 4.5). Test large text mode by overriding MediaQuery textScaleFactor to 1.5 and asserting no RenderOverflow. Manual: execute TalkBack walkthrough on Android emulator and VoiceOver walkthrough on iOS simulator, documenting each interactive element's announced label.
Record findings in a checklist and fix before marking task complete.
QR codes rendered at the minimum 200×200 size may fail to scan under typical indoor lighting conditions on older or lower-resolution phone cameras, causing recruitment moments to fail when a peer mentor shows the screen to a prospective member.
Mitigation & Contingency
Mitigation: Set the default QR render size to 260×260 logical pixels (not the 200px minimum) and apply a high-contrast white module background. Test scan reliability on at minimum three physical devices (budget Android, mid-range Android, iPhone SE) before marking the screen as done.
Contingency: If scan reliability remains an issue, add a 'Enlarge QR' full-screen mode triggered by tapping the code, and ensure the text referral URL with copy-to-clipboard is always visible as a fallback sharing method.
The onboarding screen submits attribution and then hands off to an external membership registration URL (HLF's Dynamics portal or similar). If the external URL is unavailable, changes its format, or requires authentication the new member does not have, the conversion funnel is broken at its final step.
Mitigation & Contingency
Mitigation: Confirm the external registration URL and its expected query parameters with HLF's portal team before implementing the handoff. Record the pending_signup attribution event before launching the URL so data is not lost if the external site fails. Display a fallback message with contact information if the URL launch fails.
Contingency: If the external membership URL is not available at feature launch, implement a temporary form that collects name and email and stores a pending_member record in Supabase, allowing coordinators to manually complete registration while the integration is finalised.
Embedding the RecruitmentStatsWidget on the peer mentor home screen may conflict with existing layout components (activity summary, badge shelf), causing overflow or requiring a redesign of the home screen that is outside this epic's scope.
Mitigation & Contingency
Mitigation: Design the widget as a horizontally constrained card with a maximum height of 96dp so it can be inserted into any vertical list without overflow. Coordinate with the home screen's existing layout owners before starting the embedding task.
Contingency: If home screen embedding creates unacceptable layout conflicts, defer embedding to a separate home-screen redesign task and make the widget accessible only via the dedicated ReferralCodeScreen for the initial release.