onboard

SKILL.md

MANDATORY PREPARATION

Invoke /impeccable — 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 /impeccable teach 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:

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:

// 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:

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.
28