Write unit tests for Design Token Provider immutability
epic-visual-design-accessibility-foundation-task-012 — Create flutter_test unit tests verifying that the DesignTokenProvider exposes all tokens declared in the Accessibility Token Manifest, that token values match manifest declarations exactly, that the provider cannot be mutated at runtime, and that all tokens are accessible via the Riverpod provider graph in a test widget tree.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 5 - 253 tasks
Can start after Tier 4 completes
Implementation Notes
Use Riverpod's ProviderContainer directly for pure Dart token value tests (faster, no widget pump needed). Reserve WidgetTester + ProviderScope tests only for the provider-graph-access assertions. Structure tests in describe-style groups: group('token presence', ...), group('token values', ...), group('immutability', ...), group('provider graph', ...). For immutability tests, attempt to use ProviderContainer.read() followed by container.updateOverrides([]) to simulate override — assert the canonical constant is unaffected.
Reference the manifest constants directly in test expectations (e.g., expect(token.minTouchTarget, equals(AccessibilityTokenManifest.minTouchTargetPt))). Avoid magic numbers in test assertions. Since NHF, Blindeforbundet, and HLF users include people with motor and cognitive disabilities, touch target and contrast token correctness is safety-critical — treat value mismatch as a blocker, not a warning.
Testing Requirements
Unit tests only using flutter_test and Riverpod's ProviderContainer/ProviderScope test utilities. Cover: (1) token presence — one test per token category (color, typography, spacing, touch targets); (2) value correctness — assert exact constant values match manifest; (3) immutability — attempt runtime override and assert provider state unchanged; (4) provider graph accessibility — mount minimal test widget tree with ProviderScope and read each provider. No golden tests, no integration tests. Target 100% line coverage on DesignTokenProvider class.
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.