从零新建 UI surface 时，用 sddesign…

当用户要求对 UI 运行 sddesign，或在设计/UI/前端工作中提到 sddesign，且要从头开始做一个 net-new surface 时适用。

适用场景

解决思路

1. 维护时注意 HARNESS MIRROR：不要在此处编辑；规范源在 skills/ 或 commands/；编辑源后复制到 cli/assets/<harness>/ 和 repo-root harness mirrors。
2. 加载 `ui-craft` skill；若也安装了 `ui-craft` skill，先读其 `SKILL.md` 获取 Discovery + Anti-Slop + Craft Test，再应用下面的特定 lens。
3. 对 `$ARGUMENTS` 运行 spec-driven design pipeline。
4. 遵守 ORCHESTRATE-ONLY RULE：本命令只编排已有 phase commands，必须不重新实现或复制它们的逻辑；每个 composition rule、wireframe algorithm、craft rule、convergence engine 都在 phase commands 中。
5. 本命令只贡献：1) gate 检测（artifact 是否存在？）；2) 提供提示（运行 phase X 或跳过？）；3) 进度报告（checklist）；4) degraded-mode honesty（跳过什么及其代价）。不确定时调用 phase command，不要内联其步骤。
6. 开始时打印 Progress Checklist，并在每个 gate 解决后更新：`[ ] brief [ ] tokens [ ] shape (spec) [ ] craft (build) [ ] converge [ ] ship`。
7. 使用标记：`[✓]` 表示 completed/skipped-with-artifact；`[>]` 表示当前 gate；`[–]` 表示 skipped-without-artifact（degraded）。
8. Gate 1 — Brief：检查 `.ui-craft/brief.md` 是否存在。
9. 若存在：标记 `[✓] brief`；注意 brief §6 learned constraints 和 a11y/correctness floor 对所有下游 gate 生效，优先于任何 spec.md composition choice。
10. 若不存在：提供现在运行 `/brief`。
11. 用户确认：运行 `/brief`；完成后标记 `[✓] brief`。
12. 用户拒绝：标记 `[–] brief`；记录下游影响：无 brief 时，craft 将使用 skill 默认值；composition 不会锚定到项目原则。
13. Gate 2 — Tokens：检查 token spine 是否存在（查找 CSS variables `--color-*`、`--font-*`、`--accent-*`，Tailwind `theme.extend` with tokens，或 token file）。
14. 若存在：标记 `[✓] tokens`。
15. 若不存在：提供现在运行 `/tokens`。
16. 用户确认：运行 `/tokens`；完成后标记 `[✓] tokens`。
17. 用户拒绝：标记 `[–] tokens`；记录下游影响：无 token spine 时，craft 将建立最小 inline token set；它不会匹配已有系统。
18. Gate 3 — Shape (spec)：在运行 `/shape` 前执行 existing-surface guard：检查 `.ui-craft/spec.md` 是否已包含此 surface 的 `## Surface: <name>` 块。
19. 若已包含：不要重跑 shape 并盲目追加重复 section；提供更新已有 section 或跳过 shape（spec 已存在）。
20. 运行 `/shape`，针对 `$ARGUMENTS` 中描述的 surface；Shape 产生其完整五步输出（content inventory、ASCII layout、state list、open questions）。
21. Persist in pipeline（默认）：在 `/sddesign` pipeline 内，shape 的 Step 6 spec persist 是默认——除非用户明确选择退出 spec gate，否则自动确认。
22. persist 写入 `.ui-craft/spec.md`（或追加 surface section）；这是 pipeline 的重点。
23. persist 完成：`.ui-craft/spec.md` 被写入（或 surface section 被追加）；标记 `[✓] shape (spec)`。
24. 用户明确退出 persist：标记 `[–] shape (spec, unsaved)`；记录下游影响：无 spec.md 时，craft (build) 将基于 shape 打印输出构建；acceptance bar 不会被持久化。
25. Gate 4 — Craft (build)：运行 `/craft <surface>`，其中 `<surface>` 匹配 `$ARGUMENTS` 中的描述。
26. `/craft` 在构建前声明 Craft Read（`references/craft-intent.md`）：surface kind、audience、theme/accent、DESIGN_VARIANCE，以及一个 signature bet。
27. signature bet 在此 gate 内构建，不推迟到 converge 或 polish。
28. 如果 spec section 指定 composition，Craft Read 必须与其一致。
29. `/craft` 在构建前加载 `.ui-craft/spec.md`。
30. 如果 `[✓] shape (spec)` 已设置，spec 选择的 composition、component inventory、state lattice、acceptance bar 优先于 recipe defaults——spec 中每个 acceptance bar item 必须在 craft 报告 done 前为 green。
31. 如果 `[–] shape (spec, unsaved)`，craft 基于打印到终端的 shape 输出构建；在 checklist 中注明。
32. 当构建完成，标记 `[✓] craft (build)`。
33. Gate 5 — Converge：运行 `../skills/ui-craft/references/loops.md` 中的 `visual-anti-slop` preset。
34. 迭代：evaluate → fix one → re-evaluate，直到 zero-critical gate 通过或预算耗尽（默认预算 3 iterations）。
35. 如果 loop gate 通过（零 critical findings）：标记 `[✓] converge`。
36. 如果预算耗尽且有 open findings：标记 `[>] converge (open findings)`；列出 loop report 中未解决的 findings。
37. Gate 6 — Ship：运行 `/finalize` verdict。
38. Finalize 根据 10-pass finish bar 和 brief/token gate 报告 READY / NOT READY / BLOCKED。
39. 打印最终 verdict 和完整 resolved checklist：`[✓] brief [✓] tokens [✓] shape (spec) [✓] craft (build) [✓] converge [✓] ship`。
40. Degraded-mode honesty：如果有任何 gate 被标记 `[–]`，在 ship verdict 中列出它们及下游影响，例如：Skipped gates: tokens (skipped) → token spine not validated; shape (spec, unsaved) → acceptance bar not persisted. These gaps reduce the ship verdict's confidence.
41. Precedence：Brief §6 learned constraints 和 a11y/correctness floor 在每个 gate 优先于 spec.md composition choices。
42. 如果 constraint 与 spec.md decision 冲突，constraint 胜出——更新 spec section 以反映胜出选择，并注明 brief §6 reference。
43. Next step：Ship；pipeline 已走 rungs 1 到 3；`.ui-craft/spec.md` 是下一次 session 的记录。

适用边界 · 注意事项

• 不是从零开始的新 surface 时不要用；它面向 net-new surface。
• 已存在同一 surface 的 `## Surface: <name>` 块时，不要重跑 `/shape` 并盲目追加重复 section；应更新已有 section 或跳过。
• 如果不需要完整流水线、spec 持久化，或只做局部样式微调，则不适用。