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>
9.3 KiB
UI フェーズをデザインする方法
目標: プランナーがタスクを書く前に、スペーシング・カラー・タイポグラフィ・コピーライティングの決定を固定したロック済みの UI デザインコントラクト（UI-SPEC.md）を作成し、実行中のアドホックなスタイリング選択による視覚的な一貫性の欠如を防ぐ。
前提条件: .planning/ROADMAP.md が存在すること。フェーズにフロントエンドまたは UI 作業が含まれること。事前に /gsd-discuss-phase N を実行することを強く推奨します。UI リサーチャーは CONTEXT.md を読み込んで、すでに決定済みの事項を再確認しないようにします。
このフェーズに UI コントラクトが必要かどうかを判断する
すべてのフェーズで /gsd-ui-phase が必要なわけではありません。以下の場合に使用してください。
- フェーズが新しい UI サーフェス（ページ、フロー、レイアウト）を導入する
- 複数のコンポーネントが構築され、視覚的な一貫性が重要
- 新しいプロジェクトのフロントエンドを開始し、デザインシステムのベースラインが必要
- 既存プロジェクトに大幅な UI 作業を追加し、実行前にトークン・スペーシング・カラーを固定したい
以下の場合はスキップしてください。
- フェーズが純粋にバックエンド、インフラ、またはユーザー向け出力のないデータ作業
- 以前のフェーズの UI-SPEC.md がすでに存在し、このフェーズが新しいサーフェスを導入せず同一のビジュアルパターンで構築する
確信が持てない場合、安全ゲートが促してくれます。workflow.ui_safety_gate が有効（デフォルト）な場合、/gsd-plan-phase はフロントエンド作業を検出したが UI-SPEC.md がない場合に警告を表示し、先に /gsd-ui-phase を実行するかどうかを確認します。
UI デザインコントラクトを実行する
/gsd-ui-phase 2
フェーズ番号を省略した場合、GSD Core は現在のフェーズを対象とします。
コマンドは 2 つのステージで実行されます。
gsd-ui-researcher—CONTEXT.md、RESEARCH.md、REQUIREMENTS.mdを読み込んで既存の決定事項を確認し、デザインシステムの状態（shadcn のcomponents.json、Tailwind 設定、既存トークン）を検出し、スペーシング・カラー・タイポグラフィ・コピーライティング・レジストリ安全性の 5 つの領域で未回答のデザイン問題のみを確認します。gsd-ui-checker— 生成されたUI-SPEC.mdを 7 つの側面で検証します。問題が発見された場合、指摘された項目のみを対象に研究者が再実行されるリビジョンループが起動します（最大 2 回のイテレーション）。
出力: .planning/phases/{phase-dir}/ 内の {padded_phase}-UI-SPEC.md。
UI-SPEC がカバーする内容
リサーチャーは 5 つの領域で決定を固定します。
| 領域 | 例 |
|---|---|
| スペーシング | ベーススケール（4px または 8px）、グリッドの整合、コンポーネントのパディング |
| カラー | プライマリ・アクセント・ニュートラルパレット；60/30/10 ルール；ダークモードの考慮 |
| タイポグラフィ | フォントファミリー、サイズ・ウェイトスケールの制約、見出し階層 |
| コピーライティング | CTA ラベル、空の状態のメッセージ、エラー状態のコピー、ローディングインジケーター |
| レジストリ安全性 | shadcn コンポーネントの検査プロトコル（以下を参照） |
チェッカーは 6 つの柱（それぞれ 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> # インストール前にソースを確認する
npx shadcn diff <component> # 公式レジストリと比較する
レジストリ安全性が対処されていない場合、チェッカーはスペックを 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（またはスペックがない場合は抽象的な 6 柱標準）に対して監査します。
/gsd-ui-review # 現在のフェーズを監査する
/gsd-ui-review 3 # フェーズ 3 を監査する
フロントエンドコードがあるプロジェクトであれば動作します。GSD プロジェクトの初期化は必要ありません。
確認内容（6 柱、各 1〜4 点）：
- コピーライティング — CTA ラベル、空の状態、エラー状態
- ビジュアル — フォーカルポイント、ビジュアル階層、アイコンのアクセシビリティ
- カラー — アクセント使用の規律、60/30/10 準拠
- タイポグラフィ — フォントサイズとウェイトの制約遵守
- スペーシング — グリッドの整合、トークンの一貫性
- エクスペリエンスデザイン — ローディング・エラー・空の状態のカバレッジ
出力: スコアと優先度の高い上位 3 件の修正点を含む {padded_phase}-UI-REVIEW.md。gsd-browser などのブラウザ MCP サーバーが設定されている場合、監査はビジュアルエビデンスとしてスクリーンショットも取得します。
スクリーンショットの保存先: スクリーンショットは .planning/ui-reviews/ に保存されます。バイナリファイルが git に含まれないよう、.gitignore が自動的に作成されます。スクリーンショットは /gsd-complete-milestone 実行時にクリーンアップされます。
フェーズライフサイクルにおける推奨位置
/gsd-discuss-phase N ← 実装方針を固定する
/gsd-ui-phase N ← デザインコントラクトを固定する（フロントエンドフェーズ）
/gsd-plan-phase N ← リサーチ + 計画（UI-SPEC.md をコンテキストとして読み込む）
/gsd-execute-phase N ← 並行実行
/gsd-verify-work N ← 手動 UAT
/gsd-ui-review N ← 事後的なビジュアル監査（オプションだが推奨）
/gsd-ui-phase はディスカッションとプランの間に位置します。これはプランナーが UI-SPEC.md をデザインコンテキストとして読み込むためです。PLAN.md 内のタスクは、スペックが固定したスペーシングトークン・カラー変数・コピーライティング決定を参照します。