Onboarding Redesign, Soft Paywall & Free Tier — Design Spec

Date: 2026-07-06 Status: Implemented Design reference: design/stitch-onboarding/ (Stitch export: 10 screens, light + dark variants, code.html per screen, design tokens in botanical_vitality/DESIGN.md (light) and nocturnal_botanical/DESIGN.md (dark))

Goal

Replicate the Learna-style onboarding → soft paywall → sign-up flow, remove the hard paywall (client and server), and introduce a free tier with 3 monthly scan credits. Sign-up moves to the end of onboarding, after the paywall (pattern credited with +52% sales in the reference video).

1. New user flow

Welcome (social proof)
→ Benefit slides (3)
→ Personalization questions (existing: source, goal, experience, customize)
→ "Personalizing your care plan…" progress screen
→ Paywall (dismissible ✕)
→ Sign-up (Continue with Apple / Email)
→ App (tabs), free plan with 3 credits/month

The guest demo scan stays available from the welcome screen, but it must use the same AI identification path as a normal scan. Demo scans must never return local hash/mock plant results or fake confidence values.
Existing users: "Log in" link on the welcome screen → login.
Paywall ✕ during onboarding → continues to sign-up. Paywall ✕ in-app → simply closes.

2. Screens

Each screen follows the Stitch mockup in design/stitch-onboarding/<name>/screen.png (+ _dark_mode variant). code.html is the source of truth for spacing/sizes. Design tokens (colors, Plus Jakarta Sans-style extra-bold typography) come from the two DESIGN.md files, mapped into the existing constants/Colors.ts light/dark system.

Screen	Stitch reference	Implementation	Imagery
Welcome	`welcome_to_greenlens`	Redesign `app/onboarding.tsx`: hero photo, rating badge "4.8", testimonial card, "Let's Go" CTA, "Log in" link, legal footer. Keep demo-scan entry.	Bright plant-room photo (new or existing asset)
Benefit slide 1 "Scan Any Plant"	`scan_any_plant`	New screen(s), progress dots, Continue	Reuse existing render style (`assets/onboarding_*_mockup.png` language); scan-frame + "Monstera identified · 98%" chip built natively in RN, NOT baked into the photo
Benefit slide 2 "Health Check & Care Plan"	`health_check_care_plan`	New screen	Photo + native overlay card (Overwatering detected / 7-day rescue plan ready)
Benefit slide 3 "Never Forget Watering"	`never_forget_watering`	New screen	Photo + native reminder chips
Personalization questions	`personalization_question`	Restyle existing `app/onboarding/{source,goal,experience,customize}.tsx`: top progress bar + back arrow, white option cards radius 16, selected = green border + tint, Continue button	Emoji/icon per option
Personalizing progress	`personalizing_your_plan`	New screen: animated % + progress ring, sequential checkmarks ("Analyzing your answers", "Building your care plan", "Preparing your scan credits", "Finalizing your plan"), testimonial card (filled stars), rating badge. Auto-advances to paywall.	Small round plant photo in ring
Paywall	`greenlens_pro_paywall`	Redesign paywall mode of `app/profile/billing.tsx`: ✕ top-left, Restore top-right, "GreenLens Pro / Get Unlimited Access", plan card, Free Trial toggle (ON = yearly with 7-day trial → "Due today €0 / Due €39.99"; OFF = monthly, no trial), CTA "Try Free"/"Start Now", Cancel Anytime, Privacy/Terms. Dates dynamic. Credit top-ups remain reachable.	`assets/paywall_scan_background.png` as header
Sign-up	`sign_up_for_greenlens`	Restyle `app/auth/signup.tsx`: dark botanical hero with ", Let's finish your setup!" (name from onboarding answers if given, else generic), "Continue with Apple" (exists), OR divider, "Continue with Email" expanding to email/password fields (two-step), "Already have an account? Log in", legal.	`assets/welcome_botanical_hero.png` (replaces Stitch photo with baked-in fake form)
Login	`login_to_greenlens`	Restyle `app/auth/login.tsx`: "Welcome back!", Apple button, email/password, Forgot password?, "New here? Create account".	Clean botanical photo (existing assets)
Out of credits	`out_of_credits`	New bottom sheet over scanner: leaf icon with "0" badge, "You're out of free scans", renewal date, "See Pro Plans" → paywall, top-up chips (+30/+100/+250, BEST badge on 250), "Maybe later".	—

Known mockup fixes (agreed): replace AI-artifact photos (garbled phone UI on scan slide, fake forms baked into sign-up/login backgrounds), filled stars on testimonials, dynamic dates.

3. Free tier (backend, `server/lib/billing.js` + `server/index.js`)

FREE_MONTHLY_CREDITS: 0 → 3. Existing monthly-allowance reset logic already covers free accounts; verify reset works for plan free.
Remove server hard paywall: drop ensureActiveProEntitlement from scan and health-check endpoints (server/index.js). Credit consumption becomes the only gate; 0 credits → existing 402 INSUFFICIENT_CREDITS error.
Same scan model for free and pro (getScanModel returns the pro model for both plans). Cost accepted (~cents/user/month at 3 scans).
Low-confidence AI review pass stays pro-only (unchanged) so a free scan never burns 2 credits, and Pro keeps a quality edge.
Guest demo scans use AI identification without consuming account credits. Guests remain blocked from health checks and semantic search, but /v1/scan may run the primary identification model for the limited pre-auth demo experience.
Trial handling unchanged (yearly plan carries 7-day trial, 30 credits during trial).

4. Soft paywall (app)

app/_layout.tsx: remove the !hasActiveEntitlement → Redirect /profile/billing block (line ~169). Signed-in users always reach the tabs regardless of plan.
Scanner: on 402 INSUFFICIENT_CREDITS → open the out-of-credits bottom sheet (dismissible) instead of blocking.
Free users see a credits badge (e.g. "3 scans left") on Home/Scanner so the limit is visible before it bites.
Existing PostHog events (trial_started, purchase events) stay; add events for paywall_shown / paywall_dismissed / onboarding step views.

5. Out of scope

Instagram-story auto-advance on benefit slides (manual Continue first)
Win-back / cancellation flows
Android Google Sign-In (RevenueCat Android key still placeholder)
Chat-style onboarding rebuild

6. Open questions

Exact free-credit renewal display date source (billing summary already exposes renewal info for pro; confirm shape for free accounts).
Whether existing signed-in free users (previously hard-walled) need a one-time "you now have 3 free scans" toast. Nice-to-have.

6.7 KiB Raw Blame History