Skip to content

ONBOARDING_SETUP.md

Latest commit

 

History

History
334 lines (264 loc) · 9.03 KB

ONBOARDING_SETUP.md

File metadata and controls

334 lines (264 loc) · 9.03 KB
Raw

Dorian Onboarding - Implementation Complete ✓

What Was Built

A sophisticated, Anthropic-style onboarding experience with 8 screens that feels intelligent, thoughtful, and premium while remaining warm and human.

Flow Structure

  1. Welcome (Email)

    • Elegant email input with real-time validation
    • Checkmark animation on valid email
    • Helper text: "We'll use this to save your work and send important updates"

  2. Personal (Name)

    • First name (required) + Last name (optional)
    • Auto-focus on first input
    • Press Enter to continue

  3. Organization (Company)

    • Optional step with "Skip this step" link
    • Company/organization name input
    • Helpful context text

  4. Business Category (Industry)

    • 12 elegant cards with titles + descriptions
    • Auto-advance on selection (400ms delay)
    • Smooth hover states and checkmark animations

  5. Team Size (Scale)

    • 6 minimal selection pills
    • Range from "Just me" to "1,000+ people"
    • Auto-advance on selection

  6. Primary Intent (Goals)

    • 6 thoughtful goal cards (multi-select)
    • Email Intelligence, Customer Conversations, Data Transformation, etc.
    • Continue button appears after ≥1 selection

  7. Toolkit (Tools)

    • Searchable grid of popular tools
    • Organized by category (Communication, Productivity, etc.)
    • Multi-select with checkmarks
    • "I'll configure this later" skip option

  8. Loading (Preparing)

    • Rotating status messages
    • Smooth progress bar (0-100%)
    • Elegant completion checkmark
    • Auto-redirect to builder

Design System

Colors (Anthropic-Inspired)

  • Primary: #6a041d (Maroon)
  • Background: #faf7f2 (Warm off-white)
  • Surface: #fbf9f6 (Secondary bg)
  • Text: Warm neutrals with proper hierarchy

Typography

  • Headings: Fraunces (300 weight, large sizes)
  • Body: DM Sans (400-600 weights)
  • No emojis - keeps it sophisticated
  • Thoughtful copy - every word is intentional

Animations (Linear-Inspired)

  • Screen transitions: 400ms slide + fade
  • Card selection: Spring physics
  • Input validation: Smooth shake on error
  • Checkmarks: Scale + fade entrance
  • Loading: Linear progress with message rotation

Features Implemented

State Management ✓

  • Auto-save to localStorage after each step
  • Resume from last step on page refresh
  • Data persists until completion
  • Clean up on successful completion

Navigation ✓

  • Back button on all steps (except first)
  • Keyboard shortcuts:
    • Enter - Continue (when valid)
    • Escape - Go back
  • Progress indicator (1/7, 2/7, etc.)

Validation ✓

  • Email: Real-time regex validation with elegant error states
  • Required fields: Smooth feedback
  • Auto-advance: Cards and pills (400ms delay)
  • Multi-select: Dynamic continue button

Accessibility ✓

  • Semantic HTML throughout
  • Keyboard navigation
  • Focus management (auto-focus on inputs)
  • Touch-friendly (48px minimum on mobile)
  • Respects prefers-reduced-motion

File Structure

dorian/dorian-ui/src/components/onboarding/
├── OnboardingFlow.jsx              # Main orchestrator (state, routing)
├── OnboardingFlow.css              # Comprehensive styling
├── README.md                       # Full documentation
├── index.js                        # Exports + utilities
├── components/
│   ├── ProgressIndicator.jsx      # Progress bar component
│   ├── ProgressIndicator.css
│   ├── StepContainer.jsx          # Wrapper for each step
│   ├── StepContainer.css
│   ├── AnimatedInput.jsx          # Elegant form inputs
│   └── AnimatedInput.css
└── steps/
    ├── WelcomeStep.jsx            # Step 1: Email
    ├── PersonalStep.jsx           # Step 2: Name
    ├── OrganizationStep.jsx       # Step 3: Company
    ├── BusinessCategoryStep.jsx   # Step 4: Industry
    ├── TeamSizeStep.jsx           # Step 5: Team size
    ├── PrimaryIntentStep.jsx      # Step 6: Goals
    ├── ToolkitStep.jsx            # Step 7: Tools
    └── LoadingStep.jsx            # Step 8: Loading

Integration

Routes Added

  • /onboarding - The onboarding flow

HomePage Updated

  • "Start Building" buttons now check if user has completed onboarding
  • First-time users → /onboarding
  • Returning users → /builder

App.jsx Updated

  • Added OnboardingFlow route
  • Maintains existing HomePage and BuilderPage routes

Testing the Onboarding

1. Start Fresh (First-Time User Experience)

# Open browser console and run:
localStorage.removeItem('dorian_onboarding_complete');
localStorage.removeItem('dorian_onboarding_data');

# Then navigate to:
http://localhost:3000/onboarding

Or simply click "Start Building" on the homepage without having completed onboarding.

2. Test Progress Persistence

  1. Start onboarding
  2. Complete a few steps (e.g., email + name)
  3. Refresh the page
  4. ✓ Should resume from where you left off

3. Test Navigation

  • ✓ Click "Back" button
  • ✓ Press Escape to go back
  • ✓ Press Enter to continue (on valid inputs)
  • ✓ Click cards/pills to select and auto-advance

4. Test Validation

  • ✓ Enter invalid email → See error message + shake animation
  • ✓ Enter valid email → See green checkmark
  • ✓ Try to continue without required field → Button disabled

5. Test Completion

  • ✓ Complete all 7 steps
  • ✓ Watch loading screen progress
  • ✓ Get redirected to /builder
  • ✓ Try clicking "Start Building" again → Should go directly to builder

Utility Functions

import {
  isOnboardingComplete,
  getOnboardingData,
  resetOnboarding
} from './components/onboarding';

// Check completion status
if (!isOnboardingComplete()) {
  navigate('/onboarding');
}

// Get saved data
const data = getOnboardingData();
console.log(data);
/*
{
  email: "user@example.com",
  firstName: "Jane",
  lastName: "Doe",
  organizationName: "Acme Inc.",
  businessCategory: "b2b",
  teamSize: "small",
  primaryGoals: ["email", "automation"],
  tools: ["Gmail", "Slack", "Notion"],
  completedAt: 1234567890
}
*/

// Reset for testing
resetOnboarding();

Copy Principles (Anthropic-Style)

✅ Use

  • Understanding, experience, context, workflow
  • Intelligent, personalize, thoughtful
  • Sophisticated but approachable tone

❌ Avoid

  • Emojis (keep it clean)
  • Exclamation marks (except sparingly)
  • "Awesome!", "Great!", "Perfect!" (too generic)
  • Overly casual language

Examples

  • ❌ "Great choice!" → ✅ "This will help us serve you better"
  • ❌ "You're almost done!" → ✅ "Just a few more questions"
  • ❌ "Let's go!" → ✅ "Continue"

Responsive Design

  • Mobile: Stacked cards, increased touch targets
  • Tablet: 2-column grids where appropriate
  • Desktop: Centered content, max-width 640px
  • Typography: Fluid scaling with clamp()

Dark Mode Support

  • ✓ Full dark mode support
  • ✓ Theme-aware colors and shadows
  • ✓ Smooth transitions between themes
  • ✓ Maintains readability in both modes

Performance

  • Lazy loading: Only loads current step
  • Optimistic updates: Immediate UI feedback
  • Local storage: No server calls during onboarding
  • Animations: Respect prefers-reduced-motion

Next Steps

Immediate

  1. Test the flow:

    cd dorian/dorian-ui
npm run dev
# Navigate to http://localhost:3000/onboarding

  2. Verify all steps work:

    • Email validation
    • Navigation (back/forward)
    • Auto-advance on selection
    • Data persistence
    • Completion redirect

Optional Enhancements

  • Add analytics tracking for each step
  • Template recommendations based on selections
  • Integration setup flows
  • Team invitation after onboarding
  • Save to backend (vs localStorage)
  • A/B test different copy variations

Troubleshooting

Onboarding Not Showing?

// Check completion status
console.log(localStorage.getItem('dorian_onboarding_complete'));

// Reset if needed
localStorage.removeItem('dorian_onboarding_complete');

Data Not Persisting?

// Check saved data
console.log(localStorage.getItem('dorian_onboarding_data'));

Styling Issues?

  • Verify global.css is loaded
  • Check theme is initialized (App.jsx useEffect)
  • Inspect element for conflicting styles

Summary

✨ What You Get:

  • 8-screen sophisticated onboarding flow
  • Anthropic-style copy and design
  • Smooth animations and transitions
  • Full state persistence
  • Keyboard shortcuts
  • Accessibility support
  • Dark mode support
  • Mobile responsive
  • Zero additional dependencies needed

🎯 User Experience:

  • Feels intelligent and thoughtful
  • One question at a time (progressive disclosure)
  • Respects user's time and intelligence
  • Beautiful, purposeful animations
  • Premium, warm, human feel

🚀 Ready to Use:

  • All routes configured
  • HomePage integration complete
  • State management working
  • Full documentation included
  • Comprehensive testing guide

Status: ✅ Complete and ready for testing

Navigate to /onboarding to experience the flow!