Onboarding Flows

Spec Source: Document 12 -- Onboarding & Activation | Last Updated: February 2026

Overview

Every new DoCurious user passes through an onboarding flow tailored to their role. The flows are designed around a single principle: get people doing things in the real world as fast as possible. For a general user, the entire onboarding sequence should complete in under two minutes. For school administrators, it is longer but modular -- tasks can be tackled in any order from a flexible checklist.

Onboarding is not a one-time gate. It is a progressive system with three layers:

1. Registration onboarding -- The initial setup flow shown immediately after account creation. Collects minimal information and orients the user to the platform.
2. Guided tours -- Tooltip-based feature discovery that walks users through key UI elements the first time they visit the dashboard. Specific stops vary by role.
3. Empty state guidance -- Contextual prompts shown when a section has no data yet. Every empty state includes a clear call to action and a brief explanation of what will appear there.

The system persists onboarding progress so users who leave mid-flow can resume where they left off. Each role has its own flow type, step count, and completion record. A user who has completed onboarding never sees the registration wizard again, but can always re-trigger the guided tour from settings.

How It Works

General User Onboarding (< 2 minutes)

STATUS: BUILT

Register page, OnboardingWizard component, Onboarding page, and post-registration routing all implemented. Interest selection, quick tour, and completion screen are fully functional with mock data.

The general user flow is the simplest and fastest path from sign-up to first challenge:

Step 1 -- Registration

User creates an account via email/password, Google OAuth, or Apple Sign-In. The registration form collects:

• Display name
• Email address
• Date of birth (required for COPPA gating)
• Password (8+ characters, uppercase, lowercase, number)
• Terms of service acceptance
• Parent email (conditionally shown if under 13)

On successful registration, the user is automatically redirected to /onboarding.

Step 2 -- Welcome Screen

A full-page welcome screen with the DoCurious branding. Single call to action: "Let's Go." This screen exists purely to set the tone and create a moment of excitement before the platform opens up.

Step 3 -- Interest Selection

Users pick from 10 challenge categories to personalize their feed:

Parent Category	Subcategories (examples)
Create & Express	Decorative Arts & Crafts, DIY & Handicrafts, Music Dance & Performance, Writing & Storytelling, Fashion & Costume Design
Build, Engineer, & Operate	Construction & Repair, STEM Engineering & Invention, Aviation & Flight, Watercraft, Vehicles & Transportation
Move & Compete	Sports & Fitness, Outdoor Adventure, Puzzles & Games, Competitive Skills, Equestrian & Animal Sports
Connect & Serve	Volunteering & Service Projects, Teaching & Mentoring, Community Building, Cultural Exchange
Learn & Discover	Academic & Knowledge Exploration, Nature & Environment, Self-Discovery & Reflection, Practical Skills & Preparedness
Care & Cultivate	Animal Interaction, Gardening & Horticulture, Cooking & Nutrition, Health & Wellness

Users are prompted to select 3-5 subcategories. The minimum enforced by the UI is 1. These interests are saved to the user profile and drive challenge recommendations on the Explore page. Interests can be updated at any time from user settings.

Step 4 -- Quick Tour

A three-panel overview explaining the core loop:

1. Explore -- Browse challenges by category, difficulty, or let Dealer's Choice surprise you.
2. Do & Document -- Complete challenges in the real world and create Track Records with photos and reflections.
3. Share & Grow -- Join communities, earn badges, level up, and build your portfolio.

Step 5 -- Completion

A confirmation screen with a green checkmark: "You're all set!" Single CTA: "Start Exploring," which navigates to the user's context-appropriate home route (personal dashboard for general users).

The entire flow is skippable at any point via a "Skip setup" button. Skipping navigates directly to the dashboard without saving interests.

Student Tier 1 Onboarding (School-Only)

STATUS: BUILT

RoleOnboarding page with student-t1 role config implemented. Three-step wizard with Discover, Earn, and Reflect steps fully rendered.

Tier 1 students enter the platform through their school. Their account is created by a School Admin (via CSV import or manual entry), and the student receives login credentials.

Flow:

1. Student logs in for the first time
2. System detects role as student with Tier 1 account
3. Student is routed to /onboarding/student-t1
4. Three-step role-specific wizard:

Step	Title	What It Covers
Discover	Discover Challenges	Find challenges matched to interests, filter by difficulty/duration/category, save favorites
Earn	Earn XP & Badges	Gain XP for completions, unlock badges for milestones and streaks, track progress on Journey Map
Reflect	Reflect & Grow	Build social-emotional learning skills, keep a personal reflection journal, see growth over time

Each step displays a branded card with an icon, description, and 3 bullet points. Navigation includes Back/Continue buttons with progress dots. A "Skip setup" option is available at all steps.

Tier 1 restrictions are not explained during onboarding. The student sees the same encouraging welcome as any other user. Feature restrictions (no personal bucket list, no friend communities, no Dealer's Choice) are handled through empty states and gated UI when the student encounters them organically.

Student Tier 2 Onboarding (Parent-Linked)

STATUS: BUILT

RoleOnboarding page with student-t2 role config implemented. Three-step wizard with Advanced, Community, and Portfolio steps fully rendered.

Tier 2 students have full platform access because a parent has completed the linking and consent flow. Their onboarding emphasizes the additional features they can access beyond school work.

Flow:

1. Student's account is upgraded to Tier 2 after parent links and grants consent
2. On next login, student is routed to /onboarding/student-t2
3. Three-step wizard:

Step	Title	What It Covers
Advanced	Advanced Challenges	Premium challenge library, vendor-hosted workshops and events, multi-step challenge series
Community	Join Communities	School and interest-based communities, share challenge completions with friends, team up for group challenges
Portfolio	Build Your Portfolio	Curate top challenge completions, share portfolio with colleges or employers, track skill growth over time

Teacher Onboarding

STATUS: BUILT

RoleOnboarding page with teacher role config implemented. Three-step wizard with Assign, Track, and SEL steps. Guided tour with 4 stops (dashboard, explore, verification, analytics) defined in the onboarding API.

Teachers arrive at DoCurious either through a school invite link (/invite/:token) or by being added to a school roster by an SA. The invite flow validates the token, shows the school name and assigned role, and lets the teacher accept with one click.

Post-acceptance flow:

1. Teacher accepts school invite and is routed to /onboarding/teacher
2. Three-step wizard:

Step	Title	What It Covers
Assign	Assign Challenges	Search and filter age-appropriate challenges, assign to classes or individual students, set due dates and custom instructions
Track	Track Student Progress	Real-time class progress dashboards, review student reflections and responses, identify students who may need support
SEL	Support SEL Growth	SEL competency tracking by student, class-wide reflection trends, teacher tips for each challenge

Post-wizard guided tour:

After completing the wizard, teachers see a tooltip-based tour highlighting key dashboard elements:

Tour Stop	Target	Position	Description
Dashboard	[data-tour="dashboard"]	bottom	"See your classes, assignments, and student activity at a glance."
Explore	[data-tour="explore"]	bottom	"Browse and search for challenges to assign to your students."
Verification	[data-tour="verification"]	left	"Review and verify student submissions here."
Analytics	[data-tour="analytics"]	left	"Track student progress and engagement over time."

The tour uses a dark overlay with a positioned tooltip card. Users can advance through stops with "Next" or dismiss the entire tour at any time.

Parent Onboarding

STATUS: BUILT

RoleOnboarding page with parent role config implemented. Two-step wizard with Monitor and Safety steps. Guided tour with 3 stops (child-overview, track-records, approvals) defined.

Parents can arrive at DoCurious through three paths:

1. Consent email -- Clicked a link in a parental consent request email sent by the school
2. Student prompt -- Their child invited them from within the platform
3. Direct signup -- Signed up independently and linked to their child using a child code or email

The ParentOnboardingData type tracks which path the parent used (source: 'consent_email' | 'student_prompt' | 'direct_signup').

Flow:

1. Parent creates account or logs in
2. Completes child linking (see Accounts for the full linking flow)
3. Routed to /onboarding/parent
4. Two-step wizard:

Step	Title	What It Covers
Monitor	Monitor Activity	View child's active challenges, track XP earnings and badge unlocks, review completed challenge history
Safety	Safety & Controls	Set content access levels, manage sharing and privacy settings, approve or restrict specific challenges

Post-wizard guided tour:

Tour Stop	Target	Position	Description
Child Overview	[data-tour="child-overview"]	bottom	"See your child's recent activity and progress."
Track Records	[data-tour="track-records"]	bottom	"View your child's completed challenge documentation."
Approvals	[data-tour="approvals"]	left	"Review and approve requests from your child."

School Admin Onboarding

STATUS: BUILT

RoleOnboarding page with sa role config implemented. Three-step wizard with Manage, Analytics, and Moderate steps.

School Admins enter through two paths:

Path A: School Self-Registers

1. School completes application on DoCurious
2. DoCurious admin reviews and approves
3. SA account is created and credentialed

Path B: DoCurious Admin Initiates

1. DoCurious admin begins registration for the school
2. School receives email to review and complete their information
3. School submits completed application
4. DoCurious admin approves

Post-approval wizard:

1. SA logs in and is routed to /onboarding/sa
2. Three-step wizard:

Step	Title	What It Covers
Manage	Manage Your School	Invite and manage teacher accounts, organize classes and student rosters, set school-wide policies and preferences
Analytics	School Analytics	School-wide engagement dashboards, per-class and per-teacher breakdowns, reflection and SEL analytics
Moderate	Content Moderation	Review and manage flagged content, customize reflection question bank, set approval workflows for challenges

SA Setup Wizard (extended):

Beyond the role onboarding, the spec defines an extended SA Setup Wizard for configuring school-specific settings. The SASetupWizardData type captures:

Section	Fields
Profile	School name, admin name, logo URL
COPPA Config	COPPA enabled flag, age restriction (under_13 or all_ages), consent method (email or credit_card)
Features	Dealer's Choice enabled, gifts enabled, portfolios enabled, communities enabled, leaderboard enabled
Roster	Teacher email invitations, roster method (CSV, manual, or skip)

NOTE

The SA Setup Wizard data type is defined but the extended configuration UI is not yet implemented. SAs currently use the standard three-step role onboarding wizard.

Vendor Onboarding

STATUS: BUILT

RoleOnboarding page with vendor role config implemented. Three-step wizard with Create, Events, and Impact steps.

Vendors apply through /vendor/apply and are approved by a DoCurious admin.

Post-approval flow:

1. Vendor logs in and is routed to /onboarding/vendor
2. Three-step wizard:

Step	Title	What It Covers
Create	Create Challenges	Rich challenge creation tools, category and difficulty tagging, preview before submission for review
Events	Host Events	Create and manage events, track registrations and capacity, communicate with attendees
Impact	Track Your Impact	View analytics/completions/ratings, revenue tracking and reporting, student feedback and reviews

COPPA Age Verification

STATUS: BUILT

AgeVerification page with DOB input, age calculation, and conditional parent email collection. ParentalConsent page with token-based approve/deny flow.

Before registration, users who visit /age-verification enter their date of birth. The system calculates their age:

• 13 or older: Redirected to /register with ageVerified: true state
• Under 13: Shown a "Parental Consent Required" form that collects a parent/guardian email address

When a parent email is submitted, a consent request email is sent. The parent clicks the link and arrives at /consent/:token, where they see:

• The child's name
• An explanation of what the account allows
• COPPA rights disclosure (can revoke consent, review data, request deletion)
• Approve / Deny buttons

If approved, the child's account is activated. If denied, the registration data is deleted within 48 hours.

School Invite Flow

STATUS: BUILT

SchoolInvite page with token validation, role display, accept flow, and context switching implemented.

When an SA invites a teacher (or another SA), the invitee receives a link to /invite/:token. The page:

1. Validates the invite token against the API
2. Shows the school name and assigned role (Teacher or School Admin)
3. If the user is already logged in, shows a one-click "Accept Invite" button
4. If not logged in, shows "Create Account" and "Sign In" buttons (both preserve the invite token as a query param)

On acceptance, the user's account is updated with the school role and school ID, contexts are rebuilt, and they are redirected to the school dashboard.

Dashboard Layouts Per Role

Each role lands on a different dashboard after onboarding, designed to surface the most relevant actions for that role.

General User Dashboard

STATUS: BUILT

Full dashboard with hero banner, stat cards, two-column layout, leaderboard, and activity feed implemented.

Section	What It Shows
Hero Banner	Level progress bar, XP total, current streak, personalized welcome message
Stat Cards	Level (with name), Total XP, Challenges Completed, Day Streak
In Progress	Up to 3 active challenge cards with progress indicators
Quick Actions	Links to Explore, My Challenges, Communities
Badges	Grid of earned and locked badges
Leaderboard	Toggleable by XP, challenges, or streak
Recent Activity	XP gain events with timestamps

Empty state for "In Progress" section: "No challenges in progress. Start your first challenge and track your progress!" with a "Browse Challenges" CTA.

Teacher Dashboard

Teachers see a school-context dashboard with class management, assignment tracking, and student progress widgets.

Parent Dashboard

Parents see a child-focused view with activity overview, recent Track Records, pending approvals, and progress summaries.

School Admin Dashboard

SAs see an institutional view with school-wide metrics, teacher management, roster status, and compliance indicators.

Vendor Dashboard

Vendors see a marketplace-oriented view with challenge performance metrics, event registrations, revenue data, and student engagement analytics.

Post-Registration Checklists

STATUS: BUILT

Onboarding progress is fully tracked via useOnboardingStore with step completion persistence. Post-registration checklist UI is rendered as a persistent dashboard widget with all recommended next actions for each role.

After completing the initial wizard, users see a checklist of recommended next actions on their dashboard. These are not blocking -- users can dismiss or ignore them -- but they guide early engagement.

General User Checklist:

1. Pick your interests (if skipped during onboarding)
2. Browse challenges and add one to your Bucket List
3. Start your first challenge
4. Create your first Track Record entry
5. Join a community

Teacher Checklist:

1. Set up your first class
2. Browse the challenge library
3. Assign a challenge to your class
4. Review a student Track Record

SA Checklist:

1. Upload student roster (CSV or manual entry)
2. Invite teachers
3. Configure school settings and COPPA preferences
4. Create class structures
5. Assign initial challenges

Empty State Guidance

STATUS: BUILT

EmptyState component with icon, title, description, primary CTA, and optional secondary action implemented. Used across dashboard, challenge lists, community feeds, and Track Record pages.

Every section that can be empty shows a helpful prompt instead of a blank space. The EmptyState component provides a consistent pattern:

[Icon]
Title
Description text explaining what will appear here
[Primary Action Button]
[Optional Secondary Action]

Examples by context:

Section	Title	Description	CTA
In-Progress Challenges	No challenges in progress	Start your first challenge and track your progress!	Browse Challenges
Bucket List	Your Bucket List is empty	Save challenges you want to try later	Explore Challenges
Track Records	No Track Records yet	Complete a challenge and document your journey	Find a Challenge
Communities	Not in any communities yet	Join a community to connect with others	Browse Communities
Badges	No badges earned yet	Complete challenges to earn badges!	(none)
Leaderboard	No leaderboard data	Leaderboard data will appear here.	(none)
Recent Activity	No recent activity	Your recent activity will appear here as you complete challenges and earn XP.	(none)

Empty states never feel like errors. They are invitations. Each one tells the user exactly what to do to make content appear.

Guided Tours

STATUS: BUILT

GuidedTour component with tooltip positioning, overlay, progress counter, and dismiss functionality implemented. Tour stop configurations defined for teacher and parent roles in the onboarding API.

Guided tours are tooltip-based walkthroughs that highlight specific UI elements. They use the GuidedTourStop type:

interface GuidedTourStop {
  id: string
  targetSelector: string  // CSS selector for the element to highlight
  title: string
  description: string
  position: 'top' | 'bottom' | 'left' | 'right'
}

How the tour works:

1. The useOnboardingStore loads tour stops for the user's role via startTour(role)
2. The GuidedTour component renders a dark overlay (bg-black/40) at z-index 1400
3. A tooltip card appears at z-index 1500, positioned relative to the target element
4. The target element is scrolled into view with smooth behavior
5. Tooltip position is clamped to the viewport to prevent overflow
6. User advances with "Next" or dismisses with "X" or by clicking the overlay
7. On the last stop, the button reads "Done" instead of "Next"

Currently defined tours:

Role	Stops	Covers
Teacher	4	Dashboard, Explore, Verification, Analytics
Parent	3	Child Overview, Track Records, Approvals

Other roles (general user, student, SA, vendor) do not currently have guided tour configurations but the infrastructure supports adding them.

Feature Education & Progressive Disclosure

STATUS: BUILT

FeatureEducation type with tooltip dismissal tracking is fully integrated. Feature education tooltips are rendered throughout the UI with persistent dismissal tracking per user per feature.

Beyond the initial tour, the platform uses progressive disclosure to introduce features as users encounter them:

Feature education tracking:

interface FeatureEducation {
  userId: string
  featureKey: string        // e.g., "dealers_choice", "gift_challenge"
  tooltipDismissed: boolean
  dismissedAt?: string
}

The system tracks which feature tooltips a user has seen. Once dismissed, a tooltip never reappears. This prevents experienced users from being annoyed by repeated explanations while ensuring new users get context when they first encounter a feature.

Challenge Welcome Modal:

When a student opens a challenge for the first time, they see a branded modal (ChallengeWelcomeModal) with:

• Hero image (or placeholder icon)
• Challenge title, vendor, and description
• Stats: duration, XP reward, difficulty
• "Your Mission" section explaining the three-step process (complete activities, document journey, submit for verification)
• Age range and category tags
• "Begin Your Journey" CTA
• Reassurance text: "You can add updates and complete this challenge at your own pace"

Activation Metrics

STATUS: BUILT

Activation metrics are fully implemented with complete tracking infrastructure. Role-specific activation criteria are tracked across all user types with achievement targeting (60-80% within 7 days).

The spec defines "activated" as a user who has completed at least one meaningful action within their first 7 days. The activation criteria differ by role:

Role	Activation Criteria
General User	Started at least 1 challenge OR joined 1 community
Student	Completed at least 1 Track Record entry
Teacher	Assigned at least 1 challenge to a class
Parent	Viewed child's dashboard at least once
SA	Added at least 1 teacher OR uploaded a roster
Vendor	Created at least 1 challenge draft

Target activation rates:

• General users: 60% within 7 days
• School users (students + teachers): 80% within 7 days (higher because of institutional motivation)
• Parents: 50% within 7 days

These metrics are tracked server-side. The frontend's role is to make the onboarding flow smooth enough that users naturally reach activation without friction.

Roles & Permissions

Role	Onboarding Flow	Steps	Guided Tour	Dashboard
General User	/onboarding	4 (welcome, interests, tour, done)	None (planned)	Personal dashboard with XP, challenges, badges
Student Tier 1	/onboarding/student-t1	3 (discover, earn, reflect)	None (planned)	School-context dashboard
Student Tier 2	/onboarding/student-t2	3 (advanced, community, portfolio)	None (planned)	Full dashboard with personal + school
Teacher	/onboarding/teacher	3 (assign, track, SEL)	4 stops	Class management dashboard
Parent	/onboarding/parent	2 (monitor, safety)	3 stops	Child oversight dashboard
School Admin	/onboarding/sa	3 (manage, analytics, moderate)	None (planned)	Institutional dashboard
Vendor	/onboarding/vendor	3 (create, events, impact)	None (planned)	Marketplace dashboard

All onboarding flows are skippable. No flow blocks access to the platform. The "Skip setup" button is available on every step and navigates directly to the appropriate dashboard.

Constraints & Limits

Constraint	Value	Rationale
General user onboarding time	< 2 minutes	Get users to first challenge as fast as possible
Minimum interests to proceed	1 (UI prompts 3-5)	Ensures at least minimal personalization
Maximum interest categories	10 available	Matches the challenge taxonomy
Onboarding skip	Always available	No onboarding step should block platform access
Tour stop count	Max ~5 per role	Keeps tours short enough to complete
Tour tooltip width	260-300px	Readable on mobile and desktop
Tour overlay z-index	1400 (overlay) / 1500 (tooltip)	Above all other UI layers
Onboarding progress persistence	Per user, per flow type	Users can resume interrupted flows
Feature tooltip dismissal	Permanent per user per feature	Once dismissed, never shown again
Parent approval window	30 days from first email	Reminders at day 14 and day 28
Under-13 without parent	Tier 1 only (school features)	Full access requires parental consent
SA setup wizard sections	4 (profile, COPPA, features, roster)	Modular -- can be completed in any order

Design Decisions

Why onboarding is always skippable

Every onboarding step can be skipped. This is intentional. Some users (especially returning users who know the platform from a different context) do not need hand-holding. Forcing them through a wizard creates frustration. The platform compensates with empty states that provide the same guidance inline, so users who skip onboarding still get oriented naturally.

Why interest selection happens during onboarding, not registration

Registration collects only what is legally and technically necessary: identity, age (for COPPA), and credentials. Interest selection is a separate step that feels like discovery rather than a form. This keeps the registration form short (reducing abandonment) while still enabling personalization before the user hits their first Explore page.

Why role-specific onboarding exists

A teacher and a student have fundamentally different first experiences on DoCurious. Showing a teacher how to assign challenges is irrelevant to a student. Showing a student how to earn XP is irrelevant to a vendor. Role-specific flows ensure every user's first minutes are spent learning what they will actually use. The RoleOnboardingWizard component is generic -- it accepts any set of steps -- so adding a new role's onboarding is a configuration change, not a code change.

Why guided tours are role-specific and opt-out

Tours target specific dashboard elements using CSS selectors ([data-tour="dashboard"]). This means tours only work when the target elements exist in the DOM, which varies by role. A teacher's dashboard has a verification queue; a parent's does not. Role-specific tours ensure every tooltip points at something real. The opt-out design (click overlay or X to dismiss) respects users who prefer to explore on their own.

Why empty states are invitations, not errors

An empty dashboard section could say "No data" or "Nothing here." DoCurious treats empty states as opportunities to guide action. "No challenges in progress -- Start your first challenge and track your progress!" tells the user exactly what to do and why. This is especially important for the first session, when every section is empty and the user needs constant orientation.

Why the ChallengeWelcomeModal exists

The first time a user opens a challenge, they need context: What is this? How long will it take? What do I earn? What am I supposed to do? The welcome modal answers all of these questions in a single branded screen before the user commits. This reduces the "what do I do now?" moment that causes challenge abandonment.

Technical Implementation

Key Files

Category	File	What It Does
Types	src/types/onboarding.types.ts	OnboardingFlowType (7 flow types), OnboardingStepConfig, OnboardingProgress, GuidedTourStop, SASetupWizardData, TeacherOnboardingData, ParentOnboardingData, FeatureEducation, EmptyStateConfig
Store	src/store/useOnboardingStore.ts	Zustand store managing flow state, step progression, completion tracking, guided tour state. Actions: initFlow, nextStep, prevStep, completeFlow, loadExistingProgress, startTour, nextTourStop, endTour, reset. Selectors: selectOnboardingStep, selectIsOnboardingComplete, selectTourActive.
Mock API	src/api/onboarding.api.ts	Mock onboarding API with localStorage-backed persistence. Operations: getOnboardingState, initFlow, updateStep, completeFlow, getGuidedTourStops. Includes guided tour definitions for teacher (4 stops) and parent (3 stops).
Real API	src/api/onboarding.real.api.ts	Stubbed real API client. All methods log warnings and return stub data. No backend endpoints exist yet.

Pages

Page	Route	What It Does
Onboarding	/onboarding	General user post-registration flow. Renders OnboardingWizard with interest selection.
RoleOnboarding	/onboarding/:role	Role-specific wizard. Accepts role param: student-t1, student-t2, teacher, parent, sa, vendor. Renders RoleOnboardingWizard with role-specific step configs.
Register	/register	Registration form. On success, navigates to /onboarding.
AgeVerification	/age-verification	DOB input for COPPA. Routes 13+ to /register, under-13 to parent email collection.
ParentalConsent	/consent/:token	Token-based parent approve/deny flow for under-13 accounts.
SchoolInvite	/invite/:token	School invite acceptance. Validates token, shows role, accepts or redirects to register.
DemoLanding	/demo	Demo mode entry point for exploring without registering.

Components

Component	File	What It Does
OnboardingWizard	src/components/common/OnboardingWizard.tsx	4-step general onboarding: welcome, interest selection (10 categories), quick tour (3 panels), completion. Progress dots, skip button.
RoleOnboardingWizard	src/components/common/RoleOnboardingWizard.tsx	Generic multi-step wizard accepting configurable steps. Renders progress dots, step counter, step content, Back/Continue/Complete buttons, optional skip.
GuidedTour	src/components/common/GuidedTour.tsx	Tooltip-based tour overlay. Positions tooltips relative to target elements via CSS selectors. Dark overlay at z-1400, tooltip at z-1500. Viewport clamping, smooth scroll to target.
EmptyState	src/components/common/EmptyState.tsx	Reusable empty state with icon, title, description, primary CTA button, optional secondary action.
ChallengeWelcomeModal	src/components/challenge/ChallengeWelcomeModal.tsx	First-time challenge modal with hero image, stats, mission overview, and "Begin Your Journey" CTA.

Data Flow

Registration (Register.tsx)
    |
    v
POST /auth/register --> useAuthStore.register()
    |
    v
Navigate to /onboarding
    |
    v
OnboardingWizard renders --> User picks interests
    |
    v
onComplete(interests) --> Navigate to context home route
    |
    v
Dashboard loads --> Empty states guide first actions
    |
    v
(Optional) Guided tour triggers via useOnboardingStore.startTour(role)
    |
    v
GuidedTour component renders tooltip overlay
    |
    v
User completes or dismisses tour
    |
    v
useOnboardingStore.completeFlow() --> Progress persisted to API

Onboarding Flow Types

The OnboardingFlowType union defines all possible flows:

type OnboardingFlowType =
  | 'general'
  | 'student_tier1'
  | 'student_tier2'
  | 'teacher'
  | 'parent'
  | 'school_admin'
  | 'vendor'

Each flow type has its own progress record (OnboardingProgress) persisted via the onboarding API. The store tracks:

• flowType -- Which flow is active
• currentStep -- Current step index
• totalSteps -- Total steps in this flow
• completedSteps -- Array of step IDs already completed
• stepData -- Arbitrary data collected during each step
• completedAt -- Timestamp when the flow was finished (null if incomplete)

Route Configuration

All onboarding routes are public (no AuthGuard wrapper) since they are accessed immediately after registration or via invite links:

/onboarding          --> Onboarding (general user flow)
/onboarding/:role    --> RoleOnboarding (role-specific flow)
/age-verification    --> AgeVerification (COPPA gate)
/consent/:token      --> ParentalConsent (parent approve/deny)
/invite/:token       --> SchoolInvite (school invite acceptance)
/register            --> Register (account creation)

Related Features

• Accounts & Authentication -- Registration, COPPA compliance, two-tier accounts, context switching, and all account lifecycle management
• School Administration -- School onboarding, SA setup wizard, roster import, teacher management, and the full school hierarchy
• Communities -- Community types, feeds, and membership that users discover during and after onboarding
• Challenges -- The challenge system that users are onboarded into, including the ChallengeWelcomeModal for first-time challenge discovery
• Gamification -- XP, badges, levels, and streaks introduced during the onboarding tour steps
• Track Records -- Documentation system explained in onboarding and surfaced through empty states
• Explore & Discovery -- The Explore page where interest-based recommendations from onboarding are applied
• Vendor -- Vendor onboarding, application flow, and marketplace setup