Ux Onboarding

Onboarding Flow Skill

How this skill behaves (read first)

This is a generative skill, and onboarding is a prime over-design trap: the default instinct is a multi-screen tour nobody reads plus a wall of upfront questions and "enable all permissions" prompts — which actively blocks the product and drives drop-off. The lessons are blunt: most apps don't need a tutorial; users learn by using. So this skill gates hard:

1. First gate: does this even need onboarding? Often the answer is "barely" — and the best onboarding is the lightest one that gets users to value.
2. Apply the always-true core — the principles that hold for any first-run experience.
3. Choose the method and asks deliberately — surface the context-dependent decisions with trade-offs; don't default to a 6-screen carousel.

Then hand off to the audits — especially dark-patterns (onboarding is where forced permissions/notifications and friend-spam concentrate).

---

Step 0 — Establish context, starting with the gate

Gate — does it need onboarding? Per the lessons, onboarding is warranted mainly when:

• the app is complex (explain features as users reach them, not upfront), or
• you genuinely need data to function (e.g. a banking app), or
• workflows are unique/unfamiliar, or
• a tutorial is expected (e.g. mobile gaming).

If none hold, recommend the lightest touch — empty-state nudges and contextual tips — over a tour. Then capture:

• Product complexity — learn-by-doing vs. genuinely needs explanation.
• What's truly required to start — the minimum data/permissions, if any.
• Audience — novice vs. expert; one persona or several (drives persona-based branching).
• Platform — mobile (system permission prompts, tight space) vs. web.

State assumptions if proceeding without answers.

---

The always-apply core (true for any onboarding)

• Front-load value; deliver an early win. Show the benefit before asking for anything. Duolingo ends onboarding with two real sentences. Early success drives retention.
• Keep it short. ~4–5 screens max; most users expect onboarding to take ≤60 seconds. If it feels like a lecture, users skip it.
• Ask for the minimum, and say why. Don't bombard with questions before trust is built. Every field/permission needs a clear "why now"; if you can't justify it at launch, collect it later, contextually.
• One thing at a time. One contextual tip at a time; introduce features at the pace users meet them. Less is more.
• Apply progressive disclosure. Primary/most-common features first; reveal advanced options on request. Keep to ≤2 levels of depth.
• Always skippable, with visible progress. Tell users how many steps and where they are; let them exit. Never trap them in the tour.
• Use empty states and success states. A blank screen is an onboarding opportunity (educational content + a clear CTA); a success state early creates a positive first connection.
• End with a clear, relevant CTA — the next logical action ("Start shopping", "Create your first project").
• Don't re-show completed onboarding. Track state; repeating tips after completion is friction.

---

The context-dependent decisions (surface, don't auto-apply)

Present each with its trade-off and a recommendation tied to Step 0. Defaulting to "full walkthrough + ask everything" is the failure mode.

| Decision | Apply when | Avoid / adapt when | Default recommendation | |---|---|---|---| | Onboard at all (and how heavy) | App is complex, data-required, unfamiliar, or tutorial-expected | Simple learn-by-doing apps | Lightest touch that reaches value; prefer empty-state + contextual tips over a tour | | Method (walkthrough / interactive tour / contextual tips / checklist / empty-state-led / permission priming) | Match to need: interactive tour for hands-on learning, checklist for multi-step setup, contextual tips for discoverable features | A static swipe-through carousel at first launch (usually skipped) | Interactive/contextual over static; see method notes below | | Customization / persona questions | Answers genuinely change the experience (e.g. proficiency level, freelancer vs. enterprise) | Asking for data you won't use, or visual customization at first launch | Ask only if it reshapes onboarding; explain why; else defer | | Permission / notification timing | Contextually, at the moment of value, with permission priming (explain benefit before the system prompt) | Requesting all permissions / "enable all notifications" upfront | Contextual + primed — never force-all (→ dark-patterns) | | Registration timing | Account genuinely needed before value | Forcing signup before users see anything | Gradual engagement — let users preview/try first (delaying registration can lift signups ~29%) | | Feature / instructional onboarding | Unique or newly-released features; genuinely unfamiliar workflows | At first launch for a self-evident app | Promote new features contextually, not in a launch tutorial |

Method notes (the picker's menu)

• Interactive tour — hands-on, triggered in context (learn by doing).
• Contextual tips — minimal cues, one at a time, at point of need.
• Checklist — guided setup with progress; good sense of accomplishment for multi-step products.
• Empty-state-led — the screen itself teaches the first action; lightest touch.
• Permission priming — a value-explaining screen before the system permission dialog.
• Walkthrough (static screens) — only if necessary; ≤4–5 screens, focus on the few most exciting/essential things.

---

Validate the result (orchestration)

> Hand-offs name each lens by its installable skill name. Invoke one only if that skill is installed; if it isn't, this skill's own core already carries these rules — proceed without it rather than blocking.

After generating or revising, hand the result to the audit lenses rather than declaring it done. These are candidate lenses — posture is set by docs/orchestration-policy.md, or route the whole thing through ux-design-review. Here, dark-patterns, heuristics, and microcopy are Tier A (auto-run); accessibility and aesthetics are Tier B (offered) — under an existing design system aesthetics is suppressed and accessibility narrows to usage. If the user invoked this skill for one specific thing, respect that scope.

• ux-dark-patterns-audit (Tier A) — the onboarding-specific traps: forced/upfront permissions, "enable all notifications", friend-spam contact access, confirmshaming a skip option. Onboarding should respect autonomy (mindful onboarding).
• ux-aesthetics-audit (Tier B — offer; suppress under a design system) — do the tips/overlays/tour screens create clutter or bury the primary action?
• ux-heuristics-audit (Tier A) — user control (skippable), visibility (progress, success states), recognition, help & documentation.
• ux-accessibility-audit (Tier B — offer; narrow under a design system) — tooltips/overlays reachable by keyboard and screen readers; the flow is skippable without a mouse.
• ux-microcopy-audit (Tier A) — onboarding copy (tips, CTAs, empty/success states) is clear, action-based, and on-voice.

If an audit flags overload or a forced action, resolve toward the gate: the lightest flow that still reaches value.

---

Common do/don't patterns

| ❌ Don't | ✅ Do | |---|---| | Add a tutorial because every app has one | Gate first — many apps just need empty-state + contextual tips | | 6+ static walkthrough screens at first launch | ≤4–5 screens, or skip the carousel for in-context guidance | | Ask every question / request all permissions upfront | Minimum asks; permission priming at the moment of value | | Force signup before showing anything | Gradual engagement — preview/try first | | Explain features before delivering value | Front-load an early win | | Block users in the tour | Always skippable, with visible progress | | Leave empty/success states blank | Use them to teach the first action and reward early success | | Keep showing tips after completion | Track state; don't repeat | | "Enable all notifications" to maximize re-engagement | Contextual, justified opt-ins (→ dark-patterns audit) | | Ship without checking | Hand off to dark-patterns + aesthetics + heuristics + accessibility |

---

Source lessons (Uxcel)

• Best Practices for User Onboarding Flow Design
• Best Practices for Onboarding UX
• Basics of Mobile Onboarding
• Progressive Disclosure in UX
• Attention & Well-being

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Uxcel-Lab
• Source: Uxcel-Lab/product-skills
• License: MIT
• Homepage: https://uxcel.com

Install and usage instructions live in the source repository linked above.