3bb2f8f1c5
* chore: wire docs/agents config into AGENTS.md Agent skills section
Add the `## Agent skills` discovery block pointing the engineering
skills at the existing docs/agents/{issue-tracker,triage-labels,domain}.md
files (issue tracker, triage label mapping, single-context domain docs).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: rebrand to GSD Core and restructure docs with Diataxis
Reorganise the root README and docs/ around the Diataxis framework
(tutorials, how-to guides, reference, explanation), add new how-to
guides and schema references (STATE.md / CONTEXT.md / PLAN.md /
planning artifacts), and cross-link the whole set. Update the lone
legacy gsd-build reference to open-gsd; keep internal get-shit-done/
filesystem paths unchanged (directory rename tracked separately in
open-gsd/gsd-core#604). Regenerate the ja-JP, ko-KR, pt-BR and zh-CN
localised trees to mirror the new structure.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: backfill changeset PR number (#605)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
150 lines
9.3 KiB
Markdown
150 lines
9.3 KiB
Markdown
# 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 デザインコントラクトを実行する
|
||
|
||
```bash
|
||
/gsd-ui-phase 2
|
||
```
|
||
|
||
フェーズ番号を省略した場合、GSD Core は現在のフェーズを対象とします。
|
||
|
||
コマンドは 2 つのステージで実行されます。
|
||
|
||
1. **`gsd-ui-researcher`** — `CONTEXT.md`、`RESEARCH.md`、`REQUIREMENTS.md` を読み込んで既存の決定事項を確認し、デザインシステムの状態（shadcn の `components.json`、Tailwind 設定、既存トークン）を検出し、スペーシング・カラー・タイポグラフィ・コピーライティング・レジストリ安全性の 5 つの領域で未回答のデザイン問題のみを確認します。
|
||
2. **`gsd-ui-checker`** — 生成された `UI-SPEC.md` を 6 つの側面で検証します。問題が発見された場合、指摘された項目のみを対象に研究者が再実行されるリビジョンループが起動します（最大 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 の初期化を提案します。フローは以下の通りです。
|
||
|
||
1. `ui.shadcn.com/create` にアクセスしてプリセット（カラー、ボーダー半径、フォント）を設定する
|
||
2. プリセット文字列をコピーする
|
||
3. 以下を実行する：
|
||
|
||
```bash
|
||
npx shadcn init --preset <paste>
|
||
```
|
||
|
||
プリセット文字列は GSD Core の計画成果物として第一級の扱いを受け、フェーズとマイルストーンを通じて再現可能です。
|
||
|
||
---
|
||
|
||
## レジストリ安全ゲート
|
||
|
||
サードパーティの shadcn レジストリは任意のコードを注入できます。`workflow.ui_safety_gate` が有効（デフォルト）な場合、非公式のコンポーネントをインストールする前に以下の手順をスペックが要求します。
|
||
|
||
```bash
|
||
npx shadcn view <component> # インストール前にソースを確認する
|
||
npx shadcn diff <component> # 公式レジストリと比較する
|
||
```
|
||
|
||
レジストリ安全性が対処されていない場合、チェッカーはスペックを BLOCKED としてフラグを立てます。プロジェクトが shadcn を使用していない場合や、別の審査プロセスがある場合は、`/gsd-settings` でゲートを無効化してください。
|
||
|
||
---
|
||
|
||
## スケッチ知見をヘッドスタートとして使う
|
||
|
||
すでに `/gsd-sketch --wrap-up` を実行済みの場合、UI リサーチャーは `.claude/skills/sketch-findings-[project]/` を自動的に読み込みます。事前に検証された決定（レイアウト・パレット・タイポグラフィ・スペーシング）はロック済みとして扱われ、再確認されません。実行開始時に以下のメモが表示されます。
|
||
|
||
```text
|
||
⚡ 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 柱標準）に対して監査します。
|
||
|
||
```bash
|
||
/gsd-ui-review # 現在のフェーズを監査する
|
||
/gsd-ui-review 3 # フェーズ 3 を監査する
|
||
```
|
||
|
||
フロントエンドコードがあるプロジェクトであれば動作します。GSD プロジェクトの初期化は必要ありません。
|
||
|
||
**確認内容（6 柱、各 1〜4 点）：**
|
||
|
||
1. コピーライティング — CTA ラベル、空の状態、エラー状態
|
||
2. ビジュアル — フォーカルポイント、ビジュアル階層、アイコンのアクセシビリティ
|
||
3. カラー — アクセント使用の規律、60/30/10 準拠
|
||
4. タイポグラフィ — フォントサイズとウェイトの制約遵守
|
||
5. スペーシング — グリッドの整合、トークンの一貫性
|
||
6. エクスペリエンスデザイン — ローディング・エラー・空の状態のカバレッジ
|
||
|
||
**出力:** スコアと優先度の高い上位 3 件の修正点を含む `{padded_phase}-UI-REVIEW.md`。`gsd-browser` などのブラウザ MCP サーバーが設定されている場合、監査はビジュアルエビデンスとしてスクリーンショットも取得します。
|
||
|
||
**スクリーンショットの保存先:** スクリーンショットは `.planning/ui-reviews/` に保存されます。バイナリファイルが git に含まれないよう、`.gitignore` が自動的に作成されます。スクリーンショットは `/gsd-complete-milestone` 実行時にクリーンアップされます。
|
||
|
||
---
|
||
|
||
## フェーズライフサイクルにおける推奨位置
|
||
|
||
```text
|
||
/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` 内のタスクは、スペックが固定したスペーシングトークン・カラー変数・コピーライティング決定を参照します。
|
||
|
||
---
|
||
|
||
## Related
|
||
|
||
- [スパイクとスケッチ](spike-and-sketch.md)
|
||
- [フェーズを計画する](plan-a-phase.md)
|
||
- [コマンドリファレンス](../COMMANDS.md)
|
||
- [ドキュメント一覧](../README.md)
|