4918c62d76
* test(#2845): failing-first suite for UI-SPEC inventory provenance Binds two shared formats before either exists, so the suite is RED against next: the gsd-ui-checker dimension roster (asserted independently on twelve surfaces, eight English and four translated) and the provenance-line grammar the UI-SPEC template emits and Dimension 7 consumes. Every parity assertion is paired with a synthetic mutation case, so the guard's failure branch executes rather than only reading a correct tree: limit-1 (a surface still declaring 6), limit (7), limit+1 (8), a dropped dimension, a label that drifts on one surface only, a non-contiguous roster, a duplicated number, and a surface that stops declaring a count at all. A seeded fast-check property renders the roster under formatting noise (CRLF, padding, interleaved sections) and asserts the parse round-trips and is strictly sensitive to a dropped heading. Assertions are on parsed typed records, never raw substrings. * docs: normalize design-a-ui-phase how-to to American English House style for docs/ is American English (CLAUDE.md). This file carried colour/initialisation/initialise/artefact throughout. Spelling only — no content change; kept separate from the #2845 feature commit so the release-notes classifier and the hotfix cherry-pick filter see it for what it is. * feat(#2845): require provenance for UI-SPEC component inventories A UI-SPEC's component inventory was treated downstream as a closed allowlist while the document recorded nothing about whether the list had been enumerated from the installed design system or recalled from memory. A recalled inventory is indistinguishable from an enumerated one, so an executor complying with the spec builds against a fraction of what the package offers, and every gate stays green because they assert semantics rather than composition. The UI-SPEC template gains a Component Inventory slot carrying one of two provenance lines: the command that enumerated the list, the count it returned, the resolved package@version and the date; or a Could not enumerate record with a real reason. gsd-ui-researcher gains an enumeration ladder and must record the line rather than write the list from recall. gsd-ui-checker gains Dimension 7. An inventory with no provenance line, a count with no command, an empty could-not-enumerate reason, or a line still carrying the template's unfilled placeholders BLOCKs; a partial line, a line placed below its table, or an honest negative record FLAGs; a complete line passes, and so does a spec carrying no inventory at all, which keeps every UI-SPEC predating the dimension validating unchanged. Whatever the verdict, an unsourced inventory is reported as a non-exhaustive list of known-good components rather than a closed allowlist, so the executor is never blocked from a component the spec merely failed to mention. The checker never runs the recorded command. The dimension count moved on all thirteen surfaces that assert it, across five languages. Also corrects the claim in the English, Korean and Portuguese how-tos that this checker applies a scored six-pillar rubric — that rubric belongs to /gsd-ui-review's retroactive audit. * chore(#2845): backfill changeset pr number to 3745 --------- Co-authored-by: sim <sim@local>
6.3 KiB
如何为阶段设计 UI
目标： 生成一份已锁定的 UI 设计契约（UI-SPEC.md），在规划者编写任务之前，确定间距、颜色、字体和文案的决策，从而防止执行阶段因随意选择样式导致视觉不一致。
前置条件： .planning/ROADMAP.md 已存在，且该阶段包含前端或 UI 工作。强烈建议先运行 /gsd-discuss-phase N——UI 研究员会读取 CONTEXT.md，以避免重复询问您已经做出的决策。
判断此阶段是否需要 UI 契约
并非所有阶段都需要 /gsd-ui-phase。在以下情况下使用它：
- 该阶段引入新的 UI 界面（页面、流程、布局）
- 将构建多个组件，且视觉一致性至关重要
- 您正在为新项目的前端建立设计系统基线
- 您正在为现有项目新增大量 UI 工作，希望在执行前锁定 token、间距和颜色
在以下情况下跳过它：
- 该阶段纯粹是后端、基础设施或数据工作，没有面向用户的输出
- 早期阶段已存在 UI-SPEC.md，且此阶段在完全相同的视觉模式上构建，不引入新界面
如果不确定，安全门会提示您：当 workflow.ui_safety_gate 启用时（默认启用），/gsd-plan-phase 在检测到前端工作但没有 UI-SPEC.md 时会发出警告，并询问是否先运行 /gsd-ui-phase。
运行 UI 设计契约
/gsd-ui-phase 2
如果未指定阶段编号，GSD Core 会以当前阶段为目标。
该命令分两个阶段运行：
gsd-ui-researcher— 读取CONTEXT.md、RESEARCH.md和REQUIREMENTS.md中的已有决策，检测设计系统状态（shadcncomponents.json、Tailwind 配置、现有 token），并仅针对以下五个领域中尚未回答的设计问题进行提问：间距、颜色、字体、文案和注册表安全。gsd-ui-checker— 从七个维度验证生成的UI-SPEC.md。如果发现问题，修订循环会重新运行研究员（最多两次迭代），专门针对被标记的项目。
输出： .planning/phases/{phase-dir}/ 中的 {padded_phase}-UI-SPEC.md。
UI-SPEC 涵盖的内容
研究员在五个领域锁定决策：
| 领域 | 示例 |
|---|---|
| 间距 | 基础比例（4px 或 8px）、网格对齐、组件内边距 |
| 颜色 | 主色、强调色、中性色调色板；60/30/10 规则；深色模式考量 |
| 字体 | 字体家族、字号/字重比例约束、标题层次结构 |
| 文案 | CTA 标签、空状态消息、错误状态文案、加载指示器 |
| 注册表安全 | shadcn 组件检查协议（见下文） |
检查器按六个支柱验证规格，每项评分 1–4：文案、视觉、颜色、字体、间距和体验设计（加载/错误/空状态覆盖）。
shadcn 初始化
对于 React、Next.js 和 Vite 项目，若未找到 components.json，研究员会提议初始化 shadcn。流程如下：
- 访问
ui.shadcn.com/create，配置您的预设（颜色、边框圆角、字体） - 复制预设字符串
- 运行：
npx shadcn init --preset <paste>
预设字符串成为 GSD Core 规划产物中的一等公民，可在各阶段和里程碑间复现。
注册表安全门
第三方 shadcn 注册表可能注入任意代码。当 workflow.ui_safety_gate 启用时（默认启用），规格要求在安装任何非官方组件之前执行以下步骤：
npx shadcn view <component> # inspect source before installing
npx shadcn diff <component> # compare against the official registry
如果未处理注册表安全问题，检查器会将规格标记为 BLOCKED。若您的项目不使用 shadcn，或您有其他审查流程，可通过 /gsd-settings 禁用此门控。
使用草图发现结果作为起点
如果您已运行 /gsd-sketch --wrap-up，UI 研究员会自动加载 .claude/skills/sketch-findings-[project]/。经过预验证的决策（布局、调色板、字体、间距）将被视为已锁定——研究员不会重新询问它们。运行开始时会显示一条提示：
⚡ Sketch findings detected: .claude/skills/sketch-findings-[project]/SKILL.md
Pre-validated decisions (layout, palette, typography, spacing) should be treated
as locked — not re-asked.
这是在 /gsd-ui-phase 之前运行 /gsd-sketch --wrap-up 的主要原因：它将对话式的设计探索转化为具有约束力的契约输入。
使用 /gsd-ui-review 进行事后视觉审计
/gsd-ui-review 在执行之后运行，而非之前。用它来对照 UI-SPEC 审计已实现的前端（当没有规格时，则对照抽象的六支柱标准进行审计）。
/gsd-ui-review # audit the current phase
/gsd-ui-review 3 # audit phase 3 specifically
它适用于任何包含前端代码的项目——不需要 GSD 项目初始化。
检查内容（六支柱，每项评分 1–4）：
- 文案 — CTA 标签、空状态、错误状态
- 视觉 — 焦点、视觉层次、图标无障碍性
- 颜色 — 强调色使用规范、60/30/10 合规性
- 字体 — 字号和字重约束遵循情况
- 间距 — 网格对齐、token 一致性
- 体验设计 — 加载、错误和空状态覆盖
输出： {padded_phase}-UI-REVIEW.md，包含评分和前三项优先修复事项。当配置了 gsd-browser 等浏览器 MCP 服务器时，审计还会捕获截图作为视觉证据。
截图存储： 截图保存至 .planning/ui-reviews/。系统会自动创建 .gitignore 以防止二进制文件提交到 git。截图会在 /gsd-complete-milestone 期间清理。
在阶段生命周期中的推荐位置
/gsd-discuss-phase N ← lock implementation preferences
/gsd-ui-phase N ← lock design contract (frontend phases)
/gsd-plan-phase N ← research + plan (reads UI-SPEC.md as context)
/gsd-execute-phase N ← parallel execution
/gsd-verify-work N ← manual UAT
/gsd-ui-review N ← retroactive visual audit (optional but recommended)
/gsd-ui-phase 位于 discuss 和 plan 之间，因为规划者会将 UI-SPEC.md 作为设计上下文读取——PLAN.md 中的任务会引用规格锁定的间距 token、颜色变量和文案决策。