Apply design tokens and WCAG contrast to BadgeCardWidget
epic-achievement-badges-foundation-task-009 — Integrate the project's design token system into BadgeCardWidget. Earned badge cards must use an accent colour from the design tokens that passes WCAG 2.2 AA contrast ratio (4.5:1 for normal text, 3:1 for large text and UI components) against the card background token. Locked badge cards must render in a greyscale/muted token variant. Use BadgeIconAssetManager's contrast validator to assert correct contrast at widget construction time in debug mode.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 3 - 413 tasks
Can start after Tier 2 completes
Implementation Notes
The WCAG 2.2 AA relative luminance formula (IEC 61966-2-1) is: L = 0.2126*R + 0.7152*G + 0.0722*B where sRGB channels are linearised. Contrast ratio = (L1 + 0.05) / (L2 + 0.05). Implement this in BadgeIconAssetManager.validateContrastRatio if not already done. Wrap the debug-mode assertion in an assert() statement or a kDebugMode guard so it is completely stripped in release builds — do not use if (kDebugMode) without confirming tree-shaking eliminates it.
Prefer token names that encode their intent (e.g., badgeEarnedBackground, badgeEarnedText) over generic palette names to make future token swaps safe. The greyscale locked variant should use the same token family as disabled UI elements already defined in the project's design token system for visual consistency.
Testing Requirements
Write unit tests that: (1) call BadgeIconAssetManager.validateContrastRatio with the earned card foreground/background token colour pair and assert it returns true (passes AA), (2) call validateContrastRatio with a known-failing pair (e.g., light grey on white) and assert it returns false, (3) verify the locked card text colour tokens also pass 4.5:1 via the same validator. Write a widget test that constructs BadgeCardWidget in debug mode and asserts no FlutterError or assertion error is thrown. If golden tests exist from task-008, update them to reflect the token-driven styling.
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.