A habit gamification app for kids — powered by a magical unicorn pet
Built for a 5-year-old girl who deserves a magical way to build good habits. Every completed habit feeds her unicorn — and earns stars she can spend on real rewards.
- Open the app each morning and tap habits as you do them
- Every tap earns ⭐ stars — watch the unicorn change mood!
- Habits that need parent sign-off show a "⏳ Waiting…" badge
- Save up stars and spend them in the 🏪 Reward Shop
- Tap 👩👧 Parent → enter your 4-digit PIN
- Review pending habits and tap ✅ Approve (25% chance of a lucky bonus star!)
- Award stars directly for habits you observed yourself
- Check the 📊 Dashboard for streaks and weekly progress
- Use ⚙️ Configure to customise habits, rewards, and data backup
| Feature | Details |
|---|---|
| Daily habit checklist | Grouped into Morning / All Day / Evening |
| Once-daily habits | Big tap button, turns green when done |
| Repeatable habits | Tap multiple times (water glasses, potty), shows progress dots |
| Parent-approve habits | Tapping sends to parent queue — child sees "⏳ Waiting…" |
| Parent-only habits | Hidden from child, awarded directly by parent |
| Star counter | Animated bump on every completion |
| Unicorn pet | 5 mood states driven by daily completion percentage |
| Streak banner | 🔥 Shown whenever current streak > 0 |
| Reward shop | Redeem accumulated stars for real prizes |
| Sound effects | Chime tones on completion (toggleable 🔔/🔕) |
| Browser navigation | Back/forward buttons work via History API |
| Mood | Trigger | Feeling |
|---|---|---|
| 😴 Sleepy | Nothing done yet | Grey, half-closed eyes |
| 😐 Okay | 1–39% of daily stars earned | Neutral |
| 😊 Happy | 40–69% earned | Smiling, gentle glow |
| ✨ Magical | 70–99% earned | Sparkles, glowing mane |
| 🎉 Party | 100% earned or 7-day streak + 70% | Rainbow, dancing |
| Feature | Details |
|---|---|
| PIN gate | 4-digit PIN with dot indicators — setup on first use |
| Approvals tab | Review pending habits, approve with optional lucky star bonus |
| Direct award | Grant stars for parent-observed habits (calm voice, etc.) |
| Dashboard | Streak stats, today's snapshot, 7-day star bar chart |
| Configure — Habits | Add / edit / archive habits, set emoji, points, type, time of day |
| Configure — Rewards | Add / edit rewards with custom emoji or uploaded thumbnail |
| Configure — Backup | Export all data to JSON / restore from JSON file |
| Undo today | Reset today's entries if something was tapped by mistake |
| Change PIN | Update PIN from within Configure |
| Stars earned (total) | Level | Name |
|---|---|---|
| Starting out | 1 | Baby Sparkle |
| Growing up | 2 | Sparkle |
| Getting powerful | 3 | Super Sparkle |
| Maximum magic | 4 | Rainbow Sparkle |
| Concern | Choice | Why |
|---|---|---|
| UI framework | React 19 + TypeScript 5 | Type-safe, component-driven |
| Build tool | Vite 6 | Instant HMR, fast production builds |
| Styling | CSS Modules | Scoped styles, no runtime cost |
| Local persistence | localStorage |
UserProgress + parent PIN (simple key/value) |
| Structured storage | IndexedDB via idb v8 |
Habits, daily entries, rewards — queryable, survives reloads |
| PWA | vite-plugin-pwa + Workbox |
Service worker, offline cache, installable on any device |
| Navigation | history.pushState + popstate |
Back/forward button support without a router |
| Sound | Web Audio API | Synthesised chimes — no audio files, works fully offline |
| Deployment | GitHub Actions → GitHub Pages | Auto-deploys on every push to main |
App.tsx ──(props + handlers)──▶ Screens / Components
▲
│ reads on mount, writes on every change
│
localStorage ──── UserProgress (stars, streak, level), Parent PIN
IndexedDB ──── habits, daily_entries, rewards (idb v8)
All state lives in App.tsx and flows down as props — no context, no global store.
src/
├── components/
│ ├── HabitCard/ Tap button, repeatable dots, waiting badge
│ ├── UnicornPet/ Mood-reactive image + CSS animations
│ ├── StarBurst/ Celebration particle overlay on completion
│ ├── WaterTracker/ 5-dot water progress indicator
│ └── PinGate/ 4-digit PIN setup & verify (dot display + numpad)
├── screens/
│ ├── HomeScreen/ Child-facing habit checklist
│ ├── ParentApprovalScreen/ Approve pending, award direct
│ ├── ParentDashboard/ Streak calendar, weekly bar chart
│ ├── ConfigureScreen/ Habits + rewards CRUD, backup/restore
│ └── RewardsScreen/ Shop grid, redeem flow
├── storage/
│ ├── localStorage.ts lsGet / lsSet typed wrappers
│ ├── indexedDB.ts getDB singleton + helpers (getEntriesForDate, getStarsPerDay, …)
│ └── backup.ts exportBackup() / importBackup()
├── data/
│ ├── habits.ts DEFAULT_HABITS (seeded on first run)
│ └── rewards.ts DEFAULT_REWARDS (seeded on first run)
├── utils/
│ ├── unicornMood.ts computeMood(stars, max, streak) → UnicornMood
│ └── sounds.ts Web Audio chime synthesiser
├── styles/
│ ├── global.css CSS custom properties (colours, fonts, radii, shadows)
│ └── animations.css Keyframe animations (slide-up, sparkle-bump, dance, …)
└── types/index.ts Shared types: Habit, DailyEntry, UserProgress, …
git clone https://github.com/pradeepverse/sparkle-app.git
cd sparkle-app
npm install
npm run dev # http://localhost:5173/sparkle-app/
npm run build # TypeScript check + production build
npx tsc --noEmit # type-check onlyManual UI testing is done with the Playwright MCP server configured in .mcp.json (headless Chromium, 390×844 — iPhone viewport).
Every push to main triggers .github/workflows/deploy.yml:
npm ci→npm run build(tsc --noEmit && vite build)- Upload
dist/as a GitHub Pages artifact - Deploy to
https://pradeepverse.github.io/sparkle-app/
Note: The
base: '/sparkle-app/'invite.config.tsmust match the GitHub repository name exactly.
| Platform | Steps |
|---|---|
| Android (Chrome) | Menu → Add to Home Screen |
| iOS (Safari) | Share button → Add to Home Screen |
| Desktop (Chrome/Edge) | Click the install icon in the address bar |
Once installed, the app works fully offline — all assets are pre-cached by the service worker.
Everything lives entirely on the device — no server, no account, no analytics, no tracking.
Use Parent → Configure → Backup to:
- Export a JSON snapshot (download to your device)
- Import to restore on a new device or after clearing browser storage
- Phase 4 — animated unicorn evolution cutscene on level-up
- Phase 5 — sibling profiles (multiple children, one device)
- Phase 6 — weekly recap notification via Web Push
Built with love for one very sparkly little girl ✨