guiding-users
This skill provides systematic patterns and components for implementing user onboarding and guidance mechanisms, including product tours, feature spotlights, interactive tutorials, tooltips, checklists, and help panels. Use it when building first-time user experiences, feature discovery systems, guided walkthroughs, contextual help systems, setup flows, or measuring onboarding effectiveness, with built-in support for accessibility requirements and timing strategies.
git clone --depth 1 https://github.com/ancoleman/ai-design-components /tmp/guiding-users && cp -r /tmp/guiding-users/skills/guiding-users ~/.claude/skills/guiding-usersSKILL.md
# 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:** ```bash 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: ```bash 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
Manage Linux systems covering systemd services, process management, filesystems, networking, performance tuning, and troubleshooting. Use when deploying applications, optimizing server performance, diagnosing production issues, or managing users and security on Linux servers.
Data pipelines, feature stores, and embedding generation for AI/ML systems. Use when building RAG pipelines, ML feature serving, or data transformations. Covers feature stores (Feast, Tecton), embedding pipelines, chunking strategies, orchestration (Dagster, Prefect, Airflow), dbt transformations, data versioning (LakeFS), and experiment tracking (MLflow, W&B).
Strategic guidance for designing modern data platforms, covering storage paradigms (data lake, warehouse, lakehouse), modeling approaches (dimensional, normalized, data vault, wide tables), data mesh principles, and medallion architecture patterns. Use when architecting data platforms, choosing between centralized vs decentralized patterns, selecting table formats (Iceberg, Delta Lake), or designing data governance frameworks.
Design cloud network architectures with VPC patterns, subnet strategies, zero trust principles, and hybrid connectivity. Use when planning VPC topology, implementing multi-cloud networking, or establishing secure network segmentation for cloud workloads.
Design comprehensive security architectures using defense-in-depth, zero trust principles, threat modeling (STRIDE, PASTA), and control frameworks (NIST CSF, CIS Controls, ISO 27001). Use when designing security for new systems, auditing existing architectures, or establishing security governance programs.
Assembles component outputs from AI Design Components skills into unified, production-ready component systems with validated token integration, proper import chains, and framework-specific scaffolding. Use as the capstone skill after running theming, layout, dashboard, data-viz, or feedback skills to wire components into working React/Next.js, Python, or Rust projects.
Builds AI chat interfaces and conversational UI with streaming responses, context management, and multi-modal support. Use when creating ChatGPT-style interfaces, AI assistants, code copilots, or conversational agents. Handles streaming text, token limits, regeneration, feedback loops, tool usage visualization, and AI-specific error patterns. Provides battle-tested components from leading AI products with accessibility and performance built in.
Constructs secure, efficient CI/CD pipelines with supply chain security (SLSA), monorepo optimization, caching strategies, and parallelization patterns for GitHub Actions, GitLab CI, and Argo Workflows. Use when setting up automated testing, building, or deployment workflows.