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

1. First login and account creation
2. Core value delivery (aha moment)
3. Feature discovery points
4. Potential confusion or abandonment
5. 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:

1. Start with essential guidance only
2. Add contextual help based on user behavior
3. Implement analytics to measure effectiveness
4. Iterate based on data
5. 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

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

Next Steps

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