critical priority low complexity frontend pending frontend specialist Tier 4

Acceptance Criteria

A designTokenProvider Riverpod provider (Provider<DesignTokenProvider>) is defined and accessible from any widget that has a WidgetRef or Ref.
The provider is declared as a top-level constant using @riverpod annotation or Provider() syntax — it must NOT be created inside a widget's build method.
The provider is read-only (Provider, not StateProvider or StateNotifierProvider) — no widget can mutate the token set at runtime.
An organisationThemeProvider (or equivalent) exists that the designTokenProvider reads to determine which org-specific token set to return, enabling multi-org support without duplicating providers.
A widget test verifies that ref.read(designTokenProvider).colors.colorPrimary500 returns the correct Color for a given organisation theme scoped via ProviderScope overrides.
The provider is accessible without a BuildContext via a ProviderContainer in pure Dart unit tests.
All existing widgets that directly imported DesignTokenProvider are refactored to consume it via ref.watch(designTokenProvider), OR a migration note is added to the task's PR description if refactoring is out of scope.
The provider is exported from the design_system barrel file (lib/design_system/design_system.dart) so consumers need only one import.
No circular provider dependencies are introduced — token providers must not depend on feature-level providers.

Technical Requirements

frameworks
Flutter
Riverpod
Dart
data models
DesignTokenProvider
OrgTheme
performance requirements
designTokenProvider must be a Provider (synchronous, cached) — never a FutureProvider
Token access via ref.watch must not trigger unnecessary widget rebuilds when the org theme has not changed
security requirements
The provider must not be overridable in production builds — ProviderScope overrides are permitted in tests only
ui components
ProviderScope (root)
ConsumerWidget / ConsumerStatefulWidget

Execution Context

Execution Tier
Tier 4

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 (or derived from the auth/session provider that knows the current user's organisation) — designTokenProvider should use ref.watch(organisationThemeProvider) internally and return the appropriate DesignTokenProvider instance.

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.

Component
Design Token Provider
data medium
Epic Risks (3)
high impact medium prob technical

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.

medium impact high prob scope

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.

medium impact medium prob dependency

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.