Implement BadgeCardWidget base UI component
epic-achievement-badges-foundation-task-008 — Implement the BadgeCardWidget as a stateless Flutter widget that renders a single badge. The widget must display: badge icon (locked or unlocked variant via BadgeIconAssetManager), badge name label, earned/locked state with visually distinct styling, and an optional milestone progress indicator (e.g., LinearProgressIndicator showing progress toward earning the badge). Apply correct semantic labels and accessibility roles so VoiceOver/TalkBack correctly announces badge name, earned state, and progress percentage.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 2 - 518 tasks
Can start after Tier 1 completes
Implementation Notes
Keep the widget strictly stateless — all state (earned/locked, progress) is passed in as constructor parameters, enabling the parent BLoC or Riverpod provider to control rendering. Use a Stack to overlay a greyscale ColorFilter over the icon image for locked state rather than maintaining separate greyscale assets. Wrap the LinearProgressIndicator in an ExcludeSemantics widget and express the progress via the parent Semantics label as a percentage string (e.g., '45% complete') so screen readers give a meaningful announcement rather than reading the raw slider value. Follow the project's design token system for spacing and typography — do not hardcode pixel values.
Reference the project's AppButton widget for patterns on how semantic roles are applied in this codebase.
Testing Requirements
Write widget tests (flutter_test) covering: (1) earned badge renders accent styling and no progress bar, (2) locked badge renders muted styling and no progress bar when progress is null, (3) locked badge with progress renders LinearProgressIndicator with correct value, (4) Semantics tree contains expected label string for each state. Use WidgetTester.pump and find.byType/find.bySemanticsLabel. Achieve 90%+ line coverage on the widget file. Additionally, run a golden test for each of the three states to catch unintended visual regressions.
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.