Guiding Users Through Onboarding and Help Systems

Purpose

This skill provides systematic patterns for onboarding users and delivering contextual help, from first-time product tours to ongoing feature discovery. It covers the complete spectrum of user guidance mechanisms, ensuring optimal user activation, feature adoption, and self-service support.

When to Use

Activate this skill when:

Building first-time user experiences or product tours
Implementing feature discovery and announcements
Creating interactive tutorials or guided tasks
Adding tooltips, hints, or contextual help
Designing setup flows or completion checklists
Building help panels or documentation systems
Implementing progressive disclosure patterns
Measuring onboarding effectiveness and user activation
Ensuring onboarding accessibility

Quick Decision Framework

Select the appropriate guidance mechanism based on user state and content type:

First-time user          → Product Tour (step-by-step)
New feature launch       → Feature Spotlight (tooltip + animation)
Complex workflow         → Interactive Tutorial (guided tasks)
Account setup            → Checklist (progress tracking)
Contextual help needed   → Tooltip/Hint system
Ongoing support          → Help Panel (sidebar/searchable)
Feature unlock           → Progressive Disclosure

Reference references/selection-framework.md for detailed selection criteria.

Core Guidance Mechanisms

Product Tours

Step-by-step walkthroughs that guide users through key features:

Sequential spotlights with modal overlays
Progress indicators (Step 2 of 5)
Skip, Previous, and Next controls
Dismiss and resume capability
Context-sensitive activation

Implementation:

npm install react-joyride

See examples/first-time-tour.tsx for complete implementation. Reference references/product-tours.md for patterns and best practices.

Feature Spotlights

Announce new features to existing users:

Pulsing hotspot animations
Contextual tooltip with arrow
"Got it" acknowledgment
Auto-dismiss after first view
Non-blocking overlay

See examples/feature-spotlight.tsx for implementation. Reference references/tooltips-hints.md for patterns.

Interactive Tutorials

Guided task completion with validation:

"Complete these tasks to get started"
Checkbox completion tracking
Celebration animations on completion
Sandbox mode with sample data
Undo and reset capabilities

See examples/guided-tutorial.tsx for implementation. Reference references/interactive-tutorials.md for patterns.

Setup Checklists

Track multi-step onboarding progress:

Visual progress indicators (3/4 complete)
Direct links to each task
Profile completion percentages
Achievement badges and gamification
Persistent until completed

See examples/setup-checklist.tsx for implementation. Reference references/checklists.md for patterns.

Contextual Tooltips and Hints

Just-in-time help when users need it:

Hover or click-triggered tooltips
Progressive hint levels (1, 2, 3)
"Need help?" assistance triggers
Context-aware suggestions
Keyboard-accessible

See examples/contextual-help.tsx for implementation. Reference references/tooltips-hints.md for complete patterns.

Help Panels

Comprehensive help systems:

Sidebar or drawer interface
Contextual help based on current page
Search help articles and docs
Video tutorials and demos
Contact support integration
Collapsible and resizable

See examples/help-panel.tsx for implementation. Reference references/help-systems.md for patterns.

Timing and Triggering Strategies

When to Show Onboarding

Appropriate triggers:

First login (always)
Immediately after signup
New feature launch (to existing users)
User appears stuck (smart triggering based on inactivity)
User explicitly requests help

When NOT to Show Onboarding

Avoid showing when:

User is mid-task or focused
Shown in every session (becomes annoying)
Before allowing free exploration
Tour exceeds 7 steps (too long)
User already dismissed or completed

Auto-dismiss timing:

Simple tooltips: 5-7 seconds
Feature announcements: 10-15 seconds or manual dismiss
Tours: User-controlled, no auto-dismiss
Persistent hints: Until user acknowledges

Reference references/timing-strategies.md for detailed guidelines.

Progressive Disclosure Patterns

Show only what's needed, when it's needed:

Techniques:

Accordion Help: Collapsed by default, expand for details
"Learn More" Links: Deep dive content optional
Advanced Settings: Hidden behind "Show advanced" toggle
Gradual Feature Introduction: Unlock features as user progresses
Contextual Hints: Show based on user actions

Reference references/progressive-disclosure.md for implementation patterns.

Accessibility Requirements

Keyboard Navigation

Essential keyboard support:

Tab through tour steps and controls
ESC to dismiss tours and tooltips
Arrow keys for Previous/Next navigation
Enter/Space to activate buttons
Focus visible indicators

Screen Reader Support

ARIA patterns for announcements:

Announce step number and total (Step 2 of 5)
Read tooltip and help content
Describe highlighted UI elements
Announce progress completion
Alert on errors or blockers

Reduced Motion

Respect prefers-reduced-motion:

Disable pulsing animations
Use instant transitions instead of animations
Remove parallax and complex effects
Maintain functionality without motion

To validate accessibility:

node scripts/validate_accessibility.js

Reference references/accessibility-patterns.md for complete implementation.

Library Recommendations

Primary: react-joyride (Feature-Rich, Accessible)

Library: /gilbarbara/react-joyride Trust Score: 9.6/10 Code Snippets: 29+

Best for comprehensive product tours:

WAI-ARIA compliant out of the box
Full keyboard navigation support
Highly customizable styling
Programmatic control
Localization support
Active maintenance

npm install react-joyride

See examples/joyride-tour.tsx for complete setup.

Alternative: driver.js (Lightweight, Modern)

Best for minimal bundle size:

Vanilla JavaScript (framework agnostic)
~5KB gzipped
Modern API design
No dependencies

npm install driver.js

Alternative: intro.js (Classic, Proven)

Best for traditional tours:

Battle-tested library
Wide browser support
JSON-based tour configuration
Extensive plugin ecosystem

npm install intro.js

Reference references/library-comparison.md for detailed analysis and selection criteria.

Design Token Integration

All onboarding components use the design-tokens skill for consistent theming:

Token categories used:

Colors: Tour spotlight, overlay, tooltip backgrounds, hotspot colors
Spacing: Tour padding, tooltip spacing, arrow size
Typography: Title sizes, body text, help content
Borders: Border radius for modals and tooltips
Shadows: Elevation for tour spotlights and tooltips
Motion: Transition durations, pulse animations

Supports light, dark, high-contrast, and custom brand themes. Reference the design-tokens skill for complete theming documentation.

Measuring Success

Key Metrics

Track these indicators:

Tour completion rate (target: >60%)
Time to first value (faster = better)
Feature adoption rate post-tour
Support ticket reduction
User activation rate (completed key actions)
Drop-off points in tours

Optimization Strategies

Iterate based on data:

A/B test tour length (shorter often better)
Test different messaging and copy
Measure drop-off at each step
Simplify steps with high abandonment
Add skip options for returning users
Personalize based on user type

To analyze onboarding metrics:

python scripts/analyze_onboarding_metrics.py

Reference references/measuring-success.md for complete analytics implementation.

Anti-Patterns to Avoid

Common mistakes that harm user experience:

❌ Forced Tours: Requiring tour completion before product use ❌ Too Long: Tours exceeding 7 steps lose user attention ❌ Every Session: Showing same tour repeatedly ❌ No Skip Option: Preventing users from exploring independently ❌ Wall of Text: Using lengthy explanations instead of visuals ❌ Blocking Everything: Preventing interaction during tours ❌ Premature Guidance: Showing help before users explore ❌ Poor Timing: Interrupting focused work ❌ No Context: Generic tips without specific relevance

Implementation Workflow

Step 1: Map User Journey

Identify key moments:

First login and account creation
Core value delivery (aha moment)
Feature discovery points
Potential confusion or abandonment
Achievement and progress milestones

Step 2: Choose Guidance Mechanisms

Match mechanisms to moments:

First login → Product tour (3-5 steps max)
Core features → Interactive tutorial
Setup requirements → Checklist
New features → Spotlight + tooltip
Ongoing help → Help panel

Step 3: Implement with Progressive Enhancement

Build incrementally:

Start with essential guidance only
Add contextual help based on user behavior
Implement analytics to measure effectiveness
Iterate based on data
A/B test variations

Step 4: Test Accessibility

Verify compliance:

Keyboard navigation works completely
Screen reader announces properly
Reduced motion preference honored
Focus management correct
ARIA labels descriptive

Run validation:

node scripts/validate_accessibility.js

Step 5: Monitor and Optimize

Track and improve:

Monitor completion rates
Identify drop-off points
Gather user feedback
A/B test improvements
Update based on findings

Working Examples

Start with the example matching the use case:

first-time-tour.tsx           # Product walkthrough with react-joyride
feature-spotlight.tsx         # New feature announcement
guided-tutorial.tsx           # Interactive task completion
setup-checklist.tsx           # Multi-step onboarding progress
contextual-help.tsx           # Tooltips and progressive hints
help-panel.tsx                # Sidebar help with search
celebration-animation.tsx     # Completion feedback

Resources

Scripts (Token-Free Execution)

scripts/generate_tour_config.js - Generate tour configurations from user flows
scripts/analyze_onboarding_metrics.py - Analyze completion and drop-off rates
scripts/validate_accessibility.js - Test keyboard and screen reader support

References (Detailed Documentation)

references/product-tours.md - Tour patterns, step design, navigation
references/interactive-tutorials.md - Guided tasks and sandbox modes
references/tooltips-hints.md - Contextual help and progressive hints
references/checklists.md - Progress tracking and gamification
references/help-systems.md - Help panels, videos, and documentation
references/progressive-disclosure.md - Advanced patterns and feature unlocking
references/timing-strategies.md - When and how to trigger guidance
references/accessibility-patterns.md - WCAG compliance and ARIA patterns
references/measuring-success.md - Analytics and optimization
references/library-comparison.md - Detailed library evaluation
references/selection-framework.md - Decision trees for choosing mechanisms

Examples (Implementation Code)

Complete working implementations for all guidance types
Integration examples with common frameworks
Accessibility-compliant patterns
Design token integration examples

Assets (Templates and Configs)

assets/celebration-animations/ - Success animations and confetti
assets/tour-templates.json - Reusable tour configurations
assets/message-templates.json - Tooltip and hint copy templates
assets/timing-config.json - Recommended timing values

Cross-Skill Integration

This skill works with other component skills:

Forms: Guided form completion, validation hints
Dashboards: Feature tours, widget explanations
Tables: Data grid tutorials, feature discovery
AI Chat: Chat interface walkthroughs
Navigation: Menu and navigation guidance
Feedback: Success celebrations, progress notifications
Design Tokens: All visual styling and theming

Key Principles

Respect User Time: Keep tours under 7 steps, make skippable
Show, Don't Tell: Use visuals and interactions over text
Progressive Enhancement: Start simple, add guidance as needed
Context is King: Show help when and where it's relevant
Measure Everything: Track completion, iterate based on data
Accessibility First: Keyboard, screen reader, reduced motion support
Celebrate Progress: Acknowledge completion and achievements
Allow Exploration: Don't force tours, enable discovery

Next Steps

Map the user journey and identify key moments
Choose appropriate guidance mechanisms for each moment
Install react-joyride or preferred library
Start with one critical flow (usually first-time experience)
Implement with accessibility built-in
Add analytics tracking
Test with real users
Iterate based on metrics and feedback