guiding-users

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

本Skill为用户入门流程和上下文帮助提供系统化模式，涵盖从首次产品导览到持续功能发现的全场景。它覆盖了完整的用户引导机制，确保实现最优的用户激活、功能采用率和自助服务支持。

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

在以下场景中启用本Skill：

构建首次用户体验或产品导览
实现功能发现与公告
创建交互式教程或引导式任务
添加工具提示、提示信息或上下文帮助
设计设置流程或完成清单
构建帮助面板或文档系统
实现渐进式披露模式
衡量入门流程有效性与用户激活情况
确保入门流程的无障碍访问性

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.

根据用户状态和内容类型选择合适的引导机制：

首次使用用户          → 产品导览（分步式）
新功能发布           → 功能聚焦提示（工具提示+动画）
复杂工作流           → 交互式教程（引导式任务）
账户设置            → 清单（进度追踪）
需要上下文帮助时   → 工具提示/提示系统
持续支持需求          → 帮助面板（侧边栏/可搜索）
功能解锁            → 渐进式披露

详细选择标准请参考

references/selection-framework.md

。

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.

引导用户了解关键功能的分步式漫游：

带模态覆盖层的连续聚焦高亮
进度指示器（第2步/共5步）
跳过、上一步和下一步控制
关闭与恢复功能
上下文敏感触发

实现方式：

bash

npm install react-joyride

完整实现示例请查看

examples/first-time-tour.tsx

。模式与最佳实践请参考

references/product-tours.md

。

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.

向现有用户推送新功能公告：

脉动热点动画
带箭头的上下文工具提示
"已了解"确认按钮
首次查看后自动关闭
非阻塞式覆盖层

实现示例请查看

examples/feature-spotlight.tsx

。模式请参考

references/tooltips-hints.md

。

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.

带验证的引导式任务完成流程：

"完成以下任务开始使用"
复选框完成追踪
完成时的庆祝动画
含示例数据的沙箱模式
撤销与重置功能

实现示例请查看

examples/guided-tutorial.tsx

。模式请参考

references/interactive-tutorials.md

。

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.

追踪多步骤入门流程进度：

可视化进度指示器（3/4已完成）
指向各任务的直接链接
资料完成百分比
成就徽章与游戏化设计
完成前持续显示

实现示例请查看

examples/setup-checklist.tsx

。模式请参考

references/checklists.md

。

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.

用户需要时提供即时帮助：

悬停或点击触发的工具提示
渐进式提示等级（1、2、3级）
"需要帮助？"触发按钮
上下文感知建议
键盘可访问

实现示例请查看

examples/contextual-help.tsx

。完整模式请参考

references/tooltips-hints.md

。

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.

综合帮助系统：

侧边栏或抽屉式界面
基于当前页面的上下文帮助
帮助文章与文档搜索
视频教程与演示
联系支持集成
可折叠与调整大小

实现示例请查看

examples/help-panel.tsx

。模式请参考

references/help-systems.md

。

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.

避免在以下场景展示：

用户正在执行任务或处于专注状态
每次会话都展示（会引起反感）
未允许用户自由探索前
导览超过7步（过长）
用户已关闭或完成过该引导

自动关闭时机：

简单工具提示：5-7秒
功能公告：10-15秒或手动关闭
导览：由用户控制，不自动关闭
持久提示：直到用户确认

详细指南请参考

references/timing-strategies.md

。

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.

仅在需要时展示必要内容：

实现技巧：

折叠式帮助：默认折叠，展开查看详情
"了解更多"链接：可选的深度内容
高级设置：隐藏在"显示高级选项"开关后
逐步功能介绍：随用户使用进度解锁功能
上下文提示：根据用户操作展示

实现模式请参考

references/progressive-disclosure.md

。

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

必备的键盘支持：

通过Tab键切换导览步骤和控件
ESC键关闭导览和工具提示
方向键控制上一步/下一步
Enter/Space键激活按钮
可见的焦点指示器

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

用于公告的ARIA模式：

播报步骤编号和总步数（第2步/共5步）
读取工具提示和帮助内容
描述高亮的UI元素
播报进度完成情况
错误或阻塞时发出警报

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.

尊重

prefers-reduced-motion

设置：

禁用脉动动画
使用即时过渡替代动画
移除视差和复杂效果
无动画时仍保持功能可用

验证无障碍访问性：

bash

node scripts/validate_accessibility.js

完整实现请参考

references/accessibility-patterns.md

。

Library Recommendations

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.

所有入门组件均使用design-tokens skill实现一致主题：

使用的令牌类别：

颜色：导览高亮、覆盖层、工具提示背景、热点颜色
间距：导览内边距、工具提示间距、箭头大小
排版：标题尺寸、正文文本、帮助内容
边框：模态框和工具提示的圆角
阴影：导览高亮和工具提示的层级阴影
动效：过渡时长、脉动动画

支持浅色、深色、高对比度和自定义品牌主题。完整主题文档请参考design-tokens skill。

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

追踪以下指标：

导览完成率（目标：>60%）
首次价值获取时间（越快越好）
导览后的功能采用率
支持工单减少量
用户激活率（完成关键操作）
导览中的流失节点

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:

bash

python scripts/analyze_onboarding_metrics.py

Reference

references/measuring-success.md

for complete analytics implementation.

基于数据迭代改进：

A/B测试导览长度（通常越短越好）
测试不同的文案和信息
衡量每一步的流失率
简化高弃用率的步骤
为回访用户添加跳过选项
根据用户类型个性化定制

分析入门流程指标：

bash

python scripts/analyze_onboarding_metrics.py

完整分析实现请参考

references/measuring-success.md

。

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

损害用户体验的常见错误：

❌ 强制导览：要求完成导览才能使用产品 ❌ 过长导览：超过7步的导览会分散用户注意力 ❌ 重复展示：每次会话都显示相同导览 ❌ 无跳过选项：阻止用户自主探索 ❌ 文字堆砌：用冗长说明代替视觉展示 ❌ 完全阻塞：导览期间禁止交互 ❌ 提前引导：用户探索前就展示帮助 ❌ 时机不当：打断用户的专注工作 ❌ 缺乏上下文：与场景无关的通用提示

Implementation Workflow

实现工作流

Step 1: Map User Journey

步骤1：映射用户旅程

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

步骤2：选择引导机制

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

为各节点匹配对应机制：

首次登录 → 产品导览（最多3-5步）
核心功能 → 交互式教程
设置要求 → 清单
新功能 → 聚焦提示+工具提示
持续帮助 → 帮助面板

Step 3: Implement with Progressive Enhancement

步骤3：渐进增强实现

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

增量式构建：

仅从核心引导开始
根据用户行为添加上下文帮助
实现分析功能衡量有效性
基于数据迭代
A/B测试变体

Step 4: Test Accessibility

步骤4：无障碍访问测试

Verify compliance:

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

Run validation:

bash

node scripts/validate_accessibility.js

验证合规性：

键盘导航完全可用
屏幕阅读器播报正确
尊重减少动效偏好
焦点管理正确
ARIA标签描述清晰

运行验证：

bash

node scripts/validate_accessibility.js

Step 5: Monitor and Optimize

步骤5：监控与优化

Track and improve:

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

追踪并改进：

监控完成率
识别流失节点
收集用户反馈
A/B测试改进方案
根据发现更新内容

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

根据使用场景选择对应示例：

first-time-tour.tsx           # 基于react-joyride的产品导览
feature-spotlight.tsx         # 新功能公告示例
guided-tutorial.tsx           # 交互式任务完成示例
setup-checklist.tsx           # 多步骤入门进度追踪示例
contextual-help.tsx           # 工具提示和渐进式提示示例
help-panel.tsx                # 带搜索的侧边栏帮助示例
celebration-animation.tsx     # 完成反馈动画示例

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

```
scripts/generate_tour_config.js
```
- 从用户流生成导览配置
```
scripts/analyze_onboarding_metrics.py
```
- 分析完成率和流失率
```
scripts/validate_accessibility.js
```
- 测试键盘和屏幕阅读器支持

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

```
references/product-tours.md
```
- 导览模式、步骤设计、导航
```
references/interactive-tutorials.md
```
- 引导式任务和沙箱模式
```
references/tooltips-hints.md
```
- 上下文帮助和渐进式提示
```
references/checklists.md
```
- 进度追踪和游戏化
```
references/help-systems.md
```
- 帮助面板、视频和文档
```
references/progressive-disclosure.md
```
- 高级模式和功能解锁
```
references/timing-strategies.md
```
- 引导触发的时机与方式
```
references/accessibility-patterns.md
```
- WCAG合规和ARIA模式
```
references/measuring-success.md
```
- 分析与优化
```
references/library-comparison.md
```
- 库的详细评估
```
references/selection-framework.md
```
- 机制选择决策树

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

```
assets/celebration-animations/
```
- 成功动画和彩屑效果
```
assets/tour-templates.json
```
- 可复用导览配置
```
assets/message-templates.json
```
- 工具提示和提示文案模板
```
assets/timing-config.json
```
- 推荐时机配置值

Cross-Skill Integration

跨Skill集成

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

本Skill可与其他组件Skill配合使用：

Forms：引导式表单填写、验证提示
Dashboards：功能导览、部件说明
Tables：数据网格教程、功能发现
AI Chat：聊天界面漫游
Navigation：菜单和导航引导
Feedback：成功庆祝、进度通知
Design Tokens：所有视觉样式和主题

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

尊重用户时间：导览控制在7步以内，支持跳过
直观展示：用视觉和交互替代文字说明
渐进增强：从简单开始，按需添加引导
上下文优先：在合适的时间和地点展示帮助
全面衡量：追踪完成率，基于数据迭代
无障碍优先：支持键盘、屏幕阅读器、减少动画
庆祝进度：认可用户的完成和成就
允许探索：不强制导览，支持自主发现

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

映射用户旅程并识别关键节点
为每个节点选择合适的引导机制
安装react-joyride或首选库
从一个关键流程开始（通常是首次使用体验）
内置无障碍访问功能实现
添加分析追踪
真实用户测试
根据指标和反馈迭代改进

guiding-users

Original

Translation

Guiding Users Through Onboarding and Help Systems

引导用户完成入门流程与帮助系统搭建

Purpose

用途

When to Use

适用场景

Quick Decision Framework

快速决策框架

Core Guidance Mechanisms

核心引导机制

Product Tours

产品导览

Feature Spotlights

功能聚焦提示

Interactive Tutorials

交互式教程

Setup Checklists

设置清单

Contextual Tooltips and Hints

上下文工具提示与提示信息

Help Panels

帮助面板

Timing and Triggering Strategies

触发时机策略

When to Show Onboarding

何时展示入门引导

When NOT to Show Onboarding

何时避免展示入门引导

Progressive Disclosure Patterns

渐进式披露模式

Accessibility Requirements

无障碍访问要求

Keyboard Navigation

键盘导航

Screen Reader Support

屏幕阅读器支持

Reduced Motion

减少动画

Library Recommendations

推荐库

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

首选：react-joyride（功能丰富、无障碍支持完善）

Alternative: driver.js (Lightweight, Modern)

替代方案：driver.js（轻量、现代）

Alternative: intro.js (Classic, Proven)

替代方案：intro.js（经典、成熟）

Design Token Integration

设计令牌集成

Measuring Success

成功衡量

Key Metrics

关键指标

Optimization Strategies

优化策略

Anti-Patterns to Avoid

需避免的反模式

Implementation Workflow

实现工作流

Step 1: Map User Journey

步骤1：映射用户旅程

Step 2: Choose Guidance Mechanisms

步骤2：选择引导机制

Step 3: Implement with Progressive Enhancement

步骤3：渐进增强实现

Step 4: Test Accessibility

步骤4：无障碍访问测试

Step 5: Monitor and Optimize

步骤5：监控与优化

Working Examples

示例代码

Resources

资源

Scripts (Token-Free Execution)

脚本（无需令牌即可执行）

References (Detailed Documentation)

参考文档（详细说明）

Examples (Implementation Code)