🏠 Overview › ✅ Implementation Tasks ›✅ epic-visual-design-accessibility-foundation-task-001

Define Accessibility Token Manifest schema and structure

epic-visual-design-accessibility-foundation-task-001 — Design and implement the versioned JSON/Dart schema for the Accessibility Token Manifest, declaring all color pair contrast ratios, type scale constraints, and minimum sizing requirements. Establish the manifest format as the machine-readable contract layer that all downstream components consume.

critical priority low complexity backend pending frontend specialist Tier 0

Acceptance Criteria

A versioned JSON schema file (accessibility_token_manifest.schema.json) exists in the repository defining the structure for color_pairs, type_scale, and sizing_constraints sections.
A corresponding Dart class (AccessibilityTokenManifest) is generated or hand-written that mirrors the JSON schema with typed fields — no dynamic maps or Object types.
The schema includes a top-level 'version' field (semver string) and a 'generated_at' ISO-8601 timestamp field to support audit trails.
The color_pairs section schema defines: foreground token name, background token name, contrast_ratio (double), wcag_level ('AA' | 'AAA'), and text_size_category ('normal' | 'large' | 'ui_component').
The type_scale section schema defines: scale_name, min_font_size_sp (double), min_line_height_multiplier (double), min_letter_spacing_em (double).
The sizing_constraints section schema defines: component_name, min_touch_target_width_dp (int), min_touch_target_height_dp (int), wcag_criterion (string).
A Dart fromJson / toJson round-trip test passes without data loss for a sample manifest with at least 3 color pairs, 3 type scale entries, and 3 sizing constraints.
The schema and Dart class are co-located in lib/design_system/accessibility/ with a barrel export file.
A README comment block at the top of the Dart file explains the manifest's role as the authoritative contract and references WCAG 2.2 success criteria by number.

Technical Requirements

frameworks
Flutter
Dart
data models
AccessibilityTokenManifest
ColorPairEntry
TypeScaleConstraint
SizingConstraint
performance requirements
Manifest deserialization must complete in < 5ms on debug builds — it is loaded once at app startup
security requirements
Manifest must be embedded as a compile-time asset, not fetched at runtime, to prevent tampering

Execution Context

Execution Tier
Tier 0

Tier 0 - 440 tasks

Implementation Notes

Define the Dart model as a pure immutable value object using final fields and a const constructor where possible — this enables compile-time safety and allows the manifest to be a compile-time constant. Use json_serializable (if already in pubspec) or hand-write fromJson/toJson to avoid adding new dependencies. The JSON schema file serves a dual purpose: documentation for designers and input validation for any tooling that generates the manifest. Structure the Dart class hierarchy as: AccessibilityTokenManifest → List, List, List.

Avoid inheritance — use composition. The manifest should NOT contain the actual token values (e.g., Color(0xFF...)) — it contains only symbolic token names (strings like 'color.primary.500') and their computed constraint metadata. Token resolution happens in DesignTokenProvider (task-004).

Testing Requirements

Write unit tests in flutter_test covering: (1) fromJson correctly deserializes a full sample manifest, (2) toJson produces output that round-trips back to an identical object, (3) missing required fields throw a descriptive FormatException, (4) the version field is validated as a valid semver string. No widget tests required for this task. Target 100% line coverage for the manifest class.

Component
Accessibility Token Manifest
data low
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