@namewta/speculo 0.8.6 → 0.8.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namewta/speculo",
-  "version": "0.8.6",
+  "version": "0.8.7",
   "description": "Workflow-packaged AI collaboration assets with state-safe refresh tooling.",
   "type": "module",
   "bin": {

package/template/canonical/canonical-specdev-goal-plan.md

@@ -177,7 +177,7 @@ Goal Plan 不复制 Ticket 的局部施工路线、全部文件预测或逐项
 - Tickets Map 与全部 Ticket 存在、Ready、DAG 无环；
 - 每个验收合同被 Ticket 覆盖；
 - writable/shared path 有唯一 owner，Wave 候选无写冲突；
-- config schema v5，`max_implementation_agents` 与 `max_integration_attempts` 为正整数；原型变体范围读取 planning 配置；
+- config schema v5，`max_implementation_agents` 与 `max_integration_attempts` 为正整数；UI 设计候选范围读取 planning 配置；
 - 父分支可定位，implementation commit 与本地 integration 已获授权；
 - Deep Ticket 的迁移、兼容、监控、恢复和不可逆批准点完整。
 - Ticket 与 `specdev/changes/{change}/spec.md`、`specdev/changes/{change}/ADR.md`、`specdev/adr/`、`specdev/context/` 和当前代码事实不存在未处理冲突；
@@ -558,13 +558,15 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Goal Plan | `specdev/changes/{change}/goal-plan.md` | 跨 Ticket 调度、Gate、共享所有权、迁移顺序、集成和偏差治理 | 复制 Ticket 全文 |
 | Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
 | 代码审查 | `specdev/changes/{change}/reviews/CR-###.md` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
-| 原型记录 | `specdev/changes/{change}/prototypes/{prototype-id}/record.md` | 一个问题、分支、资产、答案、promotion 和清理 | 生产实现或多个问题的计划 |
+| UI 设计包 | `specdev/changes/{change}/prototypes/{design-id}/design-system.md`、`specdev/changes/{change}/prototypes/{design-id}/comparison/` 与 `specdev/changes/{change}/prototypes/{design-id}/final/` | 项目 UI 证据、功能风格候选、逐层用户决定、设计 token、交互合同和可运行 HTML/CSS/JS 投影 | 生产 UI 实现或替用户确认高影响偏好 |
 | Stakeholder 问卷 | `specdev/changes/{change}/questionnaires/{slug}.md` | 第三方原始回答和恢复条件 | 未经转录确认的产品/架构决定 |
 | Wayfinder 地图 | `specdev/changes/{change}/wayfinder-map.md` | 目的地、说明、已关闭决策索引、战争迷雾和范围之外 | 开放 Ticket 正文或答案详情 |
 | Wayfinder Ticket | `specdev/changes/{change}/investigation/{investigation-id}.md` | 一个可精确陈述的问题、类型、阻塞和关闭状态 | 解决方案评论或交付目标 |
 | Wayfinder solution comment | `specdev/changes/{change}/investigation/comments/{investigation-id}/NN-solution.md` | Ticket 的答案、结果事实和资产指针 | 地图索引或产品实现 |
 | 架构审查 | `specdev/changes/{change}/architecture-review.md` 与 `specdev/changes/{change}/architecture-review.html` | 深化候选、证据、可视化、选择和访谈状态 | 未经用户选择的执行契约 |
 
+UI 设计包中的 `{design-id}` 由 P-prototype 分配为当前 change 内最小未占用的 `UI-NNN`；设计系统文档是唯一设计权威，comparison 与 final 不建立第二套规则。
+
 Change CONTEXT/ADR 是 active change 内的执行权威，不是 workflow 级永久知识。G 和其他设计/执行 Works 只读 `specdev/context/` 与 `specdev/adr/`；只有 A 在 change 完成、实现证据验证、毕业评估和用户确认后才能写入永久 namespace。未毕业内容随归档 change 保留，不能从 change 工件消失。
 
 ## 2. 权威顺序
@@ -850,12 +852,12 @@ Owner 原子更新 `specdev/changes/{change}/.status.json` 的 `change_status`
 
 # Dev Worktree
 
-本 Skill 由 T-tickets/P-goal-plan/I-implement 和 P-prototype 复用。`purpose=ticket` 仅在 Goal Plan 选择 `required` 时使用完整 source → candidate → parent 状态机；`current` Ticket 不调用本 Skill。`purpose=prototype` 只使用调用方批准的临时生命周期。
+本 Skill 由 T-tickets、P-goal-plan 和 I-implement 复用。仅在 Goal Plan 选择 `required` 时使用完整 source → candidate → parent 状态机；`current` Ticket 不调用本 Skill。
 
 ## 输入
 
 - `operation=create | restore | finalize | remove`；
-- `purpose=ticket | prototype`；
+- `purpose=ticket`；
 - repository、父分支、`base_sha`、branch、portable workspace locator；
 - workspace、implementation 和 integration owner；
 - 允许动作、路径合同、验证合同、调用方状态记录位置。
@@ -884,7 +886,7 @@ implementation owner 只在来源 worktree 修改授权项目路径，运行 Tic
 
 ## 4. 移除
 
-`operation=remove` 先验证 Ticket 已 `integrated` 或 prototype 已结束、目标 worktree clean、checkpoint 可恢复且删除目标精确。只有明确 cleanup 授权时删除来源 branch/worktree；强制删除需要单独确认。删除后重读 `git worktree list` 与 refs，并只把调用方生命周期状态更新为 `removed`；`base_sha`、source checkpoint、candidate/result、验证、E2E 与 Evidence 字段必须原样保留。
+`operation=remove` 先验证 Ticket 已 `integrated`、目标 worktree clean、checkpoint 可恢复且删除目标精确。只有明确 cleanup 授权时删除来源 branch/worktree；强制删除需要单独确认。删除后重读 `git worktree list` 与 refs，并只把调用方生命周期状态更新为 `removed`；`base_sha`、source checkpoint、candidate/result、验证、E2E 与 Evidence 字段必须原样保留。
 
 **完成标准**：只删除精确授权目标；失败保留现场与恢复命令。
 
@@ -910,14 +912,12 @@ implementation owner 只在来源 worktree 修改授权项目路径，运行 Tic
 - `specdev-worktree/` 已由 Speculo init 加入项目 `.gitignore`；
 - 目标 branch/worktree 不覆盖现有用户 workspace，路径合同无冲突。
 
-Prototype 只要求调用方已记录本次临时 branch/worktree 授权、问题、owner、locator 和清理策略；它不写 Ticket worktree 状态。
-
 ## 创建 Ticket 来源 worktree
 
 1. 重读父分支 HEAD、工作树、现有 worktrees 与 refs；父 HEAD 与计划基线不一致时由 Lead决定更新 `base_sha` 或阻塞；
 2. 固定 branch `speculo/<change>/<ticket-id>` 与 locator `specdev-worktree/<ticket-id>`；
 3. 确认目标 branch/path 不存在，或其实际记录精确匹配当前 Ticket；
-4. 从 `base_sha` 创建 Git worktree，不复用其他 Ticket/原型目录；
+4. 从 `base_sha` 创建 Git worktree，不复用其他 Ticket 目录；
 5. 在来源 worktree 读取项目 Agent 指令、依赖、构建与路径合同；
 6. 安装实际需要的依赖，运行最小非 E2E 基线；
 7. Lead 写入 `specdev/changes/{change}/.status.json`，状态为 `active`。
@@ -1612,8 +1612,8 @@ node "${ZIP_SCRIPT}" "${RETURN_STAGING}" \
     "default_depth": "standard",
     "require_ready_gate": true,
     "require_evidence": true,
-    "ui_prototype_default_variants": 3,
-    "ui_prototype_max_variants": 5
+    "ui_design_default_candidates": 3,
+    "ui_design_max_candidates": 4
   }
 }
 ```
@@ -1665,19 +1665,19 @@ node "${ZIP_SCRIPT}" "${RETURN_STAGING}" \
     },
     "planning": {
       "type": "object",
-      "required": ["default_depth", "require_ready_gate", "require_evidence", "ui_prototype_default_variants", "ui_prototype_max_variants"],
+      "required": ["default_depth", "require_ready_gate", "require_evidence", "ui_design_default_candidates", "ui_design_max_candidates"],
       "properties": {
         "default_depth": {"enum": ["lite", "standard", "deep"]},
         "require_ready_gate": {"type": "boolean"},
         "require_evidence": {"type": "boolean"},
-        "ui_prototype_default_variants": {"type": "integer", "minimum": 1},
-        "ui_prototype_max_variants": {"type": "integer", "minimum": 1}
+        "ui_design_default_candidates": {"type": "integer", "minimum": 2, "maximum": 4},
+        "ui_design_max_candidates": {"type": "integer", "minimum": 2, "maximum": 4}
       },
       "additionalProperties": true
     }
   },
   "allOf": [{
-    "$comment": "ui_prototype_default_variants <= ui_prototype_max_variants is enforced by validate-specdev.mjs because JSON Schema cannot compare sibling numeric values."
+    "$comment": "ui_design_default_candidates <= ui_design_max_candidates is enforced by validate-specdev.mjs because JSON Schema cannot compare sibling numeric values."
   }],
   "additionalProperties": false
 }

package/template/canonical/canonical-specdev-grill-with-docs.md

@@ -376,13 +376,15 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Goal Plan | `specdev/changes/{change}/goal-plan.md` | 跨 Ticket 调度、Gate、共享所有权、迁移顺序、集成和偏差治理 | 复制 Ticket 全文 |
 | Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
 | 代码审查 | `specdev/changes/{change}/reviews/CR-###.md` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
-| 原型记录 | `specdev/changes/{change}/prototypes/{prototype-id}/record.md` | 一个问题、分支、资产、答案、promotion 和清理 | 生产实现或多个问题的计划 |
+| UI 设计包 | `specdev/changes/{change}/prototypes/{design-id}/design-system.md`、`specdev/changes/{change}/prototypes/{design-id}/comparison/` 与 `specdev/changes/{change}/prototypes/{design-id}/final/` | 项目 UI 证据、功能风格候选、逐层用户决定、设计 token、交互合同和可运行 HTML/CSS/JS 投影 | 生产 UI 实现或替用户确认高影响偏好 |
 | Stakeholder 问卷 | `specdev/changes/{change}/questionnaires/{slug}.md` | 第三方原始回答和恢复条件 | 未经转录确认的产品/架构决定 |
 | Wayfinder 地图 | `specdev/changes/{change}/wayfinder-map.md` | 目的地、说明、已关闭决策索引、战争迷雾和范围之外 | 开放 Ticket 正文或答案详情 |
 | Wayfinder Ticket | `specdev/changes/{change}/investigation/{investigation-id}.md` | 一个可精确陈述的问题、类型、阻塞和关闭状态 | 解决方案评论或交付目标 |
 | Wayfinder solution comment | `specdev/changes/{change}/investigation/comments/{investigation-id}/NN-solution.md` | Ticket 的答案、结果事实和资产指针 | 地图索引或产品实现 |
 | 架构审查 | `specdev/changes/{change}/architecture-review.md` 与 `specdev/changes/{change}/architecture-review.html` | 深化候选、证据、可视化、选择和访谈状态 | 未经用户选择的执行契约 |
 
+UI 设计包中的 `{design-id}` 由 P-prototype 分配为当前 change 内最小未占用的 `UI-NNN`；设计系统文档是唯一设计权威，comparison 与 final 不建立第二套规则。
+
 Change CONTEXT/ADR 是 active change 内的执行权威，不是 workflow 级永久知识。G 和其他设计/执行 Works 只读 `specdev/context/` 与 `specdev/adr/`；只有 A 在 change 完成、实现证据验证、毕业评估和用户确认后才能写入永久 namespace。未毕业内容随归档 change 保留，不能从 change 工件消失。
 
 ## 2. 权威顺序
@@ -678,8 +680,8 @@ Ticket 只有同时满足以下适用条件才可设置 `ready: true`：
     "default_depth": "standard",
     "require_ready_gate": true,
     "require_evidence": true,
-    "ui_prototype_default_variants": 3,
-    "ui_prototype_max_variants": 5
+    "ui_design_default_candidates": 3,
+    "ui_design_max_candidates": 4
   }
 }
 ```
@@ -731,19 +733,19 @@ Ticket 只有同时满足以下适用条件才可设置 `ready: true`：
     },
     "planning": {
       "type": "object",
-      "required": ["default_depth", "require_ready_gate", "require_evidence", "ui_prototype_default_variants", "ui_prototype_max_variants"],
+      "required": ["default_depth", "require_ready_gate", "require_evidence", "ui_design_default_candidates", "ui_design_max_candidates"],
       "properties": {
         "default_depth": {"enum": ["lite", "standard", "deep"]},
         "require_ready_gate": {"type": "boolean"},
         "require_evidence": {"type": "boolean"},
-        "ui_prototype_default_variants": {"type": "integer", "minimum": 1},
-        "ui_prototype_max_variants": {"type": "integer", "minimum": 1}
+        "ui_design_default_candidates": {"type": "integer", "minimum": 2, "maximum": 4},
+        "ui_design_max_candidates": {"type": "integer", "minimum": 2, "maximum": 4}
       },
       "additionalProperties": true
     }
   },
   "allOf": [{
-    "$comment": "ui_prototype_default_variants <= ui_prototype_max_variants is enforced by validate-specdev.mjs because JSON Schema cannot compare sibling numeric values."
+    "$comment": "ui_design_default_candidates <= ui_design_max_candidates is enforced by validate-specdev.mjs because JSON Schema cannot compare sibling numeric values."
   }],
   "additionalProperties": false
 }

package/template/canonical/canonical-specdev-spec.md

@@ -367,13 +367,15 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Goal Plan | `specdev/changes/{change}/goal-plan.md` | 跨 Ticket 调度、Gate、共享所有权、迁移顺序、集成和偏差治理 | 复制 Ticket 全文 |
 | Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
 | 代码审查 | `specdev/changes/{change}/reviews/CR-###.md` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
-| 原型记录 | `specdev/changes/{change}/prototypes/{prototype-id}/record.md` | 一个问题、分支、资产、答案、promotion 和清理 | 生产实现或多个问题的计划 |
+| UI 设计包 | `specdev/changes/{change}/prototypes/{design-id}/design-system.md`、`specdev/changes/{change}/prototypes/{design-id}/comparison/` 与 `specdev/changes/{change}/prototypes/{design-id}/final/` | 项目 UI 证据、功能风格候选、逐层用户决定、设计 token、交互合同和可运行 HTML/CSS/JS 投影 | 生产 UI 实现或替用户确认高影响偏好 |
 | Stakeholder 问卷 | `specdev/changes/{change}/questionnaires/{slug}.md` | 第三方原始回答和恢复条件 | 未经转录确认的产品/架构决定 |
 | Wayfinder 地图 | `specdev/changes/{change}/wayfinder-map.md` | 目的地、说明、已关闭决策索引、战争迷雾和范围之外 | 开放 Ticket 正文或答案详情 |
 | Wayfinder Ticket | `specdev/changes/{change}/investigation/{investigation-id}.md` | 一个可精确陈述的问题、类型、阻塞和关闭状态 | 解决方案评论或交付目标 |
 | Wayfinder solution comment | `specdev/changes/{change}/investigation/comments/{investigation-id}/NN-solution.md` | Ticket 的答案、结果事实和资产指针 | 地图索引或产品实现 |
 | 架构审查 | `specdev/changes/{change}/architecture-review.md` 与 `specdev/changes/{change}/architecture-review.html` | 深化候选、证据、可视化、选择和访谈状态 | 未经用户选择的执行契约 |
 
+UI 设计包中的 `{design-id}` 由 P-prototype 分配为当前 change 内最小未占用的 `UI-NNN`；设计系统文档是唯一设计权威，comparison 与 final 不建立第二套规则。
+
 Change CONTEXT/ADR 是 active change 内的执行权威，不是 workflow 级永久知识。G 和其他设计/执行 Works 只读 `specdev/context/` 与 `specdev/adr/`；只有 A 在 change 完成、实现证据验证、毕业评估和用户确认后才能写入永久 namespace。未毕业内容随归档 change 保留，不能从 change 工件消失。
 
 ## 2. 权威顺序
@@ -663,8 +665,8 @@ Direct Spec Evidence 至少包含：用户批准与轻量合同、Lead、实施
     "default_depth": "standard",
     "require_ready_gate": true,
     "require_evidence": true,
-    "ui_prototype_default_variants": 3,
-    "ui_prototype_max_variants": 5
+    "ui_design_default_candidates": 3,
+    "ui_design_max_candidates": 4
   }
 }
 ```
@@ -716,19 +718,19 @@ Direct Spec Evidence 至少包含：用户批准与轻量合同、Lead、实施
     },
     "planning": {
       "type": "object",
-      "required": ["default_depth", "require_ready_gate", "require_evidence", "ui_prototype_default_variants", "ui_prototype_max_variants"],
+      "required": ["default_depth", "require_ready_gate", "require_evidence", "ui_design_default_candidates", "ui_design_max_candidates"],
       "properties": {
         "default_depth": {"enum": ["lite", "standard", "deep"]},
         "require_ready_gate": {"type": "boolean"},
         "require_evidence": {"type": "boolean"},
-        "ui_prototype_default_variants": {"type": "integer", "minimum": 1},
-        "ui_prototype_max_variants": {"type": "integer", "minimum": 1}
+        "ui_design_default_candidates": {"type": "integer", "minimum": 2, "maximum": 4},
+        "ui_design_max_candidates": {"type": "integer", "minimum": 2, "maximum": 4}
       },
       "additionalProperties": true
     }
   },
   "allOf": [{
-    "$comment": "ui_prototype_default_variants <= ui_prototype_max_variants is enforced by validate-specdev.mjs because JSON Schema cannot compare sibling numeric values."
+    "$comment": "ui_design_default_candidates <= ui_design_max_candidates is enforced by validate-specdev.mjs because JSON Schema cannot compare sibling numeric values."
   }],
   "additionalProperties": false
 }

package/template/canonical/canonical-specdev-tickets.md

@@ -654,13 +654,15 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Goal Plan | `specdev/changes/{change}/goal-plan.md` | 跨 Ticket 调度、Gate、共享所有权、迁移顺序、集成和偏差治理 | 复制 Ticket 全文 |
 | Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
 | 代码审查 | `specdev/changes/{change}/reviews/CR-###.md` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
-| 原型记录 | `specdev/changes/{change}/prototypes/{prototype-id}/record.md` | 一个问题、分支、资产、答案、promotion 和清理 | 生产实现或多个问题的计划 |
+| UI 设计包 | `specdev/changes/{change}/prototypes/{design-id}/design-system.md`、`specdev/changes/{change}/prototypes/{design-id}/comparison/` 与 `specdev/changes/{change}/prototypes/{design-id}/final/` | 项目 UI 证据、功能风格候选、逐层用户决定、设计 token、交互合同和可运行 HTML/CSS/JS 投影 | 生产 UI 实现或替用户确认高影响偏好 |
 | Stakeholder 问卷 | `specdev/changes/{change}/questionnaires/{slug}.md` | 第三方原始回答和恢复条件 | 未经转录确认的产品/架构决定 |
 | Wayfinder 地图 | `specdev/changes/{change}/wayfinder-map.md` | 目的地、说明、已关闭决策索引、战争迷雾和范围之外 | 开放 Ticket 正文或答案详情 |
 | Wayfinder Ticket | `specdev/changes/{change}/investigation/{investigation-id}.md` | 一个可精确陈述的问题、类型、阻塞和关闭状态 | 解决方案评论或交付目标 |
 | Wayfinder solution comment | `specdev/changes/{change}/investigation/comments/{investigation-id}/NN-solution.md` | Ticket 的答案、结果事实和资产指针 | 地图索引或产品实现 |
 | 架构审查 | `specdev/changes/{change}/architecture-review.md` 与 `specdev/changes/{change}/architecture-review.html` | 深化候选、证据、可视化、选择和访谈状态 | 未经用户选择的执行契约 |
 
+UI 设计包中的 `{design-id}` 由 P-prototype 分配为当前 change 内最小未占用的 `UI-NNN`；设计系统文档是唯一设计权威，comparison 与 final 不建立第二套规则。
+
 Change CONTEXT/ADR 是 active change 内的执行权威，不是 workflow 级永久知识。G 和其他设计/执行 Works 只读 `specdev/context/` 与 `specdev/adr/`；只有 A 在 change 完成、实现证据验证、毕业评估和用户确认后才能写入永久 namespace。未毕业内容随归档 change 保留，不能从 change 工件消失。
 
 ## 2. 权威顺序
@@ -966,12 +968,12 @@ Direct Spec Evidence 至少包含：用户批准与轻量合同、Lead、实施
 
 # Dev Worktree
 
-本 Skill 由 T-tickets/P-goal-plan/I-implement 和 P-prototype 复用。`purpose=ticket` 仅在 Goal Plan 选择 `required` 时使用完整 source → candidate → parent 状态机；`current` Ticket 不调用本 Skill。`purpose=prototype` 只使用调用方批准的临时生命周期。
+本 Skill 由 T-tickets、P-goal-plan 和 I-implement 复用。仅在 Goal Plan 选择 `required` 时使用完整 source → candidate → parent 状态机；`current` Ticket 不调用本 Skill。
 
 ## 输入
 
 - `operation=create | restore | finalize | remove`；
-- `purpose=ticket | prototype`；
+- `purpose=ticket`；
 - repository、父分支、`base_sha`、branch、portable workspace locator；
 - workspace、implementation 和 integration owner；
 - 允许动作、路径合同、验证合同、调用方状态记录位置。
@@ -1000,7 +1002,7 @@ implementation owner 只在来源 worktree 修改授权项目路径，运行 Tic
 
 ## 4. 移除
 
-`operation=remove` 先验证 Ticket 已 `integrated` 或 prototype 已结束、目标 worktree clean、checkpoint 可恢复且删除目标精确。只有明确 cleanup 授权时删除来源 branch/worktree；强制删除需要单独确认。删除后重读 `git worktree list` 与 refs，并只把调用方生命周期状态更新为 `removed`；`base_sha`、source checkpoint、candidate/result、验证、E2E 与 Evidence 字段必须原样保留。
+`operation=remove` 先验证 Ticket 已 `integrated`、目标 worktree clean、checkpoint 可恢复且删除目标精确。只有明确 cleanup 授权时删除来源 branch/worktree；强制删除需要单独确认。删除后重读 `git worktree list` 与 refs，并只把调用方生命周期状态更新为 `removed`；`base_sha`、source checkpoint、candidate/result、验证、E2E 与 Evidence 字段必须原样保留。
 
 **完成标准**：只删除精确授权目标；失败保留现场与恢复命令。
 
@@ -1026,14 +1028,12 @@ implementation owner 只在来源 worktree 修改授权项目路径，运行 Tic
 - `specdev-worktree/` 已由 Speculo init 加入项目 `.gitignore`；
 - 目标 branch/worktree 不覆盖现有用户 workspace，路径合同无冲突。
 
-Prototype 只要求调用方已记录本次临时 branch/worktree 授权、问题、owner、locator 和清理策略；它不写 Ticket worktree 状态。
-
 ## 创建 Ticket 来源 worktree
 
 1. 重读父分支 HEAD、工作树、现有 worktrees 与 refs；父 HEAD 与计划基线不一致时由 Lead决定更新 `base_sha` 或阻塞；
 2. 固定 branch `speculo/<change>/<ticket-id>` 与 locator `specdev-worktree/<ticket-id>`；
 3. 确认目标 branch/path 不存在，或其实际记录精确匹配当前 Ticket；
-4. 从 `base_sha` 创建 Git worktree，不复用其他 Ticket/原型目录；
+4. 从 `base_sha` 创建 Git worktree，不复用其他 Ticket 目录；
 5. 在来源 worktree 读取项目 Agent 指令、依赖、构建与路径合同；
 6. 安装实际需要的依赖，运行最小非 E2E 基线；
 7. Lead 写入 `specdev/changes/{change}/.status.json`，状态为 `active`。
@@ -1194,8 +1194,8 @@ Prototype 只要求调用方已记录本次临时 branch/worktree 授权、问
     "default_depth": "standard",
     "require_ready_gate": true,
     "require_evidence": true,
-    "ui_prototype_default_variants": 3,
-    "ui_prototype_max_variants": 5
+    "ui_design_default_candidates": 3,
+    "ui_design_max_candidates": 4
   }
 }
 ```
@@ -1247,19 +1247,19 @@ Prototype 只要求调用方已记录本次临时 branch/worktree 授权、问
     },
     "planning": {
       "type": "object",
-      "required": ["default_depth", "require_ready_gate", "require_evidence", "ui_prototype_default_variants", "ui_prototype_max_variants"],
+      "required": ["default_depth", "require_ready_gate", "require_evidence", "ui_design_default_candidates", "ui_design_max_candidates"],
       "properties": {
         "default_depth": {"enum": ["lite", "standard", "deep"]},
         "require_ready_gate": {"type": "boolean"},
         "require_evidence": {"type": "boolean"},
-        "ui_prototype_default_variants": {"type": "integer", "minimum": 1},
-        "ui_prototype_max_variants": {"type": "integer", "minimum": 1}
+        "ui_design_default_candidates": {"type": "integer", "minimum": 2, "maximum": 4},
+        "ui_design_max_candidates": {"type": "integer", "minimum": 2, "maximum": 4}
       },
       "additionalProperties": true
     }
   },
   "allOf": [{
-    "$comment": "ui_prototype_default_variants <= ui_prototype_max_variants is enforced by validate-specdev.mjs because JSON Schema cannot compare sibling numeric values."
+    "$comment": "ui_design_default_candidates <= ui_design_max_candidates is enforced by validate-specdev.mjs because JSON Schema cannot compare sibling numeric values."
   }],
   "additionalProperties": false
 }

package/template/canonical/canonical-specdev-wayfinder.md

@@ -49,7 +49,7 @@ Wayfinder 默认进行**规划**：每个 Ticket 解决一个决策，当地图
 每个 Ticket 要么是 **HITL**，与一个代表自己发言的人类一起工作；要么是 **AFK**，由 Agent 独立驱动。HITL Ticket 只能通过实时交流解决，Agent 绝不代替人类一方发言。
 
 - **Research（AFK）**：阅读文档、第三方 API 或知识库等资源，揭示某个决策等待的事实。调用 下方 `<research>` 标签。当需要当前工作目录之外的知识时使用。
-- **Prototype（HITL）**：调用 “原型阶段” 回答一个 UI/逻辑问题，并把 record、临时 branch/worktree 和运行 URL 链接为 solution comment 资产；P 不实现目的地。
+- **Prototype（HITL）**：调用 “原型阶段” 检测项目 UI、比较功能风格候选并逐步确认设计方向，把 `specdev/changes/{change}/prototypes/{design-id}/design-system.md` 与 comparison locator 链接为 solution comment 资产；`{design-id}` 使用 P 返回的 `UI-NNN`，P 不实现目的地。
 - **Grilling（HITL）**：对话。调用 “设计访谈能力” 的 grilling 与 domain-modeling 能力，但本会话只关闭当前 Wayfinder Ticket。
 - **Task（HITL 或 AFK）**：在决策做出前必须完成的手动工作。它通过为决策解除阻塞赢得位置，不以交付目的地为目标。Agent 能独立驱动时使用 AFK，否则给人类精确清单。
 
@@ -346,8 +346,8 @@ resolution: answered
     "default_depth": "standard",
     "require_ready_gate": true,
     "require_evidence": true,
-    "ui_prototype_default_variants": 3,
-    "ui_prototype_max_variants": 5
+    "ui_design_default_candidates": 3,
+    "ui_design_max_candidates": 4
   }
 }
 ```
@@ -399,19 +399,19 @@ resolution: answered
     },
     "planning": {
       "type": "object",
-      "required": ["default_depth", "require_ready_gate", "require_evidence", "ui_prototype_default_variants", "ui_prototype_max_variants"],
+      "required": ["default_depth", "require_ready_gate", "require_evidence", "ui_design_default_candidates", "ui_design_max_candidates"],
       "properties": {
         "default_depth": {"enum": ["lite", "standard", "deep"]},
         "require_ready_gate": {"type": "boolean"},
         "require_evidence": {"type": "boolean"},
-        "ui_prototype_default_variants": {"type": "integer", "minimum": 1},
-        "ui_prototype_max_variants": {"type": "integer", "minimum": 1}
+        "ui_design_default_candidates": {"type": "integer", "minimum": 2, "maximum": 4},
+        "ui_design_max_candidates": {"type": "integer", "minimum": 2, "maximum": 4}
       },
       "additionalProperties": true
     }
   },
   "allOf": [{
-    "$comment": "ui_prototype_default_variants <= ui_prototype_max_variants is enforced by validate-specdev.mjs because JSON Schema cannot compare sibling numeric values."
+    "$comment": "ui_design_default_candidates <= ui_design_max_candidates is enforced by validate-specdev.mjs because JSON Schema cannot compare sibling numeric values."
   }],
   "additionalProperties": false
 }

package/template/workflows/specdev/I-init-setup/I-init-setup.md

@@ -55,7 +55,7 @@ keywords: [初始化, 配置, status, tracking, 验证命令]
 仅在上下文未提供时询问：
 
 - 交互语言与持久化工件语言；
-- implementation subagent、集成尝试次数和原型变体上限（初始化时写入 config，Lead 不计入）；
+- implementation subagent、集成尝试次数和 UI 设计候选上限（初始化时写入 config，Lead 不计入）；
 - Deep Ticket 的迁移、发布和不可逆操作是否必须人工批准；
 
 不询问可由仓库事实回答的文件位置、脚本名或默认分支。

package/template/workflows/specdev/I-init-setup/config-template.json

@@ -21,7 +21,7 @@
     "default_depth": "standard",
     "require_ready_gate": true,
     "require_evidence": true,
-    "ui_prototype_default_variants": 3,
-    "ui_prototype_max_variants": 5
+    "ui_design_default_candidates": 3,
+    "ui_design_max_candidates": 4
   }
 }

package/template/workflows/specdev/P-goal-plan/planning-modes.md

@@ -10,7 +10,7 @@
 - Tickets Map 与全部 Ticket 存在、Ready、DAG 无环；
 - 每个验收合同被 Ticket 覆盖；
 - writable/shared path 有唯一 owner，Wave 候选无写冲突；
-- config schema v5，`max_implementation_agents` 与 `max_integration_attempts` 为正整数；原型变体范围读取 planning 配置；
+- config schema v5，`max_implementation_agents` 与 `max_integration_attempts` 为正整数；UI 设计候选范围读取 planning 配置；
 - 父分支可定位，implementation commit 与本地 integration 已获授权；
 - Deep Ticket 的迁移、兼容、监控、恢复和不可逆批准点完整。
 - Ticket 与 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`、`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`、`<Path>{roots.state}/specdev/adr/</Path>`、`<Path>{roots.state}/specdev/context/</Path>` 和当前代码事实不存在未处理冲突；

package/template/workflows/specdev/P-prototype/P-prototype.md

@@ -2,47 +2,51 @@
 id: specdev/prototype
 type: workflow-entry
 workflow: specdev
-name: 原型
-description: 在获授权的临时 branch/worktree 中构建一次性 Logic 或 UI 原型，回答一个明确设计问题并持久化答案、资产定位和清理状态。
-keywords: [prototype, 原型, logic, UI, variant, 一次性代码, 设计问题]
+name: UI 设计原型
+description: 检测现有项目的 UI 事实，按产品任务推荐并逐步选择设计风格，生成持久化设计系统文档、多风格 HTML 对照和可运行 HTML/CSS/JS 原型。
+keywords: [prototype, UI 原型, 风格检测, 设计系统, HTML, CSS, 交互, design tokens]
 ---
 
-# 原型
+# UI 设计原型
 
 > 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
 
-原型是**回答一个问题的一次性代码**。P 不交付生产实现，也不把原型代码提升到 main；它把答案和一手资料 locator 交给后续 G/S/Tickets/I。
+本 Work 的主导词是**设计定向**：先从项目事实识别现状，再让用户看到基于功能而非流行色推荐的候选，最后把选择固化为既可阅读又可运行的 UI 设计包。P 不修改生产 UI；后续 S、Tickets 和 I 以设计包为视觉与交互权威。
 
 ## 输入与所有权
 
-- 一个可精确陈述的问题，来自用户、G、Spec 或 `<Path>{roots.state}/specdev/changes/{change}/investigation/{investigation-id}.md</Path>`；
-- 相关代码、组件系统、领域上下文和 ADR；
-- 获授权的项目可写范围及临时 branch/worktree。
+- 必需输入：目标项目或新产品设想、核心用户任务，以及当前 SpecDev change。
+- 可选输入：现有代码、页面、截图、设计 token、品牌约束、ADR、Spec、调查和用户明确给出的参考产品。
+- 项目事实权威：依赖清单、样式源码、组件实现、路由、真实页面、测试和可复现截图；仅凭依赖名称不得断言实际风格。
+- 用户决定权威：产品方向、候选风格、密度、色调、字体气质、圆角、交互反馈和跨端优先级。
 
-P 拥有 `<Path>{roots.state}/specdev/changes/{change}/prototypes/{prototype-id}/record.md</Path>`。代码写在临时 workspace 的项目路径附近；state 只保存项目相对 Path、branch、commit 和可迁移 `workspace_ref`。
+P 拥有 `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/</Path>`。其中 `design-id` 使用当前 change 内最小未占用的 `UI-NNN`；目录中的设计系统主文档是唯一设计权威，comparison 和 final 文件均由它或其中已记录的候选决定派生。P 不写永久 research namespace，不创建 branch/worktree，不提交生产代码。
 
 ## 流程
 
-1. **锁定问题**：一个 record 只回答一个问题。业务逻辑、状态转换或数据形态使用 Logic；页面外观、信息层级或交互布局使用 UI。问题含糊且用户不在线时按周围代码选择，并在 record 写明假设。
-2. **建立临时工作区**：按 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>` 创建/恢复工作区。创建 branch、commit 或删除 worktree 分别遵守现有授权边界；路径名明确包含 prototype。
-3. **执行分支**：Logic 加载 `<Path>{roots.workflows}/specdev/P-prototype/logic-prototype.md</Path>`；UI 加载 `<Path>{roots.workflows}/specdev/P-prototype/ui-prototype.md</Path>`。两个分支都把完整状态呈现给评审者，不依赖生产数据写入。
-4. **捕获答案**：使用 `<Path>{roots.workflows}/specdev/P-prototype/prototype-record-template.md</Path>` 记录问题、运行方法、资产、验证反馈、赢家/拒绝项、结论、promotion target 和清理状态，原子重读。
-5. **关闭或阻塞**：答案已确认时 `status: answered`；用户选择不继续时 `discarded`；原型无法回答问题时 `blocked` 并说明缺失输入。Wayfinder 调用时，把 record/branch/URL 写入当前 Ticket 的 solution comment，并只关闭该 Ticket。
-6. **验证与路由**：使用 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>` 的 `--stage prototype` 校验当前 change。需要产品决定返回 G，需要外部行为合同返回 S，需要执行计划返回 Tickets；生产实现只进入 I。
+1. **创建或恢复设计包**：读取 change 与 `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/design-system.md</Path>`。不存在时从 `<Path>{roots.workflows}/specdev/P-prototype/design-system-template.md</Path>` 创建，写入 `status: detecting` 并原子重读；存在时只询问尚未确认的高影响选择。
+2. **检测现有风格**：加载 `<Path>{roots.workflows}/specdev/P-prototype/detect-existing-style.md</Path>`，穷尽技术栈、布局、视觉 token、组件状态、响应式与可访问性证据。新项目明确记录 `project_kind: new`，不伪造检测结果。
+3. **建立功能候选**：读取 `<Path>{roots.workflows}/specdev/P-prototype/design-library/INDEX.md</Path>`，依据产品任务、平台和信息密度从八种风格及六种布局中推荐 2-4 个候选。每个候选写明适合原因、需要保留/调整/替换的现有事实、参考项目和迁移成本。
+4. **逐项选择并持久化**：加载 `<Path>{roots.workflows}/specdev/P-prototype/style-selection-protocol.md</Path>`。每轮只处理一个决策层；每个答案立即写回设计系统主文档并重读。高影响偏好未确认时保持 `status: selecting`，不得自行标记 Ready。
+5. **生成可视对照与最终原型**：加载 `<Path>{roots.workflows}/specdev/P-prototype/generate-design-package.md</Path>`。为每个候选生成独立 comparison variant，再生成 comparison 索引。用户确认或明确组合后，把最终 HTML/CSS/JS 作为具名代码块写入设计系统主文档，再物化到 final 目录。
+6. **验证并封板**：运行 `<Path>{roots.workflows}/specdev/P-prototype/tools/materialize-prototype.mjs</Path> --check` 和 `<Path>{roots.workflows}/specdev/P-prototype/tools/validate-design-package.mjs</Path>`；随后运行 SpecDev `--stage prototype`。全部通过且选择闭合后设置 `status: ready`，更新 `works_run` 并清空 `current_work`。缺少项目事实或用户决定时设置 `blocked` 并保留恢复位置。
+7. **返回路由**：返回设计包、comparison 和 final 的完整路径、验证命令与结果、未决问题和下一 Work。需要补足产品决定时返回 G；需要写外部行为合同返回 S；需要拆实施工作返回 Tickets；已有 Ready Ticket 才返回 I。Wayfinder 调用时只把设计包与 comparison locator 写入对应 solution comment。
 
 ## 完成标准
 
-- 只有一个问题和一个正确分支；
-- 原型极易运行，完整状态可见；
-- 临时 branch/worktree 与项目路径可恢复且不含机器绝对路径；
-- 原型没有测试、生产数据库依赖或伪装成生产代码；
-- 答案、资产、赢家、拒绝项、promotion target 和清理状态完整；
-- main 不保留落选变体、switcher 或原型外壳；
-- Wayfinder Ticket、solution comment 与 prototype record 可互相定位。
+- 现有项目的检测结论逐项有项目相对证据；新项目明确没有既有风格。
+- 候选由功能、平台和密度推导，不只更换颜色；用户已看到每个候选的独立 HTML。
+- 设计系统主文档完整包含 UI 结构、CSS token、交互 JS 和最终 HTML 源码，并记录研究出处与拒绝理由。
+- comparison 索引可导航到 2-4 个候选，final HTML 可离线运行；桌面与移动宽度不存在空白、遮挡或无意横向溢出。
+- 字体、间距、圆角、色彩、层级、控件状态、异步反馈、响应式、键盘、focus 和 reduced motion 均有明确合同。
+- Markdown 代码块与 `final/` 文件逐字一致，schema、局部校验和 SpecDev stage 校验全部通过。
+- 设计包不包含机器绝对路径、敏感值、生产数据写入、发布动作或未授权的生产实现。
 
 ## 子文件引用
 
-- Logic：`<Path>{roots.workflows}/specdev/P-prototype/logic-prototype.md</Path>`
-- UI：`<Path>{roots.workflows}/specdev/P-prototype/ui-prototype.md</Path>`
-- Record：`<Path>{roots.workflows}/specdev/P-prototype/prototype-record-template.md</Path>`
-- Schema：`<Path>{roots.workflows}/specdev/common/schemas/prototype-record.schema.json</Path>`
+- 检测：`<Path>{roots.workflows}/specdev/P-prototype/detect-existing-style.md</Path>`，仅在步骤 2 加载。
+- 选择：`<Path>{roots.workflows}/specdev/P-prototype/style-selection-protocol.md</Path>`，仅在步骤 4 加载。
+- 生成：`<Path>{roots.workflows}/specdev/P-prototype/generate-design-package.md</Path>`，仅在步骤 5 加载。
+- 模板：`<Path>{roots.workflows}/specdev/P-prototype/design-system-template.md</Path>`，创建设计包时加载。
+- 设计库：`<Path>{roots.workflows}/specdev/P-prototype/design-library/INDEX.md</Path>`，建立候选或查具体规则时渐进读取。
+- Schema：`<Path>{roots.workflows}/specdev/P-prototype/design-package.schema.json</Path>`。

package/template/workflows/specdev/P-prototype/design-library/INDEX.md

@@ -0,0 +1,43 @@
+# P-prototype 设计库
+
+本目录是 P-prototype 的静态设计参考层。它帮助 UI 原型先按任务、对象、密度和平台选择结构，再选择视觉表达；它不拥有运行时状态，不替代项目现有设计系统，也不授权修改生产代码。
+
+研究快照固定在 commit `49b565913c52f4867456e609696625157f19b930`。快照是证据与可运行样板，不在原型过程中原地修改；需要复用时，把所需 HTML/CSS/JS/图片和 attribution 复制到当前 change 的设计包。
+
+## 渐进披露入口
+
+| 当前问题 | 读取 | 读完应得到 |
+|---|---|---|
+| 先决定信息架构、密度和组件边界 | `<Path>{roots.workflows}/specdev/P-prototype/design-library/foundations.md</Path>` | 一个主布局范式、密度档和设计系统边界 |
+| 在八种可运行风格中选择起点 | `<Path>{roots.workflows}/specdev/P-prototype/design-library/style-index.md</Path>` | 一个主风格、必要时一个受控对照风格 |
+| 寻找相似产品及其真实模式 | `<Path>{roots.workflows}/specdev/P-prototype/design-library/product-pattern-index.md</Path>` | 对应项目、可借鉴模式和一手研究路径 |
+| 定义浅色/深色、语义 token、字号与层级 | `<Path>{roots.workflows}/specdev/P-prototype/design-library/color-and-theme.md</Path>` | 可实现的主题与密度假设 |
+| 设计导航、表格、表单、反馈或危险操作 | `<Path>{roots.workflows}/specdev/P-prototype/design-library/interaction-patterns.md</Path>` | 完整状态和验证动作 |
+| 需要窄屏、触屏、桌面/Web/移动重排 | `<Path>{roots.workflows}/specdev/P-prototype/design-library/responsive-and-platforms.md</Path>` | 每个平台的任务职责和断点行为 |
+| 需要引用、复制资产或判断证据强度/许可 | `<Path>{roots.workflows}/specdev/P-prototype/design-library/research-provenance.md</Path>` | 可追溯来源、复用边界和 attribution |
+
+## 使用顺序
+
+1. 检测现有项目或明确新产品设想，并列出核心对象、最常见的 3-5 个任务、目标输入设备和最坏数据状态。
+2. 读取 foundations，选择一个主布局范式。不要先按品牌色、圆角或流行风格选择页面。
+3. 读取 style-index，按功能推荐 2-4 个结构不同的候选，并为每个候选生成独立 comparison HTML。
+4. 读取 product-pattern-index，只深入与当前对象、任务或平台相似的项目研究；星标不构成设计质量或许可结论。
+5. 只加载当前问题涉及的 theme、interaction 或 responsive 文件。精确值必须能回到 snapshot 中的 token、CSS 或研究证据。
+6. 复制样板时保留相对目录关系和所需 attribution；把 demo 名称、权限、Git、同步与审批状态替换为原型自己的假数据，不把演示逻辑当作真实业务逻辑。
+7. 用真实极端数据、键盘、目标宽度和浅/深主题验证。选择、拒绝理由和最终源码进入设计系统主文档，设计库本身保持不变。
+
+## 快照入口
+
+- 总报告：`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/report/OPEN_SOURCE_UI_RESEARCH_2026.md</Path>`
+- 八种风格总览：`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/ui-gallery/index.html</Path>`
+- 样板使用说明：`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/ui-gallery/README.md</Path>`
+- 结构化项目数据：`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/data/projects.json</Path>` 与 `<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/data/extended-projects.json</Path>`
+- 综合 token：`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/reference/design-tokens.css</Path>`
+
+## 完成门
+
+- 选择理由落在任务模型、信息密度、输入设备和状态复杂度，而不是“看起来像”；
+- 一个布局范式和一个主风格已明确，所有新增 token 都有语义角色；
+- loading、empty、no-results、error、offline、read-only、permission 与长文本按适用性逐项处理；
+- 窄屏改变任务流而非压缩桌面多栏；
+- 引用与复制均可回到固定 commit、研究文件和 attribution。

package/template/workflows/specdev/P-prototype/design-library/color-and-theme.md

@@ -0,0 +1,65 @@
+# 色彩、主题与视觉层级
+
+视觉系统先定义角色，再选择色值。固定快照中的 `<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/reference/design-tokens.css</Path>` 是跨项目综合起点，不是任何单一产品的 token 复制品。
+
+## 最小语义集合
+
+```text
+canvas
+surface-1 / surface-2 / surface-3 / overlay
+text-primary / text-secondary / text-tertiary / text-disabled
+border-subtle / border-default / border-strong
+accent / accent-hover / accent-subtle / accent-contrast
+success / warning / danger / info (+ subtle variants)
+hover / selected / pressed / focus-ring / scrim
+```
+
+业务组件消费语义角色，不直接写 `#fff`、`black` 或任意透明度。品牌 accent 只服务主要动作、选中和链接；状态色必须同时配图标、文本或形状。数据可视化色板、Git diff、syntax highlight 和业务状态分别建组，不复用 UI accent 充当所有含义。
+
+## 浅色与深色
+
+- 两种主题一起设计，不把深色简单反相。深色 overlay 往往比基础表面更亮，边框和语义色需要重新分配明度与对比。
+- 分别检查正文、次要文字、图标、边框、focus ring 和状态，而不只检查按钮。
+- 中性色保持低 chroma，避免所有表面都带强品牌倾向。
+- 用户切换主题时保持布局、选择、输入和面板尺寸；主题改变不应触发内容重排。
+- 高对比需求不能只靠增加饱和度，应重新检查边界、文字与焦点。
+
+## 字体和密度
+
+| 角色 | 字号/行高起点 |
+|---|---|
+| 坐标、元数据、辅助标签 | 11-12px / 16px；不承载长文本、错误原因或主要操作 |
+| 表格、侧栏、紧凑控件 | 13px / 18-20px |
+| 默认 UI 正文与表单 | 14px / 20px |
+| 内容正文 | 15-16px / 24-26px |
+| 小节/弹窗标题 | 16-18px / 22-26px |
+| 页面标题 | 20-24px / 28-32px |
+
+工具界面不使用营销页级大标题。数字表格可启用 tabular numerals，代码/SQL/ID 使用 mono；中英文混排单独验证 CJK 回退和行高。不使用负字距挤压 UI，长名称通过布局、换行或中间截断处理。
+
+| 密度 | 控件高度 | 表格行高 | 典型任务 |
+|---|---:|---:|---|
+| Compact | 28px | 32px | SQL、日志、开发工具 |
+| Default | 32-36px | 36-40px | CRM、项目管理、后台 |
+| Comfortable | 40px | 44-48px | 文档、协作、低频表单 |
+| Touch | 44-48px | 48-52px | 移动与触屏 |
+
+## 圆角、边框与阴影
+
+- 2-4px：代码块、表格小元素、密集工具按钮。
+- 4-6px：输入、按钮、菜单项、紧凑面板。
+- 6-8px：普通卡片、popover、较大控件。
+- 8-12px：dialog、sheet、移动大容器；移动样板可因触屏语言使用更大值。
+- pill：状态徽标、分段选择滑块或真正胶囊语义，不用于所有按钮。
+
+同一视觉层只保留 2-3 个主圆角。常驻页面分区、侧栏、表格和检查器用 1px 边框或背景差建立层级，不用浮卡阴影；popover/menu 使用清晰边框和中等阴影；dialog 使用 scrim 与较大阴影；focus ring 独立于层级阴影。hover、selected、pressed 必须是不同 token。
+
+## 原型验证
+
+- 浅色、深色、200% 缩放和常见色觉差异下，文本与状态仍可区分；
+- 页面没有绕过 token 的随机颜色、圆角和阴影；
+- 状态不只依赖颜色；
+- 最长名称、中文、数字和错误文案不会撑坏控件；
+- reduced motion 时 token 中的 UI duration 降为零或对应交互停止非必要动画。
+
+八种具体 `.theme-*` 实现在 `<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/ui-gallery/styles/pages.css</Path>`，综合 token 的使用约束在 `<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/reference/USAGE.md</Path>`。