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.

Onboarding Types: User vs. Space

ProductReady distinguishes between two types of onboarding:

User Onboarding (One-time per user)

• Happens once when user first signs up
• Follows the user across all spaces
• Focuses on account setup, profile completion, and platform familiarization
• Examples: Email verification, profile setup, payment method, platform tour

Space Onboarding (Per space creation)

• Happens every time a user creates a new space/workspace
• Specific to each space context
• Focuses on space configuration, team setup, and project initialization
• Examples: Space naming, inviting team members, setting up integrations, initial project setup

Why this matters:

• User onboarding teaches "how to use the platform"
• Space onboarding teaches "how to set up this specific workspace"
• Users should never see user onboarding steps again after completion
• Users should see space onboarding for every new space they create

TL;DR - Four Onboarding Components

ProductReady provides four UI components for onboarding:

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

Space Journey (Space Onboarding):
┌─────────────────┐     ┌─────────────────────┐
│  Space Setup    │     │  Space Tour         │
│  Wizard         │ ──► │  (space-specific)   │
│  (4 steps)      │     │                     │
└─────────────────┘     └─────────────────────┘

🔐 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 (User Onboarding)

The 3-step wizard modal that appears on first login. This is USER onboarding - happens once per user account.

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 (User Onboarding)

For AI Agent apps where users want to start conversing immediately. This is USER onboarding - guides users through initial platform features.

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 (User Onboarding)

For developer tools that require code setup, API keys, or configuration. This is USER onboarding - teaches platform setup and 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 (User Onboarding)

Interactive spotlight tours that guide users through specific page features on first visit. This is USER onboarding - helps users discover platform features.

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

Component 5: Space Setup Wizard (Space Onboarding)

The wizard that appears when creating a new space. This is SPACE onboarding - happens every time a user creates a new space.

When to Use

Your app supports multiple spaces/workspaces, and each space needs configuration (team members, settings, integrations).

Why This Pattern

Unlike user onboarding (which happens once), space onboarding helps users configure each workspace they create. Users may create multiple spaces for different projects, teams, or purposes.

Layout

┌─────────────────────────────────────────────────────┐
│ Create New Space                            [X]      │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│                                                      │
│ Step 1 of 4: Space Basics                           │
│                                                      │
│ Space Name *                                         │
│ ┌──────────────────────────────────────────┐        │
│ │ My Awesome Project                       │        │
│ └──────────────────────────────────────────┘        │
│                                                      │
│ Space Type *                                         │
│ ○ Personal    ○ Team    ○ Enterprise                │
│                                                      │
│ Description (optional)                               │
│ ┌──────────────────────────────────────────┐        │
│ │                                          │        │
│ └──────────────────────────────────────────┘        │
│                                                      │
│                          [Back]  [Next: Team Setup] │
└─────────────────────────────────────────────────────┘

Space Onboarding Steps

Step 1: Space Basics

• Space name (required)
• Space type (Personal / Team / Enterprise)
• Description (optional)

Step 2: Team Setup (if team space)

• Invite team members by email
• Assign roles (Admin / Member / Viewer)
• Skip option: "I'll invite team later"

Step 3: Initial Configuration

• Choose project template (Blank / Starter Kit / Import)
• Select integrations (GitHub, Slack, Linear, etc.)
• All optional - can be configured later

Step 4: Space Tour

• Quick tour of space dashboard
• Highlight key features (settings, team management, projects)
• Show how to switch between spaces

Key Features

• Quick completion: < 5 minutes from start to finish
• Skippable steps: Team and integrations can be skipped
• Repeatable: Shows every time user creates a new space
• Context-aware: Different options for Personal vs. Team spaces
• Progress tracking: Visual indicator shows current step

User Value

• ✅ Organized workspaces: Separate spaces for different projects
• ✅ Team collaboration: Easy team member invitation
• ✅ Quick setup: Get started in minutes
• ✅ Flexible: Skip optional steps, configure later
• ✅ Consistent experience: Same flow for every new space

Implementation Example

// Trigger space setup wizard
<Button onClick={() => setShowSpaceWizard(true)}>
  Create New Space
</Button>

// Space wizard component
<SpaceSetupWizard
  open={showSpaceWizard}
  onOpenChange={setShowSpaceWizard}
  onComplete={(spaceData) => {
    // Create space and redirect
    createSpace(spaceData);
    router.push(`/spaces/${spaceData.id}`);
  }}
/>

When Space Onboarding Triggers

• User clicks "Create New Space" button
• User upgrades from personal to team plan
• User accepts team invitation (abbreviated version - skip space creation, show tour only)

Space vs. User Onboarding

Choosing the Right Combination

Recommended Combinations

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

User: Wizard Modal → Stepper (with "View Guide" link) → Optional /onboarding
Space: Space Wizard (if multi-space) → Space Tour

Developer Tools (e.g., Sandock):

User: Wizard Modal → [Complete Setup] button in nav → /onboarding page
Space: Space Wizard (if multi-space) → Space Tour

Multi-Space SaaS:

User: Wizard Modal → Feature Tour
Space: Space Wizard → Space Tour (every new space)

Simple Apps:

User: Wizard Modal → Homepage with clear CTAs (no additional components)
Space: Not applicable (single workspace)

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

User Onboarding Metrics

Space Onboarding 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.

What's the difference between user onboarding and space onboarding?

User onboarding happens once per user account and teaches platform usage. Space onboarding happens every time a user creates a new workspace and focuses on workspace configuration. Users should never see user onboarding again after completion, but will see space onboarding for each new space they create.

Why repeat space onboarding for every new space?

Each space may have different purposes (personal project vs. team collaboration), different team members, and different integrations. Repeating the setup wizard ensures each workspace is properly configured for its specific use case.

Related Resources

• Quick Start Guide
• Survey System
• Design System

Last Updated: December 2025