--- name: Onboarding slug: onboarding-4 category: Frontend description: Onboarding designs first-run experiences, empty states, and guided flows that help users reach value quickly. Use it for activation, getting started, and new user journeys. github: "https://github.com/AkaraChen/aghub/tree/main/.agents/skills/onboard" language: TypeScript stars: 264 forks: 17 install: "npx degit https://github.com/AkaraChen/aghub/tree/main/.agents/skills/onboard ~/.claude/skills/onboard" installs_to: ~/.claude/skills/onboard source_path: .agents/skills/onboard/SKILL.md collection_size: 25 category_size: 600 collection_url: "https://dirskills.com/collections/AkaraChen/aghub" added: 2026-09-02T05:20:03.209Z last_synced: 2026-09-02T05:20:03.209Z canonical_url: "https://dirskills.com/skills/onboarding-4" --- # Onboarding Onboarding designs first-run experiences, empty states, and guided flows that help users reach value quickly. Use it for activation, getting started, and new user journeys. **Install:** ```bash npx degit https://github.com/AkaraChen/aghub/tree/main/.agents/skills/onboard ~/.claude/skills/onboard ``` ## README ## 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 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**: ```javascript // 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.