/guiding-users

name: guiding-users
description: Implements onboarding and help systems including product tours, interactive tutorials, tooltips, checklists, help panels, and progressive disclosure patterns. Use when building first-time experiences, feature discovery, guided walkthroughs, contextual help, setup flows, or user activation features. Provides timing strategies, accessibility patterns (keyboard, screen readers, reduced motion), and metrics for measuring onboarding success.

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 animati