Configure analysis_options.yaml with accessibility lint rules
epic-visual-design-accessibility-foundation-task-006 — Set up the Flutter Accessibility Lint Configuration by adding accessibility-focused lint rules to analysis_options.yaml. Enable rules that surface missing semantics labels, inadequate touch targets, hardcoded colors bypassing the token system, and other WCAG 2.2 violations so IDE and CI dart analyze runs catch issues immediately.
Acceptance Criteria
Technical Requirements
Implementation Notes
Start from the official `flutter_lints` package (`flutter pub add --dev flutter_lints`). In `analysis_options.yaml`, set `include: package:flutter_lints/flutter.yaml` then add an `linter > rules` block. Key rules to enable: `avoid_hardcoded_colors` (if available in flutter_lints version), `use_full_hex_values_for_flutter_colors`, `sized_box_for_whitespace`. For accessibility-specific rules not in flutter_lints, add `package:accessibility_lint` as a dev dependency if the project permits it.
Document each rule with a comment referencing the WCAG 2.2 criterion it enforces (e.g., `# WCAG 1.4.3 – Contrast Minimum`). Keep rules as `errors` rather than `warnings` for critical accessibility rules so CI fails fast. Avoid over-linting — only enable rules that have zero false positives on the existing codebase or the build will be unusable from day one.
Testing Requirements
Verify lint rules fire correctly by introducing intentional violations in a scratch file: (1) add a hardcoded Color(0xFF123456) and confirm analyzer reports it, (2) add a widget missing a Semantics wrapper and confirm the rule fires, (3) restore the file and confirm clean analysis. These smoke tests should be documented as manual QA steps in the PR description, not automated tests.
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.