| name | user-onboarding |
| description | Designs and writes user onboarding — empty states, first-run flows, signup-step cutting, setup wizards, lifecycle emails — selling the better user, not the product. Use when shaping what new users see first, writing onboarding or welcome copy, or handling blank screens. Triggers: onboarding, empty state, first run, welcome copy, setup wizard, lifecycle email. |
User Onboarding
Principles from "The Elements of User Onboarding" by Samuel Hulick for designing and writing onboarding experiences that make users successful. Applies to both shaping features (what to build, what to cut, how to structure flows) and writing copy (empty states, welcome messages, CTAs). Supplemental source: Lidwell/Holden/Butler, Universal Principles of Design (2003), for entry-point mechanics.
Core Philosophy: The Fire Flower
Don't sell the fire flower. Sell the ability to throw fireballs.
Every onboarding decision — what to build, what to cut, what to write — should be about the user becoming better, not about the product being great. Your product is the fire flower; the user becoming a fireball-throwing Mario is the real value.
Define your singular improvement. Articulate what your product makes people better at in a single statement — not a list of features. "We make people better at remembering things" not "we help with writing, storing, and searching notes." This singular definition should drive every onboarding decision.
Test: Does this feature/copy talk about THEM or about US?
- Bad: "Our powerful analytics dashboard..."
- Good: "See exactly where your customers come from..."
- Bad: "We offer industry-leading project management..."
- Good: "Ship projects on time without the midnight scrambles..."
The Customer Journey
Each stage is a transition where users drop off. Onboarding lives in the gap between Marketing and Product.
Introduced → Signup → First Use → Recurring Use → Purchase → Ongoing Use → Advanced
Know which transition you're designing for. Different stages need different approaches:
- Introduced → Signup: Selling the dream, aha moment, rational ammunition
- Signup → First Use: First impressions, empty states, quick win
- First Use → Recurring Use: Momentum, setup quests, lifecycle emails, social accountability
- Recurring Use → Purchase: The value should already be self-evident by now
Before changing screens, audit the whole adoption chain. Start from a thriving
user and retrace every required or seemingly necessary touchpoint: acquisition
promise/search result, landing page, pricing, signup form, confirmation email,
first app screen, and getting-started state. Document what each step promises,
asks, and hands off to the next. A page, email, or ad outside the app is still
onboarding; broken scent there cannot be repaired with coachmarks later.
By Context
| Context | When to Use | Reference |
|---|
| Empty States | Designing or writing copy for screens with no user data yet | empty-states.md |
| First Impressions | Shaping the first-run experience, welcome screens, post-signup flow | first-impressions.md |
| Pre-Signup | Landing pages, marketing, selling the dream before signup | selling-the-dream.md |
| Progress & Momentum | Setup quests, progress bars, lifecycle emails, keeping users moving | driving-momentum.md |
Read the appropriate reference based on context.
When onboarding decisions become reusable agent guidance, preserve the surface and evidence: stage in the journey, current user state, desired quick win, step added/removed, source example, and known exceptions. If a first-run or empty-state pattern lacks evidence, park it as a coverage gap instead of inventing a universal rule from one product.
For provenance and parked candidate rules, see sources.md and coverage-gaps.md.
Universal Rules
- Talk about them, not you. "You can slay from far away!" beats "This thing is totally the best."
- Sell outcomes, not features. Lead with what improves in their life.
- Never blame the user. Especially for states they couldn't have influenced yet.
- Maintain scent of information. Each touchpoint must deliver on what the previous one promised.
- Treat attention like oxygen. It's finite and precious. Every word must earn its place.
- Be the world's best butler, not a DMV teller. Warm, helpful, and anticipating needs.
- Encourage at inflection points. When they complete something hard, celebrate with them.
- Leverage what users already carry; reward curiosity instead of instructing. Build on knowledge users bring, curate the invisible layer that supports it, and let explorable details replace instruction (Wardle, Config 2024; Andy Allen).
- Design the share artifact. Spoiler-free, narrates the user's journey, no self-promoting link-back — artifacts that don't self-promote get shared more (Wardle).
- Sequence trust from low stakes to high. Never ask for the high-stakes commitment first; wrap novel tech in a familiar analog; diagnose whose trust is missing — sometimes users distrust themselves, not you (Jude, Config 2025).
- You have ~30 seconds — and name the private shame. Deliver a first win before users retreat to the tool they know; naming a self-blamed pain creates instant resonance. Caveat: a simpler learning experience is not always the better UX (Feener, Browser Company).
- Invert the funnel — ask after value. Radically streamline or fully invert signup; build canvases (multiple paths to the goal), not corridors (Zhang, Config 2024).
- Free play before signup. Let people try before authenticating, and constrain that first-use surface so the free taste is a good one (Ryo Lu, Cursor, 2025). AI-native version: prove value at step one instead of asking questions (Emily Campbell →
ai-experience-design, references/patterns.md).
- Delight has a measured conversion cost — spend it deliberately. Emotional framing before signup can cost real sign-ups; pay only when the emotional frame is the product's edge, and design targeted, not generalized (Conde, Dive Club).
- Pattern fidelity for utilitarian flows. Signup and setup are the follow-patterns zone; save invention for the product's signature moments (Jacoby, Dive Club).
Quote texture and case detail for rules 8–15: field-notes.md.
Shaping Onboarding Features
When deciding what to build or cut from an onboarding flow:
- Every step is a drop-off point. Ruthlessly question each one.
- Don't mistake activity for achievement. Amazon 1-Click vs a full shopping cart — same outcome, wildly different step counts.
- For each step ask: Does this help them reach their quick win? Can a machine do it? Can we use a smart default? Can we defer it until after they've experienced value?
- Define flows by user improvement, not by steps. Beginning state = who they are arriving. End state = who they are after "base camp."
- Points of Friction slow users down (confusion, tedious fields). Points of Disconnect let them drift away (coupon code fields, external links). Eliminate both.
- Treat first use as an entry point (Lidwell/Holden/Butler, Universal Principles of Design, "Entry Point"). Check for "minimal barriers, points of prospect, and progressive lures": remove registration/permission/loading barriers, let users survey what is possible, then place one visible lure just past the threshold that pulls them into the quick win.
- For any personal-data field, explain why you ask and what you'll do with the answer; make it optional and editable (Metts & Welfle, Writing Is Designing, ch. 5 — Fitbit's sex question, which trans users can't answer without knowing whether it's demographic or biometric). Exclusion compounds at scale: "If you exclude even one-tenth of one percent, that means there are 755 million people" less able to use your product.
- The quick win must: demonstrate core product value, be achievable in one sitting, not depend on other people, harness the user's current intent.
Design backward from the behavior (Cindy Alvarez, Build Better Products, ch. 8). "Features don't matter. They don't matter at all. All that matters is customer behavior." Start with the recurring behavior the product needs, then classify onboarding work:
- Required — the minimum path to the user's first real value.
- Encouraged — actions that make future success more likely but can wait.
- Eventual — advanced setup, mastery, integrations, polish.
"When a new user comes to your product, give them a task." Empty welcomes and feature tours are weaker than a constrained job with a visible finish. For habit products, use Amy Jo Kim's sequence via Klein: core loop first, then onboarding, then discovery, then mastery. If there is no strong loop, "you're building a leaky bucket." Build the thing someone will do every day before decorating the path into it.
Explain the ask before the user pays the cost (Sten). If onboarding needs integrations, profile data, permissions, or setup work, show the value unlocked by that step in the user's words before asking for it. Reduce initial commitment where possible: make non-essential integrations skippable, defer setup until after the quick win, and keep the first path to value short enough that the product proves itself before the form grows.
Design for real-life chaos. Sten's healthcare example generalizes: new users may be tired, distracted, anxious, one-handed, under time pressure, or unsure whether they belong. Pattern fidelity and plain language matter most in these utilitarian first-use flows; save novelty for the product's signature moments after trust is established.
Dark-pattern boundary: a dark pattern is any interface element that benefits the company at the expense of what a reasonable, fully informed user would agree to. If the onboarding goal depends on hiding cost, commitment, consent, or cancellation, route to ux-writing (error-messages) / web-design (form-design) ethics rather than conversion optimization.
Quick Copy Formulas
Empty state pattern:
[What will appear here once they take action].
[What they'll be able to do with it — paint the picture].
[CTA button to take that action]
Welcome message pattern:
[Brief warm greeting]
[Orient them: here's what to do first]
[Single clear CTA toward their quick win]
Feature introduction pattern:
[User outcome this enables — in their words]
[Briefest possible explanation of how]
[CTA to try it]
Setup-step rationale pattern:
[Why this helps you right now].
[What we will do with the information/access].
[Skip/edit reassurance if available]
Related skills
Define the product's writing voice with ux-writing (ui-voice-and-tone), then structure the first-run flow and write the welcome/empty-state copy here in that voice — this skill owns the flow and quick-win framing, that one owns the voice. For failure states, route to ux-writing (error-messages). For in-app feature teaching after signup — no-tutorial first launches, visual cues, gesture hints, tips — use feature-discoverability (the Apple counterpart to this skill's journey framework). For courses, workshops, curricula, practice/feedback systems, and job aids, route to learning-experience-design.
Staleness note: the Hulick journey framework and copy rules are durable. Universal Rules 8–15 come from 2024–25 Config talks and Dive Club interviews; the product examples (Wordle, Waymo, Arc, TikTok, Cursor) and any numbers in them describe those products at that moment — verify before citing them as current behavior.
