Files

Jakub Zych a9a7a328e6 refactor: hard-fork GSD -> MSD (Make Software Done)

Mechanical rename produced by scripts/msd-rename.cjs: gsd/Gsd/GSD -> msd/Msd/MSD
across contents and paths, upstream package/repo coordinates -> @golem15/msd-core
and golem15com/msd-core. Deep links into upstream history, sibling upstream
packages, the GSD-2 import feature, CHANGELOG.md and .changeset/ are kept as-is.

Hand edits on top: MSD block-letter banner and logos, LICENSE copyright line,
package/plugin identity, regenerated lockfile, install-tree fixtures, derived
registries and benchmark baseline; migration checksum baseline re-locked
(MSD keeps its own install state, so no install had applied the old sums);
sort-order and regex-escaped expectations in tests adjusted.

2026-10-06 01:47:40 +02:00

9.3 KiB

Raw Permalink Blame History

UI フェーズをデザインする方法

目標: プランナーがタスクを書く前に、スペーシング・カラー・タイポグラフィ・コピーライティングの決定を固定したロック済みの UI デザインコントラクト（UI-SPEC.md）を作成し、実行中のアドホックなスタイリング選択による視覚的な一貫性の欠如を防ぐ。

前提条件: .planning/ROADMAP.md が存在すること。フェーズにフロントエンドまたは UI 作業が含まれること。事前に /msd-discuss-phase N を実行することを強く推奨します。UI リサーチャーは CONTEXT.md を読み込んで、すでに決定済みの事項を再確認しないようにします。

このフェーズに UI コントラクトが必要かどうかを判断する

すべてのフェーズで /msd-ui-phase が必要なわけではありません。以下の場合に使用してください。

フェーズが新しい UI サーフェス（ページ、フロー、レイアウト）を導入する
複数のコンポーネントが構築され、視覚的な一貫性が重要
新しいプロジェクトのフロントエンドを開始し、デザインシステムのベースラインが必要
既存プロジェクトに大幅な UI 作業を追加し、実行前にトークン・スペーシング・カラーを固定したい

以下の場合はスキップしてください。

フェーズが純粋にバックエンド、インフラ、またはユーザー向け出力のないデータ作業
以前のフェーズの UI-SPEC.md がすでに存在し、このフェーズが新しいサーフェスを導入せず同一のビジュアルパターンで構築する

確信が持てない場合、安全ゲートが促してくれます。workflow.ui_safety_gate が有効（デフォルト）な場合、/msd-plan-phase はフロントエンド作業を検出したが UI-SPEC.md がない場合に警告を表示し、先に /msd-ui-phase を実行するかどうかを確認します。

UI デザインコントラクトを実行する

/msd-ui-phase 2

フェーズ番号を省略した場合、MSD Core は現在のフェーズを対象とします。

コマンドは 2 つのステージで実行されます。

msd-ui-researcher — CONTEXT.md、RESEARCH.md、REQUIREMENTS.md を読み込んで既存の決定事項を確認し、デザインシステムの状態（shadcn の components.json、Tailwind 設定、既存トークン）を検出し、スペーシング・カラー・タイポグラフィ・コピーライティング・レジストリ安全性の 5 つの領域で未回答のデザイン問題のみを確認します。
msd-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>

プリセット文字列は MSD Core の計画成果物として第一級の扱いを受け、フェーズとマイルストーンを通じて再現可能です。

レジストリ安全ゲート

サードパーティの shadcn レジストリは任意のコードを注入できます。workflow.ui_safety_gate が有効（デフォルト）な場合、非公式のコンポーネントをインストールする前に以下の手順をスペックが要求します。

npx shadcn view <component>   # インストール前にソースを確認する
npx shadcn diff <component>   # 公式レジストリと比較する

レジストリ安全性が対処されていない場合、チェッカーはスペックを BLOCKED としてフラグを立てます。プロジェクトが shadcn を使用していない場合や、別の審査プロセスがある場合は、/msd-settings でゲートを無効化してください。

スケッチ知見をヘッドスタートとして使う

すでに /msd-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.

/msd-ui-phase の前に /msd-sketch --wrap-up を実行する主な理由はこれです。会話形式のデザイン探索がコントラクト入力として確定されます。

`/msd-ui-review` による事後的なビジュアル監査

/msd-ui-review は実行前ではなく実行後に使用します。実装済みのフロントエンドを UI-SPEC（またはスペックがない場合は抽象的な 6 柱標準）に対して監査します。

/msd-ui-review        # 現在のフェーズを監査する
/msd-ui-review 3      # フェーズ 3 を監査する

フロントエンドコードがあるプロジェクトであれば動作します。MSD プロジェクトの初期化は必要ありません。

確認内容（6 柱、各 1〜4 点）：

コピーライティング — CTA ラベル、空の状態、エラー状態
ビジュアル — フォーカルポイント、ビジュアル階層、アイコンのアクセシビリティ
カラー — アクセント使用の規律、60/30/10 準拠
タイポグラフィ — フォントサイズとウェイトの制約遵守
スペーシング — グリッドの整合、トークンの一貫性
エクスペリエンスデザイン — ローディング・エラー・空の状態のカバレッジ

出力: スコアと優先度の高い上位 3 件の修正点を含む {padded_phase}-UI-REVIEW.md。msd-browser などのブラウザ MCP サーバーが設定されている場合、監査はビジュアルエビデンスとしてスクリーンショットも取得します。

スクリーンショットの保存先: スクリーンショットは .planning/ui-reviews/ に保存されます。バイナリファイルが git に含まれないよう、.gitignore が自動的に作成されます。スクリーンショットは /msd-complete-milestone 実行時にクリーンアップされます。

フェーズライフサイクルにおける推奨位置

/msd-discuss-phase N      ← 実装方針を固定する
/msd-ui-phase N           ← デザインコントラクトを固定する（フロントエンドフェーズ）
/msd-plan-phase N         ← リサーチ + 計画（UI-SPEC.md をコンテキストとして読み込む）
/msd-execute-phase N      ← 並行実行
/msd-verify-work N        ← 手動 UAT
/msd-ui-review N          ← 事後的なビジュアル監査（オプションだが推奨）

/msd-ui-phase はディスカッションとプランの間に位置します。これはプランナーが UI-SPEC.md をデザインコンテキストとして読み込むためです。PLAN.md 内のタスクは、スペックが固定したスペーシングトークン・カラー変数・コピーライティング決定を参照します。

9.3 KiB Raw Permalink Blame History Unescape Escape