guiding-users

引导用户完成入门并使用帮助系统

目的

此技能提供系统化的模式，帮助用户完成入门并提供情境化帮助，涵盖从首次产品导览到持续发现功能的全过程。它涵盖各类用户引导机制，确保用户得到最佳激活、采用功能并获得自助支持。

适用场景

在以下情况下启用此技能：

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

快速决策框架

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

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

详细的选择标准请参阅 references/selection-framework.md。

核心引导机制

产品导览

逐步引导用户了解关键功能：

• 通过模态叠层逐步聚焦界面区域
• 进度指示器（第 2 步，共 5 步）
• 跳过、上一步和下一步控件
• 支持关闭后恢复
• 根据情境触发

实现：

npm install react-joyride

完整实现请参阅 examples/first-time-tour.tsx。 相关模式和最佳实践请参阅 references/product-tours.md。

功能聚焦提示

向现有用户介绍新功能：

• 脉冲式热点动画
• 带箭头的情境化工具提示
• “知道了”确认操作
• 首次查看后自动关闭
• 非阻塞式叠层

实现请参阅 examples/feature-spotlight.tsx。 相关模式请参阅 references/tooltips-hints.md。

交互式教程

通过验证引导用户完成任务：

• “完成这些任务即可开始”
• 通过复选框跟踪完成情况
• 完成时显示庆祝动画
• 使用示例数据的沙盒模式
• 支持撤销和重置

实现请参阅 examples/guided-tutorial.tsx。 相关模式请参阅 references/interactive-tutorials.md。

设置清单

跟踪多步骤入门流程的进度：

• 可视化进度指示器（已完成 3/4 项）
• 每项任务的直接链接
• 个人资料完成百分比
• 成就徽章和游戏化元素
• 完成前持续显示

实现请参阅 examples/setup-checklist.tsx。 相关模式请参阅 references/checklists.md。

情境化工具提示和提示信息

在用户需要时及时提供帮助：

• 通过悬停或点击触发的工具提示
• 渐进式提示级别（1、2、3）
• “需要帮助？”辅助触发项
• 感知情境的建议
• 支持键盘操作

实现请参阅 examples/contextual-help.tsx。 完整模式请参阅 references/tooltips-hints.md。

帮助面板

全面的帮助系统：

• 侧边栏或抽屉式界面
• 根据当前页面提供情境化帮助
• 搜索帮助文章和文档
• 视频教程和演示
• 集成联系支持功能
• 可折叠和调整大小

实现请参阅 examples/help-panel.tsx。 相关模式请参阅 references/help-systems.md。

时机与触发策略

何时显示入门引导

适当的触发时机：

• 首次登录（始终显示）
• 注册后立即显示
• 新功能上线时（面向现有用户）
• 用户似乎遇到困难时（根据非活跃情况智能触发）
• 用户主动请求帮助时

何时不应显示入门引导

以下情况应避免显示：

• 用户正在执行任务或专注于当前操作时
• 每次会话都显示（会令人厌烦）
• 尚未允许用户自由探索时
• 导览超过 7 步（时间过长）
• 用户已经关闭或完成导览时

自动关闭时机：

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

详细指南请参阅 references/timing-strategies.md。

渐进式披露模式

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

技巧：

1. 折叠式帮助：默认折叠，展开后查看详情
2. “了解更多”链接：可选查看深入内容
3. 高级设置：隐藏在“显示高级设置”切换项后
4. 渐进式功能介绍：随着用户不断熟悉，逐步解锁功能
5. 情境提示：根据用户操作显示

请参阅 references/progressive-disclosure.md，了解实现模式。

无障碍要求

键盘导航

必备的键盘支持：

• 使用 Tab 键浏览引导步骤和控件
• 按 ESC 关闭引导和工具提示
• 使用方向键进行“上一步”/“下一步”导航
• 按 Enter/Space 激活按钮
• 显示清晰的焦点指示器

屏幕阅读器支持

用于播报的 ARIA 模式：

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

减少动态效果

遵循 prefers-reduced-motion：

• 禁用脉冲动画
• 使用即时切换而非动画
• 移除视差效果和复杂特效
• 确保无动态效果时功能仍然可用

验证无障碍支持：

node scripts/validate_accessibility.js

请参阅 references/accessibility-patterns.md，了解完整实现。

库推荐

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

库： /gilbarbara/react-joyride 信任评分： 9.6/10 代码片段： 29+

适用于全面的产品引导：

• 开箱即符合 WAI-ARIA 标准
• 完整支持键盘导航
• 样式高度可定制
• 支持编程式控制
• 支持本地化
• 积极维护中

npm install react-joyride

请参阅 examples/joyride-tour.tsx，了解完整设置。

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

适用于需要最小化打包体积的场景：

• 原生 JavaScript（与框架无关）
• 压缩后约 5KB
• 现代 API 设计
• 无依赖

npm install driver.js

替代方案：intro.js（经典、可靠）

适用于传统引导：

• 久经考验的库
• 广泛支持各类浏览器
• 基于 JSON 的引导配置
• 丰富的插件生态

npm install intro.js

请参阅 references/library-comparison.md，了解详细分析和选择标准。

设计令牌集成

所有引导组件均使用 design-tokens 技能，以确保主题一致：

使用的令牌类别：

• 颜色：引导聚光区、遮罩层、工具提示背景、热点颜色
• 间距：引导内边距、工具提示间距、箭头大小
• 字体排版：标题大小、正文文本、帮助内容
• 边框：模态框和工具提示的圆角
• 阴影：引导聚光区和工具提示的层级效果
• 动态效果：过渡时长、脉冲动画

支持浅色、深色、高对比度和自定义品牌主题。 请参阅 design-tokens 技能，了解完整的主题文档。

衡量成功

关键指标

跟踪以下指标：

• 引导完成率（目标：>60%）
• 首次获得价值所需时间（越短越好）
• 引导后的功能采用率
• 支持工单减少量
• 用户激活率（完成关键操作的用户比例）
• 引导流程中的流失节点

优化策略

根据数据进行迭代：

• 对引导时长进行 A/B 测试（通常越短越好）
• 测试不同的消息和文案
• 衡量每个步骤的流失情况
• 简化弃用率较高的步骤
• 为回访用户添加跳过选项
• 根据用户类型进行个性化设置

分析引导指标：

python scripts/analyze_onboarding_metrics.py

请参阅 references/measuring-success.md，了解完整的分析实现。

应避免的反模式

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

❌ 强制引导：要求用户完成引导后才能使用产品 ❌ 内容过长：超过 7 个步骤的引导会失去用户的注意力 ❌ 每次会话都显示：反复显示相同的引导 ❌ 没有跳过选项：阻止用户自行探索 ❌ 大段文字：使用冗长的说明，而不是视觉内容 ❌ 阻止所有操作：引导期间禁止用户进行交互 ❌ 过早提供指导：用户尚未探索就显示帮助 ❌ 时机不佳：打断专注的工作 ❌ 缺乏上下文：提供与具体情况无关的通用提示

实施工作流

步骤 1：梳理用户旅程

确定关键时刻：

1. 首次登录和创建账户
2. 实现核心价值（顿悟时刻）
3. 发现功能的节点
4. 可能造成困惑或导致用户放弃的节点
5. 成就和进度里程碑

步骤 2：选择指导机制

根据不同节点匹配相应机制：

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

步骤 3：渐进式增强实施

逐步构建：

1. 从必要的指导内容开始
2. 根据用户行为添加情境化帮助
3. 实施分析以衡量效果
4. 根据数据迭代
5. 对不同方案进行 A/B 测试

步骤 4：测试无障碍功能

验证是否符合要求：

• 键盘导航功能完整
• 屏幕阅读器能够正确播报
• 遵循减少动态效果偏好
• 焦点管理正确
• ARIA 标签描述清晰

运行验证：

node scripts/validate_accessibility.js

步骤 5：监控并优化

跟踪并改进：

• 监控完成率
• 找出流失节点
• 收集用户反馈
• 对改进方案进行 A/B 测试
• 根据调查结果更新

可运行示例

从与使用场景匹配的示例开始：

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

资源

脚本（无 Token 执行）

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

参考资料（详细文档）

• 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 - 选择机制的决策树

示例（实现代码）

• 涵盖所有指导类型的完整可运行实现
• 与常见框架集成的示例
• 符合无障碍要求的模式
• 设计 Token 集成示例

资源文件（模板和配置）

• assets/celebration-animations/ - 成功动画和纸屑效果
• assets/tour-templates.json - 可复用的引导配置
• assets/message-templates.json - 工具提示和提示文案模板
• assets/timing-config.json - 建议的时间值

跨技能集成

此技能可与其他组件技能配合使用：

• 表单：引导式表单填写、验证提示
• 仪表板：功能引导、组件说明
• 表格：数据网格教程、功能探索
• AI 聊天：聊天界面引导
• 导航：菜单和导航指导
• 反馈：成功庆祝、进度通知
• 设计 Token：所有视觉样式和主题

核心原则

1. 尊重用户时间：引导步骤控制在 7 步以内，并允许跳过
2. 展示，而非讲述：优先使用视觉内容和交互，而非文字
3. 渐进式增强：从简单开始，按需添加引导
4. 情境至上：在相关的时间和位置提供帮助
5. 全面衡量：跟踪完成情况，并根据数据迭代
6. 无障碍优先：支持键盘、屏幕阅读器和减少动态效果
7. 庆祝进步：认可用户的完成情况和成就
8. 允许探索：不强制用户参加引导，让用户自主发现

后续步骤

1. 梳理用户旅程并确定关键时刻
2. 为每个时刻选择合适的引导方式
3. 安装 react-joyride 或首选库
4. 从一个关键流程开始（通常是首次使用体验）
5. 实现内置无障碍支持
6. 添加分析跟踪
7. 邀请真实用户测试
8. 根据指标和反馈迭代