Implement PeerMentorProfileHeader avatar widget

epic-peer-mentor-detail-screen-ui-components-task-007 — Build PeerMentorProfileHeader with a circular avatar that loads from a remote URL and falls back to generated initials in a colored circle when the image is null or fails to load. Include the mentor's display name, org role label (sourced from OrgLabelsProvider), and primary status badge slot. Apply error-state styling (e.g., red border ring) when the mentor's HLF cert is expired.

high priority low complexity frontend pending frontend specialist Tier 2

Acceptance Criteria

When a valid avatar URL is provided, the widget loads and displays the image in a circular clip without visible corners or overflow

When the avatar URL is null or the image fails to load (network error, 404), the widget shows a colored circle containing the mentor's initials (first letter of first name + first letter of last name, uppercased)

The initials background color is deterministically generated from the mentor's display name (e.g., name hash mod palette length) — the same name always produces the same color

The mentor's display name is rendered below the avatar using a style consistent with the design token typography scale

The org role label is sourced from OrgLabelsProvider and reflects the correct terminology for the active organization

A primary status badge slot is rendered; when no badge data is provided the slot is empty and takes no vertical space (does not leave a gap)

When the mentor's HLF cert is expired, a red border ring is applied around the avatar circle with a width and color matching the design spec

Widget renders correctly at all standard screen widths (320dp–428dp) without overflow

Widget is stateless and receives all data via constructor parameters — no internal data fetching

Technical Requirements

frameworks

Flutter

flutter_test

data models

PeerMentor (displayName, avatarUrl, hlf certification status)

OrgLabelsProvider (org role label lookup)

performance requirements

Avatar image loading must not block the UI thread — use cached_network_image or Flutter's Image.network with loadingBuilder

Initials fallback must render synchronously with no async gap

security requirements

Avatar URL must be loaded over HTTPS only — reject HTTP URLs silently and fall back to initials

ui components

CircleAvatar or ClipOval with Image.network / cached_network_image

Text widget for initials fallback

Container with BoxDecoration for the red error-state ring

OrgLabelsProvider (existing, from task-002 dependency)

Status badge slot widget (accepts nullable child)

Execution Context

Execution Tier

Tier 2

Tier 2 - 518 tasks

Can start after Tier 1 completes

View Full Execution Plan

Implementation Notes

Create PeerMentorProfileHeader as a StatelessWidget accepting: String? avatarUrl, String displayName, bool hlfCertExpired, Widget? statusBadge, and a BuildContext-based org label resolution. For the initials color, implement a deterministic hash: take displayName.hashCode, take its absolute value, and index into a fixed list of design-token-approved background colors (avoid red/green to not conflict with status semantics).

For the avatar, use a Stack: bottom layer is the initials circle, top layer is the network image (which becomes invisible on error). This avoids a flicker from showing initials then switching to image — instead the image sits on top and the initials are always rendered beneath. For the red ring, wrap the avatar stack in a Container with BoxDecoration(shape: BoxShape.circle, border: Border.all(color: tokenColorError, width: 2.0)) conditionally. The status badge slot should be: if (statusBadge != null) statusBadge else const SizedBox.shrink().

Source org role label via context.read().peerMentorRoleLabel or equivalent — do not hardcode 'Peer Mentor'.

Testing Requirements

Write widget tests using flutter_test. Test 1: pass a null avatarUrl — assert initials text is displayed and no Image widget is in the tree. Test 2: simulate image load error via a fake network image provider — assert fallback initials appear. Test 3: pass hlfCertExpired: true — assert a Container/DecoratedBox with a red border is present in the widget tree.

Test 4: pass hlfCertExpired: false — assert no red border container exists. Test 5: verify OrgLabelsProvider returns the correct role label by injecting a mock provider. Test 6: pass a null status badge — assert the badge slot renders with zero height. Golden tests are optional but recommended for the avatar + initials fallback for visual regression.

Component

Peer Mentor Profile Header

ui low

Dependencies (2)

Extend OrgLabelsProvider to supply hardcoded fallback terminology strings when the Supabase stream is unavailable or returns null values. Define a LabelDefaults constant map covering all label keys used across peer mentor detail widgets, ensuring graceful degradation for offline or unconfigured orgs. epic-peer-mentor-detail-screen-ui-components-task-002 Build the CertificationStatusBadge as a pill-shaped Flutter widget that derives its visual state (valid, expiring-soon, expired) from an expiry date prop using design tokens for colors and typography. Implement compact and full size variants controlled by a size enum prop. Use design token color variables — never hardcoded hex values. epic-peer-mentor-detail-screen-ui-components-task-003

Epic Risks (2)

medium impact medium prob dependency

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.

high impact low prob technical

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.

Quick Links

All Tasks Execution Plan