Add semantics and WCAG compliance to ProfileHeader
epic-peer-mentor-detail-screen-ui-components-task-008 — Add merged Semantics to PeerMentorProfileHeader so VoiceOver reads the header as a single announcement: name, role, and certification status combined. Verify avatar fallback initials have sufficient contrast against their generated background color. Ensure the error-state HLF cert ring color passes AA contrast against both light and dark backgrounds.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 3 - 413 tasks
Can start after Tier 2 completes
Implementation Notes
Wrap PeerMentorProfileHeader's root widget in a MergeSemantics widget, then add a Semantics widget immediately inside it with a computed label string: '$displayName, $orgRoleLabel, ${hlfCertExpired ? "HLF certification expired" : "Active"}'. The MergeSemantics will absorb all child semantics nodes into one. Wrap the avatar image (not the initials text) in ExcludeSemantics to prevent the image from contributing a redundant node.
For the initials palette contrast check: write a test helper computeContrastRatio(Color foreground, Color background) using the WCAG luminance formula — this is straightforward arithmetic and does not require external packages. For the ring color: if the current design token for error (typically a red) fails 3:1 on dark backgrounds, introduce a separate dark-mode error ring token (slightly lighter red). Coordinate with task-007 implementor to ensure the palette array is exported as a const so the test can iterate over it directly.
Testing Requirements
Write widget tests using flutter_test. Test 1: render header with hlfCertExpired: false — call tester.getSemantics(find.byType(PeerMentorProfileHeader)) and assert the label equals the expected merged string (name + role + 'Active'). Test 2: render with hlfCertExpired: true — assert the label contains 'certification expired' or equivalent. Test 3: assert that no descendant of PeerMentorProfileHeader has an independent SemanticsNode with a non-empty label (i.e., MergeSemantics is working — only one node visible to the accessibility tree).
Test 4: iterate over all colors in the initials palette and assert each passes the 4.5:1 contrast ratio against the initials text color using a helper function. Manual VoiceOver and TalkBack testing required on device — document in PR.
The org labels system may not yet have label keys defined for peer mentor detail screen terminology (role labels, section headings), requiring additions to the label key registry that must be coordinated with the admin configuration team.
Mitigation & Contingency
Mitigation: Audit existing label keys in the terminology system before starting OrgLabelsProvider integration. Submit required new label keys for admin configuration in parallel with component implementation.
Contingency: If label keys are not available at integration time, use hardcoded English fallbacks with a clear TODO for admin configuration, ensuring the widget renders correctly while keys are being provisioned.
The design token semantic colors (warning, error surface) may not meet WCAG 2.2 AA 4.5:1 contrast ratio when rendered on the app's background surface tokens, requiring design system changes that affect the entire app.
Mitigation & Contingency
Mitigation: Run contrast ratio validation on the token palette during Epic 1 design token implementation. Flag any failing pairs to the design system owner before building UI components that depend on them.
Contingency: If tokens fail contrast requirements, define supplementary high-contrast override tokens specific to alert and badge contexts that meet AA without modifying the global palette.