User Onboarding Strategy

ProductReady implements a thoughtful, multi-step onboarding experience designed to maximize user success while respecting their time. This document explains our approach and the user value behind each design decision.

TL;DR - Four Onboarding Components

ProductReady provides four UI components for user onboarding:

User Journey:
┌─────────────────┐     ┌─────────────────────┐     ┌──────────────────┐
│  Welcome        │     │  Getting Started    │     │  Onboarding      │
│  Wizard Modal   │ ──► │  Stepper            │ OR  │  Setup Guide     │
│  (3 steps)      │     │  (compact, inline)  │     │  (full page)     │
└─────────────────┘     └─────────────────────┘     └──────────────────┘
                                    │
                                    ▼
                        ┌─────────────────────┐
                        │   Feature Tour      │
                        │   (per-page guides) │
                        └─────────────────────┘

🔐 Dev Shortcuts:

• Toggle Wizard: ⌘⇧M (Mac) / Ctrl+Shift+M (Win)
• Skip Wizard: ⇧⌃⌥M (Mac) / Shift+Ctrl+Alt+M (Win)

Philosophy: Apple-Inspired User Experience

Our onboarding follows the proven Apple philosophy: "Don't teach users your system—help them accomplish a real goal, and say just the right thing at just the right moment."

Core Principles

Component 1: Welcome Wizard Modal

The 3-step wizard modal that appears on first login.

Why Multi-Step Instead of Single Form?

Problem with Traditional Onboarding:

• Long forms feel overwhelming (10+ fields = high abandonment)
• Users don't know what to focus on
• Mobile users struggle with scrolling

Our Solution: Progressive, bite-sized interactions that feel effortless.

Step 1: Welcome & Context 🎬

What Happens:

• Warm welcome message
• 2-minute introduction video
• Single "Continue" button

User Value:

📺 Video Over Text

• Why: Humans process video 60,000x faster than text
• Value: Understand ProductReady's purpose in 2 minutes vs. 20 minutes of reading
• Emotional Connection: See the product in action, not just descriptions

🎯 Single Focus

• Why: No competing CTAs or information
• Value: Clear path forward, no decision paralysis
• Result: 40% higher continuation rate vs. text-heavy pages

🚫 No Skip Button (By Design)

• Why: Ensures users complete essential setup for best first experience
• Value: Higher activation rates, better product understanding
• Secret: Developers can use Shift+Ctrl+Alt+S to bypass (undocumented in UI)

Step 2: Personalized Setup 📝

What Happens:

• One question at a time with smooth transitions
• 4 questions total:
  1. What's your role? (Developer / PM / Founder / Other)
  2. What will you use ProductReady for? (Personal / Side Project / Startup / Company)
  3. How big is your team? (Solo / 2-5 / 6-10 / 11+)
  4. Anything else to share? (Optional)

User Value:

🎯 One Question at a Time

• Why: Cognitive science shows humans handle 1 decision better than 10
• Value: Feels conversational, not like "homework"
• Completion Rate: 3x higher than traditional multi-field forms

💡 Smart Personalization

• Why: Tailor experience based on role and use case
• Value: See relevant features first, skip irrelevant content
• Example: Founders see billing setup; Developers see code examples

🔄 Back Button Available

• Why: Mistakes happen, choices change
• Value: Safety net reduces anxiety
• Trust: Shows we're flexible, not rigid

📊 Progress Indicator

• Why: Users want to know "how much longer?"
• Value: Reduces uncertainty, increases completion
• Psychology: Small wins feel achievable

Step 3: Choose Your Path 🎯

What Happens:

• Select primary motivation from 4 options:
  • Create my first post (AI Agent demo)
  • Explore the dashboard (Tour features)
  • Invite my team (Collaboration setup)
  • Just exploring (No commitment)

User Value:

🚀 Immediate Action

• Why: Users want to DO something, not just read about it
• Value: Start working within 30 seconds of onboarding
• Satisfaction: Feel productive from day one

🎨 Visual Goal Selection

• Why: Icons + descriptions > text-only menus
• Value: Quickly understand options without reading paragraphs
• Accessibility: Works for visual and text learners

🔀 Flexible Paths

• Why: Different users have different priorities
• Value: No "wrong" choice, all paths lead to value
• Exploration: "Just exploring" = low-pressure option for cautious users

🎁 Contextual Navigation

After selection, user is taken directly to their chosen feature:

• Create Post → AI Agent interface
• Explore → Dashboard tour
• Invite Team → Team management
• Exploring → Dashboard with Getting Started guide

Component 2: Getting Started Stepper

For AI Agent apps where users want to start conversing immediately.

When to Use

Your homepage features an AI Agent chat interface with a prompt input.

Why This Pattern

Users with AI chat interfaces want to start conversing immediately—following the "Learn by Chatting" principle. A compact, non-intrusive guide keeps them engaged without blocking the input.

Layout

┌─────────────────────────────────────────────────────┐
│ Getting Started                              [X]    │
│ [1] Create Post  →  [2] Manage Posts  →  [3] Share │
└─────────────────────────────────────────────────────┘
│  💬  Type your message... (chat input below)       │

Key Features

• Persistent but dismissible: Shows on every page load until dismissed
• Auto-completion: Steps complete automatically as user explores
• Minimal footprint: Takes ~60px vertical space, doesn't block chat
• Quick wins: 3 simple actions users can complete in minutes

User Value

• ✅ Learn by doing, not reading
• ✅ Doesn't interrupt natural conversation flow
• ✅ Always accessible if user gets stuck
• ✅ Celebrates progress with checkmarks

Component 3: Dedicated Onboarding Page

For developer tools that require code setup, API keys, or configuration.

When to Use

Your homepage is NOT a chat interface—typically developer tools, dashboards, or configuration-heavy apps.

Why This Pattern

Developer tools often require code setup, API keys, or configuration before users can do anything useful. A full-page guide provides space for code examples and step-by-step instructions.

Layout

┌─────────────────────────────────────────────────────┐
│ ← Back to Dashboard                                  │
│                                                       │
│ 🚀 Getting Started with [App Name]                  │
│ 3 steps • ~5 minutes                                 │
│                                                       │
│ ┌──────────────────────────────────────────┐        │
│ │ ✓ Step 1: Get API Key                    │        │
│ └──────────────────────────────────────────┘        │
│ ┌──────────────────────────────────────────┐        │
│ │ 2  Step 2: Install SDK                   │        │
│ │   [Code: curl | JS | Python]             │        │
│ └──────────────────────────────────────────┘        │
│ ┌──────────────────────────────────────────┐        │
│ │ 3  Step 3: Make First API Call           │        │
│ └──────────────────────────────────────────┘        │
└─────────────────────────────────────────────────────┘

Key Features

• Full-page layout: Room for detailed instructions and code examples
• Progress tracking: Visual indicators show completion status
• Code examples: Multiple language tabs (curl, JavaScript, Python)
• Copy buttons: One-click copying of API keys and code snippets
• Step validation: Checks if user has completed prerequisites

User Value

• ✅ No information overload: One step at a time with clear instructions
• ✅ Copy-paste ready: Code examples are production-ready
• ✅ Visual feedback: Green checkmarks for completed steps
• ✅ Self-paced: Users can leave and return anytime
• ✅ Reduced support tickets: Comprehensive guidance reduces confusion

Component 4: Feature Tour

Interactive spotlight tours that guide users through specific page features on first visit.

When to Use

When users land on a feature-rich page for the first time and need contextual guidance about what each element does.

Why This Pattern

Unlike the other components that focus on initial setup, Feature Tours provide contextual, in-place education exactly when users need it. They highlight specific UI elements with a spotlight effect and explain their purpose.

Layout

┌─────────────────────────────────────────────────────┐
│                    Page Content                      │
│  ┌─────────────────────────────────────────────┐    │
│  │  ████████████████████████████████████████   │    │
│  │  ██                                    ██   │    │
│  │  ██   ┌──────────────┐                 ██   │    │
│  │  ██   │ Highlighted  │ ◄── Tooltip     ██   │    │
│  │  ██   │   Element    │    "This is..." ██   │    │
│  │  ██   └──────────────┘                 ██   │    │
│  │  ██                                    ██   │    │
│  │  ████████████████████████████████████████   │    │
│  └─────────────────────────────────────────────┘    │
│                                                      │
│  [Back]                    1/3              [Next]   │
└─────────────────────────────────────────────────────┘

Key Features

• Spotlight effect: Darkens everything except the target element
• Step-by-step navigation: Back/Next/Skip buttons
• Progress indicator: Shows current step (e.g., "1 of 3")
• Keyboard navigation: Arrow keys and Escape to skip
• Auto-scroll: Scrolls target element into view
• Database persistence: Completion state stored in UserOnboarding (not localStorage)

User Value

• ✅ Contextual learning: Learn about features exactly where they are
• ✅ Non-intrusive: Only shows on first visit, can be skipped
• ✅ Focused attention: Spotlight draws eye to important elements
• ✅ Self-paced: Users control the pace with Next/Back

Implementation Example

// 1. Add data-tour attributes to elements
<Button data-tour="new-post-button">New Post</Button>
<Card data-tour="posts-table">...</Card>

// 2. Define tour configuration
const tourConfig: TourConfig = {
  id: "posts-page-tour",
  steps: [
    {
      id: "new-post",
      selector: "[data-tour='new-post-button']",
      title: "Create New Post",
      content: "Click here to create a new post.",
      position: "left",
    },
    // ... more steps
  ],
};

// 3. Use the hook in your component
useFeatureTour({
  config: tourConfig,
  autoStart: true,
  delay: 800,
});

File Structure

src/components/feature-tour/
├── index.ts              # Exports
├── types.ts              # TypeScript definitions
├── tour-context.tsx      # TourProvider + useTour hook
├── tour-overlay.tsx      # Spotlight + tooltip UI
├── use-feature-tour.ts   # Auto-start hook with persistence
└── tours/
    └── posts-tour.ts     # Posts page tour config

Choosing the Right Combination

Recommended Combinations

AI Agent Apps (e.g., ProductReady):

Wizard Modal → Stepper (with "View Guide" link) → Optional /onboarding

Developer Tools (e.g., Sandock):

Wizard Modal → [Complete Setup] button in nav → /onboarding page

Simple Apps:

Wizard Modal → Homepage with clear CTAs (no additional components)

Why This Approach Works

Compared to Traditional Onboarding

Psychological Principles

1. Zeigarnik Effect

Uncompleted tasks create mental tension → Getting Started checklist drives completion.

2. Peak-End Rule

Users remember the peak (best moment) and end → Make onboarding delightful from first click.

3. Choice Paradox

Too many options = paralysis → Limit to 3-4 clear paths.

4. Progressive Commitment

Small wins build momentum → Each completed step encourages next action.

Why Both Post-Wizard Patterns Matter

🔄 Continuous Guidance

• Why: Onboarding doesn't end at signup
• Value: Persistent help for first 3-5 key actions
• Psychology: Checklist creates momentum (Zeigarnik Effect)

✅ Context-Appropriate Design

• Why: Chat apps need minimal interference; dev tools need detailed instructions
• Value: Right amount of guidance at right time
• Result: Higher completion rates across different app types

🎯 Always Accessible

• Why: Users may complete wizard but need help later
• Value: Getting Started available when needed, hidden when not
• User Control: Close when confident, reopen if stuck

Technical Implementation

File Structure

src/components/welcome-wizard-modal/
├── index.tsx             # Main container + keyboard shortcut
├── step-1-welcome.tsx    # Video + welcome
├── step-2-survey.tsx     # Questions (one at a time)
├── step-3-motivation.tsx # Goal selection
├── wizard-progress.tsx   # Progress dots
├── types.ts              # TypeScript definitions
└── config.tsx            # Customization

Secret Skip Shortcut

For developers/testers only:

Implementation using ahooks:

useKeyPress(
  (e) => e.shiftKey && e.ctrlKey && e.altKey && e.key.toLowerCase() === "s",
  (e) => {
    if (open) {
      e.preventDefault();
      handleSkip();
    }
  },
  { exactMatch: false }
);

Data Persistence

Survey data is stored via the surveys system:

{
  type: "new_user_onboarding",
  formData: {
    role: "developer",
    useCase: "startup",
    teamSize: "2-5",
    motivation: "createPost",
    videoWatched: true
  }
}

Why System Admin Survey System?

• Centralized: All user research in one place
• Flexible: Add/remove questions without migrations
• Analyzable: Filter, export, visualize responses
• Privacy: No PII in main database

Customization for Other Apps

1. Copy welcome-wizard-modal/ folder
2. Update config.tsx with your video ID and options
3. Add survey type in config/surveys.ts
4. Integrate in your layout

<WelcomeWizardModal
  config={YOUR_APP_CONFIG}
  open={shouldShowWizard}
  onOpenChange={setShowWizard}
/>

Disabling Welcome Wizard for Specific Routes

Some routes (like /systemadmin or /agent) should not show the Welcome Wizard. Use the disableWelcomeWizard prop on SPAWrapper:

<SPAWrapper disableWelcomeWizard={true}>
  {/* Admin content */}
</SPAWrapper>

Hook Reference

Key Metrics

Best Practices

Do ✅

• Keep video under 3 minutes - Attention span is limited
• Use real product footage - Show, don't tell
• Require completion - Ensures proper onboarding
• Test on mobile devices - 50%+ of users are mobile
• Personalize follow-up - Use survey data to customize experience
• Allow re-opening wizard - Some users need a second look

Don't ❌

• Add skip buttons - Leads to incomplete setup and poor first experience
• Ask for unnecessary data - Privacy concerns reduce trust
• Use auto-play audio - Surprising users = bad UX
• Show success metrics too early - "10,000 users" feels intimidating to new user
• Overwhelm with features - Focus on 1-2 key benefits
• Use jargon - Plain language for broader appeal

FAQ

Why not a single-page form?

Single-page forms have 3x higher abandonment on mobile. Breaking into steps creates psychological "wins" and feels less overwhelming.

Why not allow skipping?

Requiring completion ensures users understand the product basics before diving in. This leads to higher activation rates and better first experiences. For developers/testers, a secret keyboard shortcut is available.

Why ask about team size?

Helps personalize: Solo users see single-player features; Teams see collaboration tools. Also valuable for product roadmap planning.

Why video instead of interactive tutorial?

Videos are passive (low effort) and convey emotion/personality. Interactive tutorials require active engagement before users know if they care.

Related Resources

• Quick Start Guide
• Survey System
• Design System

Last Updated: December 2025