Add VoiceOver/TalkBack descriptions to milestone badge
epic-annual-impact-summary-ui-components-task-009 — Wire SummaryAccessibilityProvider into MilestoneBadgeWidget to attach Semantics with the generated announcement strings for both locked ('Badge locked: [name]. Requirement: [criterion]') and unlocked ('Badge earned: [name]. [description]') states. Ensure focus order is logical when badges appear in a shelf layout.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 3 - 413 tasks
Can start after Tier 2 completes
Implementation Notes
Wrap the entire badge content in a single Semantics widget with label and excludeSemantics:false; wrap all internal decorative elements (image, icon, gradient overlay) with ExcludeSemantics. Pull announcement strings from SummaryAccessibilityProvider via a Riverpod Consumer or ref.watch — do not construct strings inside the widget. For the live announcement on unlock, use a didUpdateWidget lifecycle check: if oldWidget.badge.isUnlocked == false && widget.badge.isUnlocked == true, call SemanticsService.announce(label, TextDirection.ltr) after the frame. Do not use liveRegion:true on the Semantics node itself as this can cause double-announcements on some platforms; prefer the explicit announce call.
For shelf layout focus order, rely on the natural widget tree order (left-to-right rendering) — do not use sortKey unless the visual order genuinely differs from the tree order. This task is marked critical because Blindeforbundet users depend entirely on screen readers.
Testing Requirements
Widget tests using flutter_test and SemanticsController: (1) assert that tester.getSemantics(find.byType(MilestoneBadgeWidget)).label equals the locked format string when badge.isUnlocked=false; (2) assert the unlocked format string when badge.isUnlocked=true; (3) assert decorative child widgets have no semantics label (excludeSemantics); (4) simulate state change from locked→unlocked and assert SemanticsService.announce was called with the unlocked string. Use TestSemantics matchers. No golden tests required. Accessibility audit: run Flutter's SemanticsChecker in debug mode and confirm no warnings.
Simultaneous count-up animations across multiple stat cards and chart draw-in animations on lower-end Android devices may cause frame drops below 60fps, degrading the premium Wrapped experience and making the feature feel unpolished.
Mitigation & Contingency
Mitigation: Stagger animation starts using AnimationController with staggered intervals rather than starting all animations simultaneously. Use RepaintBoundary around each animated widget to isolate rasterisation. Profile on a mid-range Android device (e.g., equivalent to Pixel 4a) during development, not just at QA.
Contingency: If frame rate targets cannot be met on low-end devices, implement a device-capability check at startup and substitute simpler fade-in animations for the count-up and chart draw-in on devices below a CPU performance threshold.
The activity-type-breakdown-widget must render organisation-specific activity type labels sourced from the terminology system. If the terminology provider is not yet integrated at the time this widget is built, the widget will display hardcoded system labels, which is a regression risk for multi-org support.
Mitigation & Contingency
Mitigation: Accept activity type labels as a typed parameter in the widget constructor rather than reading from the terminology provider directly inside the widget. The BLoC or repository layer resolves labels before passing them to the widget, maintaining clean separation and testability.
Contingency: If terminology resolution is unavailable at widget integration time, display internal activity type keys as a temporary fallback with a localised suffix '(label pending)' visible only in non-production builds so QA can identify unresolved labels.