Onboarding Flows

Onboarding Flows

Overview

Onboarding's only job is time to first value — get the user to the "aha" moment with the least friction. Two workhorse patterns: a stepper wizard for required setup, and a checklist for optional-but-guided tasks. Always allow skip/resume; never trap users behind a wall of forms.

When to use

• First-run setup after signup (workspace, profile, invite team).
• A guided checklist on an otherwise empty dashboard.
• Any multi-step task that benefits from chunking.

Stepper wizard

Keep step state explicit and show progress so users know how much is left:

const steps = ["Workspace", "Invite team", "Connect data"] as const;
const [step, setStep] = React.useState(0);
const progress = ((step + 1) / steps.length) * 100;

  
    
      Step {step + 1} of {steps.length}
      {steps[step]}
    
    
  

  {step === 0 &&  setStep(1)} />}
  {step === 1 &&  setStep(2)} onBack={() => setStep(0)} />}
  {step === 2 &&  setStep(1)} />}

  
     setStep((s) => Math.max(0, s - 1))} disabled={step === 0}>Back
    Skip for now
  

Persist progress server-side (or in the URL) so a refresh or return visit resumes where they left off.

Setup checklist (progressive)

Great on an empty dashboard — shows value and a clear path, dismissible once done:

  Get started
    {done}/{total} complete
    
  
  
    {tasks.map((t) => (
      
        
        {t.label}
        {!t.done && }
      
    ))}
  

Principles

• Progressive disclosure. Ask for the minimum now; defer the rest to settings.
• Show progress. A Progress bar or "Step x of n" reduces drop-off.
• Always skippable. Forced onboarding inflates churn; let users explore.
• Prefill smart defaults. Don't ask what you can infer (timezone, name from email).
• Celebrate completion. A success state + a clear next action.

Pitfalls

• Too many required steps before any value — cut to the essentials.
• No skip/resume — refresh loses progress and frustrates.
• Progress not persisted — returning users restart from zero.
• A 12-field form labeled "Quick setup."
• Dead end at the end — always point to the next meaningful action.

Hand-off

First-run guidance built from forms-and-validation steps and empty-and-loading-states; completion lands users in dashboard-layout.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: param087
• Source: param087/saas-ui-skills
• License: MIT

Install and usage instructions live in the source repository linked above.