/onboard

name: onboard
description: "Designs and improves onboarding flows, empty states, and first-run experiences to help users reach value quickly. Use when the user mentions onboarding, first-time users, empty states, activation, getting started, or new user flows."
argument-hint: "[target]"
user-invocable: false

MANDATORY PREPARATION

Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: the "aha moment" you want users to reach, and users' experience level.

---

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:

1. **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?

2. **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?)

3. **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