guiding-users

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:

1. Accordion Help: Collapsed by default, expand for details
2. "Learn More" Links: Deep dive content optional
3. Advanced Settings: Hidden behind "Show advanced" toggle
4. Gradual Feature Introduction: Unlock features as user progresses
5. 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_metr