1> **Additional context needed**: the "aha moment" you want users to reach, and users' experience level.
  2
  3Get users to first value as fast as possible. Onboarding's job is not to teach the product. Its job is to get people to the moment that proves the product is worth their time.
  4
  5## Assess Onboarding Needs
  6
  7Understand what users need to learn and why:
  8
  91. **Identify the challenge**:
 10   - What are users trying to accomplish?
 11   - What's confusing or unclear about current experience?
 12   - Where do users get stuck or drop off?
 13   - What's the "aha moment" we want users to reach?
 14
 152. **Understand the users**:
 16   - What's their experience level? (Beginners, power users, mixed?)
 17   - What's their motivation? (Excited and exploring? Required by work?)
 18   - What's their time commitment? (5 minutes? 30 minutes?)
 19   - What alternatives do they know? (Coming from competitor? New to category?)
 20
 213. **Define success**:
 22   - What's the minimum users need to learn to be successful?
 23   - What's the key action we want them to take? (First project? First invite?)
 24   - How do we know onboarding worked? (Completion rate? Time to value?)
 25
 26**CRITICAL**: Onboarding should get users to value as quickly as possible, not teach everything possible.
 27
 28## Onboarding Principles
 29
 30Follow these core principles:
 31
 32### Show, Don't Tell
 33- Demonstrate with working examples, not just descriptions
 34- Provide real functionality in onboarding, not separate tutorial mode
 35- Use progressive disclosure, teach one thing at a time
 36
 37### Make It Optional (When Possible)
 38- Let experienced users skip onboarding
 39- Don't block access to product
 40- Provide "Skip" or "I'll explore on my own" options
 41
 42### Time to Value
 43- Get users to their "aha moment" ASAP
 44- Front-load most important concepts
 45- Teach 20% that delivers 80% of value
 46- Save advanced features for contextual discovery
 47
 48### Context Over Ceremony
 49- Teach features when users need them, not upfront
 50- Empty states are onboarding opportunities
 51- Tooltips and hints at point of use
 52
 53### Respect User Intelligence
 54- Don't patronize or over-explain
 55- Be concise and clear
 56- Assume users can figure out standard patterns
 57
 58## Design Onboarding Experiences
 59
 60Create appropriate onboarding for the context:
 61
 62### Initial Product Onboarding
 63
 64**Welcome Screen**:
 65- Clear value proposition (what is this product?)
 66- What users will learn/accomplish
 67- Time estimate (honest about commitment)
 68- Option to skip (for experienced users)
 69
 70**Account Setup**:
 71- Minimal required information (collect more later)
 72- Explain why you're asking for each piece of information
 73- Smart defaults where possible
 74- Social login when appropriate
 75
 76**Core Concept Introduction**:
 77- Introduce 1-3 core concepts (not everything)
 78- Use simple language and examples
 79- Interactive when possible (do, don't just read)
 80- Progress indication (step 1 of 3)
 81
 82**First Success**:
 83- Guide users to accomplish something real
 84- Pre-populated examples or templates
 85- Celebrate completion (but don't overdo it)
 86- Clear next steps
 87
 88### Feature Discovery & Adoption
 89
 90**Empty States**:
 91Instead of blank space, show:
 92- What will appear here (description + screenshot/illustration)
 93- Why it's valuable
 94- Clear CTA to create first item
 95- Example or template option
 96
 97Example:
 98```
 99No projects yet
100Projects help you organize your work and collaborate with your team.
101[Create your first project] or [Start from template]
102```
103
104**Contextual Tooltips**:
105- Appear at relevant moment (first time user sees feature)
106- Point directly at relevant UI element
107- Brief explanation + benefit
108- Dismissable (with "Don't show again" option)
109- Optional "Learn more" link
110
111**Feature Announcements**:
112- Highlight new features when they're released
113- Show what's new and why it matters
114- Let users try immediately
115- Dismissable
116
117**Progressive Onboarding**:
118- Teach features when users encounter them
119- Badges or indicators on new/unused features
120- Unlock complexity gradually (don't show all options immediately)
121
122### Guided Tours & Walkthroughs
123
124**When to use**:
125- Complex interfaces with many features
126- Significant changes to existing product
127- Industry-specific tools needing domain knowledge
128
129**How to design**:
130- Spotlight specific UI elements (dim rest of page)
131- Keep steps short (3-7 steps max per tour)
132- Allow users to click through tour freely
133- Include "Skip tour" option
134- Make replayable (help menu)
135
136**Best practices**:
137- Interactive over passive (let users click real buttons)
138- Focus on workflow, not features ("Create a project" not "This is the project button")
139- Provide sample data so actions work
140
141### Interactive Tutorials
142
143**When to use**:
144- Users need hands-on practice
145- Concepts are complex or unfamiliar
146- High stakes (better to practice in safe environment)
147
148**How to design**:
149- Sandbox environment with sample data
150- Clear objectives ("Create a chart showing sales by region")
151- Step-by-step guidance
152- Validation (confirm they did it right)
153- Graduation moment (you're ready!)
154
155### Documentation & Help
156
157**In-product help**:
158- Contextual help links throughout interface
159- Keyboard shortcut reference
160- Search-able help center
161- Video tutorials for complex workflows
162
163**Help patterns**:
164- `?` icon near complex features
165- "Learn more" links in tooltips
166- Keyboard shortcut hints (`⌘K` shown on search box)
167
168## Empty State Design
169
170Every empty state needs:
171
172### What Will Be Here
173"Your recent projects will appear here"
174
175### Why It Matters
176"Projects help you organize your work and collaborate with your team"
177
178### How to Get Started
179[Create project] or [Import from template]
180
181### Visual Interest
182Illustration or icon (not just text on blank page)
183
184### Contextual Help
185"Need help getting started? [Watch 2-min tutorial]"
186
187**Empty state types**:
188- **First use**: Never used this feature (emphasize value, provide template)
189- **User cleared**: Intentionally deleted everything (light touch, easy to recreate)
190- **No results**: Search or filter returned nothing (suggest different query, clear filters)
191- **No permissions**: Can't access (explain why, how to get access)
192- **Error state**: Failed to load (explain what happened, retry option)
193
194## Implementation Patterns
195
196### Technical approaches:
197
198**Tooltip libraries**: Tippy.js, Popper.js
199**Tour libraries**: Intro.js, Shepherd.js, React Joyride
200**Modal patterns**: Focus trap, backdrop, ESC to close
201**Progress tracking**: LocalStorage for "seen" states
202**Analytics**: Track completion, drop-off points
203
204**Storage patterns**:
205```javascript
206// Track which onboarding steps user has seen
207localStorage.setItem('onboarding-completed', 'true');
208localStorage.setItem('feature-tooltip-seen-reports', 'true');
209```
210
211**IMPORTANT**: Don't show same onboarding twice (annoying). Track completion and respect dismissals.
212
213**NEVER**:
214- Force users through long onboarding before they can use product
215- Patronize users with obvious explanations
216- Show same tooltip repeatedly (respect dismissals)
217- Block all UI during tour (let users explore)
218- Create separate tutorial mode disconnected from real product
219- Overwhelm with information upfront (progressive disclosure!)
220- Hide "Skip" or make it hard to find
221- Forget about returning users (don't show initial onboarding again)
222
223## Verify Onboarding Quality
224
225Test with real users:
226
227- **Time to completion**: Can users complete onboarding quickly?
228- **Comprehension**: Do users understand after completing?
229- **Action**: Do users take desired next step?
230- **Skip rate**: Are too many users skipping? (Maybe it's too long or not valuable)
231- **Completion rate**: Are users completing? (If low, simplify)
232- **Time to value**: How long until users get first value?
233
234When users hit the aha moment fast and don't drop off, hand off to `{{command_prefix}}impeccable polish` for the final pass.