Badge Shelf Widget
Component Detail
Description
Displays a horizontal scrollable shelf of earned and locked badges on the peer mentor profile screen. Each badge shows locked/unlocked state with appropriate visual treatment including grayscale for locked and full-color for earned badges.
badge-shelf-widget
Summaries
The Badge Shelf Widget is a core engagement driver on the peer mentor profile screen, making achievements highly visible and aspirational to both the mentor and the mentees they support. By displaying earned badges alongside locked ones, this component creates a clear and compelling progression system that motivates continued platform engagement and session completion. Badge visibility directly supports retention metrics by giving mentors a tangible sense of status and progress toward the next achievement milestone. For the platform, a compelling badge collection experience increases the perceived value of sustained participation, reducing churn and supporting subscription renewal rates.
The accessible design ensures this motivational experience reaches all users regardless of ability or assistive technology usage.
This medium-complexity UI component depends on both Badge Card Widget and Badge Repository, meaning both must be completed or at minimum interface-stable before the shelf can be integrated and tested end-to-end. Development should plan for one to two sprints covering horizontal scroll behaviour, earned versus locked state management, and tap interaction handling. Key testing areas include scroll performance with large badge collections on lower-end devices, accessibility of the scrollable shelf for VoiceOver and TalkBack users, and badge refresh behaviour when new badges are earned mid-session. Coordination with the backend team is required to confirm Badge Repository data availability on the expected timeline.
Design sign-off is also needed early on the locked badge visual treatment — grayscale filter versus semi-transparent overlay — to avoid mid-sprint rework.
BadgeShelfWidget accepts two typed lists: earned EarnedBadge objects and available BadgeDefinition objects, delegating individual badge rendering entirely to BadgeCardWidget to maintain a clean separation of concerns. The widget renders a horizontally scrollable ListView or Row with each BadgeDefinition mapped to a BadgeCardWidget, passing the corresponding EarnedBadge if found in the earned list. onBadgeTap receives the tapped BadgeDefinition and should trigger a bottom sheet or modal presenting badge detail and the earned date sourced from EarnedBadge.earnedAt when present. refreshBadges() should invalidate provider or BLoC state to trigger a re-fetch from Badge Repository.
setLockedOverlay() enables programmatic locked treatment across all badges, useful for preview or permission-gated states. Data model dependencies are badge and earned_badge; verify the repository layer maps both correctly from the database schema before wiring the widget into the feature tree.
Responsibilities
- Render earned and locked badge states on profile
- Display badge icons with accessible text labels
- Support horizontal scrolling for badge collections
- Show earned date on badge tap
Interfaces
BadgeShelfWidget({required List<EarnedBadge> earned, required List<BadgeDefinition> available})
onBadgeTap(BadgeDefinition badge)
refreshBadges()
setLockedOverlay(bool locked)
Relationships
Related Data Entities (2)
Data entities managed by this component