用户引导与帮助系统技能Skill guiding-users

---

name: 引导用户 description: 实现入职和帮助系统，包括产品导览、互动教程、工具提示、清单、帮助面板和渐进式披露模式。用于构建首次用户体验、功能发现、引导walkthrough、上下文帮助、设置流程或用户激活功能。提供定时策略、可访问性模式（键盘、屏幕阅读器、减少运动）以及衡量入职成功度的指标。

引导用户通过入职和帮助系统

目的

该技能提供系统的模式，用于入职用户和提供上下文帮助，从首次产品导览到持续功能发现。它涵盖完整的用户指导机制，确保最佳的用户激活、功能采用和自助支持。

何时使用

在以下情况下激活此技能：

• 构建首次用户体验或产品导览
• 实现功能发现和公告
• 创建互动教程或引导任务
• 添加工具提示、提示或上下文帮助
• 设计设置流程或完成清单
• 构建帮助面板或文档系统
• 实现渐进式披露模式
• 衡量入职效果和用户激活
• 确保入职可访问性

快速决策框架

基于用户状态和内容类型选择适当的指导机制：

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

参考 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 gzipped
• 现代API设计
• 无依赖

npm install driver.js

备选：intro.js（经典，验证）

最适合传统导览：

• 经过实战测试的库
• 广泛的浏览器支持
• JSON-based导览配置
• 丰富的插件生态系统

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           # 使用react-joyride的产品导览
feature-spotlight.tsx         # 新功能公告
guided-tutorial.tsx           # 互动任务完成
setup-checklist.tsx           # 多步骤入职进度
contextual-help.tsx           # 工具提示和渐进提示
help-panel.tsx                # 带搜索的侧边栏帮助
celebration-animation.tsx     # 完成反馈

资源

脚本（无需令牌执行）

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

示例（实现代码）

• 所有指导类型的完整工作实现
• 与常见框架的集成示例
• 可访问性合规模式
• 设计令牌集成示例

资产（模板和配置）

• assets/celebration-animations/ - 成功动画和彩带
• assets/tour-templates.json - 可重用导览配置
• assets/message-templates.json - 工具提示和提示文案模板
• assets/timing-config.json - 推荐定时值

跨技能集成

该技能与其他组件技能协作：

• 表单：引导表单完成、验证提示
• 仪表板：功能导览、小部件解释
• 表格：数据网格教程、功能发现
• AI聊天：聊天界面导览
• 导航：菜单和导航指导
• 反馈：成功庆祝、进度通知
• 设计令牌：所有视觉样式和主题化

关键原则

1. 尊重用户时间：保持导览在7步内，允许跳过
2. 展示，而非告诉：使用视觉和交互而非文本
3. 渐进增强：从简单开始，根据需要添加指导
4. 上下文为王：在相关时和地点显示帮助
5. 衡量一切：跟踪完成，基于数据迭代
6. 可访问性优先：支持键盘、屏幕阅读器、减少运动
7. 庆祝进步：确认完成和成就
8. 允许探索：不强制导览，启用发现

下一步

1. 映射用户旅程并识别关键时刻
2. 为每个时刻选择适当的指导机制
3. 安装react-joyride或首选库
4. 从一个关键流程开始（通常是首次体验）
5. 实现时内置可访问性
6. 添加分析跟踪
7. 用真实用户测试
8. 基于指标和反馈迭代