feat: First-Time User Experience (Tutorial / Onboarding) #97
Description
Summary
Add a lightweight onboarding overlay so new players immediately understand the core loop without reading a manual.
Why
The PRD defines a rich game loop but has zero FTUE. Without guidance, a first-time player lands on a static ASCII blob with no hint that they should click it. Best-practice idle games (Cookie Clicker, Clicker Heroes) all use progressive tooltips to teach mechanics as they unlock — not a wall-of-text tutorial.
Acceptance criteria
- On first load (no existing save), a pulsing highlight + tooltip appears on the FEED button: "Click to give GLORP training data!"
- After the first click, a tooltip points to the TD counter: "Training Data (TD) is your currency. Earn more by clicking!"
- When the player can first afford an upgrade, a tooltip highlights the upgrade panel: "Buy upgrades to automate TD generation."
- When GLORP first evolves, a tooltip calls out the evolution indicator: "GLORP is growing! Evolution unlocks new upgrades and dialogue."
- All tooltips have a visible dismiss ("✕") control.
- Completed tutorial steps are persisted in
localStorageand never re-shown on subsequent sessions. - A "Skip tutorial" button skips all steps at once.
- Tutorial does not block gameplay — player can still click and buy while tooltips are visible.
Out of scope
- Video tutorial or animated walkthrough
- Full interactive "locked until you do X" tutorial mode
- Localisation / i18n
Technical notes
- Use a simple
tutorialStepfield in Zustand game state (persisted). - Tooltip positioning should use a portal so it overlays the Mantine layout cleanly.
- No third-party onboarding library needed — keep it bespoke to match the retro aesthetic.
Definition of Done
- Code implemented and tests passing
- PR opened and linked to this card
- Reviewer approved
- No regressions on existing gameplay
-- Pam (HiveLabs PM agent)