product-ui-prototyping

产品 UI 原型设计

概述

通过生成和编辑屏幕图像，将产品构想转化为可测试的 UI 行为。生成逐状态的视觉效果、可点击的转场逻辑，以及按平台区分的查看器，让团队在实现前即可端到端地浏览原型。

原型文件夹约定（项目本地）

• 对于每个原型项目，在当前项目的 ui-prototypes/ 目录下创建或使用一个文件夹：
  • ui-prototypes/<prototype-name>/
• 将所有原型产物保存在该文件夹中，确保每个原型都独立完整。
• 为 <prototype-name> 使用清晰的 kebab-case 名称。
• 按平台分开存放图像资源：
  • ui-prototypes/<prototype-name>/images/web/<flow>/...
  • ui-prototypes/<prototype-name>/images/ios/<flow>/...
  • ui-prototypes/<prototype-name>/images/android/<flow>/...
• 按平台和流程分别存放流程图：
  • ui-prototypes/<prototype-name>/flow-maps/<platform>/<flow>.json
• 保留一份清单，将每张图像映射到其确切的生成／编辑提示词：
  • ui-prototypes/<prototype-name>/image-prompt-manifest.md
  • ui-prototypes/<prototype-name>/prompts/<platform>/<flow>/<screen>-<state>.md
• 如果用户指定了其他位置，请遵循用户指定的路径。

输入策略（灵活）

• 如果存在 ui-prototypes/<prototype-name>/experience-story.md，请将其用作屏幕、操作和转场的上游来源。
• 如果该文件不存在，请直接继续，并在此工作流中定义屏幕和转场。
• 不要因缺少任何特定上游文件而阻碍原型设计。

工作流

语音通知（Speak 工具，必需）

• 在关键阶段边界使用 Speak 工具播报状态，让用户无需持续盯着屏幕。
• 硬性要求：以下每个关键阶段都必须在开始和完成时播报（不得选择性跳过）。
• 必须播报的阶段：
  • 工作流启动（prototype target acknowledged，next stage），
  • 转场模型阶段（started，然后是 ui-behavior-test-matrix.md 已起草／更新），
  • 每个平台和流程的基准屏幕阶段（started，然后是基准屏幕集已写入），
  • 每个平台和流程的交互状态阶段（started，然后是状态集已写入），
  • 清单同步阶段（started，然后是 image-prompt-manifest.md 已更新且内容一致），
  • 点击浏览包阶段（started，然后是流程图和查看器已写入），
  • 查看器冒烟测试阶段（started，然后是 Pass／Fail 结果），
  • 最终交付阶段（started，然后是交付包已准备就绪）。
• 语音播报触发策略：
  • 不得跳过必需的阶段边界播报事件，
  • 对于完成事件，只有在里程碑已可靠完成后（文件已写入且相关检查结果已知）才播报，
  • 不要在必需的阶段边界事件之间播报部分草稿或中间提示词迭代，
  • 将时间接近的里程碑更新合并为一条简短消息。
• 每条语音消息应简短（1～2 句），先说明状态，并明确下一步。
• 如果 Speak 工具失败或不可用，请继续工作流，并以文本提供相同的更新。
• 不要播报机密、令牌或完整的敏感内容。

工具执行规范

• 严格按顺序逐次调用图像工具。
• 不要并行运行针对不同屏幕／状态的多次生成／编辑图像调用。
• 等待每次调用完成并检查输出，然后再发起下一次调用。
• 处理包含多个屏幕／状态的批次时，请按确定的队列顺序逐一处理。
• 调用图像工具时，始终使用绝对文件系统路径。
• 生成或编辑图像时，始终为 output_file_path 提供绝对路径。
• 编辑图像时，源图像路径必须使用绝对路径。

提示词沿袭与更新规范

• 迭代更新时，默认使用 edit image，并以最近获批的源图像（“shell”）为基准。
• 首稿、大幅结构调整，或多次编辑仍无法恢复准确度时，使用 generate image。
• 更新图像前，从清单中的 Prompt Path 读取当前提示词，并确认其 Parent Image（如有）。
• 在当前提示词的基础上创建下一个提示词（保留未变更的约束，只修改所请求的内容差异，并明确指出未变更的区域）。
• 将更新后的提示词保存回同一提示词路径，作为最新的事实来源。
• 对于编辑操作，提示词文件必须记录：
  • 人类意图标题：UI Purpose、User Can Do、Transition Outcome
  • 转换元数据：Trigger、From State、To State
  • 输入／输出关联：Input Image、预期的 Output Image
• 对于替换更新，将新图像写入同一图像路径，除非用户明确要求创建新变体。
• 除非用户明确要求分支，否则不要创建带版本号（v2、v3 等）的提示词文件。
• 每个屏幕／流程保留一个规范的 shell，并以该 shell 或其获批的后代为基础派生状态变体。

转换可追溯性模型

• 将文档视为相互关联的四个层次：
  • 规范行为意图：ui-behavior-test-matrix.md（transition_id、触发条件、起始／目标状态、验收检查）
  • 导航运行时：从行为矩阵派生的 flow-maps/<platform>/<flow>.json 转换
  • 编辑执行：目标状态的提示词文件（精确的编辑提示词 + 转换元数据）
  • 资源沿袭：image-prompt-manifest.md（输入／输出图像路径和父级关联）
• 同一转换在全部四个层次中使用相同的 transition_id。
• 如果迭代时复用同一图像路径，则在磁盘上保留最新输出，并在提示词文件中追加迭代日志部分（简短的差异摘要 + 上一个输入图像路径）。

资源生命周期规范（必需）

• 仅保留符合最新产品愿景和当前有效用例的活跃资源。
• 当某个用例／流程／屏幕／状态失效、弃用或过时时，从以下目录中删除其文件：
  • images/
  • prompts/
  • flow-maps/
  • viewer/（如果移除了该流程）
• 除非用户明确要求归档，否则不要为了“以防万一”而保留已弃用的资源。
• 如果命名过时或含义不清，请重命名文件／文件夹，以反映当前产品用语和用例意图。
• 重命名或删除后，在同一变更中更新所有引用：
  • image-prompt-manifest.md
  • flow-map 中的 screens[].image 路径
  • viewer 地图路径配置
• 优先使用稳定、描述清晰的 kebab-case 名称，体现平台、流程、屏幕和状态。

1) 定义产品意图与约束

• 定义目标平台（web、ios、android）和视口假设。
• 根据支持的比例列表，定义各平台／流程的目标宽高比。
• 定义用户画像、核心待办事项和关键路径。
• 定义设计约束：品牌调性、无障碍需求、组件风格和数据密度。
• 生成资源前，定义保真度级别（wireframe、mid、high）。
• 定义必须能在本地查看器中导航的平台＋流程组合。

2）映射屏幕、操作和状态

• 为每个流程创建一张状态转换表：
  • transition_id（稳定的键，例如 gateway_validate_to_success）
  • screen
  • trigger（点击/轻触/提交/导航/系统事件）
  • from_state
  • to_state
  • expected_feedback（视觉反馈 + 微文案）
• 将此表作为规范，并确保所有映射/清单中的转换 ID 与之保持一致。
• 至少涵盖适用的 default、focus、pressed、disabled、loading、success、error 和 empty 状态。
• 优先完成一个关键流程，再扩展到次要流程。

3）创建一个规范的产品基础规格并锁定外壳

• 构建一个可复用的 product_base_spec（平台、视口、排版、间距、设计令牌、无障碍设计意图）。
• 在所有生成/编辑提示词中复用相同的基础规格，避免屏幕之间的风格漂移。
• 对每个屏幕，先创建并锁定一张规范的外壳图像，再开始分支创建状态。
• 如果初次生成不够准确，就反复编辑同一外壳，直到布局和视觉标识保持稳定。

4）生成基线屏幕

• 使用图像生成工具生成全新的屏幕草稿。
• 如果草稿不够准确，就通过多轮 edit image 进行优化，直到规范外壳锁定。
• 按顺序执行基线工作：每次工具调用处理一个屏幕，然后先检查结果，再处理下一个屏幕。
• 在每条生成提示词中明确指定比例，并在该平台和流程中保持比例不变。
• 每次生成/编辑工具调用都使用绝对 output_file_path。
• 将每张基线图像使用的确切提示词保存到：
  • ui-prototypes/<prototype-name>/prompts/<platform>/<flow>/<screen>-default.md
• 使用确定性的样式说明和共享基础规格，确保各屏幕的排版、间距、图标和颜色一致。
• 将锁定的外壳输出保存到稳定的目录结构中：
  • ui-prototypes/<prototype-name>/images/<platform>/<flow>/<screen>-default.png
• 为目标平台和流程实际写入整组基线屏幕后，再告知已完成。

5）基于基线创建交互状态

• 对于迭代式状态更新，默认从锁定的外壳（或最近获批的前序状态）使用 edit image。
• 仅当某个状态需要有意进行结构性差异时，才使用 generate image 创建该状态。
• 在更新后的提示词中保留未变更的约束和固定外壳元素，以保持布局和视觉标识的连贯性。
• 按顺序执行状态更新：每次更新调用一个工具，然后先检查结果，再进行下一次更新。
• 每次编辑调用都保留源图像的比例。
• 编辑输入和 output_file_path 均使用绝对路径。
• 对于每次编辑调用，在清单行中记录工具调用的输入/输出：
  • Input Image（必填）
  • Output Image（除非创建分支，否则与 Image Path 相同）
• 确保每个编辑后的状态都对应一个转换元组：
  • (transition_id, trigger, from_state, to_state)
• 将每张编辑后图像使用的确切提示词保存到：
  • ui-prototypes/<prototype-name>/prompts/<platform>/<flow>/<screen>-<state>.md
• 仅编辑与状态相关的差异：
  • 悬停/焦点环
  • 按下时的立体感
  • 禁用状态的对比度
  • 加载状态的提示方式
  • 验证/成功/错误消息
• 将输出保存为：
  • ui-prototypes/<prototype-name>/images/<platform>/<flow>/<screen>-<state>.png
• 为目标平台和流程实际写入整组交互状态后，再告知已完成。

6) 维护图片/提示词清单（必需）

• 实时维护 ui-prototypes/<prototype-name>/image-prompt-manifest.md。
• 将此清单视为最新的事实来源（仅包含当前的产物集）。
• 每个图片产物添加一行（包括 default 和每个已编辑状态）。
• 每行至少记录：
  • Transition ID
  • Use Case
  • Platform
  • Flow
  • Screen
  • State
  • Trigger
  • From State
  • To State
  • Situation/Purpose
  • Image Path
  • Input Image（用于编辑）
  • Prompt Path
  • Source（Generate/Edit）
  • Parent Image（用于已编辑状态）
• 确保 images/ 中的每张图片都恰好对应一行清单记录。
• 确保每条 Edit 记录都有非空的 Input Image 和 transition tuple（Trigger、From State、To State）。
• 对于替换更新，更新现有清单记录，而不是创建新记录。
• 图片或提示词被替换或删除时，移除过时/旧版记录。
• 仅保留当前原型修订版中的有效图片/提示词对。
• 产物被删除或重命名时，立即更新/移除相应记录，确保清单与文件系统保持一一对应。
• 清单同步内容已实际写入并与当前产物保持一致后，再说明已完成。

7) 连接屏幕以支持点击模拟

• 每个平台+工作流创建一份流程图：
  • ui-prototypes/<prototype-name>/flow-maps/<platform>/<flow>.json
• 根据 ui-behavior-test-matrix.md 推导流程图转换；不要维护独立的转换定义。
• 为每条链接添加定义：
  • transition_id
  • screen
  • trigger
  • hotspot（x、y、width、height）
  • target_screen
  • transition（instant、fade、slide）
• 确保热点命名具有确定性，便于非开发人员快速审查和迭代。

8) 编制行为测试矩阵

• 创建 ui-prototypes/<prototype-name>/ui-behavior-test-matrix.md，每条转换占一行。
• 将此文件视为转换的规范事实来源。
• 包含：
  • transition_id
  • flow
  • screen
  • trigger
  • from_state
  • to_state
  • expected next state image
  • acceptance check
  • open question / risk
• 对任何触发条件的反馈不明确或缺失的阻塞问题进行标记。
• ui-behavior-test-matrix.md 已实际写入/更新后，再说明已完成。

9) 为非开发人员准备评审包

• 准备一份简洁的评审材料：
  • 可选：如果团队需要叙述性概览，可提供 ui-prototypes/<prototype-name>/ui-prototype-spec.md 摘要
  • ui-prototypes/<prototype-name>/image-prompt-manifest.md，用于追溯提示词/图片
  • ui-prototypes/<prototype-name>/flow-maps/<platform>/<flow>.json，用于点击模拟链接
  • ui-prototypes/<prototype-name>/viewer/<platform>/<flow>/ 本地点击模拟查看器文件
  • 按工作流和平台分组的图片集链接
  • 需由产品/设计团队确认的未决事项
• 尽量采用面向产品的措辞，避免使用实现层面的术语。

10) 发布本地点击模拟查看器

• 对于每组平台+工作流图片，将查看器模板复制到：
  • ui-prototypes/<prototype-name>/viewer/<platform>/<flow>/
• 配置每个查看器实例，使其加载对应的流程图文件：
  • ../../../flow-maps/<platform>/<flow>.json
• 在查看器代码中，始终从绝对基准 URL 解析流程图/图片 URL：
  • 使用 new URL(mapPath, window.location.href) 构建流程图 URL
  • 根据解析后的流程图 URL 解析每个 screens[].image
• 在本地提供工作区根目录，并打开：
  • http://localhost:4173/ui-prototypes/<prototype-name>/viewer/<platform>/<flow>/index.html
• 使用按平台/工作流划分的查看器进行产品/设计评审，以便直接评审每组图片。
• 目标平台+工作流的流程图和查看器文件已实际写入后，再说明已完成。

11) 查看器冒烟测试（必需）

• 交接前，对查看器 JavaScript 运行语法检查。
• 在本地运行项目，并至少确认：
  • 查看器页面已加载，
  • 流程图 JSON 已加载，
  • 一个引用的图像已加载，
  • 启动屏幕正常呈现，且没有 URL 解析错误。
• 如果任何检查失败，请在交付前修复查看器的路径解析问题。
• 检查完成后，口头说明查看器冒烟测试结果（Pass/Fail）。

提示词模式与检查清单

• 阅读并复用 references/prompt-patterns.md，用于：
  • UX 标准覆盖与产品基础规范
  • 生产屏幕生成与状态编辑模板
  • Shell 锁定与迭代编辑提示词模式
  • 图像/提示词清单模板与日志检查清单
  • 流程步骤与跨平台适配模板
  • 点击式流程图模板、查看器兼容性规则与验收检查清单

默认输出

• ui-prototypes/<prototype-name>/ui-behavior-test-matrix.md
• ui-prototypes/<prototype-name>/image-prompt-manifest.md
• ui-prototypes/<prototype-name>/prompts/<platform>/<flow>/*.md
• ui-prototypes/<prototype-name>/flow-maps/<platform>/<flow>.json
• ui-prototypes/<prototype-name>/viewer/<platform>/<flow>/index.html
• ui-prototypes/<prototype-name>/viewer/<platform>/<flow>/viewer.css
• ui-prototypes/<prototype-name>/viewer/<platform>/<flow>/viewer.js
• ui-prototypes/<prototype-name>/images/web/<flow>/*.png
• ui-prototypes/<prototype-name>/images/ios/<flow>/*.png
• ui-prototypes/<prototype-name>/images/android/<flow>/*.png

质量门槛

• 确保每个关键触发操作都能在一次状态转换内产生清晰、可见的反馈。
• 确保各平台和流程中的状态在视觉上保持一致。
• 确保为每个平台 + 流程明确指定纵横比，并保持一致。
• 确保生成的图像不会被归一化/拉伸而导致 UI 几何形状失真。
• 确保每张图像在 image-prompt-manifest.md 中都有对应的提示词记录。
• 确保清单仅包含最新的有效产物（不含过时的旧条目）。
• 确保每个迭代更新提示词均基于清单 Prompt Path 引用的当前提示词生成。
• 确保每张状态图像都保留 Shell 连贯性（布局/框架/间距/组件几何形状），除非已记录有意进行的结构更改。
• 确保每张编辑后的图像都有可追溯的来源链：Parent Image + Input Image +（Trigger、From State、To State）。
• 确保每个清单中的 Transition ID 都存在于 ui-behavior-test-matrix.md 中。
• 确保每个流程图转换都对应一个矩阵 transition_id，且触发语义相匹配。
• 确保已移除或失效的用例不再留有过时/已弃用的产物。
• 确保文件/文件夹名称反映最新产品愿景，并在图像、提示词、流程图和查看器之间保持一致。
• 确保错误状态和空状态包含恢复指引。
• 确保模型图中体现无障碍提示（焦点可见性、对比度意图、清晰易读的层级）。
• 确保每个流程图中的每个点击触发操作都指向有效的目标屏幕。
• 确保每个平台 + 流程的查看器中，每个可点击热点和启动屏幕的导航均正常工作。
• 确保每个平台 + 流程资源包的查看器冒烟测试均通过。

交接

• 将已批准的行为规范和状态资源交接给实现团队。
• 如果接下来需要进行工程规划，请调用 $software-engineering-workflow-skill，并将 ui-prototypes/<prototype-name>/ui-behavior-test-matrix.md、相关的 ui-prototypes/<prototype-name>/flow-maps/<platform>/<flow>.json 文件、ui-prototypes/<prototype-name>/image-prompt-manifest.md 以及查看器行为说明作为输入。
• 写入所有必需的交接产物后，口头说明最终交接已完成。