Add type scale and minimum sizing constraints to manifest
epic-visual-design-accessibility-foundation-task-003 — Extend the Accessibility Token Manifest with type scale constraints (minimum font sizes, line heights, letter spacing) and minimum touch target sizing requirements (48x48dp per WCAG 2.2 success criterion 2.5.8). Ensure manifest entries are versioned for future enforcement audits.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 2 - 518 tasks
Can start after Tier 1 completes
Implementation Notes
Map Flutter's Material 3 TextTheme names directly to the manifest type_scale entries (displayLarge, displayMedium, displaySmall, headlineLarge, headlineMedium, headlineSmall, titleLarge, titleMedium, titleSmall, bodyLarge, bodyMedium, bodySmall, labelLarge, labelMedium, labelSmall) — this ensures a 1:1 mapping with the DesignTokenProvider's TextTheme output. For touch targets, note that Flutter's minimum tap area is enforced via the MaterialTapTargetSize.padded theme setting, but the manifest documents the visual size requirement, not the tap area padding. Document this distinction in a comment. The 'added_in_version' field should be auto-populated by a build script if possible, or set manually to '1.0.0' for the initial manifest.
Bump the manifest's top-level version field from '1.0.0' to '1.1.0' in this task to reflect the addition of type scale and sizing data (semantic versioning: minor bump for additive changes).
Testing Requirements
Extend the existing manifest compliance test suite with two new test groups: (1) Type scale compliance — iterate all TypeScaleConstraint entries and assert min_font_size_sp and min_line_height_multiplier meet their respective thresholds by style category; (2) Touch target compliance — iterate all SizingConstraint entries and assert both dimensions are ≥ 48dp. These tests join the CI gate established in task-002. Also add a snapshot test that serializes the complete manifest to JSON and compares it to a committed golden file — this prevents silent regressions when manifest entries are edited.
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.