Expose token provider via Riverpod providers
epic-visual-design-accessibility-foundation-task-005 — Wire the DesignTokenProvider into the Riverpod provider graph so that all Flutter widgets and services can access design tokens via dependency injection. Ensure the provider is immutable and cannot be overridden at runtime, guaranteeing consistent token consumption across all organisation tenants.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 4 - 323 tasks
Can start after Tier 3 completes
Implementation Notes
Use Riverpod's @riverpod code generation annotation if the project already uses riverpod_generator — this produces type-safe provider references and eliminates boilerplate. If using manual Provider() syntax, declare providers in a dedicated file (lib/design_system/providers/design_token_providers.dart) and avoid placing them in the same file as the DesignTokenProvider class to maintain separation of concerns. For the immutability guarantee in production, use Dart's const constructor on the provider's return value and avoid exposing any setter or mutable state. For the multi-org scenario, the organisationThemeProvider should be a StateProvider
Document in the barrel file's README comment that ProviderScope must be placed at the root of the widget tree (above MaterialApp) to ensure all widgets have access.
Testing Requirements
Write widget tests using ProviderScope with overrides to test both: (1) the default org theme returns the expected DesignTokenProvider instance with correct token values; (2) overriding organisationThemeProvider with a different OrgTheme value causes designTokenProvider to return a different color set. Write a unit test using ProviderContainer (no widget tree) to assert the provider resolves synchronously. Add a golden test that renders a simple widget consuming tokens via the provider and compare it against a committed golden image for each supported org theme — this prevents silent visual regressions when token values change.
The WCAG 2.2 relative luminance formula requires gamma-corrected sRGB calculations. Floating-point rounding differences between Dart and reference implementations could produce off-by-one classifications for near-threshold color pairs, resulting in pairs that just pass or just fail in CI but behave differently at runtime.
Mitigation & Contingency
Mitigation: Implement the algorithm directly from the WCAG 2.2 specification using the exact linearisation constants. Validate the Dart implementation against the W3C reference test vectors and against a known-good JavaScript implementation for at least 50 color pairs spanning the compliance boundaries.
Contingency: If discrepancies are found, add a configurable tolerance margin (e.g., ±0.005 on the ratio) and flag near-threshold pairs as warnings rather than hard failures, escalating to the design team for manual review.
The token manifest is a static data file. If developers add new color tokens to the design-token-provider without updating the manifest, the manifest becomes stale and the CI validator produces false negatives — passing builds that contain unvalidated color pairs.
Mitigation & Contingency
Mitigation: Add a CI step that cross-references every token constant exported by the design-token-provider against the manifest at build time, failing if any token is present in the provider but absent from the manifest. Document this requirement clearly in the contributing guide.
Contingency: If drift is detected post-merge, run a full manifest regeneration script and treat the resulting manifest diff as a blocking pull request with mandatory accessibility review.
The flutter_accessibility_lints package (or custom lint rules) may produce false positives on patterns the team deliberately uses — for example, decorative icon widgets that intentionally omit semantic labels. Excessive false positives will lead developers to add blanket ignore comments, undermining the entire lint strategy.
Mitigation & Contingency
Mitigation: Audit the full lint rule set against the existing codebase before enabling rules. Create a documented list of approved ignore-comment patterns with mandatory justification comments. Restrict ignore patterns to decorative-only contexts.
Contingency: If false positive rates exceed 10% of lint output, disable the highest-noise individual rules and replace them with targeted custom lint rules scoped to the specific patterns the team controls.