Designing a First Run

A first run has exactly one job: produce one real outcome in the user's own data, then get out of the way. Default posture — ship no tour, no welcome carousel, no interstitial video. Spend the entire budget removing steps between first paint and the first created object, and let the product's own empty screens do the teaching. Onboarding is a sequence, and it is measured in steps, not minutes. Boundary with ui-states: ui-states owns what an empty state is — its anatomy, its skeleton-versus-spinner call, its error and partial-data variants; this skill owns only the order a new account moves through and what that empty state should coach toward. If the question is "what should this empty screen look like", load ui-states instead. Whether the first success moment earns a flourish is delight's call, not this skill's.

Detect the first-run machinery the project already has before adding any. Look for an existing completion flag (onboarding_completed_at, hasOnboarded), a feature-flag or entitlement service, a seeded-data path in migrations or fixtures, an existing checklist component, and — critically — an already-installed tour library (shepherd.js, driver.js, intro.js, react-joyride, @reactour/tour). If one is installed, someone already decided: work inside it or argue explicitly for removing it. Never stand up a second onboarding state machine beside an existing one, and never keep first-run state somewhere the rest of the app cannot read.

Quick Reference

Topic	Where
Once the product archetype is known — solo tool, team workspace, integration/data product, marketplace, consumer mobile — open this for its activation event, first step, seeding rule, and checklist shape	first-run-patterns.md

Decision Framework: name the activation event first

Before designing any screen, write one sentence: "A new account is activated when they ______." It must be a single observable event in the product's own data — a document created, a repo connected, a first message sent — never "finished onboarding" and never "viewed the dashboard". Everything in the first run either shortens the path to that event or is cut. If you cannot name the event, you are not ready to design the sequence; ask, and say why you are asking.

Then count the steps between first paint and that event. Every step is one of three kinds, and only the first is allowed to be mandatory: