Build fl_chart Adapter with Design Tokens
epic-coordinator-statistics-dashboard-core-logic-task-005 — Create the FlChartAdapter infrastructure class that centralises all fl_chart configuration: bar chart BarData and BarTouch setup, donut chart PieChartData and PieTouch setup, axis formatters, tooltip renderers, and animation durations. All colours, font sizes, padding, and corner radii must be sourced exclusively from the design token system (DesignTokenTheme) so charts are brand-consistent across NHF, HLF, and Blindeforbundet deployments.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 1 - 540 tasks
Can start after Tier 0 completes
Implementation Notes
fl_chart's BarChartData is immutable and constructed via named parameters — build it entirely inside the factory method without storing intermediate mutable state. Access design tokens via `Theme.of(context).extension
For WCAG validation, verify each organisation's accent colour passes contrast against `AppColors.chartBackground` before committing — use a helper: `contrastRatio(Color fg, Color bg)` based on WCAG 2.1 relative luminance formula. Avoid defining chart colours inside FlChartAdapter — delegate colour selection to the calling ViewModel layer so the adapter remains a pure formatting utility.
Testing Requirements
Widget tests with flutter_test: (1) Render buildBarChartData output inside BarChart widget with a known list of BarChartSeriesViewModel — assert widget builds without error and the correct number of bar groups is present. (2) Render buildDonutChartData output inside PieChart — assert the correct number of PieSections with non-zero percentages. (3) Pass empty BarChartSeriesViewModel list — assert no exception and a valid empty chart renders. (4) For each of the three organisation themes (NHF, HLF, Blindeforbundet), override the DesignTokenTheme and assert that colours in the returned chart data change accordingly.
(5) Assert WCAG contrast ratio for the primary bar fill colour against the chart background using a helper function that computes relative luminance. Golden file tests are optional but recommended for tooltip renderer output.
fl_chart's default colour palette may not meet WCAG 2.2 AA contrast requirements when rendered on the app's dark or light backgrounds. If segment colours are insufficient, the donut chart will fail accessibility audits, which is a compliance blocker for all three organisations.
Mitigation & Contingency
Mitigation: Define all chart colours in the design token system with pre-validated contrast ratios. Run the contrast-ratio-validator against every chart colour during the adapter's unit tests. Use the contrast-safe-color-palette as the source palette.
Contingency: If a colour fails validation, replace with the nearest compliant token. If activity types exceed the available token set, implement a deterministic hashing algorithm that maps activity type IDs to compliant colours.
StatsBloc subscribing to the activity registration stream creates a long-lived subscription. If the subscription is not disposed correctly when the dashboard is closed, it will cause a stream leak and potentially trigger re-fetches on a disposed BLoC, resulting in uncaught errors in production.
Mitigation & Contingency
Mitigation: Implement subscription disposal in the BLoC's close() override. Write a widget test that navigates away from the dashboard and asserts no BLoC events are emitted after disposal.
Contingency: If leaks are detected in QA, add a mounted check guard before emitting states from async callbacks, and audit all other BLoC stream subscriptions in the codebase for the same pattern.
PersonalStatsService's Phase 4 gamification data structure is designed against an assumed future schema. If the Phase 4 Spotify Wrapped feature defines a different data contract when it is developed, the structure built now will require a breaking change and migration.
Mitigation & Contingency
Mitigation: Document the contribution data structure with explicit field semantics and versioning comments. Keep the Phase 4 fields as optional/nullable so they do not break existing consumers if the schema evolves.
Contingency: If the Phase 4 schema diverges significantly, the personal stats data can be re-mapped in a thin adapter layer without changing PersonalStatsService's core implementation.