interaction-design-board

交互设计板

将交互上的不确定性转化为可检验的证据。保持产品的真实事实和设计语言不变；充分调整交互架构，让用户能在生产代码变更前体验其中的权衡。

为请求选择路径

• 如果选择取决于行为、状态、工作流、层级或渐进式披露，请使用此技能。
• 对于静态视觉风格校准和图像矩阵，请使用 design-style-picker。
• 对于全新的产品级设计系统，请使用 gstack 的 design-consultation；对于静态生成式模型图，请使用 gstack 的 design-shotgun。
• 选定视觉方向后，如果用户仍需比较可点击的交互结构，请返回此技能。
• 如果只是已确定的一行 CSS 调整，或者用户已经提供获批的交互规范且只要求实现，请勿使用此技能。

不可妥协的结果

产出决策，而非作品集：

1. 提供多个可运行的 HTML 候选方案，并保持业务事实、产品范围、设计令牌和可用操作一致。
2. 每个候选方案都体现不同的交互假设，而非仅更换外观。
3. 设计板让用户能够操作每个候选方案、记录具体反馈、选择一个方案，或提出指定名称的混合方案。
4. 在用户批准行为前，不开始生产实现。

静态截图只能作为辅助证据。截图无法证明折叠状态、键盘操作路径、选择模型或任务交接。

工作流

1. 冻结决策约定

生成变体前，在会话工作区编写一份精简的约定：

• 用户任务： 操作者试图完成的实际任务。
• 决策范围： 正在比较的单个页面、组件或范围明确的流程。
• 不可变事实： 每个变体都必须保留的真实对象、标签、状态、权限、操作和数据语义。
• 现有设计语言： 必须保持可识别的现有令牌、组件、导航、信息密度和品牌素材。
• 首屏不变项： 任何内容展开前必须保持可见的内容。
• 交互状态： 用户必须能够体验的关键状态。
• 停止条件： 获批的变体或明确的混合方案说明；暂不编辑产品。

对于现有产品，在编写约定前，先检查其渲染页面和实现。不要用看似合理的示例数据替代未知事实。如果某些信息未知，应标记为未知；若其与交互选择无关，则可省略。

如果此决策会替换已上线的屏幕，请在检查期间以编号清单列出当前用户可见的行为：每项操作、状态、深层链接、键盘操作路径、空状态和复制功能。候选方案可以延后或舍弃其中任何一项——这份清单旨在确保舍弃行为是明确说明的权衡，而非未察觉的回归。

在提出候选架构前，请阅读 references/interaction-design-method.md。其中包含用于判断某个方向是否合理的层级、渐进式披露、比较和无障碍规则。

2. 提出不同的交互架构

默认提出三个候选方案。只有存在其他独立的交互假设时才增加候选方案；不要用细微变体填充设计板。

说明每个候选方案时，请列出：

• 它如何帮助用户完成任务的假设；
• 它将什么设为主要内容；
• 它会延后或隐藏什么；
• 可能存在的权衡；
• 原型中必须可用的状态和操作。

保持决策约定不变。调整导航、选择、披露、操作归属或信息顺序——不要同时更改颜色、文案和数据。可参考的架构类型包括命令优先、队列详情、对象优先、比较优先和账本优先；但应根据当前任务推导候选方案，而不是为了凑齐类型而套用模式。

3. 生成可独立运行的候选方案

在产品源代码树之外的会话工作区中，为每个候选方案创建一个自包含的 HTML 文件。将 CSS 和 JavaScript 内联；避免运行时网络依赖，确保每个原型都能在 Board 中运行。

如果有可用的独立工作上下文，将每个候选方案分配给一个工作者，并为其提供相同的冻结决策约定和仅针对该候选方案的假设。不要让工作者看到彼此的输出。这种隔离机制就是测试时扩展机制：它能保留不同的假设，而不是让它们收敛成相似方案。如果没有可用的工作者，就按顺序生成，但在开始下一个候选方案之前，重新阅读冻结的约定，而不是上一个候选方案。

每个候选方案都必须实现声明的状态。没有实际功能的装饰性按钮不算交互原型。应使用真实的本地状态；不要模拟产品并不具备的后端响应。

4. 构建并打开 Design Board

参照 references/board-contract.md 创建 board.json，然后运行：

SKILL_ROOT="<absolute directory containing this loaded SKILL.md>"
python3 "$SKILL_ROOT/scripts/build_board.py" \
  --manifest <session-dir>/board.json \
  --output <session-dir>/design-board.html

预期输出：

BOARD_BUILT variants=<derived count> output=<absolute path>

构建器会拒绝字节完全相同的候选方案、路径遍历、缺失声明状态，以及静态外部样式表、脚本或媒体。Board 还会向每个沙箱候选方案注入禁止网络访问的内容安全策略，防止动态 JavaScript 创建未声明的运行时依赖。请修复候选方案；不要放宽任一边界来让 Board 通过。

如果已安装 gstack 的设计可执行文件，请从当前活动的 gstack Skill 安装目录中解析其绝对路径；不要假设 $D 在新的 shell 中存在。然后记录服务器输出的准确 Board URL：

GSTACK_DESIGN="<resolved gstack design executable>"
SERVER_OUTPUT="$("$GSTACK_DESIGN" serve \
  --html <session-dir>/design-board.html --timeout 1800 2>&1)"
printf '%s\n' "$SERVER_OUTPUT"
BOARD_URL="$(printf '%s\n' "$SERVER_OUTPUT" | sed -n 's/^BOARD_URL: //p' | tail -1)"
test -n "$BOARD_URL"

如果无法解析该可执行文件，或者命令未打印 BOARD_URL，请使用主机的浏览器打开工具直接打开 design-board.html。直接文件模式仍可正常使用：提交和混搭会下载 feedback.json 或 feedback-pending.json，供 Agent 阅读。Board 本身就是选择器；聊天只是备用渠道。

5. 观察任务，而非感觉

请用户在每个候选方案中执行相同的代表性任务。记录：

• 用户首先注意到的内容；
• 用户在哪里知道或不知道接下来该做什么；
• 哪个展开项有助于呈现必要的信息，或隐藏了这些信息；
• 哪种状态转换让用户感到自然或意外；
• 哪些元素应该保留、舍弃或混搭。

不要用数值评分或“最精致的候选方案最好”的说法来替代这些观察。用户可以选择一个候选方案，也可以组合多个候选方案中的指定部分。

出现 feedback-pending.json 时，保留已接受的部分，调整指定的失败维度，只重新生成受影响的候选方案，并在同一会话目录中构建一个带版本号的 Board 文件。如果 gstack Board 已在运行，请重新加载该确切的 Board，而不是再次对旧源路径调用 serve：

curl -sS -X POST "${BOARD_URL%/}/api/reload" \
  -H 'Content-Type: application/json' \
  -d '{"html":"<absolute-versioned-board-path>"}'

预期响应：{"reloaded":true}。重复调用 serve 可能会复用 Board 实例，而不读取已更改的内容，因此不能用作重新加载机制。请用户在同一个 Board URL 中重试任务。当反馈不再改变决策时，停止增加轮次。

6. 在投入生产前冻结审批结果

用户确认反馈摘要后，按照 references/board-contract.md 中的架构，在 Board 旁边写入 approved.json。记录以下内容：

• 选定的候选方案或混合方案；
• 已批准的交互规则和首屏不变量；
• 被否决的权衡；
• 用户实际操作过的状态；
• 尚未明确的问题；
• 原型文件的准确身份。

然后，且仅在此之后，才在产品中实现。保留当前设计系统和真实数据契约。使用项目的前端实现和视觉 QA 技能，然后在真实浏览器中验证同一个代表性任务。像素相似并不足够；必须保留已批准的状态转换和信息顺序。

如果你在步骤 1 中建立了行为清单，那么只有在清单中的每一项都注明处置方式后，才算完成实现：保留、改为哪种形式，或说明为何移除。将这张表放在审查改动的人会看到的地方，而不只是会话工作区。移除项是承重项——一个无人能说明的行为，就是一项从未登记的回归，而作者最不容易察觉它。首次核对时，预计有意移除的数量会有误；在宣布改动完成前，对照清单再次检查。

如果项目有设计 SSOT，在实现过程中将已批准的交互决策写入其中。将会话反馈和原型文件保留为依据；不要把其中不断变化的值复制到通用项目说明中。

失败边界

• 不要把每个候选方案都变成不同的产品或数据模型。
• 不要用静态图像生成代替可运行的交互。
• 在身份、当前状态、主要证据或下一步操作是做出决策所必需的信息时，不要将它们隐藏在渐进式披露之后。
• 用户尚未亲自操作前，不要实现看似胜出的方案。
• 不要将原型写入生产组件目录。
• 不要声称作者自己的点击演示完成了可用性验证。Agent QA 用于发现损坏的状态；用户的任务观察才决定交互设计。

交付

返回 Board 路径或 URL、候选方案假设、反馈／审批文档路径、已执行的浏览器验证，以及明确的下一步：迭代 Board、实现已批准的候选方案，或停止。