Onboarding & First-Run

Onboarding is activation, not a tour. The goal is never to explain the product; it's to get the user to their first real moment of value as fast as possible. A carousel of feature slides, a forced product tour, a wall of setup before anything works: these are things teams build when they've confused "teaching the user" with "helping the user succeed." The user didn't sign up to learn your app. They signed up to get something done.

The best onboarding is often invisible. The product is obvious enough that the user falls into success, and the few things they genuinely need to set up are framed as steps toward their own goal, not chores for yours. This is the Jobs principle applied to the first five minutes: design is how it works, and if the user needs a manual, the design has failed (see jobs-product-design.md).

Onboarding and Setup Are Two Phases

Most teams build one flow and expect it to do two jobs. It cannot. Onboarding runs from signup to the moment the user sees the product work. Setup runs from that moment until the user goes live on real work. The two phases have different goals, so they need different screens and different metrics.

• Onboarding delivers the best version of the product that costs the user no effort. No integrations, no sales call, no configuration screens. A few clicks, then a result they can play with. Its metric is the share of new users who reach that result.
• Setup delivers the version the user will keep. Real data sources, real destinations, the tools they already run. Its metric is usage: the user is live on at least one real workflow.
• Work from the wrong phase breaks the flow in both directions. Setup put before the aha moment is a wall in front of an unproven product. Onboarding repeated after it is a tour the user has outgrown.
• Make the boundary visible. Onboarding ends with something the user can use, plus one obvious next step into setup.

The rule: if a step makes the product real, it belongs in setup, and it comes after the user has seen the product work.

Time to First Value

Every screen, field, and click between signup and the user's first win is a place they can leak away. Measure that distance and shorten it relentlessly.

• Identify the single moment of value for your product: the first generated result, the first imported contact, the first sent message. That's the target. Everything before it is overhead.
• Cut steps that don't move the user toward that moment. A profile photo, a team name, a plan choice: ask for them later, when they're actually needed, not as a gate on the front.
• Defer configuration. Sensible defaults beat a setup wizard. The user can refine once they've seen the thing work; making them configure before they understand the product is asking them to make decisions blind.

The rule: if a step doesn't help the user reach first value, it doesn't belong in onboarding. Move it downstream or kill it.

Don't Gate Before Value

A signup wall in front of an unproven product is a high price for nothing. Where the product can demonstrate value without an account, let it, and put the wall after the user has seen what they'd be signing up for.

• Let users try the core action anonymously where the architecture allows it, then prompt for an account at the natural commit point (saving, sharing, exceeding a free limit).
• When the wall does appear, make it feel earned: the user has already produced something, so creating an account preserves their work rather than unlocking a black box.
• If an account is genuinely required up front (the product can't function without identity), make signup itself trivially short and get to value immediately after (see forms.md for the field-level mechanics: correct input types, autocomplete, password-manager compatibility).

Make It Feel Built for Them

A product that serves several industries, or several jobs, reads as generic to every one of them. Onboarding is where you narrow it. The user should reach their first result thinking "this was made for my kind of work", not "this is a tool I will have to bend".

• Learn the segment in the first step, from one input. A company URL or a work email domain tells you the industry, the rough size, and often the stack. Read it instead of asking a survey. Ask a direct question only when nothing reliable can be inferred, and only when the answer changes the next screen.
• Match the proof to the segment. Show the customer logos, testimonials, templates, and integrations that belong to the user's industry. Near-peer names carry more weight than your largest customer, because the user recognizes the shape of their own problem in them. One well-known name alongside them adds credibility.
• Hide what does not apply, and keep it one click away. Features and integrations for other use cases are noise, and a screen full of them tells the user the product was built for somebody else. Hiding is not removing: a guess about the segment is sometimes wrong, so the full set stays reachable from the same screen.
• Preselect, do not prefill blindly. Suggest the templates, sample data, and connections the segment implies, and let the user change every one of them. A confident wrong guess is worse than an obvious default.
• Never invent the proof. If you have no customer in the user's industry, show the closest true thing. A fabricated logo wall is a trust failure the user only has to catch once.

Teach the Value of Paying

Onboarding is the one moment when a new user will happily look at the whole product. Use it. As the user picks what they want, they tell you what to sell them, and they learn what the paid plan is for before any limit stops them.

• Let the user choose the features they care about, paid ones included. The choice is a preference signal and a price anchor at the same time.
• Show the paid feature doing its job, then say plainly that it needs a paid plan. A locked feature the user has never seen working is a wall, not an offer. Silently dropping it from the flow teaches nothing.
• Keep the free path complete. First value never sits behind the paywall. The user has to reach a working result without paying, or there is nothing to upgrade from.
• This is not a feature tour. A tour talks at the user about features they did not ask for. This is the opposite: the user picks, the product responds, and only features their own answers made relevant ever appear (see Inline Guidance Over Modals below).
• Make the later paywall continue the work. When the user does hit the limit, name what they were doing and what the plan unlocks, so the prompt reads as the next step rather than a toll gate (see microcopy.md).

Empty States Are Onboarding

The first-use empty state is the onboarding surface for most screens. When a user lands on an empty list, panel, or dashboard, that empty state has to do the teaching: name what's missing, explain why it's empty, and give the one action that fills it.

This is already specified in ui/polish.md — Don't Overlook Empty States (type 1, first-use). The onboarding-specific emphasis:

• The CTA must move setup forward toward value: "Create your first project", "Import contacts", "Connect a data source" — never a generic "No data."
• Strip the chrome that does nothing without data (filters, sort, bulk actions, pagination). A first-use screen full of dead controls looks broken and buries the one action that matters (see ui/polish.md — Hide chrome that does nothing).
• Don't confuse a first-use empty state with a cleared-out or error-adjacent one. First-use teaches; the others acknowledge or recover. Using first-use copy when a load failed is a lie (see errors.md — Network & Async Errors, and ui/polish.md — empty state types).

Progressive Onboarding

Don't front-load everything the user will ever need to know. Reveal complexity as the user reaches for it, the same way a good form reveals fields only when they're relevant (see forms.md — Progressive Disclosure).

• Teach a feature at the moment the user first encounters it, in context, not in a pre-flight briefing they'll forget by the time it matters.
• Layer capability. The first session exposes the core path; advanced options surface once the basics are familiar. The product grows with the user instead of dumping its full surface on day one.
• Contextual hints beat a one-time tour because they arrive when the user can act on them and disappear when they can't.

Teach Experiential Products Through Use

Some products are tools for learning, making, or manipulating. Their value lives in the interaction, so a recorded explanation cannot replace using the real thing. Put the user inside a safe working example and let the first lesson be an action.

• Prefer a live example when timing, gesture, motion, or state changes are the subject. Use video as supporting context, not as the only way to understand behavior.
• Make experimentation safe and reversible. Let people change a value, replay the behavior, or reset it so cause and effect stay visible.
• Reveal source code or configuration beside the result when the audience can use it. Keep the explanation close enough that users do not have to map a distant description back to the interface.

For unfamiliar interactions, apply Inline Guidance Over Modals and Accessibility below. For copyable standalone examples, see Build Complex Examples as Standalone Components in ui/component-architecture.md. For nonlinear learning paths, see Support Browsing and Sequencing in navigation.md.

Inline Guidance Over Modals

Guidance that blocks the user is guidance they'll dismiss without reading. Prefer hints that sit beside the work over modals that stop it.

• Coach marks, inline tips, and subtle highlights point without interrupting. Use them sparingly: one or two per surface, on the things genuinely worth pointing at, not a confetti of tooltips.
• A blocking onboarding modal is justified only for something the user truly must acknowledge before continuing, the same bar as any modal (see dialogs.md — When to Use a Dialog at All, and notifications.md — Blocking Alerts & Modals). "Welcome! Here's a tour" rarely clears that bar.
• Anything resembling a tour must be skippable in one obvious action, and skipping must be remembered (see Re-Onboarding below).

Hand Off to Setup

The aha moment is the middle of the flow, not the end. Motivation peaks the second the product works, and it decays from there, so the next step has to be waiting on that screen.

• End onboarding with the result and one next action. Two competing actions split the user's attention; a dashboard of options ends the momentum entirely.
• Name the gap between the demo and the live version. "This runs on the three sample pages. Connect your site to run it on all of them." The user continues because they can see what they are missing, not because a progress bar told them to.
• Order setup by value, and put going live first. Connecting the one channel the user will actually run on beats four small configuration wins.
• Show the good version before you ask for the work. A preview of the result with real integrations attached earns the effort that a request for API keys never will.
• Measure setup by usage, not by completion. A finished checklist next to an unused product means the checklist counted the wrong thing.

Setup Checklists & Progress

A getting-started checklist turns a vague "set up the product" into a finite, completable list. It works because it shows the finish line and rewards progress.

• Keep it short (3–5 items) and order items by value, not by your data model. The first item should produce a visible result.
• Show progress concretely: "2 of 4 complete." Use tabular-nums on the counter so it doesn't reflow as it ticks (see ui/typography.md — Tabular Numbers).
• Let the user dismiss or collapse the checklist. A persistent nag that can't be hidden becomes resentment. Once complete, let it celebrate briefly and then get out of the way (this is the cleared-out empty state: acknowledge the change, don't revert to first-use language — see ui/polish.md).

// Progress reads honestly; the counter uses tabular figures so it doesn't jitter
<p className="tabular-nums">{done} of {total} complete</p>

Sample & Seed Data

An empty product is hard to understand. A populated one explains itself. Where it fits, seed the first experience with example content so the user sees the shape of success before they've built anything.

• Provide sample data, a template, or a pre-filled example the user can poke at, edit, or clear. Seeing a populated dashboard teaches more than any tooltip about an empty one.
• Make sample data obviously distinguishable and trivially removable, so the user never confuses the demo for their own content or struggles to clear it.
• A "start from a template" path is often a faster route to value than "start from blank" for first-time users, even if power users prefer the blank canvas.

Ask Only What Changes the Experience

Every onboarding question is friction. Ask only the ones whose answers actually change what the user sees next.

• If the answer doesn't branch the experience, don't ask it during onboarding. "What's your role?" is worth asking only if the product genuinely adapts to the role; otherwise it's a survey for your analytics at the cost of the user's momentum.
• Prefer inferring over asking. If you can detect locale, timezone, or context, do that instead of a question (see interactions.md — Prefer Language Settings Over Location). One company URL replaces most of a segmentation survey (see Make It Feel Built for Them above).
• When you must ask, follow the labeling and minimal-friction rules: don't over-label, combine label and value where the format speaks for itself (see ui/hierarchy.md — Labels are a Last Resort), and keep the form short (see forms.md).

Re-Onboarding

Onboarding isn't only for brand-new users. Returning users and new features need a lighter touch that respects what the user already knows.

• Don't re-run the first-run flow. A user who's been active for months should never be dropped back into the welcome tour. Track completion and respect it.
• Introduce a new feature with a single contextual hint at the point of use, not a full re-onboarding. A small "New" affordance or one-time tip is enough.
• Returning after a long absence may warrant a brief "what's changed" summary, but make it dismissable and short. The user came back to use the product, not to be re-taught it.

Accessibility

Onboarding overlays and tours are a frequent accessibility trap because they layer interactive guidance on top of the real UI.

• Coach marks and tour steps must be keyboard-operable and skippable from the keyboard. A tour the user can't escape with the keyboard strands them.
• If a step uses a spotlight/overlay, manage focus like any dialog: move focus to the step, don't let it leak to the dimmed background, return it on dismiss (see dialogs.md — Focus Management, interactions.md — Focus Management).
• Announce step changes to assistive tech with a polite live region so a screen-reader user follows the sequence (see interactions.md — Accessibility Announcements).
• Respect prefers-reduced-motion for any spotlight movement, pulsing highlight, or animated transition between steps (see ui/animation-and-motion.md).

Checklist

Goal

• Onboarding targets first value, not a feature tour
• Onboarding and setup are separate phases, split at the aha moment
• Onboarding reaches a usable result with no integration, call, or configuration
• Every pre-value step justified or removed
• Value demonstrated before the signup wall where possible
• Defaults over configuration; refine later

Relevance & upgrade

• Segment inferred from a URL or domain where that is reliable, with a short question as the fallback
• Proof, templates, and integrations match the user's industry and use case
• Inferred choices visible, editable, and never the only way through
• Features for other use cases hidden, and the full set still reachable
• Paid features chosen by the user, shown working, then priced plainly
• Free path reaches first value without the paywall

Surfaces

• First-use empty states carry the onboarding (action-forward CTA, dead chrome hidden)
• Complexity revealed progressively, in context, at point of use
• Experiential features teach through safe, reversible live examples
• Inline guidance preferred over blocking modals; tours skippable and remembered
• Setup checklist short, value-ordered, progress shown with tabular-nums, dismissable
• First value ends with one next action, and the gap to the live version is named
• Setup measured by usage in production, not by checklist completion

Content & friction

• Sample/seed data or templates show a populated state
• Only ask questions whose answers change the experience; infer where possible
• Returning users never re-run the first-run flow
• New features introduced with a single contextual hint

Accessibility

• Tour steps keyboard-operable and skippable
• Spotlight/overlay steps manage focus like a dialog
• Step changes announced via polite live region
• Reduced motion respected for highlights and transitions