| name | i-onboard |
| description | Design or improve onboarding flows, empty states, and first-time user experiences. Helps users get started successfully and understand value quickly. |
| user-invokable | true |
| argument-hint | ["TARGET=<value>"] |
Create or improve onboarding experiences that help users understand, adopt, and succeed with the product quickly.
Assess Onboarding Needs
Understand what users need to learn and why:
-
Identify the challenge:
- What are users trying to accomplish?
- What's confusing or unclear about current experience?
- Where do users get stuck or drop off?
- What's the "aha moment" we want users to reach?
-
Understand the users:
- What's their experience level? (Beginners, power users, mixed?)
- What's their motivation? (Excited and exploring? Required by work?)
- What's their time commitment? (5 minutes? 30 minutes?)
- What alternatives do they know? (Coming from competitor? New to category?)
-
Define success:
- What's the minimum users need to learn to be successful?
- What's the key action we want them to take? (First project? First invite?)
- How do we know onboarding worked? (Completion rate? Time to value?)
CRITICAL: Onboarding should get users to value as quickly as possible, not teach everything possible.
Onboarding Principles
Follow these core principles:
Show, Don't Tell
- Demonstrate with working examples, not just descriptions
- Provide real functionality in onboarding, not separate tutorial mode
- Use progressive disclosure - teach one thing at a time
Make It Optional (When Possible)
- Let experienced users skip onboarding
- Don't block access to product
- Provide "Skip" or "I'll explore on my own" options
Time to Value
- Get users to their "aha moment" ASAP
- Front-load most important concepts
- Teach 20% that delivers 80% of value
- Save advanced features for contextual discovery
Context Over Ceremony
- Teach features when users need them, not upfront
- Empty states are onboarding opportunities
- Tooltips and hints at point of use
Respect User Intelligence
- Don't patronize or over-explain
- Be concise and clear
- Assume users can figure out standard patterns
Design Onboarding Experiences
Create appropriate onboarding for the context:
Initial Product Onboarding
Welcome Screen:
- Clear value proposition (what is this product?)
- What users will learn/accomplish
- Time estimate (honest about commitment)
- Option to skip (for experienced users)
Account Setup:
- Minimal required information (collect more later)
- Explain why you're asking for each piece of information
- Smart defaults where possible
- Social login when appropriate
Core Concept Introduction:
- Introduce 1-3 core concepts (not everything)
- Use simple language and examples
- Interactive when possible (do, don't just read)
- Progress indication (step 1 of 3)
First Success:
- Guide users to accomplish something real
- Pre-populated examples or templates
- Celebrate completion (but don't overdo it)
- Clear next steps
Feature Discovery & Adoption
Empty States:
Instead of blank space, show:
- What will appear here (description + screenshot/illustration)
- Why it's valuable
- Clear CTA to create first item
- Example or template option
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:
- Appear at relevant moment (first time user sees feature)
- Point directly at relevant UI element
- Brief explanation + benefit
- Dismissable (with "Don't show again" option)
- Optional "Learn more" link
Feature Announcements:
- Highlight new features when they're released
- Show what's new and why it matters
- Let users try immediately
- Dismissable
Progressive Onboarding:
- Teach features when users encounter them
- Badges or indicators on new/unused features
- Unlock complexity gradually (don't show all options immediately)
Guided Tours & Walkthroughs
When to use:
- Complex interfaces with many features
- Significant changes to existing product
- Industry-specific tools needing domain knowledge
How to design:
- Spotlight specific UI elements (dim rest of page)
- Keep steps short (3-7 steps max per tour)
- Allow users to click through tour freely
- Include "Skip tour" option
- Make replayable (help menu)
Best practices:
- Interactive > passive (let users click real buttons)
- Focus on workflow, not features ("Create a project" not "This is the project button")
- Provide sample data so actions work
Interactive Tutorials
When to use:
- Users need hands-on practice
- Concepts are complex or unfamiliar
- High stakes (better to practice in safe environment)
How to design:
- Sandbox environment with sample data
- Clear objectives ("Create a chart showing sales by region")
- Step-by-step guidance
- Validation (confirm they did it right)
- Graduation moment (you're ready!)
Documentation & Help
In-product help:
- Contextual help links throughout interface
- Keyboard shortcut reference
- Search-able help center
- Video tutorials for complex workflows
Help patterns:
? icon near complex features- "Learn more" links in tooltips
- Keyboard shortcut hints (
⌘K shown on search box)
Empty State Design
Every empty state needs:
What Will Be Here
"Your recent projects will appear here"
Why It Matters
"Projects help you organize your work and collaborate with your team"
How to Get Started
[Create project] or [Import from template]
Visual Interest
Illustration or icon (not just text on blank page)
Contextual Help
"Need help getting started? [Watch 2-min tutorial]"
Empty state types:
- First use: Never used this feature (emphasize value, provide template)
- User cleared: Intentionally deleted everything (light touch, easy to recreate)
- No results: Search or filter returned nothing (suggest different query, clear filters)
- No permissions: Can't access (explain why, how to get access)
- Error state: Failed to load (explain what happened, retry option)
Implementation Patterns
Technical approaches:
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:
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:
- Force users through long onboarding before they can use product
- Patronize users with obvious explanations
- Show same tooltip repeatedly (respect dismissals)
- Block all UI during tour (let users explore)
- Create separate tutorial mode disconnected from real product
- Overwhelm with information upfront (progressive disclosure!)
- Hide "Skip" or make it hard to find
- Forget about returning users (don't show initial onboarding again)
Verify Onboarding Quality
Test with real users:
- Time to completion: Can users complete onboarding quickly?
- Comprehension: Do users understand after completing?
- Action: Do users take desired next step?
- Skip rate: Are too many users skipping? (Maybe it's too long/not valuable)
- Completion rate: Are users completing? (If low, simplify)
- Time to value: How long until users get first value?
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.
