Document accessibility foundation layer for downstream teams

epic-visual-design-accessibility-foundation-task-014 — Write developer documentation covering: how to read and extend the Accessibility Token Manifest, how to consume the DesignTokenProvider via Riverpod, how to use the ContrastRatioValidator in runtime checks and CI scripts, and how to interpret and act on lint rule violations. Include rationale linking requirements back to NHF, Blindeforbundet, HLF, and Barnekreftforeningen user needs.

medium priority low complexity documentation pending documentor Tier 7

Acceptance Criteria

Documentation is a single Markdown file (docs/accessibility-foundation.md) committed to the repository root docs/ directory

Section 1 explains the Accessibility Token Manifest structure: what each token category means, how constants are named, and how to add a new token with a concrete example

Section 2 provides a minimal Dart code snippet showing how to read a color token via Riverpod (ref.watch(designTokenProvider).colors.primary) in both a widget and a non-widget context

Section 3 explains ContrastRatioValidator: how to call it programmatically, what the return value means, and how to integrate it in a CI script

Section 4 lists each lint rule, the WCAG 2.2 AA criterion it enforces, and a before/after code example showing a violation and its corrected form

Section 5 contains a 'Why this matters' rationale paragraph per organization: NHF (cognitive accessibility, stroke survivors), Blindeforbundet (screen reader and VoiceOver dependency), HLF (high contrast for hearing-impaired users), Barnekreftforeningen (child users with varying ability)

Documentation is reviewed and approved by at least one team member before merge (PR review required)

All code snippets compile without errors when pasted into a Flutter project using the defined tech stack

Technical Requirements

frameworks

Flutter

Riverpod

flutter_test

data models

AccessibilityTokenManifest

DesignTokenProvider

ContrastRatioValidator

security requirements

Documentation must not include any real user data, API keys, or organization-specific personal information

Execution Context

Execution Tier

Tier 7

Tier 7 - 84 tasks

Can start after Tier 6 completes

View Full Execution Plan

Implementation Notes

Write for a mid-level Flutter developer who is new to the project. Use plain English. Avoid jargon without explanation. Structure each section with a 'What', 'How', and 'Why' sub-pattern.

For the ContrastRatioValidator section, show both the programmatic API call and the CLI invocation pattern so both app developers and DevOps engineers can use it. In the rationale section, be specific: reference that Blindeforbundet users depend on VoiceOver/JAWS and that any color token bypassing the token system will fail their assistive technology; reference that NHF users include stroke survivors for whom cognitive load is a clinical concern, not a UX preference. Keep the document under 1,500 words — if a section grows too large, link to the relevant source file instead of duplicating content. Ensure all code examples use the exact provider names and constant identifiers defined in the implementation tasks.

Testing Requirements

Documentation quality validation: (1) all Dart code snippets must be extracted and run through dart analyze to confirm they are error-free; (2) a peer review checklist must confirm all four organizations are mentioned with correct context; (3) confirm all internal links to source files (e.g., lib/design_tokens/accessibility_token_manifest.dart) resolve to actual paths. No automated test suite required, but a CI doc-lint step using markdownlint is recommended.

Component

Accessibility Token Manifest

data low

Dependencies (3)

Integrate the Flutter Accessibility Lint Configuration into the CI pipeline by adding a dart analyze step that uses the configured analysis_options.yaml. Confirm that deliberately introduced violations (e.g., a hardcoded color, missing semantics label) are caught and cause the CI step to fail, and that clean code passes without warnings. epic-visual-design-accessibility-foundation-task-013 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. epic-visual-design-accessibility-foundation-task-012 Create comprehensive flutter_test unit tests for the ContrastRatioValidator covering: known passing pairs (white on black = 21:1), known failing pairs, boundary cases at exactly 4.5:1 and 3:1, edge cases with identical colors (1:1), and all color pairs declared in the Accessibility Token Manifest. Target 100% branch coverage for the luminance algorithm. epic-visual-design-accessibility-foundation-task-011

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.

Quick Links

All Tasks Execution Plan