Accessibility audit: focus order and semantics
epic-annual-impact-summary-orchestration-task-016 — Conduct a full WCAG 2.2 AA accessibility audit of WrappedSummaryScreen. Verify logical focus traversal order through slides, progress indicator, share button, and close button. Add Semantics wrappers to all custom animated widgets so VoiceOver and TalkBack announce slide content correctly. Use the summary-accessibility-provider to suppress redundant animation semantics during screen reader mode.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 8 - 48 tasks
Can start after Tier 7 completes
Implementation Notes
Start the audit by enabling accessibility on a physical device and navigating through the entire flow with only gesture-based navigation (no visual reference) to identify focus order issues before writing any code. For animated count-up widgets, the most reliable pattern is to wrap the entire AnimatedCounter widget in a Semantics widget with label set to the final value and liveRegion: true — this causes screen readers to announce only when the animation completes. Use the summary-accessibility-provider (to be defined in task epic-annual-impact-summary-ui-components-task-001) to expose a bool reduceMotion and bool isScreenReaderActive flag; conditionally set animation durations to Duration.zero when reduceMotion is true. For the progress indicator, use Semantics(value: 'Slide $current of $total', child: ...) rather than trying to make the visual dots individually focusable — this is cleaner and matches native carousel accessibility patterns.
Check the design token color palette against WCAG contrast requirements for each slide theme variant (some slides may use inverted or coloured backgrounds). Pay special attention to the Blindeforbundet user base requirement for full VoiceOver support — this feature's gamification intent must be fully accessible, not merely compliant.
Testing Requirements
Write widget tests using Flutter's SemanticsController (tester.semantics) to assert that each slide's semantics tree contains the expected labels, values, and hints. Test that ExcludeSemantics correctly removes decorative elements from the semantics tree. Test that the progress indicator's Semantics.value reflects the correct 'Slide N of M' string for at least three slide positions. Test the reduced-motion path by injecting a MediaQueryData with disableAnimations: true via a ProviderScope override and asserting that animation durations are zero or transitions are instant.
Run manual accessibility testing on physical devices: VoiceOver on iPhone (TestFlight) and TalkBack on Android — document results. Use the Flutter accessibility scanner (google_accessibility_scanner if available, or manual Xcode Accessibility Inspector) to verify no WCAG violations remain.
If the device transitions between online and offline states while the user is mid-session in the wrapped screen, the BLoC may emit conflicting state transitions (loaded → error → offline) that cause visual flickering or an inconsistent UI state such as showing the offline banner over an already-loaded summary.
Mitigation & Contingency
Mitigation: Implement a connectivity stream listener in the BLoC that only triggers a state re-evaluation when transitioning from online to offline, not on every connectivity event. Once a summary is in the Loaded state, the BLoC should not transition to error/offline unless the user explicitly requests a refresh. Store the last-loaded data in BLoC state so it survives connectivity changes.
Contingency: If state flickering is observed in testing, add a minimum 3-second debounce on connectivity state changes before the BLoC reacts, and display a non-blocking top banner rather than replacing the entire screen state.
The push notification deep-link to the wrapped-summary-screen must work correctly whether the app is in the foreground, background, or terminated state. Handling all three app launch states on both iOS and Android is a common source of edge-case bugs, particularly when authentication state must be restored before the deep link can be resolved.
Mitigation & Contingency
Mitigation: Implement deep-link handling through the existing notification-deep-link-handler component which already manages app-state-aware routing. Define the wrapped-summary route in the navigation config early in the epic so the router is ready before notification dispatch is wired. Test all three app states (foreground, background, terminated) explicitly in the QA checklist.
Contingency: If terminated-state deep-linking fails on specific platforms, fall back to launching the app to the home screen with an in-app notification banner prompting the user to open their summary, rather than direct deep-link navigation.
The wrapped-summary-screen manages a large number of AnimationController instances (one or more per slide) via the wrapped-animation-controller. If disposal is not triggered correctly when the user exits mid-flow (e.g., via system back gesture or deep-link away), memory leaks will accumulate across session navigation.
Mitigation & Contingency
Mitigation: Implement screen disposal via Flutter's dispose() lifecycle method calling a single wrapped-animation-controller.disposeAll() method that iterates the named controller registry. Write a test that navigates to the screen, starts animations, then navigates away and verifies no active AnimationController listeners remain using Flutter's test binding.
Contingency: If disposal bugs are detected in production via memory profiling, patch by converting all AnimationControllers to use AutomaticKeepAliveClientMixin false and wrap each slide in a widget that disposes its own controller when removed from the widget tree.