[UX] Build User Onboarding Wizard, Feature Beacons, and Guided First-Time Experience

[KarenZita01]

Description

The frontend has no Guided User Experience (onboarding) for new users. When a user connects their wallet for the first time, they are dropped into a blank dashboard with no guidance on how to register a meter, create a stream, or fund their gas buffer. First-time user experience is critical for adoption.

Onboarding gaps:

• No welcome wizard for first-time users
• No tooltip/beacon system to highlight features
• No sample/demo data mode for exploration
• No empty states with actionable CTAs
• No progress tracking showing onboarding completion
• No help/documentation links in context
• No FAQ/help page for common questions
• No tutorial mode with step-by-step guidance
• No video explainer or interactive demo integration

Technical Context & Impact

• Affected Components/Files: src/components/onboarding/ (missing), app/onboarding/ (missing)
• Impact: High churn rate for new users; users don't understand product value

Step-by-Step Implementation Guide

1. Create onboarding wizard: app/onboarding/page.tsx:
   • Step 1: Connect Wallet - verify Freighter/other wallet is installed
   • Step 2: Create Your First Meter - guide to register a meter
   • Step 3: Fund Gas Buffer - explain gas buffer and guide top-up
   • Step 4: Explore Dashboard - overview of key features
   • Progress bar showing completion percentage
   • Skip button for experienced users
2. Implement beacon/tooltip system: src/components/onboarding/Beacon.tsx:
   • Highlight elements with pulsing animation
   • Tooltip explaining what the element does
   • "Got it" button to dismiss
   • Sequential: one beacon at a time
   • Store dismissed beacons in localStorage
3. Create empty states: Each data view (meters, streams, billing) needs:
   • Friendly illustration
   • Explanation: "You haven't registered any meters yet"
   • CTA button: "Register Your First Meter"
   • Link to documentation
4. Add help drawer: src/components/help/HelpDrawer.tsx:
   • Click "?" icon to open
   • Searchable FAQ
   • Quick links to documentation
   • Report issue / contact support
   • Keyboard shortcut: ? to toggle
5. Create demo mode: NEXT_PUBLIC_DEMO_MODE=true shows sample data for exploration without real wallet
6. Add onboarding progress tracking: src/lib/onboarding/store.ts tracking which steps completed
7. Contextual help links: Each page has "Learn more" links to relevant docs

Verification & Testing Steps

1. Connect wallet for first time -> onboarding wizard launches automatically
2. Complete onboarding steps -> wizard dismisses -> dashboard shows with all features
3. View empty meters page -> shows empty state with "Register Your First Meter" CTA
4. Click beacon -> tooltip appears -> click "Got It" -> next beacon appears
5. Open help drawer with ? -> search FAQ -> find relevant article
6. Set demo mode -> verify all pages show realistic sample data