onboard

Users start this workflow with . Once this skill is active, load $frontend-design — it contains design principles, anti-patterns, and the Context Gathering Protocol. Follow that protocol before proceeding — if no design context exists yet, you MUST load $setup first. Additionally gather: the "aha moment" you want users to reach, and users' experience level.

Consult the onboarding UX when deciding first-run sequencing, activation milestones, setup-wizard scope, tours vs checklists vs contextual onboarding, progressive permission requests, or how returning users should re-enter an unfinished flow. Consult the empty-state patterns when zero-data surfaces are part of the onboarding journey. Consult the cognitive load when deciding what to hide, sequence, or progressively disclose for first-time users. Consult the behavioral design when onboarding depends on priming, framing, honest progress cues, or completion momentum. Consult the permissions and roles UX when onboarding depends on request-access flows, role selection, admin-vs-member setup differences, or capability boundaries that users need explained early. Consult the ux-writing reference when onboarding clarity depends on labels, hints, reassurance copy, or CTA wording. Consult the status communication when onboarding needs notification preferences, summary modes, quiet hours, reminder settings, or interruption-level decisions. Consult the loading feedback and perceived performance when setup, imports, or first-run data preparation create waits that need honest progress and trust-preserving feedback. Consult marketing copywriting when onboarding needs stronger setup promises, first-win framing, permission prompts, or upgrade / invite messaging. Consult copy editing sweeps when revising existing onboarding copy in focused passes.

Create or improve onboarding experiences that help users understand, adopt, and succeed with the product quickly.

This skill owns onboarding strategy, activation, and time-to-value. For the detailed design of zero-data surfaces themselves, use .

Understand what users need to learn and why:

CRITICAL: Onboarding should get users to value as quickly as possible, not teach everything possible.

Empty states are not an afterthought. For many features, the empty state is the user's first real experience of the product.

Follow these core principles:

Create appropriate onboarding for the context:

Welcome Screen:

Account Setup:

Notification Preferences (when the product could become noisy or time-sensitive):

Core Concept Introduction:

First Success:

Progress and Completion Cues:

Empty States: Instead of blank space, show:

Example:

No projects yet
Projects help you organize your work and collaborate with your team.
[Create your first project] or [Start from template]

Contextual Tooltips:

Feature Announcements:

Progressive Onboarding:

When to use:

How to design:

Best practices:

When to use:

How to design:

In-product help:

Help patterns:

Every empty state needs:

"Your recent projects will appear here"

"Projects help you organize your work and collaborate with your team"

[Create project] or [Import from template]

Illustration or icon (not just text on blank page)

"Need help getting started? [Watch 2-min tutorial]"

Empty state types:

Tooltip libraries: Tippy.js, Popper.js Tour libraries: Intro.js, Shepherd.js, React Joyride Modal patterns: Focus trap, backdrop, ESC to close Progress tracking: LocalStorage for "seen" states Analytics: Track completion, drop-off points

Storage patterns:

// Track which onboarding steps user has seen
localStorage.setItem('onboarding-completed', 'true');
localStorage.setItem('feature-tooltip-seen-reports', 'true');

IMPORTANT: Don't show same onboarding twice (annoying). Track completion and respect dismissals.

NEVER:

Test with real users:

Remember: You're a product educator with excellent teaching instincts. Get users to their "aha moment" as quickly as possible. Teach the essential, make it contextual, respect user time and intelligence.