Build BadgeIconAssetManager Flutter service
epic-achievement-badges-foundation-task-006 — Implement BadgeIconAssetManager as a Flutter service class that resolves asset paths for badge icons. Must support locked and unlocked icon variants for every badge definition. Implement WCAG 2.2 AA contrast ratio validation: given a badge icon's foreground colour and a design token background colour, compute contrast ratio and return a validation result. Integrate with the project's design token system. Asset paths must be validated at runtime with graceful fallback to a placeholder icon.
Acceptance Criteria
Technical Requirements
Implementation Notes
The WCAG 2.2 relative luminance formula requires linearising sRGB values: for a channel value c (0–1), if c <= 0.04045 then linear = c/12.92, else linear = ((c + 0.055)/1.055)^2.4. Implement this as a private static method `_linearise(double c)`. The contrast ratio formula is (L1 + 0.05) / (L2 + 0.05) where L1 is the lighter luminance. Cache resolved asset paths in a `Map
For the asset existence check, wrap `rootBundle.load(path)` in a try-catch returning the placeholder path on FlutterError — this check should be async and called lazily on first resolution. Make the asset base path configurable via a constructor parameter (default 'assets/badges/') to facilitate testing with a mock asset directory. Ensure the locked/unlocked naming convention is consistent with the visual design: locked icons should be desaturated/greyed versions of unlocked icons — document this expectation for the design team even if the Flutter code just resolves paths by naming convention.
Testing Requirements
Unit tests using flutter_test: (1) resolveIconPath returns correct unlocked path for a known iconRef, (2) resolveIconPath returns correct locked path when locked=true, (3) resolveIconPath returns placeholder path when asset does not exist (mock rootBundle to throw FlutterError), (4) computeLuminance(Colors.white) returns 1.0, computeLuminance(Colors.black) returns 0.0, (5) validateContrast(Colors.black, Colors.white) returns ratio ~21.0 and passesAA=true, passesAAA=true, (6) validateContrast(Colors.white, Colors.white) returns ratio 1.0 and both false, (7) validateContrast with a mid-grey pair returns ratio ~4.6 and passesAA=true, passesAAA=false. Use testWidgets for the placeholder widget render test. 95%+ coverage on the WCAG computation logic.
Badge criteria are stored as structured JSON in badge_definitions. If the JSON schema for criteria (threshold counts, streak lengths, training completion flags) is not well-defined upfront, the evaluation service will be built against a moving target, requiring costly migrations and refactors.
Mitigation & Contingency
Mitigation: Define and document the criteria JSON schema in a shared type file before any repository code is written. Review the schema with all three organisations' badge requirements — especially Blindeforbundet's honorar thresholds — and version the JSON schema using a 'criteria_version' field from day one.
Contingency: If the criteria schema must change after services are built, write a Supabase migration to backfill existing rows and add a migration version column. Keep the evaluation service criteria parser isolated behind an interface so only one function needs updating.
Badge icon assets may not yet exist or may fail WCAG 2.2 AA contrast validation (minimum 3:1 for graphical objects) when rendered over design-token backgrounds. Missing or non-compliant icons could block UI epic delivery for Blindeforbundet, for whom screen reader and visual accessibility is non-negotiable.
Mitigation & Contingency
Mitigation: During this epic, implement the contrast-ratio validator in badge-icon-asset-manager and run it as a Flutter test against all candidate icon assets early. Coordinate with the design team to provide WCAG-compliant SVG icons in both locked and unlocked variants before the UI epic begins.
Contingency: If assets are late or fail contrast checks, ship placeholder icons that are guaranteed compliant (solid design-token colour fills with text labels) and swap in final assets post-QA without requiring a code change.