Populate manifest with WCAG 2.2 AA contrast ratio declarations
epic-visual-design-accessibility-foundation-task-002 — Fill the Accessibility Token Manifest with all required color pair contrast ratio declarations meeting WCAG 2.2 AA thresholds (minimum 4.5:1 for normal text, 3:1 for large text and UI components). Cover all color combinations used across NHF, Blindeforbundet, HLF, and Barnekreftforeningen organisation themes.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 1 - 540 tasks
Can start after Tier 0 completes
Implementation Notes
Use the WCAG 2.2 relative luminance formula to compute contrast ratios for each color pair before populating the manifest — do not estimate visually. A utility script (scripts/check_contrast.dart) is recommended to automate the computation: it reads the raw hex values from the design token source files, computes contrast ratios, and outputs the manifest entries. This script does not need to be production code but should be committed for future use. When covering all four organisation themes, note that Blindeforbundet has the most demanding accessibility requirements (screen reader users) and should be audited first.
Disabled state color pairs typically fall below 3:1 intentionally — per WCAG 2.2 SC 1.4.3 exception, disabled components are exempt; document this exemption in the manifest entry with a 'wcag_exemption' field rather than omitting the entry.
Testing Requirements
The primary test artifact for this task is the compliance gate test: a flutter_test unit test that loads the manifest, iterates every ColorPairEntry, and asserts contrast_ratio meets the WCAG 2.2 AA threshold for its text_size_category. This test must be added to the CI pipeline and must fail the build if any entry falls below threshold. Additionally, write a test that asserts the total number of color pair entries is ≥ a defined minimum (e.g., 20) to prevent accidental truncation of the manifest during future edits.
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.