Product Onboarding: How to Design the Path to First Value

Most product onboarding advice starts with a list of patterns: add a welcome modal, a five-step checklist, a tooltip tour, an empty state with a call to action, a Day-1 email. That list is not wrong so much as it is unfocused. It describes ceremony, things a team can ship, without first answering the question that decides whether any of them help:

What must actually happen before this user, team or account can reach meaningful value, and which parts of that path does the product need to explain at all?

This guide treats onboarding as a value path. You will map the route from entry to first value, decide what genuinely belongs before it, separate required setup from optional education, choose patterns that fit your product and the user's state, handle the cases teams usually forget, returning users, failed integrations, multi-user accounts, marketplaces, and measure whether any of it improved real value progression rather than tutorial completion.

Two boundaries matter from the start. What counts as first value is the activation-definition job, owned by the activation metric guide; this page assumes you can state it and focuses on how the experience gets an eligible user or account there. And locating where people drop out is the funnel-tracking job, owned by early user funnel tracking; this page uses that evidence rather than replacing it.

Table of contents

• Why onboarding is a value path, not a tour
• What product onboarding actually is
• Onboarding is not activation, and not education
• The Value-Path Map
• Required setup versus optional education
• The Friction Budget
• Pattern fit: choose the pattern for the constraint
• The Pattern Fit Matrix
• Product tours, tooltips, and contextual help
• Progressive disclosure without hiding the controls
• Empty states
• Templates and sample data
• Checklists
• Personalization and branching
• Onboarding a whole account, not just a user
• Assisted and hybrid onboarding
• Two-sided and marketplace onboarding
• Returning unactivated users
• Failure and recovery states
• Skip, dismiss, and resume
• The Onboarding State Map
• The Onboarding Drop-off Diagnostic
• Diagnose before changing the UI
• Onboarding metrics that track value, not completion
• Time to value is contextual
• Onboarding conversion is not business conversion
• Triggered email and push for recovery
• The Onboarding Decision Record
• Worked case 1: a B2B collaboration workspace
• Worked case 2: a simple single-player product
• Worked case 3: an integration-heavy analytics product
• Worked case 4: a two-sided marketplace
• Common onboarding failure modes
• Which owner to use next
• Decision clinic: the questions teams actually bring
• Frequently asked questions
• References and further reading

Why onboarding is a value path, not a tour

A product tour is one possible tool. A path is the thing that has to exist whether or not you use one.

Consider two products with identical feature sets. Product A asks the user to choose a pricing plan, invite three teammates, connect a CRM and configure notification rules before anything renders. Product B opens on a real, working view with sensible defaults, lets the user accomplish one useful thing, and only then surfaces the integrations that unlock more. Same features. Different paths. In A, onboarding is a sequence of gates; in B, onboarding is a short, purposeful ramp toward value.

The durable model this guide uses is deliberately small:

Entry / intent
   ↓
Required setup
   ↓
First meaningful action
   ↓
First value   ← the activation contract (owned elsewhere)
   ↓
Next self-directed action

Everything a product team argues about in onboarding, tours, checklists, tooltips, sample data, empty states, emails, is a decision about that diagram: add something, remove something, defer something, or explain something. When the diagram is wrong, adding patterns makes it worse, because you are decorating a path that does not lead where the user wants to go.

The working definition:

Onboarding is complete when the user or account can continue toward value without unnecessary guidance, not when every tooltip has been seen.

That definition is intentionally undramatic. It rules out "onboarding is the first five minutes," "onboarding is the checklist," and "onboarding is finished when the tour ends." It also creates a genuinely useful test for any proposed onboarding element: does this help an eligible user reach or continue past first value, or does it just demonstrate that the product has features?

What product onboarding actually is

It helps to separate three things people collapse into one word.

Getting familiar with the interface. This is the narrow sense: dedicated flows and UI elements that help a person understand a screen they have not seen before. Nielsen Norman Group defines onboarding as "the process of getting users familiar with a new interface, using dedicated flows and UI elements that are not part of the regular app interface," and notes it covers both learning the interface and completing necessary setup, and that it is not limited to first-time users. Existing users get onboarded again whenever a redesign or a genuinely new feature arrives.

Completing necessary setup. Some products cannot deliver anything until a prerequisite exists: a workspace name, a connected data source, a granted permission, an accepted invitation, a verified domain. This is not education. It is a gate in front of value, and it deserves different design treatment.

Reaching first value. The moment the product does the job the user came for. This is where onboarding hands off, and where the activation definition takes over.

A useful shorthand: interface familiarity and necessary setup are the path; first value is the destination; everything after first value belongs to retention and ongoing education.

Onboarding is not activation, and not education

Three confusions cause most of the expensive onboarding mistakes.

Onboarding is not activation

Activation is early realized value, a defined event or state that stands in for "the product worked for this user." Onboarding is the experience that gets an eligible user or account to it. They are related but owned separately, and the order matters: defining activation is a measurement decision, while designing onboarding is a product decision.

The practical consequence: "onboarding completed" is not an activation metric. A 95% tour-completion rate and a 12% activation rate is a coherent, common and bad situation. The tour is being watched; the value is not arriving. Treating completion as success hides the problem instead of surfacing it.

Onboarding is not education

Ongoing education, help centers, feature deep dives, advanced workflows, certification, serves users who already have context. Entry-to-value guidance serves users who do not yet have any. Mixing them produces the single most common structural flaw in onboarding: a long curriculum that teaches features the user has no reason to retain yet.

Nielsen Norman Group's research on onboarding tutorials is blunt about the mechanism: tutorials interrupt users, are quickly forgotten, and do not reliably improve task performance, because they present information out of context and require memorization before the user has a reason to care. That is not an argument that instruction is always wrong. It is an argument that instruction should arrive at the moment of need, not in a lecture before it.

Onboarding is not retention, email, or PLG

Onboarding influences retention but does not own it: post-activation habits, repeated value, renewal and churn are the retention system's job. Onboarding can use triggered email as a recovery mechanism, but a cadence strategy is a lifecycle-messaging job. And onboarding is one component of a product-led operating model, not a synonym for it.

The Value-Path Map

This is the primary working artifact. Fill it in for one target user or account before you choose a single pattern. It is deliberately not a score; it is a shared picture of the path.

# Onboarding Value-Path Map

Target user / account:

Primary job / intent:

Entry point(s):

Activation / first-value definition:
[Owned elsewhere, link the definition; do not redefine it here]

Required prerequisites:
- [...]

Steps before first value:
1. [...]
2. [...]

For each pre-value step:
- Why is it necessary?
- Can the product infer or default it?
- Can it be delayed until after first value?
- What happens if it is skipped?
- What failure or recovery state exists?

First meaningful value:

Expected next self-directed action:

Optional education deferred until later:
- [...]

Segments that need a different path:
- [...]

Assisted-onboarding trigger (if any):

Measurement owner:

Three rules make the map useful instead of decorative:

1. The first-value definition is a link, not a box you reinvent. If you cannot state it, stop and finish that upstream decision first.
2. Every pre-value step needs a reason to exist. "It is part of setup" is not a reason. "The product cannot compute anything without it" is.
3. The next self-directed action is part of the map. Onboarding that ends at first value without a plausible next step produces a cargo-cult success moment followed by a drop.

Required setup versus optional education

This distinction does more work than any pattern choice, so treat it as a first-class step.

Required setup is anything without which the product cannot deliver the promised value to this user or account:

• Connect the data source the product analyzes.
• Create the workspace or project the work lives in.
• Grant a permission the core action needs.
• Accept an invitation, or invite the collaborator the value depends on.
• Complete an identity, payment or security step the business model or law requires.

Optional education is helpful but not required before value:

• An advanced-feature tour.
• Keyboard shortcuts.
• Visual theming and customization.
• Secondary workflows and integrations.
• Power-user settings.

The default rule:

Defer optional education until context exists. Do not turn onboarding into a curriculum.

Nielsen Norman Group's guidance on onboarding components reaches the same place from a different direction: feature-promotion onboarding at first launch tends to be read as marketing and skipped, and visual-design customization "doesn't belong in onboarding" because users cannot yet know their preferences. Content customization, asking something the product genuinely needs to function, is the exception, not the rule.

A quick way to classify an item honestly: ask what breaks if you remove it. If the answer is "nothing about the value, but the user might miss a feature," it is optional education. If the answer is "the product cannot do the job," it is required setup. If the answer is "legal or security says so," it is a constraint, not a choice, and it should be labeled as such so nobody tries to make it "skippable."

The Friction Budget

Onboarding fails more often from accumulated unnecessary friction than from missing guidance. Before adding a pattern, decide what each pre-value step costs and whether it can move. This is a qualitative budget, not a arithmetic score.

Ask these questions for every pre-value step:

The allowed outputs are qualitative:

• Keep before value, genuinely blocking, and the value case is clear.
• Simplify, necessary but heavier than it needs to be.
• Infer or default, the product can choose safely.
• Defer, move it after first value.
• Remove, it was never required.
• Make optional, useful but not gating.
• Require assisted setup, a human should own it (see the assisted-onboarding section).

There is no "friction score," and there should not be one. A banking app that must verify identity before it can show an account is not "high friction"; it is correctly ordered. A project tool that asks for company size before rendering anything is high friction for no stated reason.

Pattern fit: choose the pattern for the constraint

Onboarding patterns are not a stack you install. Each solves a specific problem, fits a specific state, and fails in a specific way. Below, each retained pattern is described by what user problem it solves, when it fits, when it fails, what not to use it for, and how to measure it.

Welcome screen

• User problem: the user has no idea where they are or what the first action is.
• Fits when: the product is genuinely new or unfamiliar, or the entry point needs routing (by use case or role).
• Fails when: it delays the first action, restates the marketing, or appears again on later sessions.
• Not for: teaching features. Its job is framing and a single next step.
• Measure: progress from the screen into the first meaningful action, not welcome-screen views.

Empty-state guidance

• User problem: the screen is blank and the user cannot tell what belongs there or what to do.
• Fits when: a container is empty by design and its first population is a real task.
• Fails when: it becomes a marketing paragraph, offers many competing actions, or shows fake data that looks real.
• Not for: replacing a default that should exist.
• Measure: action taken from the empty state, then downstream value, not clicks on the empty-state CTA alone.

Templates

• User problem: the blank-slate cost is high and the user does not know what "good" looks like.
• Fits when: work is repetitive and a credible starting structure meaningfully reduces effort.
• Fails when: templates are generic, mismatched to the stated job, or hide how the real thing is built.
• Not for: teaching advanced configuration.
• Measure: time to first meaningful action and value reached, with template use as a segment rather than a goal.

Sample or demo data

• User problem: the user cannot see what the product will do with data before they have any.
• Fits when: value is invisible until there is data, and safe exploration is useful.
• Fails when: sample actions leak into decision-critical activation metrics; sample content looks real without labeling; or the product pretends demo success is real success.
• Not for: replacing real-data activation. Demo value is learning, not activation.
• Measure: movement from demo mode into real data, and real activation separately.

Checklist

• User problem: several meaningful setup tasks exist, order is partly flexible, and the user may leave and return.
• Fits when: each item delivers real value, progress persistence helps, and the list is short because the tasks are essential, not because five is a nice number.
• Fails when: it becomes busywork, items exist to fill the list, or completion is treated as value.
• Not for: trivial products, or as a substitute for a defined first value.
• Measure: progression toward first value per item, not checklist completion.

Progressive disclosure

• User problem: the full interface is overwhelming before the user has a task.
• Fits when: advanced capability exists but is not needed for first value.
• Fails when: necessary controls are hidden unpredictably or the path to reveal them is not discoverable.
• Not for: hiding things because the interface is poorly organized.
• Measure: task completion and discoverability of later features, not the mere fact that fewer things are visible.

Contextual tooltip or hotspot

• User problem: one specific control is genuinely ambiguous, or a relevant capability is easy to miss.
• Fits when: it fires at the moment of need, is dismissible, and can be recalled.
• Fails when: it patches bad labels, covers the interface, or points at standard elements everyone already understands.
• Not for: explaining the whole product.
• Measure: whether the confusion it was meant to fix actually drops, not tooltip click-through in isolation.

Setup wizard or guided task

• User problem: a required, multi-step setup genuinely needs sequencing.
• Fits when: steps are distinct and mostly independent; a wizard makes the order and progress clear.
• Fails when: steps are interdependent (forcing back-and-forth), or the wizard front-loads education.
• Not for: optional customization.
• Measure: completion of the required steps and arrival at first value.

Role or use-case selection

• User problem: the product serves materially different jobs, and the path to value differs.
• Fits when: the answer changes the next screen, defaults, or content in a real way.
• Fails when: it is a persona survey that changes nothing, or it adds friction before the user understands the choices.
• Not for: marketing segmentation.
• Measure: differentiated progression per branch, not survey completion.

Permission or integration setup

• User problem: value depends on access the product does not have yet.
• Fits when: it is genuinely required, and the request explains the payoff.
• Fails when: permission is requested before any context, or a failure has no recovery path.
• Not for: collecting data "just in case."
• Measure: successful setup rate, failure/retry rate and time-to-first-value, not prompt impressions.

Invite or collaboration prompt

• User problem: the value is collaborative and cannot exist with one person.
• Fits when: the invited person is a genuine prerequisite for value, not a growth lever.
• Fails when: it is forced purely to grow seats, before the inviter has seen value.
• Not for: viral growth theater.
• Measure: whether account-level value actually needs the second person, and what happens when the invite is delayed.

Triggered email or push

• User problem: the user left mid-setup, a prerequisite completed elsewhere, or the next value moment is time-delayed.
• Fits when: it is tied to a real state change and solves a timing problem.
• Fails when: it is a generic Day-1/3/7 sequence, repeats completed steps, or substitutes for product value.
• Not for: a general lifecycle cadence, that belongs to its owner.
• Measure: re-entry and next-step completion after the message, with suppression for already-converted states.

Concierge or assisted onboarding

• User problem: setup requires judgment, coordination or trust that a self-serve flow cannot provide yet.
• Fits when: migration, security review, integration, or configuration genuinely needs a human.
• Fails when: humans are used to mask broken product basics that should be automated.
• Not for: every user just because it feels safer.
• Measure: time to value and repeatability, with the goal of automating the repeatable parts.

The Pattern Fit Matrix

Pattern fit depends on the product and the state, not on fashion. Use these dimensions first; they describe the constraint you are actually designing against.

Then map likely fit. This is a starting hypothesis, not a rulebook, validate with the user's actual behavior.

Product tours, tooltips, and contextual help

The most common onboarding mistake is ordering: tour first, task later. It feels efficient, teach everything once, and it tends to fail for a predictable reason.

Nielsen Norman Group separates push revelations (help shown because it is convenient for the system) from pull revelations (help triggered by a signal that the user needs it now), and its research finds that push-style tutorials interrupt users, are quickly forgotten, and do not reliably improve task performance. Users skip them, and the "paradox of the active user" explains why: people want to start doing the thing, not study the thing.

The practical principle:

Explain controls in the context of the user's task, at the moment they need them, not in a lecture before the task exists.

That does not ban tours. It bounds them. NN/g's own research found walkthrough-style tutorials useful for a genuinely novel interaction paradigm (their example was AR), precisely because nothing in the user's existing mental model helped. A tour is defensible when the interface is new, unfamiliar, and hard to discover by doing. It is usually indefensible as the default first screen for a product whose job is already familiar.

When you do use instruction, three rules keep it honest:

1. Prefer the task over the explanation. An interactive walkthrough in which the user performs a small real action beats a carousel of screens. "Learning by doing" is not a slogan; it is what makes the information stick.
2. Make help dismissible and recallable. If a user dismisses it, they must be able to find it again when it becomes relevant.
3. Do not use onboarding to compensate for bad design. If a tooltip is explaining where a button is, the better fix may be where the button is. If a tour is explaining why a screen is confusing, the screen is the problem. Route broad usability problems to the UX fundamentals chapter instead of papering over them.

A useful diagnostic for tooltip sprawl: count how many tooltips explain standard elements. If most of them do, you have a labeling problem, not an onboarding problem.

Progressive disclosure without hiding the controls

Progressive disclosure defers advanced or rarely used options to a secondary surface so the primary surface stays focused. It is one of the few UX techniques old enough to have survived several design eras intact: Jakob Nielsen's original treatment is from 2006 and still reads as current.

Two things must be right, per NN/g:

1. The split between initial and secondary features. Everything frequently needed belongs up front; the primary surface must not be cluttered. The initial display tells the user what is important simply by being visible.
2. The path from primary to secondary must be obvious. Label the control so the user knows what they will find, and make the mechanics simple.

Two caveats matter for onboarding specifically. First, NN/g notes that designs going beyond two disclosure levels typically have low usability, so "hide it three levels deep" is usually a design smell, not progressive disclosure. Second, progressive disclosure (hierarchical: core features now, secondary on request) is different from staged disclosure (a linear wizard: first-in-task-step now, later steps next). Staged disclosure suits tasks that split cleanly into independent steps; it struggles when steps are interdependent and users must move back and forth.

For accessibility and discoverability: never make a necessary control available only on hover, only via color, or only through a tour. Progressive disclosure should reduce initial complexity while preserving a discoverable path, "hidden but findable," not "hidden and hoping."

Empty states

An empty state is a goldmine most teams leave empty. NN/g's guidance is specific about what a good one does:

• Communicate system status, the user must know whether the space is empty, still loading, or broken. A misleading "No records" that later fills with content teaches users to distrust the product.
• Provide a learning cue, tell the user what belongs here and how it gets populated.
• Provide one direct pathway to the key task, ideally a real button, with a "learn more" escape hatch if needed.

For onboarding, the design rules follow directly:

• Explain what the space is for and what will appear here.
• Give one meaningful next action, not a menu.
• Optionally offer example or template content, clearly labeled.
• Do not paste a marketing paragraph into it.
• Do not stack five calls to action.
• Do not show fabricated data that looks real.

The Loggly empty-state pattern NN/g cites is a good model: two honest pathways, add a real source, or explore with demo data. The user chooses, and the system is clear about which is which.

Templates and sample data

Templates and sample data exist to reduce the cost of a blank slate. They are worth it when the user genuinely does not know what "good" looks like, and they are dangerous when they contaminate measurement or blur the line between practice and real work.

Ask five questions before adding them:

1. Does the sample resemble the user's real job, or is it a generic demo that teaches the wrong shape?
2. Can it be safely deleted without leaving residue or confusing state?
3. Does it confuse analytics by creating events that look like real work?
4. Could it create false activation, a value event triggered by sample content rather than the user's own data?
5. Does the user clearly understand what is sample and what is real?

The measurement rule follows: demo and sample actions should be excluded from decision-critical activation metrics unless you have decided, on purpose, that demo value counts. If it does count, say so explicitly in the activation contract; if it does not, instrument the distinction. A dashboard that "activates" because it was seeded with demo data will make an onboarding change look successful when nothing real happened.

Templates differ from sample data in intent. A template is a starting structure the user fills with real content; sample data is illustrative content that is meant to be replaced. Both can help. Neither is a substitute for first value.

Checklists

Checklists work when there are several meaningful setup tasks, partially flexible order, a real chance the user leaves and returns, and a benefit to persistent progress. Then a checklist provides structure and a reason to come back.

They fail when:

• The product is trivial and one action delivers value.
• Items are busywork or exist to fill the list.
• Completion is treated as value.
• The list is long because "onboarding should have steps."

Do not recommend arbitrary 3-, 5- or 7-step counts. The number is whatever number of items are genuinely required to reach first value. If that is one, the checklist is one item and probably should not be a checklist. If it is eight and all eight are truly blocking, eight is right, and the more urgent question is whether the product should require eight things before any value.

A useful warning sign: when the checklist completion rate rises but activation does not, the checklist is describing activity rather than driving value. That is worth investigating, not celebrating.

Personalization and branching

Personalization only earns its friction when the answer materially changes the path. If two answers lead to the same next screen, you have added a question and learned nothing the user cares about.

Two rules make branching defensible:

1. Do not ask what you can safely infer. If the product can detect the user's data source, integration or account type, do not make the user declare it.
2. Ask the minimum that changes the experience, and let the user correct it. A branch the user cannot revise becomes a trap the first time the product guesses wrong.

Reasonable branch dimensions:

• Use case, genuinely different jobs with different first actions.
• Role, different setup responsibilities (admin vs. contributor).
• Account type, individual vs. team, or existing vs. new workflow.
• Data source, determines the real first action.
• Solo vs. team, determines whether collaboration is a prerequisite.

Unreasonable defaults:

• A mandatory company-size or persona survey at signup that changes nothing.
• A five-question welcome survey before any value.
• Asking about experience level the product could infer from behavior.

Nielsen Norman Group's mobile-onboarding research puts the bar plainly: keep prompts brief, explain why the data is needed and how it will be used, and if you cannot explain why the data is beneficial at launch, gather it later. Content customization that the product truly needs can belong at the start; cosmetic or marketing segmentation usually should not.

Onboarding a whole account, not just a user

This is where single-player onboarding assumptions do the most damage in B2B. A person can complete every step and the account can still be nowhere near value, because value depends on someone else.

Separate the actors:

• Buyer, chose the product, may rarely log in.
• Admin, configures identity, permissions, integrations, billing.
• Champion, drove adoption internally; needs to see and communicate account status.
• Contributor, uses the product day to day; their value may depend on others.
• Viewer, consumes output; largely unaffected by setup.
• Security / IT, gates access, compliance and rollout.

Then ask the account-level questions:

• Who must act before value exists? Often the admin grants access, or a teammate accepts an invite.
• Which actor owns each prerequisite? Attribute each blocking step to a role.
• What happens while waiting? The champion should be able to see what is pending and who owns it, instead of assuming the product is broken.
• Can work proceed partially? If one contributor is blocked, can another make progress?
• How does the champion know account status? An admin setup surface and clear waiting states answer this.

A WorkOS guide to real-world B2B onboarding makes the structural point well: the first onboarding experience often belongs not to an end user but to an admin configuring authentication, security and provisioning, and the second journey is bringing users in, via invitations, just-in-time provisioning and domain policies. It describes onboarding as "a system, not a checklist." That framing is the right one: model the account, not a single session.

The corollary for activation is important and belongs to the activation contract: if account-level value requires a second person, the activation unit is probably the account, not the individual user, and the onboarding design has to expose the waiting state honestly.

Assisted and hybrid onboarding

Not everything should be self-serve on day one, and pretending otherwise is its own failure mode. Some products legitimately need migration, integration, security review, implementation support or configuration that a wizard cannot credibly handle yet.

The design principle:

Automate repeatable friction; preserve human assistance where judgment or coordination genuinely matters.

That means the product should own the parts that are mechanical, data mapping, status tracking, provisioning, a clear setup checklist with owners, while humans own the parts that require decisions: interpreting a customer's data model, coordinating a security review, planning a rollout. It also means the product should keep improving the parts it hands to humans, so the same manual step does not survive forever.

Do not use humans to mask broken product basics. If every customer needs a call to connect a standard integration, the integration is the problem. If every customer needs a call because their data model differs, that is a genuine reason for assistance, and a signal to build configuration depth.

Measure assisted onboarding by time to value, repeatability, and how much of the manual work has been automated over time. Human help is not automatically a product failure; a permanently manual step that could be automated usually is.

Two-sided and marketplace onboarding

Two-sided products often import a one-sided onboarding funnel by mistake. Buyer and seller may have different prerequisites, different value moments, supply/demand dependencies and waiting states.

For a seller, the path to value is not "completed profile." It is closer to: a credible listing exists, verification passes, and the seller receives qualified demand. Completion of a profile is a prerequisite, not value. For a buyer, value may require supply to exist first.

So the value path branches:

• Seller value path: apply → verify → create a credible listing → receive first qualified engagement.
• Buyer value path: search → find relevant supply → transact successfully.

Design consequences:

• Do not force both sides through the same onboarding sequence.
• Model the waiting state honestly, especially at low supply or low demand.
• Do not count profile completion as activation for either side.
• Keep qualification and trust steps where they materially affect marketplace integrity, a verification step that prevents bad supply is not gratuitous friction, even though it slows one side down.

Returning unactivated users

Onboarding is not always one session. A large share of users leave mid-setup and come back later, often after a prerequisite completes elsewhere.

Design for the return state explicitly:

• Preserve progress. Completed prerequisites stay completed.
• Resume from state, not from the beginning. Never replay a tour the user finished.
• Surface the single next step. The user's next action should be obvious within seconds of returning.
• Distinguish waiting from blocked. "We are waiting for your teammate to accept" is different from "your import failed."
• Do not treat a returning user as new. A welcome modal for someone who already started is a targeting bug, not a warm gesture.

The most common returning-state failure is a product that restarts onboarding for a user who abandoned at step four, making them redo the first three. That is a design choice, and a bad one.

Failure and recovery states

Most onboarding designs only draw the happy path. Real prerequisites fail. For each critical prerequisite, design all five responses:

1. Detect the failure specifically, an integration error is not "something went wrong."
2. Explain it in the user's terms, with the likely cause.
3. Recover, retry, re-authenticate, correct the input, or escalate.
4. Preserve progress so recovery does not restart the path.
5. Provide a human path when self-recovery is not possible.

Common failure cases to design for:

• Integration or data-source connection fails.
• Permission is denied or revoked.
• An invitation is not accepted.
• An import is malformed or partially invalid.
• Email verification is delayed or lands in spam.
• An external service or async process is unavailable.

A failure that looks like a drop-off in the funnel data is often a reliability bug, not a UX problem. This is why diagnosis comes before redesign, and why a broken import needs an engineering fix rather than a rewritten empty-state message.

Skip, dismiss, and resume

"Make onboarding skippable" is good advice half the time and dangerous the rest. The right question is what kind of thing is being skipped.

• Educational suggestions should be optional, dismissible and resumable. If a user already knows the product, stop showing them the tour.
• Product requirements for value cannot be skipped, because skipping them means the user does not get the value. You can defer them, but you cannot pretend they are optional.
• Legal, security or compliance requirements are not skippable at all. Label them clearly so nobody wastes time trying to make them "friendlier" by removing them.

So the rule is not "onboarding should be skippable." It is: make the skippable things genuinely optional, and be honest about the things that are not. A dismissible tour that quietly reappears every session is worse than no tour. A required setup step hidden behind "Skip for now" that silently blocks value is worse than a clearly labeled gate.

The Onboarding State Map

Onboarding is a set of states, not a linear funnel. Design the states that apply to your product; do not force every product to use every state.

Two design rules make the map pay off. First, state beats session count: gate guidance on "has the user completed task X?" rather than "is this the third session?" Second, do not show a first-login experience to a returning user; that is one of the clearest signals that targeting has broken down.

The Onboarding Drop-off Diagnostic

When a step underperforms, the temptation is to assume "friction" and redesign the screen. Usually the cause is one of several, and only some are UX problems. Work the diagnostic honestly.

Outputs are decisions, not scores:

• Remove the step.
• Defer it after first value.
• Simplify it.
• Fix a bug (this is reliability, not copy).
• Clarify the value link.
• Default what the product can choose.
• Branch by intent or role.
• Assist with a human.
• Research more before changing anything.
• Leave unchanged, sometimes the drop-off is correct behavior.

Diagnose before changing the UI

A drop-off is not a diagnosis. It is a symptom with several plausible causes, and reaching for a redesign before separating them is how teams ship cosmetic changes that do not move the metric.

Plausible causes of the same drop-off:

• Low intent, the user was never a fit; acquisition promised the wrong thing.
• Wrong acquisition promise, the landing page and the product tell different stories.
• Missing prerequisite, the user cannot proceed because something does not exist yet.
• Technical error, the step is genuinely broken for some users.
• Unclear value, the user cannot see why the step matters.
• Confusing interaction, they want to proceed but cannot work out how.
• Too much setup, the path before value is longer than the job justifies.
• Waiting on another actor, the user has done their part; someone else has not.
• Instrumentation bug, the drop-off is partly or wholly an artifact of tracking.

Use the early-user funnel to localize where and for whom; use the measurement contract to rule out instrumentation; use session replay, usability research and support tickets to explain why; and only then design an intervention and test it. A funnel tells you where; it does not tell you why, and it cannot choose the pattern.

Onboarding metrics that track value, not completion

Measure the path, not the ceremony. Useful signals:

• Eligible users or accounts entering onboarding, the honest denominator.
• Prerequisite completion, setup steps that genuinely gate value.
• Step-to-step progression and drop-off, owned jointly with the funnel guide.
• Time between meaningful steps, reveals waiting and stalls, not just totals.
• Time to first value, contextual, not a universal target (see below).
• Activation rate, using the activation contract's definition, unit and window.
• Assisted-support rate, how often humans have to rescue setup.
• Failure and retry rate, a reliability signal hiding inside onboarding.
• Post-activation retained value, whether the people you activated stayed valuable.

Metrics to treat as diagnostic only, never as goals:

• Tour completion.
• Tooltip views or click-through.
• Checklist completion.

These can tell you whether an element is being seen. They cannot tell you whether value arrived. The moment they become targets, the team optimizes toward them: more tooltips, more steps, more checkboxes, and activation does not move.

Always state the denominator. "Onboarding conversion" without a denominator and a defined outcome is not a metric; it is a slogan.

Time to value is contextual

There is no universal time-to-value target. "Under 5 minutes," "within the first session," and "within a day" are all correct for some products and nonsense for others.

Time to value depends on:

• The complexity of the job.
• Required setup and its dependencies.
• External actors, a teammate, a customer, a provider.
• The product category and its natural cadence.
• The user's own expertise.
• Multi-user coordination.

The honest alternative, borrowed from vendor methodology rather than treated as law: describe the latency type and then optimize the delay that is genuinely unnecessary.

• Immediate, value in the first use (a calculator, a simple utility).
• Basic value, the first real interaction with core capability (a first project, a connected source).
• Short, value within days (a configured integration, a published result).
• Long, value requires weeks due to real complexity (migration, security review, rollout).
• Exceeded, value grows beyond the initial expectation.

Track the median and the spread rather than the average, because time-to-value distributions have long tails: a fast median can hide a painful 90th percentile where a whole segment is stuck. Amplitude's guidance on time-to-value makes both points, define the value event before measuring, and report percentiles, not just averages. Neither point requires a universal stopwatch target.

The question to ask is not "how fast should onboarding be?" It is "what delay in this path is unnecessary, and for whom?" A security review that takes two weeks may be unavoidable; a workspace-name field that blocks the first screen usually is not.

Onboarding conversion is not business conversion

"Onboarding conversion" hides at least four different questions. Name the outcome and the denominator every time:

• Signup → setup, did the user complete the prerequisites?
• Setup → first value, did they reach activation?
• First value → repeat value, did it become habit?
• Trial → paid, did the access model convert?

The last one is partly a monetization question, owned alongside the product-led operating model and the access-model decision, not a pure onboarding metric. A change that improves signup→setup and does nothing for setup→value is not an onboarding win. A change that improves onboarding completion but not activation is a completion win. Say which one you mean.

Triggered email and push for recovery

Triggered messages earn their place when they solve a real state or timing problem, not when they fill a calendar. They fit when:

• The user left mid-setup and needs a nudge to the next step.
• An external actor completed a prerequisite and the user should know.
• An asynchronous process finished.
• The next value moment is naturally delayed and would otherwise be missed.

They fail when:

• They are a generic Day-1/3/7 sequence sent to everyone.
• They repeat steps the user already completed.
• They fire after the user already activated.
• They are used as a substitute for product value rather than a recovery mechanism.

The design rule is state awareness and suppression: send the message that matches the user's actual state, and suppress it the moment the state changes. If your onboarding email says "finish setting up your workspace" to someone who finished yesterday, the fix is a state check, not better copy. Detailed cadence and channel strategy belong to the lifecycle-messaging owner; onboarding uses triggered communication only as part of recovery.

The Onboarding Decision Record

One copyable artifact turns all of the above into a decision. Fill it in per weak step or state.

# Onboarding Decision Record

Target user / account:

Primary job / intent:

Activation / first-value owner and definition:
[link]

Current value path:
1. [...]
2. [...]

Weakest step / state:
[...]

Observed evidence:
[...]

Competing explanations:
1. [...]
2. [...]
3. [...]

Necessary friction:
[...]

Potentially removable, deferrable or defaultable friction:
[...]

Pattern / intervention considered:
[...]

Why this pattern fits the constraint:
[...]

Primary progression outcome:
[...]

Guardrails (what must not get worse):
- [...]

Next evidence method:
[...]

Decision:
[Remove / Simplify / Defer / Default / Branch / Add guidance / Assist / Test / Hold]

No confidence percentage, no "friction score." The record exists to make the reasoning reviewable and to prevent the default move of "add a tooltip."

Worked case 1: a B2B collaboration workspace

A project-review workspace where value means a reviewer leaves feedback on a project the user created. It is multi-user, and one of the prerequisites depends on someone else acting.

Value-Path Map (abridged). Target: a small team evaluating the product. Job: get a project reviewed. Entry: signup and workspace creation. First value: the first completed review from another person.

Steps before value, classified honestly:

1. Create a workspace, required, but defaultable (name can be inferred, renamed later).
2. Create or import a project, required; the product cannot review what does not exist.
3. Invite a reviewer, required for account-level value, but it is an external dependency, so it creates a waiting state.
4. Reviewer accepts and completes the review, not the user's step; the user is waiting.

Friction Budget outputs: default the workspace name; require the project; make the invite a first-class, tracked step with its own status; do not require a billing or profile step before any of it.

Pattern fit: an empty-state action for the first project ("Create your first project, here is an example structure"); a clearly labeled invite step; no product tour; a waiting state that shows the champion who has been invited and what is pending; a resume state if they leave mid-setup.

Recovery: invite not accepted → resend, reassign, or allow the champion to complete a review themselves to see value while waiting. Import invalid → specific error and a fix path.

Metrics: project created; reviewer invited; review completed (the account-level activation event, defined upstream); time between create and review; and the waiting-state conversion, what share of accounts stuck at invite ever get a review. The honest framing: one user reaching step three is not account activation.

Worked case 2: a simple single-player product

A small utility, a unit converter, a font-pairing tool, an invoice generator, where value is immediate and obvious.

Value-Path Map. Target: an individual. Job: produce one useful output now. Entry: the tool itself. First value: the first produced output. No prerequisites. No external actors.

The honest answer: the best onboarding may be almost none. The product renders a working state with a strong default; the user acts; value happens. The only guidance that earns its place is a single contextual hint after the user acts, for example, a subtle pointer to "save" or "export" once there is something to save.

Friction Budget: every signup question is optional or absent; every customization is deferred; every educational element is deferred until the user shows a reason to need it.

Why this case matters: it is the guard against onboarding ceremony. If a product can prove the core principle, skip onboarding whenever possible and make the interface more usable instead, then a checklist, a survey and a tour are not "best practices." They are drag.

Metrics: produced output per session; return rate; and whether the contextual hint changed export behavior. There is no meaningful "onboarding completion" metric because there is no meaningful onboarding flow.

Worked case 3: an integration-heavy analytics product

A data tool whose value depends on connecting a real source, with credentials, asynchronous sync and possible failure.

Value-Path Map. Target: an analyst. Job: see a real answer about their own data. Entry: account creation. First value: a query or dashboard built on real connected data. Prerequisites: connect source, grant access, wait for sync.

Steps, classified:

1. Connect the data source, required, not deferrable.
2. Authenticate / grant permission, required; must explain the payoff before requesting.
3. Wait for initial sync, unavoidable, so it needs a waiting state.
4. Run the first query or view a populated dashboard, the value-producing action.

Pattern fit: a transparent setup surface with explicit status; sample/demo mode so the user can learn the interface before real data arrives, clearly labeled and excluded from real activation; a resume state; and failure/retry handling for connection and sync errors.

Critical measurement rule: do not claim demo-data success equals real activation. If activation is defined as "a dashboard built from real data," then demo exploration is a learning aid, not the value event. Instrument the distinction so onboarding changes are not credited for demo engagement.

Recovery: connection fails → specific error, retry, and a documented alternative; sync stalls → status plus notification; permissions denied → explanation of what is needed and why.

Metrics: source connected; sync completed; first real query/dashboard; failure and retry rate; and time from connect to first real value.

Worked case 4: a two-sided marketplace

A services marketplace where a seller's path to value is not a completed profile.

Value-Path Map (seller). Job: sell a service. First value: a qualified buyer engagement, an inquiry, a booking, a transaction. Prerequisites: identity and payment verification, a credible listing, and enough supply/demand coherence on the other side.

Completion is not value. A seller with a 100%-complete profile and no qualified demand has not activated. The profile is a prerequisite. If activation is defined as first qualified engagement, the onboarding design has to optimize the listing's quality and the seller's exposure, not just the profile meter.

Pattern fit: a listing template and examples of strong listings to reduce blank-slate cost; verification steps kept honest about why they exist (marketplace integrity is a legitimate reason); a waiting state for the first qualified engagement; and no shared funnel with buyers, whose path (search → find supply → transact) has different prerequisites.

Metrics: listing published; listing approved; first qualified engagement (activation); time to first engagement; and the share of verified sellers who ever receive qualified demand. At low supply or low demand, the binding constraint may be the marketplace, not onboarding, an important thing to say out loud instead of blaming the flow.

Common onboarding failure modes

A concise diagnostic list. These recur across products and vendor playbooks.

• Tour-first design, a feature tour before the user has a task. Explains before there is a need.
• Checklist theater, completion rises; value does not. The list describes activity, not outcome.
• Questionnaire theater, role or company data collected that does not change the experience.
• First-session dogma, a complex product forced into an arbitrary "first session" or "5 minutes" target.
• Too much education up front, advanced features taught before the user needs them.
• Required and optional mixed, the user cannot tell what actually blocks value.
• One path for all, different jobs and roles forced through the same sequence.
• No resume state, returning users restart from the beginning.
• Happy-path only, integration or permission failure has no recovery.
• Demo data counted as value, sample interaction contaminates activation metrics.
• Onboarding completion used as activation, a completion metric treated as the outcome.
• Nudge spam, emails and pushes substituting for product value.
• Tooltip sprawl, UI ambiguity patched with explanations instead of fixed.
• Growth-hack friction, a forced invite or early paywall added for business reasons without an explicit trade-off.
• Instrumentation blind spot, a drop-off that is partly or wholly a tracking artifact.

Which owner to use next

Onboarding sits inside a system, and the fastest way to make progress is to route the next question to the right owner instead of stretching this page to cover everything.

• First value is unclear or contested → the activation metric guide. Do not define activation inside an onboarding redesign.
• You cannot tell where people drop out → early user funnel tracking.
• The issue is broad usability across the product → the UX fundamentals chapter. Do not use onboarding to compensate for a confusing interface.
• The data needed to diagnose is unstable or untrustworthy → the measurement contract.
• You have a shaping intervention ready to test → the experiment hypothesis generator and the A/B test plan generator, with methodology in low-traffic experiment design.
• You need the broader self-serve value-to-revenue model → the product-led operating model.
• Repeated value after activation is weak → the retention system.
• The access model itself is the question → the free trial vs. freemium decision.
• You need to compare behavioral cohorts → the cohort method.

Decision clinic: the questions teams actually bring

Short, direct answers to the situations that come up most often. None of them has a universal number.

1. A simple tool with immediate value. Onboarding may be minimal or unnecessary. Test the product with no onboarding first; add guidance only where users demonstrably fail.

2. Tour completion is high but activation is low. Tour completion is not value. Inspect the value path, the tour may be consuming the first session that value needed.

3. A long signup questionnaire. Ask whether the answers actually branch the experience. If two answers lead to the same screen, remove or defer the question.

4. An integration is required before value. That is legitimate friction, but it should be transparent, resumable and recoverable, not hidden or pretended optional.

5. Users can get value with sample data before connecting real data. Sample mode can help learning, but it must not be confused with real activation. Instrument the distinction.

6. A multi-user B2B product. Model account and user states separately, and handle the waiting state where value depends on another actor.

7. A returning user who abandoned setup. Resume from their actual state. Do not replay completed steps or the whole onboarding.

8. Checklist completion rises, retention is flat. The checklist may be a proxy or theater. Inspect activation and repeated value, not completion.

9. Tooltip click-through is low. That is not automatically a problem. Determine whether the tooltip was needed; if it explains a standard element, fix the element.

10. Users skip the optional tutorial and still activate. Strong evidence to remove or de-emphasize the tutorial.

11. A permission prompt is denied early. This is usually a context and timing problem: explain the value before the request, and provide a recovery path.

12. Users fail because of a technical import error. This is product reliability and recovery, not a copy tweak. Fix the failure before redesigning the screen.

13. Different roles need different setup. Branch only where the role changes the required path, not to satisfy a persona model.

14. "How many onboarding steps should we have?" There is no magic number. Minimize the steps that genuinely must happen before value; the count falls out of that, not the other way around.

15. "How fast should time to value be?" There is no universal target. Compare against the job, setup and dependencies, and remove the delay that is unnecessary.

16. "Activated accounts retain better, so let us force a teammate invite." Be careful. That is often a correlation, not a cause; forcing the invite can create friction and false invitations. Test it rather than assuming it, and never make a proxy the goal.

17. Enterprise setup needs human implementation. Hybrid and assisted onboarding can be legitimate. The goal is to automate the repeatable parts over time.

18. An onboarding email fires after the user already activated. That is a state-awareness and suppression bug, not a content problem.

Frequently asked questions

What is product onboarding?

Product onboarding is the path that takes an eligible user or account from entry to first meaningful value: the required setup, the first meaningful action, and the guidance needed along the way. It includes necessary setup as well as interface familiarity, and it is not limited to first-time users, a genuinely new feature can require onboarding again. It ends when the user can continue toward value without unnecessary guidance.

What is the difference between onboarding and activation?

Activation is a definition: the early realized value event or state that stands in for "the product worked." Onboarding is the experience that gets an eligible user or account there. Defining activation is a measurement decision; designing onboarding is a product decision. "Onboarding completed" is not activation by default.

What are common product onboarding patterns?

Welcome screens, empty-state guidance, templates, sample or demo data, checklists, progressive disclosure, contextual tooltips and hotspots, setup wizards, guided tasks and interactive walkthroughs, role or use-case selection, permission and integration setup, invite prompts, triggered email or push, and concierge/assisted onboarding. None is universally right; each fits a specific problem and state.

Should onboarding use a checklist?

Only when several meaningful setup tasks exist, order is partly flexible, and the user may leave and return. Checklists fail when they are busywork, when items exist to fill the list, and when completion is treated as value. A single required step is not a checklist.

Are product tours effective?

Sometimes, for genuinely novel or unfamiliar interfaces where users cannot learn by doing. As a default first screen, tours tend to interrupt, get skipped, and be forgotten, because they present information out of context. Prefer contextual help at the moment of need, and make instruction dismissible and recallable.

How many onboarding steps should there be?

There is no magic number. Count the steps that genuinely block first value and remove or defer the rest. The count is an output of the value-path analysis, not a design target.

What is time to value?

The time from a defined start (signup, first login, purchase) to the first meaningful outcome. It is contextual: it depends on job complexity, setup, external dependencies and coordination. Optimize the unnecessary delay, not an arbitrary stopwatch target.

How do you measure onboarding success?

Track eligible users or accounts entering onboarding, prerequisite completion, step progression and drop-off, time between meaningful steps, time to first value, activation using its own definition, assisted-support rate, failure/retry rate, and post-activation retained value. Treat tour completion, tooltip views and checklist completion as diagnostic only, never as goals.

Should onboarding be skippable?

Educational guidance should be dismissible and resumable. Product requirements for value cannot be skipped, only deferred, honestly. Legal, security and compliance steps are not skippable at all and should be labeled as requirements.

How do you onboard B2B users?

Separate account-level and user-level onboarding. Identify which actor owns each prerequisite (admin, champion, contributor, buyer, security), model the waiting state when value depends on another person, and decide whether activation is a user or account event. Do not force single-player onboarding onto a multi-user product.

What is progressive disclosure?

Showing primary options first and deferring advanced or rarely used options to a secondary surface, with a clear and discoverable path to reveal them. It reduces initial complexity; it is not a license to hide necessary controls, and designs that go beyond two disclosure levels tend to hurt usability.

When should you use sample data or templates?

When the blank-slate cost is high and the user does not yet know what "good" looks like. Ask whether the sample matches the real job, whether it can be deleted, whether it confuses analytics, whether it can create false activation, and whether the user can tell sample from real. Exclude demo actions from decision-critical activation metrics unless you have decided otherwise on purpose.

How do you onboard users who return after abandoning setup?

Resume from their actual state, preserve completed prerequisites, surface the single next step, distinguish waiting from blocked, and never replay a finished tour. Returning users are a distinct state, not a second first-run.

References and further reading

Sources below informed the method. Where a claim is a general UX principle, a vendor methodology or practitioner framing is labeled as such; none is treated as universal law, and no benchmark range is published here.

• Jakob Nielsen, Progressive Disclosure, Nielsen Norman Group (2006). Source for the initial/secondary split, the discoverable path requirement, the two-level usability caveat, and the progressive-vs-staged disclosure distinction.
• Page Laubheimer, Onboarding Tutorials vs. Contextual Help, Nielsen Norman Group (2023). Source for push vs. pull revelations, why tutorials are skipped and forgotten, when walkthroughs are justified (novel paradigms), and the dismiss-and-recall guideline.
• Alita Kendrick, Mobile-App Onboarding: An Analysis of Components and Techniques, Nielsen Norman Group (2020). Source for the onboarding definition, "skip onboarding whenever possible," the feature-promotion/customization/instructions components, and the content-vs-cosmetic customization distinction.
• Kate Kaplan, Designing Empty States in Complex Applications: 3 Guidelines, Nielsen Norman Group (2021). Source for system status, learning cues, direct pathways, and the labeled demo-data pattern.
• Amplitude, What Is TTV: A Complete Guide to Time to Value. Vendor methodology used for the latency categories, define-value-before-measuring, and median/percentile reporting. Not treated as a benchmark source.
• WorkOS, Customer and user onboarding for real-world B2B SaaS (2026). Vendor practitioner framing used for the admin-first onboarding surface, organizations as the account model, invitations/JIT/domain policies, and "onboarding as a system, not a checklist."
• Appcues, User onboarding best practices and Chameleon, Onboarding UX Patterns. Vendor playbooks consulted for current table-stakes framing (welcome, checklist, tour, tooltip, empty state, measurement) and deliberately not used for their universal benchmark ranges, fixed step counts or famous-company claims.

A note on what was intentionally left out. This page does not publish activation, completion or time-to-value benchmarks, fixed step counts, or stats such as "progressive disclosure beats tours by 40%" or "empty states drive 3x engagement." Those numbers circulate widely in onboarding content, but they are context-dependent, frequently unsourced, and dangerous as targets. If a benchmark genuinely helps, cite its source, date, product category, acquisition model, metric definition and sample, and treat it as context, not a goal.

CraftUp's onboarding patterns content sits inside a broader Growth and launch context; for the adjacent owner jobs, use the activation metric guide, early user funnel tracking, the product-led operating model, the retention system and the measurement contract. For the broader growth orientation, see the Growth topic hub and the early-stage growth course.