UX Patterns Guide
UI + UX Task And Workflow Patterns established

Onboarding

Provide a short, optional where possible, context-aware onboarding path that explains value, collects only necessary setup, teaches through real actions, preserves progress, and leaves users in the product with a useful next step or configured starting point.

Open in lab Compare alternatives
Decision first

Choose this pattern when the problem matches

Use when

  • New users need orientation, setup, personalization, or instruction before the regular interface can deliver value.
  • A novel workflow or redesign requires contextual teaching that cannot be solved through labels and defaults alone.
  • The product can shorten time to first value through a guided first action, sample object, import, or checklist.

Avoid when

  • The product is already understandable through the normal interface.
  • The flow only advertises features users cannot act on yet.
  • Users are likely entering with an urgent task that onboarding would block.
  • The primary work is account creation, sign in, payment, profile setup, or permissions rather than orientation.
  • The team cannot maintain or measure the onboarding against real activation outcomes.

Problem it prevents

New users, returning users after major changes, or users entering a novel workflow may not know how to reach first value, but broad tours, forced setup, and feature promotion can delay the task they came to complete.

Pattern anatomy

What a strong implementation has to make clear

User need

The product, feature, role, account, workspace, or workflow is new enough that users need orientation before the regular interface is effective.

Pattern promise

Provide a short, optional where possible, context-aware onboarding path that explains value, collects only necessary setup, teaches through real actions, preserves progress, and leaves users in the product with a useful next step or configured starting point.

Required state

First-run welcome state with benefit-focused copy and one clear next action.

Recovery path

Users abandon because onboarding delays the first useful action.

Access contract

Keep onboarding screens in normal heading order with clear titles and step labels.

Quality bar

The difference between expert and weak execution

Strong implementation

Specific, visible, recoverable

  • A project-management app asks for role and team size, creates a sample board, highlights the first Add task action, and lets users skip the tour while keeping a setup checklist available.
  • A redesign introduces a moved Reports filter through one contextual spotlight with Show me later and Learn in context controls.
  • A new admin selects Invite teammates as their goal, imports two sample users, sees progress saved, skips notification setup, and arrives on the team page with the invite action focused.
  • A returning user sees a short contextual note about a redesigned navigation area only after opening the affected page, then can dismiss or reopen it from Help.
Weak implementation

Vague, hidden, hard to recover from

  • A first launch shows six promotional slides about every feature, requires Next on each slide, and lands on an empty dashboard.
  • A new feature tour blocks an urgent invoice workflow and cannot be reopened after the user dismisses it.
  • A user is forced to configure integrations, notifications, billing, and profile details before they know whether the product solves their task.
  • A user completes a polished onboarding tour but cannot remember where the shown feature lives because the tour was detached from the actual screen.
UI guidance
  • Render onboarding as a short purposeful path with a visible benefit, current step, skip or later path when safe, persistent resume point, and the next product action users can take immediately after finishing.
  • Keep onboarding surfaces close to the real product context: use welcome panels, contextual spotlights, setup cards, checklists, sample-data previews, or focused steps rather than long abstract slide decks.
UX guidance
  • Use onboarding only when users need orientation, minimal setup, personalization, or instruction before the normal interface can deliver value, and remove steps that merely market features or repeat what the UI already explains.
  • Design the flow around first value: collect only necessary setup data, let users skip optional teaching, preserve progress, support return later, and land users on a configured workspace, sample content, or concrete next action.
Implementation contract

What the implementation must handle

States

  • First-run welcome state with benefit-focused copy and one clear next action.
  • Optional skip, later, or resume state for non-required onboarding.
  • Minimal setup or personalization state that explains why each answer is needed.
  • Contextual teaching state attached to a real feature or empty workspace.

Interaction

  • The flow states its user benefit before asking for setup information.
  • Every step either reduces setup friction, configures the product, demonstrates a real action, or routes users to a next step they can do now.
  • Optional teaching can be skipped, resumed, and reopened without losing required setup progress.
  • Required steps explain why they are required and what remains unavailable until they are complete.

Accessibility

  • Keep onboarding screens in normal heading order with clear titles and step labels.
  • Do not rely on animation, spotlight masks, color, or pointer position alone to teach the interface.
  • Respect reduced motion and avoid moving focus unexpectedly between teaching surfaces.
  • Make skip, later, back, next, finish, and reopen controls keyboard reachable with stable labels.

Review

  • What first meaningful action does this onboarding help users complete?
  • Which steps are required for the product to work, and which are optional teaching?
  • Can users skip or resume without losing setup progress?
  • Does the flow land users in a configured product state rather than a blank surface?
Interactive lab

Inspect the states before you copy the pattern

Reach first value from a first-run flow

Choose a role goal, skip optional teaching, resume setup, create sample content, finish into the real workspace, and compare forced-tour, marketing-only, no-resume, blank-landing, permission-first, and disconnected-tutorial failures.

Onboarding
Interactive demo is ready

Launch the live UI/UX lab when you want to inspect states, keyboard behavior, and common failure modes.

State To Inspect

First-run welcome state with benefit-focused copy and one clear next action.

Keyboard / Access

Initial focus moves to the onboarding heading or first actionable control according to the surface type.

Avoid Generating

Forcing all users through a feature tour before they can do useful work.
Evidence trail

Source-backed claims behind this guidance

Fluent 2 Design System: Onboarding

Microsoft Fluent - checked

Fluent provides onboarding goals and surface choices for welcome, orient, notify, explain, and take action scenarios.

Material Design: Onboarding

Google Material Design - checked

Material guidance connects onboarding to first-run action after the flow.

NN/g: Mobile-App Onboarding

Nielsen Norman Group - checked

NN/g defines onboarding scope and cautions that many apps should avoid separate onboarding when direct use is learnable.

Full agent/debug reference

Problem Context

  • The product, feature, role, account, workspace, or workflow is new enough that users need orientation before the regular interface is effective.
  • A small amount of setup, personalization, import, permission, or preference data can make the product immediately more useful.
  • The first meaningful action is not obvious from the empty product surface alone.
  • Existing users may need migration or redesign orientation without being blocked from urgent work.
  • The team can measure whether onboarding improves activation, first task completion, setup success, or feature adoption.

Selection Rules

  • Choose onboarding when users need a first-run or new-feature path to understand value, configure essentials, or complete the first meaningful action.
  • Use empty state when the only problem is a no-content area that needs cause and next action.
  • Use wizard when the user is performing a bounded dependent setup with validation, review, and finish.
  • Use progressive disclosure when the user needs optional detail inside an existing task rather than a separate first-run flow.
  • Use carousel only when users browse peer content slides; do not disguise onboarding as a carousel unless each step supports immediate setup or action.
  • Use account creation, sign-in, permission request, payment collection, or profile setup patterns when those tasks are the primary requirement.
  • Skip separate onboarding when the interface can teach itself through labels, defaults, examples, and contextual empty states.
  • Make onboarding skippable or resumable unless a step is required for legal, safety, identity, or technical reasons.
  • Trigger feature onboarding in context when the feature becomes actionable, not at first launch for every user.

Required States

  • First-run welcome state with benefit-focused copy and one clear next action.
  • Optional skip, later, or resume state for non-required onboarding.
  • Minimal setup or personalization state that explains why each answer is needed.
  • Contextual teaching state attached to a real feature or empty workspace.
  • Progress saved state so users can leave and continue later.
  • Completion state that lands on a configured workspace, sample object, checklist, or first task.
  • Reopen or help state for users who skipped, forgot, or need the guidance later.
  • Returning-user new-feature state that avoids interrupting unrelated urgent work.

Interaction Contract

  • The flow states its user benefit before asking for setup information.
  • Every step either reduces setup friction, configures the product, demonstrates a real action, or routes users to a next step they can do now.
  • Optional teaching can be skipped, resumed, and reopened without losing required setup progress.
  • Required steps explain why they are required and what remains unavailable until they are complete.
  • Onboarding progress is stored separately from permanent product data until the user commits or finishes the relevant setup.
  • The completion transition lands users in the real interface with any created sample content, selected goal, checklist, or action focus intact.
  • New-feature onboarding appears in or near the affected feature and does not block unrelated workflows.

Implementation Checklist

  • Define the activation outcome, first meaningful action, required setup fields, optional teaching, and success metric before designing screens.
  • Remove promotional slides that do not help the user act inside the product.
  • Use existing profile, organization, device, or account data instead of asking users to repeat it.
  • Provide skip, later, and resume controls where policy and functionality allow.
  • Show progress only when it reflects real setup or teaching steps users can understand.
  • Keep copy short, benefit-focused, and tied to the next real product action.
  • Persist partial setup and make the return path visible in the app shell, help menu, or checklist.
  • Test first-run, returning-user, skipped, resumed, mobile, slow network, screen reader, reduced motion, and translated-label states.
  • Measure whether onboarding improves first task completion rather than only counting views or completions.

Common Generated-UI Mistakes

  • Forcing all users through a feature tour before they can do useful work.
  • Using onboarding to compensate for unclear navigation, labels, or empty states.
  • Asking for role, team, payment, permissions, and notifications before showing value.
  • Ending onboarding on a blank workspace with no action, example, or checklist.
  • Making skipped onboarding impossible to reopen later.
  • Using a carousel of marketing slides as if it were product setup.
  • Interrupting existing users with redesign notes while they are trying to finish unrelated work.

Critique Questions

  • What first meaningful action does this onboarding help users complete?
  • Which steps are required for the product to work, and which are optional teaching?
  • Can users skip or resume without losing setup progress?
  • Does the flow land users in a configured product state rather than a blank surface?
  • Would empty state, wizard, progressive disclosure, contextual help, or account setup be more accurate?
  • How will we know the onboarding improved activation or task success?
Accessibility
  • Keep onboarding screens in normal heading order with clear titles and step labels.
  • Do not rely on animation, spotlight masks, color, or pointer position alone to teach the interface.
  • Respect reduced motion and avoid moving focus unexpectedly between teaching surfaces.
  • Make skip, later, back, next, finish, and reopen controls keyboard reachable with stable labels.
  • Provide text alternatives for any visual product mockups or sample-data previews.
  • Preserve focus and announce progress or completion changes without trapping users in non-required teaching.
  • Ensure contextual spotlights identify the target feature and return focus to the triggering or next useful control.
Keyboard Behavior
  • Initial focus moves to the onboarding heading or first actionable control according to the surface type.
  • Tab order includes skip or later before optional teaching becomes a trap.
  • Back and Next preserve entered setup answers unless the user explicitly clears them.
  • Escape or Close follows the same skip, later, or confirmation policy as pointer dismissal.
  • After completion, focus lands on the first meaningful product action, created object, checklist, or relevant heading.
  • Reopened onboarding returns focus to the surface that launched it when closed.
Variants
  • First-run welcome
  • Setup onboarding
  • Role-based onboarding
  • Goal-based onboarding
  • Checklist onboarding
  • Contextual spotlight
  • New feature onboarding
  • Sample data onboarding
  • Import-assisted onboarding
  • Reopenable tutorial

Verification

Last verified: