Badge Card Widget
Component Detail
Description
Individual badge display card showing icon, name label, and earned/locked state. Meets WCAG 2.2 AA contrast requirements with text labels accompanying all badge icons for screen reader accessibility.
badge-card-widget
Summaries
The Badge Card Widget is the atomic visual unit of the platform's achievement system, appearing wherever badges are displayed across the peer mentor profile experience. As the foundational building block of the badge display, its design quality directly shapes how users perceive the value and meaning of their earned achievements. A well-crafted badge card with clear earned and locked state distinction, accessible labelling, and milestone progress indicators ensures all users — including those relying on screen readers — can participate equally in the recognition and reward system. This component enables the platform's broader gamification strategy by making achievements legible, attractive, and motivating at a glance, contributing to the emotional engagement that underpins long-term user retention and positive word-of-mouth referrals.
The Badge Card Widget is a low-complexity, dependency-free UI component, making it a strong candidate for early-sprint development to unblock the Badge Shelf Widget which has a direct dependency on it. A single sprint should be sufficient to implement icon rendering, contrast-compliant text labelling, locked versus earned visual state treatment, and the milestone progress indicator for near-earned badges. Accessibility requirements including WCAG 2.2 AA contrast ratios and semantic screen reader labels should be validated early using automated contrast checking tools and manual assistive technology testing to avoid compliance rework later. The primary risk is design iteration on the locked badge treatment — grayscale filter versus overlay — which could require widget rework if design decisions are finalised after implementation begins.
Early design sign-off on badge icon assets and locked state approach is strongly recommended.
BadgeCardWidget is a pure display widget accepting a required BadgeDefinition and an optional EarnedBadge nullable parameter. When earned is null, the widget applies locked visual treatment via a ColorFilter.matrix grayscale transformation on the badge icon combined with an optional lock icon overlay, controlled by applyLockedOverlay(). buildSemanticLabel() constructs a Semantics label string combining badge name, earned or locked status, and formatted earned date from EarnedBadge.earnedAt when available — this is the string emitted by VoiceOver and TalkBack. buildProgressIndicator() accepts the user's current progress value and the badge's required milestone threshold, rendering a compact LinearProgressIndicator for badges where progress is meaningful.
This widget has zero external dependencies and is fully testable in isolation using Flutter widget tests with mock BadgeDefinition and EarnedBadge fixtures, enabling high test coverage at low cost.
Responsibilities
- Render badge icon with sufficient contrast
- Show text label for screen reader compatibility
- Indicate locked vs earned state visually and semantically
- Display milestone progress indicator for near-earned badges
Interfaces
BadgeCardWidget({required BadgeDefinition definition, EarnedBadge? earned})
buildSemanticLabel()
buildProgressIndicator(int current, int required)
applyLockedOverlay()
Relationships
Dependents (3)
Components that depend on this component
Related Data Entities (2)
Data entities managed by this component