Implement Design Token Provider typed constant repository
epic-visual-design-accessibility-foundation-task-004 — Create the immutable, typed Dart constant repository (DesignTokenProvider) that exposes all color, typography, spacing, and sizing tokens consumed by downstream components. All tokens must reference values declared in the Accessibility Token Manifest to ensure the manifest remains the single source of truth.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 3 - 413 tasks
Can start after Tier 2 completes
Implementation Notes
Structure DesignTokenProvider with three inner classes: DesignTokenProvider.colors (static Color constants), DesignTokenProvider.typography (static TextStyle / TextTheme), and DesignTokenProvider.layout (spacing + sizing). This mirrors Flutter's Theme breakdown and makes autocomplete easier for downstream developers. For multi-org theming, use a factory constructor or a static method (DesignTokenProvider.forOrganisation(OrgTheme theme)) that returns an instance configured for the given org — do not use Flutter's ThemeExtension unless the team already uses it, as it adds complexity. Keep primitive colors (e.g., Color(0xFF1A73E8)) in a private _ColorPrimitives inner class and expose only semantic aliases (colorPrimary500 = _ColorPrimitives.blue600) in the public API — this two-layer approach is industry standard (Figma tokens, Tailwind, etc.) and prevents accidental use of primitives.
Generate the TextTheme using Google Fonts or the project's font package if applicable, but ensure it is compatible with system font scaling (textScaler) for accessibility.
Testing Requirements
Write unit tests (no widget tree required) covering: (1) All color token values match expected hex values for each organisation theme — use a lookup map and iterate; (2) All spacing token values follow the 8dp grid (value % 4 == 0 for all spacing constants); (3) minTouchTarget is exactly 48.0; (4) TextTheme font sizes match the min_font_size_sp values in the manifest; (5) The manifest-completeness test: load the manifest, extract all symbolic token names, and assert each resolves to a non-null constant in DesignTokenProvider. Additionally write a widget test that creates a MaterialApp using DesignTokenProvider.themeData and asserts Theme.of(context).colorScheme.primary equals the expected primary color for a given organisation.
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.