Document widget API contracts and accessibility guidelines
epic-annual-impact-summary-ui-components-task-018 — Write developer documentation for all five components (StatCardWidget, MilestoneBadgeWidget, ActivityTypeBreakdownWidget, SummaryShareOverlay, SummaryAccessibilityProvider) covering: constructor parameters, required design token classes, reduced-motion behaviour, Semantics contract, and integration example snippets. Include guidance on how to extend announcement strings for new organisations.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 6 - 158 tasks
Can start after Tier 5 completes
Implementation Notes
Prefer Dart doc comments (///) directly in the source files over a separate Markdown file — this keeps docs co-located with code and generates API docs via dart doc. For the organisation extension guide, describe the pattern: implement or extend the AccessibilityLabels class, override the relevant announcement getters, and inject the custom instance via the SummaryAccessibilityProvider constructor. Keep code snippets minimal but complete — import paths should be relative to the project root. For the reduced-motion section, create a simple table: Widget | Animation | Reduced-motion behaviour.
This makes the contract scannable. Reference the WCAG 2.2 AA success criterion (2.3.3 Animation from Interactions) when documenting reduced-motion support to give the requirement its proper context.
Testing Requirements
No automated tests required for documentation itself. However, ensure all Dart code snippets in the documentation are syntactically valid by copying them into a standalone example file and running flutter analyze.
If the project has a docs-lint CI step, ensure the new documentation file passes it. Request a peer review specifically checking: accuracy of parameter descriptions, completeness of the Semantics contract section, and clarity of the organisation extension guide.
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.