企业官网建设流程全解析

Impeccableonboard命令实战指南：从零设计首次体验、激活流程与空状态

【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable

本文导读：Impeccable 是一套让 AI 前端/UX 协作更懂设计的开源技能（Skill），其中/impeccable onboard专用于"设计首次体验（first-run flows）与空状态（empty states）"。这篇指南以 Impeccable 的 onboard 参考文档 为骨架展开，先讲清楚该命令在技能体系中的定位与触发条件，再逐步拆解"需求评估 → 设计原则 → 分场景体验设计 → 空状态设计 → 实现模式 → 质量验证"的完整工作流，最后说明如何把收尾交给/impeccable polish。读完你既能照做一次标准的 onboarding 设计评审，也能理解它在 Impeccable 技能 的 Refine/Harden 管线里所处的确切位置。

1.onboard命令定位：做什么、何时触发、如何路由

onboard是 Impeccable 技能提供的一组可调用命令之一。在技能主文档 SKILL.md 的命令总表 中，它的条目是：

onboard [target]| Refine | Design first-run flows, empty states, activation | reference/onboard.md

其正式描述（见 command-metadata.json）为：

Design onboarding flows, first-run experiences, and empty states that guide new users to value. Covers welcome screens, account setup, progressive disclosure, contextual tooltips, feature announcements, and activation moments. Use when the user mentions onboarding, first-time users, empty states, activation, getting started, new user flows, or the aha moment.

这段元数据同时给出了触发词清单——当用户提到以下任一概念时，命令路由会判定为onboard：

• onboarding / 首次体验
• first-time users / 新用户
• empty states / 空状态
• activation / 激活
• getting started / 快速上手
• new user flows / 新用户流程
• the aha moment / "顿悟时刻"

在命令分类上，Impeccable 将命令划分为 create / evaluate / refine / simplify / harden / system 六类（见 scripts/lib/skill-categories.js），onboard与polish、optimize、harden同属HARDEN（生产就绪）类别：

// scripts/lib/skill-categories.js polish: 'harden', optimize: 'harden', harden: 'harden', onboard: 'harden',

也就是说，onboard不是从零造界面，而是让已有产品在"新用户第一次进入"这条路径上变得可用、可理解、能导向价值——它与polish（最终质量收尾）、harden（错误/边界状态）、optimize（性能）站在同一质量维度的不同侧面。

调用形式为/impeccable onboard [target]（target可以是具体的页面、功能或组件）。运行时还需要"额外上下文"（Additional context needed）：你希望用户到达的"aha 时刻"是什么，以及目标用户的经验水平——这两点贯穿整个 onboard 流程的取舍。

2. 核心信条：Onboarding 不是产品教学，而是通往"首个价值"

onboard 参考文档开篇就划出了一条最重要的边界：

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.

（Onboarding 的职责不是教学产品，而是把人带到"证明产品值得他们投入时间"的那一刻。）

"Aha 时刻"（aha moment）是全篇的北极星。设计 onboarding 时，一切步骤、文案、空状态、弹层都在为这一个目标服务。随之而来的判断标准非常直接：

CRITICAL: Onboarding should get users to value as quickly as possible, not teach everything possible.

这条信条在仓库的设计语境里同样成立。Impeccable 在 SKILL.md 的 Modes 一节 区分了 Persuade（说服：访客决策并行动）、Operate（操作：访客完成任务）、Read（阅读：访客理解信息）、Experience（体验：访客身在其中）四种模式——onboarding 最典型地出现在Operate（完成任务）产品中（应用 UI、Dashboard、编辑器、管理后台、设置页），其质量底线是"可扫描性、一致性、原生预期、真实使用场景高于表现力"。

3. 第一步：评估 Onboarding 需求（Assess Onboarding Needs）

动手设计前，先搞清楚"用户需要学什么、为什么学"，从三个角度提问：

3.1 识别挑战（Identify the challenge）

• 用户试图达成什么？
• 当前体验里什么让他们困惑或不清晰？
• 用户在哪些环节卡住、流失？
• 我们想让用户到达的 "aha 时刻" 是什么？

3.2 理解用户（Understand the users）

• 他们的经验水平如何？（新手、重度用户、混合人群？）
• 他们的动机是什么？（兴奋探索型？还是工作需要、被逼使用？）
• 他们愿意投入多长时间？（5 分钟？还是 30 分钟？）
• 他们已知的替代方案是什么？（从竞品迁移过来？还是对这个品类一无所知？）

3.3 定义成功（Define success）

• 用户要成功，最少必须学会什么？
• 我们希望他们完成的关键动作是什么？（创建第一个项目？发出第一个邀请？）
• 我们怎么判断 onboarding 生效了？（完成率？到达价值的时间？）

这三个提问组与 shape.md 中关于状态与转换的发现清单（"哪些状态和转换重要：first-run、empty、loading、error、success、permissions、overflow、expert use？"）互相印证——在更早的 UX/UI 规划阶段，shape就会要求把 first-run 与 empty 纳入设计范围，而onboard是这条思路在成品界面上的落地执行者。

4. 五大设计原则（Onboarding Principles）

Show, Don't Tell（展示而非说教）

• 用可工作的示例演示，而非只靠描述；
• 在 onboarding 里提供真实功能，而不是搞一个独立的"教程模式"；
• 渐进式披露（progressive disclosure），一次只教一件事。

Make It Optional（尽量可跳过）

• 让有经验的用户能跳过 onboarding；
• 不要阻断用户进入产品；
• 提供 "Skip"（跳过）或 "I'll explore on my own"（我自己探索）选项。

Time to Value（时间到价值）

• 尽快让用户到达 "aha 时刻"；
• 优先前置最重要的概念；
• 教能带来 80% 价值的 20% 内容；
• 把高级特性留到情境化探索中去发现。

Context Over Ceremony（情境优先于仪式）

• 在用户真正需要某个功能时再教它，而不是一上来全塞；
• 空状态（empty states）本身就是 onboarding 机会；
• 在使用点提供 tooltip 与提示。

Respect User Intelligence（尊重用户智商）

• 不要居高临下、不要过度解释；
• 简洁清晰；
• 相信用户能理解标准交互模式。

5. 设计各类 Onboarding 体验（Design Onboarding Experiences）

文档把 onboarding 体验按场景拆成五类，每类都给出了适用场景与具体做法。

5.1 初次产品 Onboarding（Initial Product Onboarding）

由四个环节构成，每个都有明确要求：

欢迎屏（Welcome Screen）

• 清晰的价值主张（这是什么产品？）；
• 用户将学会/完成什么；
• 时间预估（诚实地说明投入）；
• 提供跳过选项（给有经验的用户）。

账户设置（Account Setup）

• 只收集最少必要信息（更多信息以后再问）；
• 解释你为何索取每一条信息；
• 尽量给出智能默认值；
• 合适时提供社交登录。

核心概念导入（Core Concept Introduction）

• 只引入 1～3 个核心概念（不是全部）；
• 使用简单的语言和示例；
• 尽可能可交互（动手做，而不是只读）；
• 有进度指示（"第 1 步，共 3 步"）。

首个成功（First Success）

• 引导用户完成一件真实的事；
• 提供预填充的示例或模板；
• 庆祝完成（但别过度）；
• 给出清晰的下一步。

5.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]

情境化 Tooltip（Contextual Tooltips）

• 在相关时刻出现（用户第一次看到该功能时）；
• 直接指向相关的 UI 元素；
• 简短解释 + 收益说明；
• 可关闭（提供 "Don't show again" 选项）；
• 可选 "Learn more" 链接。

功能公告（Feature Announcements）

• 新功能发布时高亮展示；
• 说明"什么是新的、为什么重要"；
• 让用户能立即尝试；
• 可关闭。

渐进式 Onboarding（Progressive Onboarding）

• 在用户遇到功能时再教；
• 用徽标/指示标记新功能或未用功能；
• 逐步解锁复杂度（不要一开始就展示所有选项）。

5.3 引导式导览与走查（Guided Tours & Walkthroughs）

何时使用：

• 功能很多的复杂界面；
• 现有产品发生重大改版；
• 需要领域知识的行业专用工具。

如何设计：

• 聚光（spotlight）特定 UI 元素（压暗页面其余部分）；
• 步骤要短（每次导览最多 3～7 步）；
• 允许用户自由点击穿行导览；
• 包含 "Skip tour" 选项；
• 可回放（放在帮助菜单里）。

最佳实践：

• 交互优于被动（让用户去点真实按钮）；
• 聚焦工作流而非孤立功能（"创建项目"而不是"这是项目按钮"）；
• 提供样例数据，让操作真的能成功。

5.4 交互式教程（Interactive Tutorials）

何时使用：

• 用户需要动手练习；
• 概念复杂或不熟悉；
• 高风险场景（先在安全环境练习更好）。

如何设计：

• 带样例数据的沙盒环境；
• 明确目标（"创建一张按地区展示销售额的图表"）；
• 逐步引导；
• 校验（确认用户做对了）；
• 毕业时刻（"你准备好了！"）。

5.5 文档与帮助（Documentation & Help）

产品内帮助：

• 贯穿界面的情境帮助链接；
• 键盘快捷键速查；
• 可搜索的帮助中心；
• 复杂工作流的视频教程。

帮助模式：

• 复杂功能旁放?图标；
• Tooltip 里的 "Learn more" 链接；
• 键盘快捷键提示（如在搜索框上显示⌘K）。

6. 空状态专项设计（Empty State Design）

空状态是 onboarding 最常见也最常被做成"白板"的地方，因此文档给它单列一节。每一个合格的空状态都需具备五要素：

1. 这里将出现什么（What Will Be Here）："Your recent projects will appear here"；
2. 为什么重要（Why It Matters）："Projects help you organize your work and collaborate with your team"；
3. 如何开始（How to Get Started）：[Create project] 或 [Import from template]；
4. 视觉趣味（Visual Interest）：插画或图标（而不是白页上一行字）；
5. 情境帮助（Contextual Help）："Need help getting started? [Watch 2-min tutorial]"。

文档进一步区分了五种空状态类型，每种的处理手法各不相同：

同样的"状态驱动"思路在 Impeccable 的harden命令（错误处理、边界状态）与polish命令（把 missing loading/empty/error/success/disabled/permission states 列为收尾必查项）中反复出现，详见 harden 参考 与 polish 参考。onboard 的视角更偏"新用户第一次看到空状态时的引导"，而非单纯的状态完备性。

7. 实现模式（Implementation Patterns）

7.1 技术选型建议

文档直接给出常见工程选型参考：

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

7.2 存储模式示例

追踪"用户看过哪些 onboarding 步骤"，文档给出的最小可行实现：

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

7.3 铁律（NEVER）

IMPORTANT: Don't show same onboarding twice (annoying). Track completion and respect dismissals.

无论用什么库，绝不（NEVER）允许以下行为，文档将其作为硬性禁止项列出：

• 在用户使用产品前，强迫他们走完冗长的 onboarding；
• 用显而易见的解释羞辱用户的智商；
• 反复展示同一个 tooltip（尊重用户的关闭操作）；
• 导览期间封锁全部 UI（让用户能够探索）；
• 创建与真实产品脱节的独立"教程模式"；
• 一次性灌输过量信息（要用渐进式披露！）；
• 隐藏 "Skip"，或让它难以被发现；
• 忘了回归用户（不要再次展示初次 onboarding）。

8. 验证 Onboarding 质量（Verify Onboarding Quality）

设计完成后，用真实用户检验，围绕六个指标收集证据：

• Time to completion（完成耗时）：用户能快速完成 onboarding 吗？
• Comprehension（理解度）：完成后用户真的理解了吗？
• Action（行动）：用户会去执行期望的下一步吗？
• Skip rate（跳过率）：太多人跳过？——那可能说明它太长或没价值；
• Completion rate（完成率）：用户完成吗？（偏低就简化）
• Time to value（到达价值时间）：用户多久获得第一个价值？

这组指标对应了 assess 阶段 里定义的成功标准——评估时预设"完成率/到达价值时间"作为成功度量，验证阶段就用同款口径实测。

9. 收尾交接：把最终打磨交给/impeccable polish

onboard 参考文档的最后一句定义了明确的交接边界：

When users hit the aha moment fast and don't drop off, hand off to/impeccable polishfor the final pass.

也就是说：onboarding 流程的"生效性"由onboard负责，而这条路径的"细节完成度"交给polish收尾。两者的分工在 polish 参考文档 中写得很清楚——polish是 refinement（精修）而非 covert redesign（偷偷重设计），它在收尾时会把状态路径（loading / empty / error / success / disabled / permission）作为与"流程与层级、布局与字体、色彩与图标、交互与状态、内容与代码"并列的五大检查面之一（见该文档的 Triage 顺序第 2 项）。因此一条高质量的 onboarding 路径通常是：

1. shape（如果是从零规划 UX/UI，会在 discovery 阶段就标记 first-run/empty 为关键状态，见 shape 参考）；
2. onboard（设计欢迎屏、激活流程、空状态、tooltip 等引导资产）；
3. polish（对整条新用户路径做逐状态、逐视口、逐输入方式的最终质量收尾与源码差异清理）。

整个流程始终对齐 Impeccable 在 SKILL.md 中声明的原则——"全部做完、一次批量检查、修复、最多再确认一轮就停"：onboard 帮助用户快速到达价值，polish 保证这条路径不残留半成品状态，两者相加才是对"首次体验即代表产品品质"的完整交付。

参考文件速查

• 本文骨架：.opencode/skills/impeccable/reference/onboard.md（技能仓库内同名副本见 skill/reference/onboard.md 与 plugin/skills/impeccable/reference/onboard.md）；
• 命令与路由定义：.opencode/skills/impeccable/SKILL.md；
• 命令元数据（触发词与描述）：.opencode/skills/impeccable/scripts/command-metadata.json；
• 命令分类（Refine/Harden）：scripts/lib/skill-categories.js；
• 收尾交接对象：.opencode/skills/impeccable/reference/polish.md；
• 上游规划（first-run/empty 状态识别）：.opencode/skills/impeccable/reference/shape.md；
• 相邻质量面（错误与边界状态）：.opencode/skills/impeccable/reference/harden.md。

【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable