Book Creation Wizard & Onboarding Flow

This document describes the complete book creation wizard flow and the post-payment onboarding experience that guides new users through their first book setup.

Overview

The book creation wizard guides users through a multi-step process to set up their first book, including optional print book pre-ordering and subscription selection. When users complete the wizard (including payment), they land on their book detail page. Without guidance, this can feel overwhelming - especially for our senior audience. The post-payment onboarding system provides a senior-friendly contextual experience that educates users about their options without forcing a rigid tutorial.

Book Creation Wizard Flow

The wizard consists of 9 steps that progressively gather information and preferences:

┌──────────────────┐
│  1. Choose Path  │ → Who is this for?
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ 2. Storyteller   │ → (Conditional: if not "self")
│      Info        │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  3. Template     │ → Select story prompts
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  4. Book Details │ → Title, description, cover
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│    5. Goals      │ → Story count & timeline
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  6. Reminders    │ → Weekly prompt emails
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ 7. Print Order   │ → Pre-order books (NEW!)
│   [EARLY BIRD]   │   $79 first + $59 each
│                  │   OR skip for later
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ 8. Subscription  │ → Choose plan
│  [+ BOOKS ADDED] │   Combined checkout
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│   9. Review      │ → Final confirmation
└────────┬─────────┘
         │
         ▼
    [PAYMENT]
         │
         ▼
  [BOOK CREATED]
         │
         ▼
┌──────────────────┐
│  Book Detail     │
│  Page + Welcome  │
│     Onboarding   │
└──────────────────┘

Wizard Steps

1. Choose Path (choose-path)

   • Determines who the book is for: self, family member, or gift
   • Affects personalization throughout the wizard
   • Component: ChoosePathStep.tsx

2. Storyteller Info (storyteller-info)

   • Shown only if path is NOT “self”
   • Captures storyteller’s name and relationship
   • Component: StorytellerInfoStep.tsx

3. Template Selection (template)

   • Choose from pre-defined story prompt templates
   • Determines the structure and prompts for the book
   • Component: TemplateSelectionStep.tsx

4. Book Details (book-details)

   • Book title and description
   • Cover photo selection
   • Component: BookDetailsStep.tsx

5. Goals (goals)

   • Set target number of stories (defaults to 10)
   • Set target completion date (auto-calculated based on story count)
   • Component: GoalsStep.tsx

6. Reminders (reminders)

   • Configure weekly story prompt emails
   • Choose email frequency and preferences
   • Component: RemindersStep.tsx

7. Print Order (print-order) - NEW

   • Pre-order 1-5 printed books at early bird pricing
   • Pricing:
     • First book: $79
     • Additional books: $59 each (bulk discount)
     • Maximum savings: $80 when ordering 5 books
   • Skip option: Order later at full price ($79/book)
   • What’s included:
     • Hardcover, professionally printed
     • Up to 200 pages of stories & photos
     • Premium paper quality (100# silk)
     • Custom cover with photos
     • Free shipping in US & Canada
     • Ships within 2 weeks of completion
   • Component: PrintOrderStep.tsx

8. Subscription (subscription)

   • Choose between Starter, Family, or Premium plans
   • Select monthly or annual billing
   • Combined checkout: If books were pre-ordered in step 7, they’re added to the subscription checkout
   • Component: SubscriptionStep.tsx

9. Review (review)

   • Summary of all selections
   • Final confirmation before creating book and processing payment
   • Component: ReviewAndStartStep.tsx

Wizard Navigation

The wizard provides:

• Progress indicator showing current step and completion
• Back button to return to previous steps
• Next/Continue button to advance (disabled until step is valid)
• Cancel button (hidden for first-time users with isOnboarding={true})

Location: /apps/web-app/app/components/books/BookCreationWizard.tsx

Print Order Integration

The PrintOrderStep introduces a new revenue opportunity and user value:

Business Logic:

• Users can pre-order 1-5 books during wizard setup
• Early bird pricing provides up to $80 in savings
• Books are added to the subscription checkout (step 8)
• Orders are fulfilled after book completion (minimum 6 stories required)

User Experience:

• Clear pricing display with per-book breakdown
• “Popular” badge on 2-book option
• Expandable details section (“What’s included?”)
• Gift idea callout to encourage multiple book purchases
• Skip button for users who want to order later

Technical Implementation:

export interface PrintOrderData {
  number_of_books: number
  skip_print_order: boolean
}

Pricing Calculation:

// From config/pricing.ts
export const BOOK_PRICING = {
  base: 79,  // Base price for a printed book
  bulk: 59,  // Bulk price for additional books
  minStories: 6, // Minimum stories required for a book
}
 
// First book: $79, additional books: $59
// Example: 3 books = $79 + $59 + $59 = $197 (save $40 vs 3 × $79)

Consistency Note: This same book pricing structure is used across all purchase flows:

• Book Creation Wizard (self/family paths) - PrintOrderStep with early bird pre-order
• Gift Purchase Flow - Books Selection step (see Gift Purchase Flow)

Both flows use calculateBookPricing() from config/pricing.ts to ensure pricing consistency.

Post-Wizard Onboarding Experience

After completing the wizard and payment, users land on their book detail page. This is where the contextual onboarding system takes over to guide them through their first story creation.

Design Philosophy

Based on industry best practices for senior UX  and Nielsen Norman Group research , we implement:

Key Principles

1. No Time Pressure - Users can take as long as they need
2. Gradual Information - Show one thing at a time, not everything at once
3. Simple Interactions - Tap/click only, no swipes or gestures required
4. Large Touch Targets - Minimum 44x44px for all interactive elements (Apple HIG)
5. Clear Language - Warm, helpful, non-condescending tone
6. Consistent Patterns - Same UI patterns throughout the app

Components

Wizard Components

BookCreationWizard

Location: /apps/web-app/app/components/books/BookCreationWizard.tsx

The main wizard orchestrator component that manages step progression, data collection, and book creation.

Key Features:

• 9-step progressive wizard flow
• Step validation before allowing progression
• Back/Next navigation with state preservation
• Combined checkout for subscription + print books
• Conditional step display (storyteller-info only shown when needed)

Props:

interface BookCreationWizardProps {
  onBookCreated: (bookId: string) => void
  onCancel: () => void
  isOnboarding?: boolean // Hides cancel for first-time users
}

Wizard Step Components

All step components follow a consistent pattern:

Standard Step Interface:

interface StepProps {
  data: StepDataType
  onChange: (data: Partial<StepDataType>) => void
  // Additional context props as needed
  storytellerName?: string
  userPath?: UserPath
}

Post-Wizard Components

1. BookWelcomeState

Location: /apps/web-app/app/components/books/BookWelcomeState.tsx

A rich empty state component that replaces the minimal “No stories yet” message with an educational, inviting experience.

Features

• Personalized Greeting: Uses book.storyteller_name and creator_relationship to personalize the welcome message
• 3 Equal-Prominence Methods: Write, Record, and AI Chat options are presented with equal visual weight
• Time Estimates: Each method shows approximate completion time
• First Prompt Preview: Shows the first prompt from the selected template
• Reassurance Tip: Reminds users they can switch methods anytime
• Help Modal: “Need help?” button opens a simple step-by-step guide

Usage

import { BookWelcomeState } from '@/app/components/books/BookWelcomeState'
 
// In your book detail page
{stories.length === 0 && isOwner && (
  <BookWelcomeState
    book={book}
    onSelectWrite={handleSelectWrite}
    onSelectRecord={handleSelectRecord}
    onSelectChat={handleSelectChat}
  />
)}

2. FirstTimeTip

Location: /apps/web-app/app/components/ui/FirstTimeTip.tsx

A contextual tip component that shows once per feature, helping users discover functionality without interrupting their flow.

Features

• Inline or Positioned: Can render as a banner or floating tooltip
• Animated Entrance: Smooth fade-in after configurable delay
• Large Dismiss Button: 44px+ touch target for easy dismissal
• Warm Styling: Amber/orange gradient matching brand colors
• Accessible: ARIA roles, focus management, keyboard support

Usage

import { FirstTimeTip } from '@/app/components/ui/FirstTimeTip'
import { useTip } from '@/lib/stores/onboardingTipsStore'
 
function MyComponent() {
  const welcomeTip = useTip('book-welcome')
 
  return (
    <FirstTimeTip
      show={welcomeTip.shouldShow}
      onDismiss={welcomeTip.dismiss}
      title="Welcome to your book!"
    >
      Pick any method below to start your first story.
    </FirstTimeTip>
  )
}

3. Onboarding Tips Store

Location: /apps/web-app/lib/stores/onboardingTipsStore.ts

A Zustand store that tracks which tips have been dismissed, persisting to localStorage.

Available Tips

API

import { useTip, useOnboardingTipsStore } from '@/lib/stores/onboardingTipsStore'
 
// Hook for individual tips
const { shouldShow, dismiss } = useTip('book-welcome')
 
// Full store access
const { dismissAllTips, resetAllTips } = useOnboardingTipsStore()

4. InputMethodModal (Extended)

Location: /apps/web-app/app/components/books/InputMethodModal.tsx

The existing input method modal has been extended to include AI Chat as a third equal option.

New Props

interface InputMethodModalProps {
  // ... existing props
  onSelectChat?: () => void
  showChatOption?: boolean // defaults to true
}

Visual Assets

Animated SVG demos are provided in /public/onboarding/:

• write-demo.svg - Typing animation with cursor blink
• record-demo.svg - Microphone with sound wave animation
• chat-demo.svg - Chat bubbles with typing indicator

These are simple, fast-loading SVGs with CSS animations. They can be replaced with GIF/WebM videos for more detailed demos in the future.

Mobile Responsiveness

The onboarding components are mobile-first:

Mobile-Specific Features

• Cards stack vertically for easy thumb reach
• Animated demos auto-play (no tap required)
• Tip dismissal via large “Got it” button
• Help button easily accessible

Accessibility

All onboarding components follow WCAG AA guidelines:

• Contrast: 4.5:1 minimum for all text
• Focus: Visible focus indicators on all interactive elements
• Screen Readers: Proper ARIA labels and roles
• Keyboard: Full keyboard navigation support
• Motion: Respects prefers-reduced-motion for animations

Success Metrics

Track these metrics to measure onboarding effectiveness:

Integration Points

New User Flow

1. User clicks “Create Book” (from dashboard or books page)
2. BookCreationWizard opens in a modal/full-screen view
3. User completes 9 steps including PrintOrderStep and SubscriptionStep
4. Combined checkout processes subscription + book pre-order payment
5. Book is created in Supabase with all wizard data
6. User lands on book detail page with BookWelcomeState shown

Book Creation Entry Points

Primary Entry:

• /apps/web-app/app/books/page.tsx - “Create Your First Book” button
• /apps/web-app/app/page.tsx (Dashboard) - “Start Your Book” CTA

Wizard Usage:

import { BookCreationWizard } from '@/app/components/books/BookCreationWizard'
 
function BooksPage() {
  const [showWizard, setShowWizard] = useState(false)
 
  const handleBookCreated = (bookId: string) => {
    router.push(`/books/${bookId}`)
    setShowWizard(false)
  }
 
  return (
    <>
      <Button onClick={() => setShowWizard(true)}>
        Create Your First Book
      </Button>
 
      {showWizard && (
        <BookCreationWizard
          onBookCreated={handleBookCreated}
          onCancel={() => setShowWizard(false)}
          isOnboarding={books.length === 0}
        />
      )}
    </>
  )
}

Book Detail Page

After wizard completion, users land on the book detail page at /apps/web-app/app/books/[id]/page.tsx:

// Lines 420-435
{stories.length === 0 ? (
  isOwner ? (
    <div className="py-2">
      <FirstTimeTip
        show={welcomeTip.shouldShow}
        onDismiss={welcomeTip.dismiss}
        title="Welcome to your book!"
      >
        Pick any method below to start your first story.
      </FirstTimeTip>
 
      <BookWelcomeState
        book={book}
        onSelectWrite={handleSelectWrite}
        onSelectRecord={handleSelectRecord}
        onSelectChat={handleSelectChat}
      />
    </div>
  ) : (
    // Non-owner empty state
  )
) : (
  // Story list
)}

Story Creation Routes

The method selection navigates to:

• Write: /books/[id]/stories/new?method=write
• Record: /books/[id]/stories/new?method=record
• Chat: /books/[id]/stories/new?method=chat

The method query param should be read by the story creation page to pre-select the appropriate input mode.

Future Enhancements

Wizard Enhancements

1. Save & Resume: Allow users to save wizard progress and return later
2. Gift Messaging: Add step for gift recipients to include personal message
3. Book Preview: Show visual preview of book layout in Review step
4. Bulk Discount Tiers: Add higher volume discounts (6-10 books, 11+ books)
5. Shipping Options: Express shipping for additional fee
6. Analytics Tracking: Track drop-off rates per wizard step

Post-Wizard Enhancements

1. Video Demos: Replace SVG placeholders with recorded GIF/WebM demos
2. Supabase Sync: Sync tip dismissal state to profiles.onboarding_data for cross-device consistency
3. Progressive Disclosure: Add more tips as users explore features
4. A/B Testing: Test different tip wording and timing
5. Method Analytics: Track which methods users choose and completion rates
6. Smart Reminders: Use book goals and reminders data to send targeted nudges

Related Documentation

• v1.1 UX Roadmap - Overall UX strategy and simplification
• Database Schema - Schema for books, stories, subscriptions
• Unified Story Canvas - Story editing experience
• Pricing Configuration - Subscription and book pricing details
• Gift Purchase Flow - Alternative flow for gifting books to others (shares book pricing structure)