open-design-game-ui-handoff

Open Design 游戏 UI 交接

在请求 Open Design 进行修改之前，先打包游戏当前已有的内容。独立版本中未包含的运行时内容应视为未指定，绝不能将其视为简化的许可。

开始采集证据前，请阅读 docs/hard-rules/ui-adaptation-upgrade-only-contract.md 和 preservation-contract.md。

打包内容标准 = claude-design-handoff-generate（负责人基准）

经过实战验证的 claude-design-handoff-generate 技能是所有 Open Design 交接的内容标准——Open Design 获得的打包内容应与 Claude Design 会话相同，另加 Open Design 的增量内容。不要另行编写更精简的简报。

对于 VFX / 技能 / 武器 / 敌人 / Boss / RIG 打包内容，请先使用 claude-design-handoff-generate 构建打包内容（或复用其生成的现有 .handoff/*.zip）：包含 Owner Summary Matrix 的 README、包含已批准机制的简报、视觉正交性表（设计不得与哪些现有身份混淆，并附这些相邻对象的参考截图）、时序/节拍序列、5 张以上真实移动端 #game WebP 证明状态、reference/ 合约（负责人决策、运行时摘录、性能预算 + 标注模板、审查合约、入门清单、场景 JSON）、密度 0-100 及 100/80/50/30/0% 锚点、扇出/纹理表、图标要求，以及升级卡文案输入。缺少正交性表的简报会导致设计与已上线的身份冲突（实测：遗漏该表时，两个引擎独立重新设计出了已上线的镇魂瓮青绿色药瓶身份）。

将现有 Claude Design 交接 zip 提供给 Open Design：原样解压，内部内容一律不改动，只在旁边添加 Open Design 增量文件：

• DESIGN.md——以愿景为先的创意封面（身份、工艺标准、何为惊艳效果），指向原始 README/简报以说明范围，并指向下方的工艺文档；
• darkbone-visual-language.md + exemplar-craft.html（来自 open-design-game-ui-concept/references/）——Open Design 引擎需要 Claude Design 产品内置提供的工艺脚手架；
• 一个以预期交付物命名的占位产物文件；
• source-manifest.json，其中包含生成合约（codex / gpt-5.6-sol / ultra / 无覆盖项）；
• 对于交互式 VFX 实验室：要求提供可脚本化的审查 API（window.DARKBONE_VFX_LAB: playBeat/playCycle/setDensity/setFloor/setTargets/setSpeed/state，每个方法均返回真值），以便按节拍驱动并记录验收结果。

启动消息要求按以下顺序阅读：DESIGN.md → 工艺文档 → 原始 README/简报 → 参考合约。 对于 UI 界面，还须在此基础上遵循下方的保留合约工作流。

VFX/技能打包内容的规范步骤指南是 references/vfx-handoff-recipe.md——这是负责人批准的流程（已于 2026-07-19 在真实的巫毒魂瓶交接中验证：盲评 91/100，获负责人青睐）。请严格遵循：打包组成、DESIGN.md 封面模板、启动/开场措辞、引擎默认值、驱动视频验收，以及移交接管的流程。

工作流

0. 按表面类型分支。 UI 表面（#home/mapselect/talent/masks/fusion/victory/steam-title/HUD） 按照下方完整的保真契约工作流执行（步骤 1-9）。VFX / skill / weapon / RIG / enemy / boss 包跳过保真契约，改为遵循上文的内容标准（claude-design-handoff-generate 包 + Open Design 差异）；其验证路径是 CD 检查器，而不是 Open Design 打包器：

   make claude-design-check ARGS="validate-handoff .handoff/<id>.zip --kind=skill_vfx"
   

   Open Design 打包器（package_open_design_handoff.mjs）强制要求提供保真契约和 UI 契约配置文件 — 它仅用于 UI 交接的把关。VFX 包仍会在 od-source-manifest.json 中附带生成契约，以及 DESIGN.md 中的 DARKBONE_VFX_LAB API 要求。

1. 列出受影响的表面及每个表面的玩家任务。将 open-design-game-ui-concept/references/darkbone-visual-language.md 和 exemplar-craft.html 复制到 交接文件夹，并按愿景优先的顺序组织 DESIGN.md：第一页 = 标识、工艺标准（“匹配范例”）、该表面应有的精美效果；保真/权威说明放在后面。以约束为先的简报往往会产出呆板的 Web 仪表板。

2. 阅读当前的所有者源文件。记录可搜索的源代码锚点，涵盖标识、动态效果、交互、文案和数据。

3. 在每个目标视口和语言区域捕获当前运行时。对于每个升级或重新设计的表面，至少使用两种状态。 真正全新的表面仅在 steam-title 契约配置文件下，才可使用 baselinePolicy: new-surface-no-runtime。其 baselineStills 必须保持为空，并提供至少两个真实的 Home contextStills；此例外不得应用于现有运行时表面。

4. 使用真实的运行时视频和带时间戳的关键帧捕获动态效果关键行为。Home、Talent 投资、Fusion 揭示和 Victory/结算揭示默认属于动态效果关键项。

5. 编写 preservation-contract.json。为每个组件指定一种处理方式（preserve、upgrade、redesign 或 untouched），并为 layout、identity、motion、interaction、copy 和 data 指定权威来源。明确声明 changeScope；它必须与权威来源不是 runtime 的轴完全一致。即使独立版本省略某项或以静态代理方式呈现，changeScope 之外的每个轴也都被冻结。data 必须始终由运行时掌控。还需记录 standaloneMotionPolicy、runtimeMotionImplementation 和具体的 runtimeOwnerAnchors。由运行时掌控的动态效果必须使用 placeholder-only-preserve-runtime 和 reuse-existing-runtime；独立版本展示的是放置位置，而非替代行为。

6. 列出必须保留的特征、禁止出现的回归、未修改的细节，以及可执行的渲染对比计划，其中应包括目标视口、语言区域、状态、动态效果状态和必需的关键节点。

7. 将所有引用的证据打包到一个 .handoff/<timestamp>-<feature>/ 文件夹中。契约中不得引用任何绝对本地路径。source-manifest.json 必须包含不可覆盖的精确生成契约 { "agentId": "codex", "model": "gpt-5.6-sol", "reasoning": "ultra", "allowOverride": false }。

8. 导入 Open Design 前进行验证：

   node .agents/skills/open-design-game-ui-handoff/scripts/validate_preservation_contract.mjs \
     --contract=.handoff/<timestamp>-<feature>/preservation-contract.json
   

9. 运行父级交接打包器。它必须调用相同的语义验证器；绕过此步骤的 zip 不是有效交接。

证据规则

• 使用实际运行的应用，不要只依赖重建的 HTML 或检查源代码。
• 开发服务器截图的前置条件（截图检查会因控制台错误和图片损坏而阻止通过）： index.html 注册了 /sw.js，这是构建产物——使用 vite dev 截图前，请在 apps/game-runtime/public/sw.js 中放置一个未提交的空操作存根，否则每个场景都会因不受支持的 MIME 类型控制台错误而失败。/masks/mask-*.webp 引用的遮罩图由 R2 托管——请根据 data/artifact-manifest.json 中的 publicUrl 条目填充 apps/game-runtime/public/masks/（不提交），否则 Home/Masks/Fusion 图片断言会失败。
• 将截图和关键帧保存为压缩的 WebP。将动态画面保存为 WebM 或 MP4。
• 至少捕捉设置、峰值／变换和稳定／结果阶段。若交互和恢复阶段具有意义，也应一并捕捉。
• 将当前动画名称或运行时源代码锚点记录为辅助证据，绝不能替代视频。
• 如果组件存在减少动态效果分支，请单独捕捉减少动态效果的状态。
• 除非所有者明确要求归档，否则将制品保存在本地并加入 git 忽略列表。

拒收条件

出现以下任一情况时，拒绝交付：

• 文件夹中缺少 darkbone-visual-language.md 或 exemplar-craft.html，或者 DESIGN.md 以约束／权威内容开篇，而非创意方向；
• 重新设计的界面少于两张当前运行时截图；
• 动态效果关键界面没有视频，或带时间戳的关键帧少于三张；
• 组件隐式授予 Open Design 权限；
• 缺少 changeScope、其范围超出已分配权限，或其范围过窄；
• 纯布局任务授予 Open Design 的身份、动态效果、交互、文案或数据权限；
• 运行时拥有的动态效果未明确标记为仅占位的独立表示，或没有现有运行时实现作为依据；
• Home、Talent、Fusion 或 Victory 未在契约中列出其已知受保护的运行时组件；
• 缺少源代码锚点、证据文件、必须保留的特征或禁止出现的回归问题；
• 由于独立版本无法渲染某个现有动态组件，设计说明就将其描述为可弃用；
• 对比方案无法按视口／状态／阶段对齐当前、独立版本和未来集成版本的渲染结果。

交付物是经验证的保留契约，以及一份自包含的交接材料。它不是运行时代码。