impeccable 的 onboard 指南：用激活时刻与空状态把新手用户带到第一个价值点

导读

本文围绕 Impeccable 设计语言技能库中的 onboard 参考文档 展开，系统讲解在 AI 辅助前端设计中如何设计新手引导（Onboarding）：从识别 "aha moment"、定义成功指标，到欢迎屏、引导式探索、空状态、上下文 Tooltip、交互式教程与落地实现模式，并给出可量化的质量验证方法。文章既完整继承原文档的实操框架，又结合本仓库中该 skill 的命令元数据与路由机制，说明 /impeccable onboard 命令如何在真实项目中触发这套方法论。读完你将获得一套"先到价值、而非先教产品"的引导设计工作流，以及可直接套用的空状态文案与 localStorage 实现片段。

在 Impeccable 的 command 体系中，onboard 是 SKILL.md 中"Refine（精修）"类别下的一条命令："Design first-run flows, empty states, activation"。它对应的 command-metadata.json 中声明了它的触发范围："Use when the user mentions onboarding, first-time users, empty states, activation, getting started, new user flows, or the aha moment"。也就是说，当你需要为某个界面设计首次运行流程、空状态或激活路径时，这套参考文档就是 AI 要遵循的作业手册。

---

一、先定义引导的边界：Onboarding 不是教学，而是"到价值"的捷径

原文档开篇就立下一个核心论断：

Onboarding's job is not to teach the product. Its job is to get people to the moment that proves the product is worth their time. （引导的工作不是教产品，而是把用户带到那个证明产品值得他们花时间的时刻。）

因此，在动手画任何欢迎页之前，应当先完成三组需求评估：

1. 识别挑战（Identify the challenge）

• 用户到底想达成什么？
• 当前体验中哪里令人困惑、不清晰？
• 用户在哪个环节卡住或流失（drop off）？
• 我们想让用户抵达的 "aha moment" 是什么？

2. 理解用户（Understand the users）

• 经验水平：新手、熟练用户，还是混合人群？
• 动机：是兴奋地探索，还是被工作要求逼着用？
• 时间投入：5 分钟还是 30 分钟？
• 已有认知：是从竞品迁移过来，还是对这类产品完全陌生？

3. 定义成功（Define success）

• 用户成功所需的最低学习量是多少？
• 我们希望他们做的关键动作是什么？（建第一个项目？发起第一次邀请？）
• 如何判断引导生效了？（完成率？到价值时间 time-to-value？）

CRITICAL：引导应当让用户尽可能快地到达价值，而不是尽可能多地教会一切。这句话是整份文档的总纲——信息密度过高、仪式感过重，都会直接毁掉激活率。

---

二、引导设计的五条核心原则

原文档给出了五条可执行的原则，任何引导方案都应逐条自检：

原则	要点
Show, Don't Tell（展示而非说教）	用可运行的示例演示，而非纯文字描述；引导中提供真实功能，而不是一个与产品脱节的"教学模式"；采用渐进式披露（progressive disclosure），一次只教一件事
Make It Optional（尽可能可选）	让熟练用户可以跳过；绝不阻塞产品访问；始终提供 "Skip" / "I'll explore on my own" 选项
Time to Value（到价值时间）	让用户 ASAP 抵达 aha moment；最重要的概念前置；只教"带来 80% 价值的 20% 内容"；高级功能留给用户按需发现
Context Over Ceremony（场景优先于仪式）	在用户真正需要某个功能时再教，而非一开始全盘托出；空状态就是引导机会；Tooltip 与提示出现在使用现场
Respect User Intelligence（尊重用户智商）	不说教、不把用户当小孩；简洁清晰；默认用户能理解标准的界面模式

把这五条对应到仓库中的实战语境：Impeccable 在 SKILL.md 中把设计分为 Persuade（说服）、Operate（操作）、Read（阅读）、Experience（体验）四种模式。onboard 面向的多是 Operate 类产品——用户来此是为了完成任务，任何阻碍其快速进入任务状态的引导都是失败的设计。这也解释了为什么"Make It Optional"和"Time to Value"在文档中被反复强调。

---

三、设计引导体验的四种场景

1. 首次产品引导（Initial Product Onboarding）

适用于用户第一次进入产品，一般由四段组成：

• Welcome Screen（欢迎屏）：清晰的价值主张（这个产品是什么）；用户将学到/达成什么；诚实的时间预估（不夸大投入）；为老手提供跳过选项。
• Account Setup（账户设置）：只收集最必要的信息，其余留到之后补；解释每个字段为什么要问；能给出智能默认值就给；适当使用社交登录。
• Core Concept Introduction（核心概念介绍）：只引入 1–3 个核心概念（绝不是全部）；用简单语言和示例；尽量可交互（动手做，而非只阅读）；给出进度指示（如"第 1 步，共 3 步"）。
• First Success（第一次成功）：引导用户完成一件真实的事；提供预填充示例或模板；庆祝完成（但别过度）；给出清晰的下一步。

2. 功能发现与采纳（Feature Discovery & Adoption）

这是引导真正持续发力的地方，文档细分了四种子模式：

Empty States（空状态）——与其展示一片空白，不如展示：

• 这里将会出现什么（描述 + 截图/插图）；
• 它为什么有价值；
• 明确的 CTA 去创建第一项内容；
• 示例或模板选项。

原文档给出的参考示例：

No projects yet
Projects help you organize your work and collaborate with your team.
[Create your first project] or [Start from template]

Contextual Tooltips（上下文提示）：在用户第一次看到某功能的相关时刻出现；直接指向相关 UI 元素；给出简短解释 + 收益；可关闭（带 "Don't show again" 选项）；可选附带 "Learn more" 链接。

Feature Announcements（功能公告）：新功能发布时高亮它；说明新增了什么、为什么重要；让用户能立即试用；可关闭。

Progressive Onboarding（渐进式引导）：在用户遇到功能时才教它；在新/未使用的功能上加徽标或指示器；逐步解锁复杂度（不要一上来展示所有选项）。

3. 引导式导览与逐步走查（Guided Tours & Walkthroughs）

适用时机：功能繁多的复杂界面；既有产品发生重大变化；需要领域知识的行业专用工具。

设计要点：

• Spotlight 聚焦特定 UI 元素（页面其余部分压暗）；
• 每段导览控制在 3–7 步以内；
• 允许用户自由点击导览步骤；
• 包含 "Skip tour" 选项；
• 可重播（放在帮助菜单中）。

最佳实践：交互优先于被动观看（让用户点击真实的按钮）；聚焦工作流而非功能点（说"创建一个项目"，而不是"这是项目按钮"）；提供示例数据，让动作真正能执行。

4. 交互式教程（Interactive Tutorials）

适用时机：用户需要动手练习；概念复杂或陌生；高风险的场景（先在安全环境里练习更合适）。

设计要点：提供带示例数据的沙盒环境；给出清晰目标（如"创建一张按地区展示销售额的图表"）；分步引导；提供校验（确认用户做对了）；设计"毕业时刻"（you're ready!）。

5. 文档与帮助（Documentation & Help）

产品内帮助要形成体系：遍布界面的上下文帮助链接、快捷键速查、可搜索的帮助中心、复杂工作流的视频教程。常见帮助模式包括：复杂功能旁的 ? 图标、Tooltip 中的 "Learn more" 链接、快捷键提示（如搜索框上显示 ⌘K）。

---

四、空状态设计专题：每一种空白都是引导触点

原文档把空状态设计单独成节，足以说明它的分量——在 Impeccable 的引导哲学里，空状态不是"什么都没有"，而是第一次激活的入口。每一个空状态都需要同时具备五要素：

要素	示例文案
What Will Be Here（这里将出现什么）	"Your recent projects will appear here"
Why It Matters（为什么重要）	"Projects help you organize your work and collaborate with your team"
How to Get Started（如何开始）	[Create project] 或 [Import from template]
Visual Interest（视觉吸引力）	插图或图标（不要只是空白页上的文字）
Contextual Help（上下文帮助）	"Need help getting started? [Watch 2-min tutorial]"

此外，空状态需要区分五种类型，因为它们需要的引导强度完全不同：

• First use（首次使用）：用户从未用过此功能 → 强调价值、提供模板；
• User cleared（用户主动清空）：用户故意删掉了所有内容 → 轻触达、易重建（用户已经懂，不需要再教一遍）；
• No results（无结果）：搜索或过滤无返回 → 建议更换查询词、清除过滤条件；
• No permissions（无权限）：无法访问 → 解释原因与如何获得权限；
• Error state（错误状态）：加载失败 → 说明发生了什么、提供重试。

---

五、实现模式：从设计到落地的技术选型

原文档明确给出了常用技术栈与存储模式，这部分是引导设计从"策略"走向"代码"的关键桥梁：

技术选型对照：

• Tooltip 库：Tippy.js、Popper.js；
• 导览库：Intro.js、Shepherd.js、React Joyride；
• 弹窗模式：焦点陷阱（focus trap）、遮罩层（backdrop）、ESC 关闭；
• 进度追踪：用 localStorage 记录 "seen" 状态；
• 数据分析：追踪完成率、流失点（drop-off points）。

存储模式（防重复打扰的关键实现）：

// Track which onboarding steps user has seen
localStorage.setItem('onboarding-completed', 'true');
localStorage.setItem('feature-tooltip-seen-reports', 'true');

IMPORTANT：不要向同一个用户展示两次相同的引导（那很烦人）。务必记录完成状态并尊重用户的关闭操作。

NEVER 清单（引导设计的红线）：

• 不要强迫用户完成冗长引导后才能使用产品；
• 不要用显而易见的解释去说教用户；
• 不要重复展示同一个 Tooltip（尊重 dismissals）；
• 不要在整个导览期间封锁全部 UI（让用户自由探索）；
• 不要创建一个与真实产品脱节的独立"教程模式"；
• 不要一次性信息轰炸（用渐进式披露！）；
• 不要把 "Skip" 藏起来或做得难找；
• 不要忘记回归用户（不要再次展示初次引导）。

从仓库实现结构看，这套"seen-state + 尊重关闭"的思想与整个 skill 中反复出现的"证据驱动、一次性验证、防重复打磨"纪律同源——例如 polish.md 要求"不要为了显得在打磨而重复加动画"，onboard 则要求"不要为了显得在引导而重复打扰"。两者的共同底层逻辑都是：用最低的打扰成本换取最高的用户价值，然后立刻停下。

---

六、验证引导质量：用可量化指标收尾

引导设计完成后，必须以真实用户测试来验收，而不是自我感觉良好。原文档给出六项关键指标：

• Time to completion（完成时间）：用户能否快速完成引导？
• Comprehension（理解度）：完成引导后用户是否真的理解了？
• Action（行动）：用户是否采取了期望的下一步？
• Skip rate（跳过率）：是否太多人跳过？（可能说明引导太长或没价值）
• Completion rate（完成率）：用户是否完成？（太低就简化）
• Time to value（到价值时间）：用户多久获得第一个价值？

这六项指标也构成了引导与整个 Impeccable 工作流衔接的判据：当用户快速抵达 aha moment 且没有流失时，引导设计即告完成，随后交接给 /impeccable polish 做最终的打磨润色。

关于这条交接线，仓库中提供了双重印证：README.md 第 54 行把 /impeccable onboard 描述为 "First-run flows, empty states, activation paths"，归入精修类命令；而 onboard 参考文档的收尾句则明示"When users hit the aha moment fast and don't drop off, hand off to /impeccable polish for the final pass"。也就是说，onboard 负责把新用户带到价值点，polish 负责把整条路径打磨到出品级——两者是引导工作流的前后半程，不应混为一谈。

此外，从 scripts/lib/skill-categories.js 的归类看，onboard 与 harden（生产级加固：错误、i18n、边界情况）在同一精修家族中，这提示了一个实战顺序：引导聚焦"第一次进入的顺利"，而错误状态、多语言扩张、权限与断网等非首次路径的健壮性往往由 harden 补位——如果你的产品面向国际用户，引导文案的本地化扩张（localization expansion）测试也应纳入验收清单。

---

七、把文档用起来：一条完整的 onboard 实战闭环

结合上文，一条可复用的实操闭环如下：

1. 触发：当需求涉及 onboarding、first-time users、empty states、activation、getting started、new user flows、aha moment 时，加载 onboard 参考文档（仓库中该 skill 的命令路由由 SKILL.md 的 Commands 表与 routing.md 共同定义）；
2. 评估：按"识别挑战 → 理解用户 → 定义成功"三问定位 aha moment 与最低学习量；
3. 设计：按首次引导、功能发现（重点做空状态）、导览、交互式教程、帮助文档分层决策，选择恰如其分的一种或组合，而不是全部堆上；
4. 落地：用文档给出的技术选型（Tippy/Popper、Intro.js/Shepherd/React Joyride）与 localStorage seen-state 实现，杜绝重复打扰；
5. 验证：对照完成时间、理解度、行动率、跳过率、完成率、到价值时间六项指标收口；
6. 交接：用户快速到价值且不流失后，交由 /impeccable polish 做最终精修；遇到错误路径、i18n、权限等非首访健壮性问题，交由同家族的 harden 思路补全。

整套方法的精髓始终只有一句：引导不是教学产品，而是为用户抢出证明产品价值的那几分钟。 在 AI 辅助生成前端的过程中，这套文档让模型产出的 onboarding 不再是"又长又像教程"的样板戏，而是真正以激活率为目标的克制的设计。