storyboard

分镜板

分镜板是一个可供评审的独立 HTML 页面，将工作范围内所有 UX 界面串联在一个视图中。仅当现有原型具有权威性且加载安全时，才会将其嵌入为 sandboxed <iframe> 元素；否则，页面会使用带标签的静态图片。顶部的流程图展示用户如何在这些界面间切换。缺失卡片会标出仍需制作的原型。每个原型都配有审核清单，供评审者批准或标记具体修改项。

**目的：**将设计审核从“打开十几个标签页，努力在脑海中记住流程”变成“打开一个页面，向下滚动即可”。它提供一个可供评审的产物，可与任何文本决策记录配套使用（如计划文档、审核备注或 PR 描述）。

何时制作

• **当一个流程包含足够多的相关界面或状态，以至于分开评审会掩盖转换、不一致或缺失时。**示例：注册 → 验证 → 引导流程，或包含破坏性操作和恢复状态的设置流程。
• **只有当合并评审带来的收益足以抵消维护成本时，才为计划中的一批工作制作。**仅凭界面数量不足以成为再制作一个产物的理由。
• 单项功能审核，适用于横跨多个状态的功能（例如一个流程在 3 个以上步骤中涉及加载 / 空状态 / 已填充 / 错误状态）。
• 用户明确提出“把所有内容放在一处”“完整流程”“审核原型”或“我想把这些内容放在一起看”。
• **制作新原型之前。**先将现有原型制作成分镜板，能直观揭示缺失内容，并促使你针对每个缺失项先提出头脑风暴问题，再开始起草。

何时不要制作

• 单个原型的工作（例如修复设置页面中的一个文案问题）。打开原型，运行 impeccable 流程，即可完成。
• 纯 API / 数据迁移 / 运维事项，没有 UX 界面。没有原型 = 无需制作分镜板。
• 范围尚未确定前的探索性 / 临时性工作。分镜板是用于评审的产物；先要有值得评审的内容。
• 已经完全构建好的功能。分镜板用于实施前。事后如果需要视觉审核，请对实际界面运行 critique 技能（来自 impeccable 系列的外部技能；如果未安装则跳过）。

技能收集的输入

起草 HTML 之前，收集以下内容：

1. **范围代码 + 标题。**例如：Onboarding v2 — reset regression、Settings page — profile + notifications、M3 · address book。用于设置页面标题和面包屑。
2. **范围内的现有原型。**浏览项目的 design-mocks 文件夹（或类似目录），收集与此范围相关的路径。每个现有原型都会成为一个嵌入面板。
3. **用户流程。**用户经历的状态序列 + 转换过程。用 ASCII 绘制在 <pre> 块中。用醒目的颜色 / 字形标出缺失项。
4. **缺失项。**此范围需要但尚不存在的新原型。每个缺失项都要有单独的卡片，其中列出用户在我们制作原型前必须回答的头脑风暴问题——每个缺失项都必须有问题。
5. **上游 / 相邻界面。**不属于此范围，但能提供上下文的界面（例如用户完成此流程后到达的页面）。以较小的 iframe 高度嵌入。
6. **配套文档链接。**计划条目、设计简报、相关 ADR、父级索引页面。

输出位置

将分镜板 HTML 放在项目现有的 mocks 或 launch-planning 文件夹中，与原型存放在一起，以便相对 iframe 路径正常工作。常见位置：

• apps/<app>/design-mocks/<scope>-audit.html
• design-mocks/<scope>-storyboard.html

将分镜板视为正在使用的审核产物，而非永久记录。使用期间遵循仓库的产物布局；审核结果上线或其假设被取代后，就将其删除，除非仍有指定负责人为当前问题维护它。Git 历史就是归档。

遵循仓库中其他产物的命名惯例。如果有原型清单或索引页面，请添加指向分镜板的醒目链接，方便查找。

必需结构（按顺序排列）

故事板是一种模式，而非模板。每个故事板都按以下顺序包含这些部分；每部分的具体内容取决于范围。

1. 面包屑导航

返回上级索引的链接（模拟稿清单、规划索引等）。

2. 标题栏

• 使用大写字母间距样式的小型胶囊标签，显示范围代码（例如 Onboarding v2，或项目使用的其他代码）。
• 描述范围的衬线展示标题。
• 简短副标题（一个句子），说明此页面的用途。
• 一段文字解释范围，并附上指向条目 README、设计简报和任何相关 ADR 的链接行。

3. 流程图

• ASCII 图必须使用 <pre>，绝不能使用 <div class="whitespace-pre">。 Prettier 会重新格式化后者并破坏布局；<pre> 不受影响。这是硬性规则——违反会导致页面损坏。
• 使用 ASCII 方框和箭头展示用户在此范围内的旅程。
• 在行内使用颜色编码：一种颜色用于已有模拟稿的节点，一种区别明显的颜色用于缺口（最好使用项目的“操作”色，让用户的视线落在此处），一种柔和的颜色用于相邻／上下文界面。
• 使用 🆕 GAP 之类的行内标记指出缺口，便于快速浏览。

4. 现有模拟稿（并排展示）

• 标题带有状态徽章（“✓ 已随……发布”）。
• 响应式网格（通常桌面端为三列，移动端折叠为单列）。每个模拟稿占一个单元格。
• 每个单元格包含：
  • 小型徽章和文件名标题。
  • 使用项目标题字体样式的模拟稿名称。
  • 简短说明（1–2 句）。
  • 固定高度的沙盒 <iframe>（主要模拟稿使用 780px 效果良好，相邻模拟稿使用 640px；可根据项目调整），或文档中说明的静态备用方案。
  • 带有 rel="noopener noreferrer" 的“在新标签页中打开 ↗”链接。
  • 审核清单卡片——针对与此模拟稿相关的每项 impeccable 规范给出提示：/critique、/clarify、/audit、/polish、/adapt、/impeccable harden、/distill。另加范围特定的问题（例如“编辑操作是否易于发现？”、“是否模拟了加载状态？”）。

5. 转换／状态缺口

当某些内容应该模拟但并不明显时（例如操作后的提示 Toast、成功确认），将其标记为“? 不明确”部分，并附上头脑风暴问题列表。与其让问题悄悄溜走，不如明确呈现歧义。

6. 待补充的缺口

• 标题带有“🆕 后续制作”徽章。
• 响应式网格。每个缺口占一个单元格。
• 使用明显不同的背景／边框（采用项目的“操作”色调）。
• 每个单元格包含：
  • 徽章和待制作模拟稿的文件名。
  • 使用项目标题字体样式的展示名称。
  • 描述此模拟稿所呈现的内容。
  • 头脑风暴问题——无序列表。每个项目对应一个起草模拟稿前必须作出的明确决策。涵盖：入口点、形态（底部面板／对话框／页面）、字段列表、边界／错误状态、与现有模式的集成、破坏性操作的语义、取消行为。

7. 上游／相邻内容（供参考）

• 使用较小的 iframe。
• 三列网格。
• 将每项标记为“非此范围内容，仅供参考”。
• 用于用户从此范围跳转进入的界面（之后会填充内容的详情页）或从此范围跳转离开的界面（上游流程）。

8. 建议顺序

使用有序列表描述从此故事板到代码落地的步骤：

1. 用户审阅此页面；批准现有模拟稿，或指出具体的修改项。
2. 回答每张缺口卡片中的头脑风暴问题。
3. 使用 /impeccable craft 制作缺口模拟稿，并通过设计流程进行审核（/shape → /critique → /layout → /clarify → /polish，并使用 /adapt 处理响应式设计、使用 /impeccable harden 处理边界状态）。
4. 修复审核中标记出的现有模拟稿问题。
5. 通过仓库授权的交付工作流保存审核后的模拟稿和审核备注。随后开始实施。

9. 页脚

元信息行：范围代码 · 最后更新日期 · 配对阅读链接。

样式约定

使用项目现有的设计令牌和布局工具——不要自行创建新的令牌或工具。如果项目使用 Tailwind，请重复使用已配置的实用类；不要在无法编译这些类的项目中输出 Tailwind 类。如果没有本地约定，请使用小型、与框架无关的内联 CSS 备用方案。具体来说：

• 颜色： 将操作、文本、背景、存在、间隙和不确定等角色映射到本地语义令牌。备用方案只能定义页面所需的最低限度无障碍颜色。
• 字体： 重复使用本地正文和标题字体栈；不要仅为了分镜图而添加衬线字体或字体依赖。
• 徽标： 使用项目的语义状态颜色，并配上文字或字形标签，确保颜色永远不是唯一的状态信号。
• iframe 框架： 固定高度、边框、圆角、浅阴影。整个网格中的视觉权重保持一致。
• 容器： 使用本地页面外壳／容器模式。与框架无关的备用方案可使用 max-width、margin-inline: auto 和响应式内边距。

遵循本地代码库现有的模拟页或索引页样式。复制同级模拟页中的 <style> 块，不要另起炉灶。

嵌入安全

将每个模拟页和 URL 都视为不可信内容，即使它们位于代码库中也不例外。优先使用相对路径、经过审核且由代码库管理的目标；绝不要嵌入包含凭据的 URL 或第三方私有页面。为每个 iframe 添加 sandbox 属性，且仅授予模拟页经证实确实需要的权限。静态模拟页不需要令牌；交互式模拟页通常需要 allow-scripts，但同源的不可信内容不能同时获得 allow-scripts 和 allow-same-origin。如果确实需要这一组合，请从隔离源提供内容，或使用静态备用方案。

为分镜图本身添加严格的内容安全策略（通常仅允许自托管的框架、图片和样式，并仅添加有本地依据的最低限度例外）。不要仅为了让模拟页正常工作而添加 allow-top-navigation、弹出窗口、表单、下载、摄像头、麦克风或剪贴板权限。如果沙箱或 CSP 导致无法忠实呈现，请标明限制并使用静态权威版本，而不是默默放宽审核页面的限制。

Prettier 安全

经验教训有三条：

1. 始终将 ASCII／多行预格式化内容包在 <pre> 中。 Prettier 会重新格式化 <div class="whitespace-pre"> 内的 HTML，破坏布局。<pre> 不受影响。
2. 不要纠结 Markdown 表格列宽。 写好表格后让 Prettier 重新对齐，再提交对齐后的版本。
3. 提交前对分镜图文件运行 prettier --write。 如果项目有 Prettier 提交前钩子，它也会检查这一点，但提前格式化更快。

约定整合

制作分镜图后：

1. 在分镜图仍有效时，将其链接添加到项目的模拟页清单或索引页中的“Active audits”或类似部分。
2. 在当前决策文档（计划、审核说明或 PR 描述）中引用它，作为视觉配套资料。
3. 分镜图删除或被取代后，移除有效链接；将长期适用的设计约束纳入持续维护的产品文档或测试中。

不可妥协事项

• 优先使用实时渲染的模拟稿。 如果权威来源可嵌入且加载安全，请使用 iframe。如果只有静态权威模拟稿，则嵌入图像，标明其不可交互，并记录哪些状态无法体验。
• 缺口必须附带头脑风暴问题。 没有问题的缺口卡片毫无价值。每个缺口都应促使大家在起草前做出决定。
• 一页，而不是一棵树。 滚动浏览一个页面，比在链接树中导航更省力。如果范围太大，导致页面难以阅读，就按子流程拆分，但每个拆分部分仍应保持为单页。
• 检查清单必须名副其实，而非装饰。 审查清单中的每一项都必须对应真正的设计规范。审查者用清单指导审查；Agent 用清单指导后续工作。如果 /critique 实际上不会运行，就不要列出它。

反模式

❌ 把静态模拟稿当作实时证据展示。 如果静态图像是现有的权威依据，使用它们没有问题，但必须标明其不可交互，而且无法证明滚动、过渡、焦点或运行时状态。

❌ 在缺口卡片上写“TODO：添加头脑风暴问题”。 没有已回答问题的缺口，就无法体现此技能的价值。现在就进行头脑风暴，或者移除该卡片。

❌ 为故事板发明专属设计令牌。 故事板应与项目原有风格一致。使用底层模拟稿采用的 Tailwind 颜色、字体和阴影。

❌ 用导航树取代可滚动的单页。 故事板的价值在于“所有内容一览无余”。子页面树会破坏这一点。只有当单页长到难以阅读时才拆分，并记录拆分原因。

❌ 用 <div class="whitespace-pre"> 编写 ASCII 图表。 Prettier 会重新格式化内部 HTML，破坏图表。始终使用 <pre>。

❌ 在故事板审查前制作新的模拟稿。 故事板中的头脑风暴问题旨在推动决策。先起草模拟稿会过早确定可能有误的答案。

调用方式

用户说 /storyboard <scope>，或提出触发短语之一（见 frontmatter 描述）。该技能会：

1. 阅读相关条目／功能文档，以及任何现有的模拟稿清单条目。
2. 收集现有模拟稿、流程、缺口和相邻界面。
3. 为每个缺口起草头脑风暴问题（不回答问题，由用户来回答）。
4. 在项目的规范路径下生成 HTML 文件。
5. 如果索引页存在，则更新模拟稿清单／索引页，添加有效审查链接。
6. 返回文件路径和简要说明，方便用户在浏览器中打开。

相关技能

• impeccable 系列（/shape、/critique、/layout、/clarify、/audit、/polish、/adapt、/impeccable harden、/distill）——来自 pbakaus/impeccable 的外部技能；审查清单会引用这些技能，缺口模拟稿的制作步骤也会运行它们。注意，harden 仅作为 /impeccable 子命令存在，并非独立技能。如果未安装这些技能，只列出实际会运行的设计规范（参见“不可妥协事项”：检查清单必须名副其实，而非装饰）。
• story-splitting——当故事板显示功能范围过广，或在实现前需要按流程、角色、状态、界面、数据、规则或质量级别拆分时使用。
• planning——将范围拆分为可实现的切片后，补充仓库自有的计划文件；仅当不存在本地归属文件且已获授权时，才将根目录下的 plans/ 用作规划技能的备用位置。
• find-gaps——故事板完成后使用，将缺失状态、未回答的头脑风暴问题和不明确的过渡转化为具体验收标准或模拟稿状态规范。
• expectations——故事板审查发现长期有效的经验后，将其归入仓库当前的指南、已接受的决策、术语表、源文件或测试。

快速参考

/storyboard <scope>
│
├─► GATHER
│   ├─ Scope code + title
│   ├─ Existing mocks in scope
│   ├─ User flow (sequence of states + transitions)
│   ├─ Gaps (new mocks needed)
│   └─ Adjacent surfaces (upstream / downstream context)
│
├─► PRODUCE (<scope>-audit.html)
│   ├─ Breadcrumb
│   ├─ Header (scope code + title + link row)
│   ├─ Flow diagram (<pre>, colour-coded, glyphs for gaps)
│   ├─ Existing mocks (3-column grid, iframes + audit checklists)
│   ├─ State gaps ("? unclear" + brainstorm questions)
│   ├─ Gaps to fill (brainstorm-question cards per gap)
│   ├─ Upstream/adjacent (context iframes at smaller height)
│   ├─ Proposed sequence (ordered list)
│   └─ Footer (meta)
│
├─► WIRE UP
│   ├─ Link from mocks manifest / index page
│   ├─ Reference from plan / audit markdown
│   └─ Reference from feature README
│
└─► USER REVIEWS
    ├─ Answers brainstorm questions per gap
    ├─ Approves existing mocks (or flags fixes)
    └─ Skill produces gap mocks via /impeccable craft

经验法则：

• 如果实时 iframe 是维护中的权威来源且可以安全渲染，优先使用实时 iframe；如果无法做到，则使用文档中说明的静态权威来源回退方案。
• 每个空缺都附有头脑风暴问题。
• 使用单页，而非树形结构。
• ASCII 内容使用 <pre>。切勿使用 <div class="whitespace-pre">。
• 使用项目现有的设计令牌。