recovery-app-onboarding

Recovery App Onboarding Excellence

Build compassionate, effective onboarding experiences for recovery and wellness applications that serve vulnerable populations with dignity and practical utility.

When to Use

✅ USE this skill for:

First-time user onboarding flows Feature discovery and app tours Progressive disclosure design Permission request timing and framing Welcome screens and value propositions Recovery program selection flows Crisis resource integration Privacy and anonymity communication

❌ DO NOT use for:

General mobile responsive design → use mobile-ux-optimizer Marketing/conversion optimization → use seo-visibility-expert Native iOS/Android development → use platform-specific skills Database schema design → use supabase-admin Core Principles 1. Compassion First, Features Second

Recovery users are often in vulnerable states. Every onboarding decision must consider:

❌ ANTI-PATTERN: "Sign up to track your progress!" ✅ CORRECT: "You're taking a brave step. Let's set up a private space for your journey."

❌ ANTI-PATTERN: Requiring account creation before showing any value ✅ CORRECT: Let users explore core features anonymously, then offer accounts for persistence

1. Value Before Commitment

Show meaningful value before asking for personal information:

WRONG ORDER: 1. Create account 2. Enter personal details 3. Grant permissions 4. Finally see the app

RIGHT ORDER: 1. Show immediate value (meeting finder, crisis resources) 2. Demonstrate app benefits 3. Offer optional account for saved data 4. Request permissions contextually

1. Non-Judgmental Language

Avoid shame-inducing or triggering language:

❌ "How many days since your last relapse?" ✅ "What's your current sobriety date?"

❌ "You failed to complete..." ✅ "No worries—pick up where you left off"

❌ "Are you an alcoholic or drug addict?" ✅ "Which recovery programs interest you?"

Mobile Onboarding UX (2025 Best Practices) Progressive Disclosure

Break complex onboarding into digestible stages:

// ✅ GOOD: Staged onboarding with clear progress const ONBOARDING_STAGES = [ { id: 'welcome', required: false }, // Emotional connection { id: 'programs', required: false }, // Personalization { id: 'features', required: false }, // Value discovery { id: 'preferences', required: false }, // Customization { id: 'safety', required: false }, // Crisis setup ];

// Each stage should be: // - Skippable (never trap users) // - Under 60 seconds to complete // - Visually distinct with progress indicators // - Reversible (can go back)

Permission Priming (28% Higher Grant Rate)

Never request permissions out of context:

// ❌ BAD: Immediate system permission dialog useEffect(() => { requestLocationPermission(); }, []);

// ✅ GOOD: Contextual priming before system dialog function MeetingSearchPrimer() { return (

"Everboarding" - Beyond First Launch

Onboarding isn't a one-time event:

// Feature discovery on first use of each feature function useFeatureOnboarding(featureId: string) { const [hasSeenTooltip, setHasSeen] = useLocalStorage(onboard:${featureId}, false);

return { showTooltip: !hasSeenTooltip, dismissTooltip: () => setHasSeen(true), }; }

// Example: First time using gratitude journal function GratitudeJournal() { const { showTooltip, dismissTooltip } = useFeatureOnboarding('gratitude');

return ( <> {showTooltip && ( )} {/ Journal UI /} </> ); }

Skeleton Loaders, Never Spinners

Recovery users in crisis need immediate feedback:

" isLoading="isLoading">// ❌ BAD: Spinner creates anxiety

// ✅ GOOD: Skeleton shows structure immediately

// Skeleton implementation function MeetingCardSkeleton() { return (

  <EmergencyContactInput
    label="Emergency Contact"
    placeholder="Someone who can help in a crisis"
  />

  <SupportPersonInput
    label="Support Person"
    placeholder="Sponsor, therapist, or trusted friend"
  />

  <div className="flex gap-2 mt-6">
    <button className="btn-secondary flex-1" onClick={handleSkip}>
      Set Up Later
    </button>
    <button className="btn-primary flex-1" onClick={handleSave}>
      Save Contacts
    </button>
  </div>
</div>

  <main className="flex-1 p-4">
    <CurrentStepComponent {...currentStep} state={state} setState={setState} />
  </main>

  <footer className="p-4 border-t border-leather-700">
    <div className="flex gap-3">
      {state.currentStep > 0 && (
        <button onClick={goBack} className="btn-secondary flex-1">
          Back
        </button>
      )}
      {currentStep.skippable && (
        <button onClick={skip} className="btn-text">
          Skip
        </button>
      )}
      <button onClick={goNext} className="btn-primary flex-1">
        {state.currentStep === STEPS.length - 1 ? 'Get Started' : 'Continue'}
      </button>
    </div>
  </footer>
</div>