Implement outlier highlighting in team summary view
epic-periodic-summaries-ui-task-009 — Integrate the outlier detection output into the CoordinatorTeamSummaryView to visually highlight mentors who are underperforming or at risk. Render distinct badges and row background tints for outliers. Add a filter toggle to show only outliers. Ensure the highlighting is accessible with sufficient contrast ratios per WCAG 2.2 AA and includes semantic labels for screen readers.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 4 - 323 tasks
Can start after Tier 3 completes
Implementation Notes
Define an OutlierSeverity enum (none, warning, error) derived from outlier_reason in a presentation mapper function, not in the BLoC or data layer. Map: 'At Risk' → warning, 'Overdue' → error, others → warning by default. OutlierBadge should use a Container with a design token background color and a Text with contrasting foreground token. Wrap the badge in Semantics(label: 'Outlier status: ${reason}', child: badge) to provide meaningful screen reader output — the visual label alone may be insufficient for low-vision users.
For the row tint, use a ColoredBox or DecoratedBox wrapping the MentorSummaryRow — avoid setting color on the ListTile directly as it has poor semantics. Keep the filter toggle state in the BLoC (FilterByOutlier event), not in local widget state, so that navigating away and back preserves the filter selection.
Testing Requirements
Widget tests: verify badge is rendered only when isOutlier is true; verify badge is absent for non-outlier rows; verify filter toggle dispatches FilterByOutlier event; verify empty state message appears when filter is active with zero outliers; verify Semantics label on badge is present and non-empty. Accessibility tests: use flutter_test's SemanticsHandle to verify semantic tree includes outlier badge labels. Manual QA checklist: run WCAG color contrast checker on badge color pairs (text + background) for both warning and error severity in light and dark modes. Golden tests: captured renders for rows with and without outlier highlighting, both themes.
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.