---
name: design-mock
description: 新機能のデザインモックを apps/web に作成し、playwright-mcp でスクリーンショットを撮って docs/spec/{feature}/README.md に貼り付ける skill。ユーザーは README の画像（または実画面）でレビューし、修正依頼があればモックを直してスクショを同じパスに上書きする。テーマ（雰囲気・色・参考デザイン）をヒアリングし、apps/admin の既存デザインを参考にしてからモックを作る。ユーザーが「モック作って」「デザインを試したい」「画面のイメージを作って」「UIのモックが欲しい」など、デザインの試作と仕様化を依頼したときに使用する。設計書（DB/API）は前提として既に存在する想定（design-feature skill の後に使う）。
---

# design-mock

新機能のデザインモックを作成し、スクリーンショットを README に貼って画像ベースでレビューしてもらう skill。

## このskillが対象とするフロー

```
前提: docs/spec/{feature}/README.md が存在する（design-feature skill 完了済み）
  ↓
Step 1: ヒアリング（テーマ・雰囲気・色味・参考デザイン）
  ↓
Step 2: 既存デザインの読み込み（apps/admin を中心に参考デザインを把握）
  ↓
Step 3: apps/web にモック作成（デザインの伝達が目的）
  ↓
Step 4: pnpm dev 起動 → playwright-mcp でスクショ撮影
  ↓
Step 5: docs/spec/{feature}/README.md に「UI 設計」セクション（スクショ画像 + 仕様）を書き出し
  ↓
Step 6: ユーザーが README の画像（または必要なら dev サーバ）でレビュー
  ↓
Step 7: 修正依頼があれば → モック修正 → スクショを同じパスに上書き → 必要なら README の仕様も更新 → Step 6 に戻る
  ↓
Step 8: ユーザー OK → 完了報告
```

**重要**: スクリーンショットは「ユーザー承認後」ではなく「モック完成直後」に撮って README に貼る。ユーザーは画像でレビューする。修正のたびにスクショを **同じファイルパスで上書き** する（README からの参照は変えない）。

## 進め方

### Step 1: テーマヒアリング

モックを作る前に、ユーザーから以下を **必ず質問** する（コンテキストから明らかな部分は省略可）:

- **対象機能**: どの機能のモックか（`docs/spec/{feature}/` のどれか）
- **雰囲気**: カジュアル / シリアス / ゲーム的 / シンプル / プレミアム など
- **色味**: プライマリカラー、グラデーションの方向性、ダーク/ライト
- **動き**: 静的 / アニメーション豊富 / 特殊効果（グロー、紙吹雪、グラデーション等）
- **参考デザイン**:
  - 既存の `apps/admin` のどの画面に寄せるか（または独自にするか）
  - 外部の参考サイト・サービス（あれば）
- **対象アプリ**: `apps/web` / `apps/admin` / `apps/mobile` のどこに作るか（基本は `apps/web`）

ユーザーの回答に不明点があれば追加で質問する。

### Step 2: 既存デザインの把握

モックを作る前に、必ず以下を読んで現在のデザインシステムを把握する:

- `apps/admin/src/app/globals.css` — カスタム CSS 変数・カラーパレット
- `apps/admin/src/app/(dashboard)/page.tsx` — ダッシュボードのレイアウト・コンポーネント例
- `apps/admin/src/app/(dashboard)/ui/` 配下 — Buttons / Alerts / Avatars / Modals 等の既存 UI コンポーネント例
- `apps/admin/src/components/` — レイアウト / 共通 UI / 機能コンポーネント
- 対象が `apps/web` の場合は `apps/web/src/app/globals.css` および既存ページも合わせて確認

ユーザーが指定したテーマと既存デザインの整合を取る（既存に揃える / 意図的に変える、を判断する）。

### Step 3: 設計書の読み込み

`docs/spec/{feature}/README.md` を読み、以下を把握:

- 必要な画面の一覧と役割
- フロー図・状態遷移
- 連携する既存機能

設計書に書かれていない画面を勝手に増やさない。

### Step 4: モック作成

**目的: デザインの伝達**。コンポーネント設計や API 連携は最低限。

#### 配置

- 基本: `apps/web/src/app/{feature}/page.tsx`（必要に応じてサブパス）
- Admin 向けの機能: `apps/admin/src/app/(dashboard)/{feature}/page.tsx`
- Mobile 向け: `apps/mobile/app/{feature}.tsx`

#### ダミーデータ

- ページ内のローカル定数として記述するか、`apps/{app}/src/libs/mock-data.ts` に集約
- API 呼び出しはせず、ハードコードした状態で各画面を表現

#### スタイル

- Tailwind CSS v4 を使用、既存の `globals.css` の CSS 変数を尊重
- ヒアリングで決めたテーマを反映:
  - 色味（プライマリ・セカンダリ・アクセント）
  - タイポグラフィ（サイズ・ウェイト）
  - 動き（ホバー・トランジション・特殊効果）
- レスポンシブは必要最低限（モバイル幅で破綻しない程度）

#### 状態の表現

- ローディング / エラー / 空 / 通常 など状態が複数ある場合は、すべて表示できるようモック内で切り替えやすくする（タブやボタンでの状態切替でも可）

#### コードスタイル

- ルート `CLAUDE.md` のコードスタイル（セミコロンなし、ダブルクォート、import順、sort-keys 等）に従う
- モック実装でも `pnpm lint:fix` が通る状態を保つ

### Step 4.5（モック完成判定）

次の Step に進む前に、モックが「ユーザーレビューに耐えうる完成度」になっているかを自分で確認する。lint エラーがあるまま、または明らかな描画崩れを残したままスクショを撮らない。

### Step 5: スクリーンショット撮影（playwright-mcp）

dev サーバを起動し、**playwright-mcp で確定モックのスクリーンショットを自動取得** して `docs/spec/{feature}/screenshots/` に保存する。手動でスクショを撮らない（再現性・差分レビュー性のため）。

#### 前提条件

- 対象アプリの dev サーバ（`pnpm dev`）が起動していること
  - 起動していなければバックグラウンドで起動し、`Ready` ログを待ってから次に進む
- `.mcp.json` に `playwright` MCP サーバーが登録済みであること（プロジェクト既設）

#### 撮影対象

設計書（`docs/spec/{feature}/README.md`）に挙がっている **画面 × 状態** の組み合わせをすべて撮る。

- 画面ごと: `/sign-in`, `/matching`, `/matching/session`, `/profile/:id` など
- 状態ごと: 待機 / 成立 / 通話中 / エラー / 空 / ローディング など、Step 4 の「状態の表現」で切替可能にしたもの
- ビューポート: デフォルトは **1280×800（デスクトップ）**。レスポンシブが重要な機能のみ **375×812（モバイル）** を追加で撮る

#### 保存パスと命名

- ディレクトリ: `docs/spec/{feature}/screenshots/`（無ければ作成）
- ファイル名: `{画面名}-{状態}.png`（状態が単一なら `{画面名}.png`）
- 例:
  - `docs/spec/auth/screenshots/sign-in.png`
  - `docs/spec/auth/screenshots/sign-in-error.png`
  - `docs/spec/matching/screenshots/session-waiting.png`
  - `docs/spec/matching/screenshots/session-active-mobile.png`

ケバブケース統一。日本語ファイル名は使わない（リンク切れ・URL エンコード問題を避けるため）。

**ファイル名は不変**: 同じ画面・状態のスクショは常に同じファイル名で保存する。修正のたびに連番（`-v2.png` 等）を付けない。後述の Step 7 で **同じパスに上書き** することで、README からの参照を変えずに最新画像が表示されるようにする。

#### playwright-mcp の使い方（指針）

各画面に対して以下を順次実行する:

1. `browser_resize` でサイズを 1280×800 にする
2. `browser_navigate` で対象 URL に遷移（例: `http://localhost:3000/sign-in`）
3. アニメーション開始の安定待ちが必要なら `browser_wait_for`（テキスト出現等）で同期 + 数秒待機
4. `browser_take_screenshot` で `docs/spec/{feature}/screenshots/{filename}.png` に保存（フルページが必要な画面のみ `fullPage: true`）
5. 状態切替が UI 操作で行われる場合（例: タブ・ボタン）は `browser_click` 等で切替後に再撮影
6. すべての撮影が終わったら `browser_close` で後始末

### Step 6: README.md にスクショ + 仕様を書き出し

撮影したスクショを参照しつつ、`docs/spec/{feature}/README.md` の「UI 設計」セクションを **追加または置き換え** する。

#### 読み込むファイル

- `apps/{app}/src/app/{feature}/**/*.tsx`
- 関連コンポーネント（`apps/{app}/src/components/...`）
- `apps/{app}/src/app/globals.css`（カスタムスタイル）
- `apps/{app}/src/libs/mock-data.ts`（ダミーデータ参照部分）

#### 記録する内容

**画面設計書**:

| パス | 画面名 | 認証 |
|---|---|---|
| `/{feature}` | 一覧 | 必要 |

各画面ごとに、**この順序** で書く:

1. **スクリーンショット（必須・最初）**: Step 5 で撮影した画像を Markdown 画像構文で参照する（`![{画面名}](./screenshots/{filename}.png)`）。状態が複数あるなら状態ごとに並べる。ユーザーはまずここを見るので、スクショは画面セクションの **冒頭** に置く
2. **ワイヤーフレーム**: 確定したレイアウトを ASCII で表現（モノクロ環境・diff レビュー用に画像と併記する）
3. **状態遷移**: 状態が複数ある場合（待機 / 成立 / 通話中 等）はそれぞれスクリーンショット + ワイヤーフレームを描く
4. **要素の説明**: 各 UI 要素の役割・動作・表示条件を箇条書き
5. **インタラクション**: ボタン押下時の挙動、遷移先

**デザイン設計書**（確定モックから読み取り、文章化する）:

1. **カラーパレット**: プライマリ / セカンダリ / アクセント / 背景 / テキスト（CSS変数または Tailwind クラスで）
2. **タイポグラフィ**: 見出し / 本文 / キャプションのサイズ・ウェイト
3. **コンポーネント**: ボタン / カード / バッジなどの基本スタイル
4. **アニメーション**: ホバー / トランジション / 特殊効果（グロー、紙吹雪、グラデーション等）
5. **ダークモード対応**: 必要なら明記
6. **レスポンシブ**: ブレークポイントごとの挙動

#### ASCII ワイヤーフレームの書き方

枠線文字（`┌─┐│└┘`）でレイアウトを表現し、矢印 `←` で各要素の役割を注記:

```
┌─────────────────────────────────────────┐
│ [ロゴ]                       [メニュー] │ ← ヘッダー
│ ┌─────────────────────────────────────┐ │
│ │  見出しテキスト                      │ │ ← メインコンテンツ
│ │  [プライマリボタン] [セカンダリ]    │ │
│ └─────────────────────────────────────┘ │
│                  [フッター]              │
└─────────────────────────────────────────┘
```

- 状態が変わる部分は別ワイヤーフレームで分けて描く
- アスキーが破綻しそうな複雑な画面はテキスト箇条書きで補完する

#### 既存形式に合わせる

既存機能の README に「UI 設計」セクションがある場合は形式を揃える。

#### 目次の更新

ルート `CLAUDE.md` のルールに従い、README.md の目次（Table of Contents）を新しい見出しに合わせて更新する:

- GitHub Markdown アンカーリンク形式（例: `[UI 設計](#ui-設計)`）
- ネストしたリスト形式
- スクリーンショット / ワイヤーフレーム / レイアウト / プロバイダー定義 等の `####` 見出しも目次に含める

### Step 7: ユーザーレビュー → 修正サイクル

ユーザーに README.md（および必要なら dev サーバの実画面）でレビューしてもらう。

#### レビュー依頼の伝え方

- 更新した README.md のパスと、貼り付けたスクショのパスを伝える
- 「README の画像をご確認ください。実画面で動作も見たい場合は `http://localhost:3000/{path}` で見られます」のように、画像レビューを基本にしつつ実画面も選べる旨を案内する

#### 修正依頼が来たら

ユーザーから修正指示が出たら次のサイクルを回す:

1. **モック修正**: Step 4 と同じ要領で `apps/{app}/src/app/{feature}/...` を編集
2. **スクショ再撮影**: dev サーバが動いていることを確認し、playwright-mcp で **同じファイルパス** に再保存（既存画像を上書き）。連番ファイル名は禁止
3. **README 仕様の更新**: スクショだけでは伝わらない仕様変化（要素追加・削除、状態追加、カラー/タイポグラフィ変更等）があれば、該当セクションを更新する
4. **目次の更新**: 見出しが増減したら目次も合わせる
5. Step 7 冒頭に戻り、再度ユーザーレビューを依頼する

#### 完了の判定

ユーザーから明示的に **OK / 確定 / これでよし** が出るまで Step 7 を反復する。

### Step 8: ユーザーへ報告

更新内容のサマリ（追加された画面、保存・上書きしたスクリーンショットのパス、デザイン仕様の項目）をファイルパス + 行数で簡潔に報告する。

## やってはいけないこと

- ヒアリングをスキップしてモックを作り始める
- 既存 `apps/admin` のデザインを確認せずにモックを作る
- 設計書（`docs/spec/{feature}/README.md`）に書かれていない画面を勝手に増やす
- モックで実 API を呼ぶ（ダミーデータで完結させる）
- モックの実装コードをそのまま README に貼り付ける（仕様書はコードではない）
- step ファイルに UI 仕様を書く（README の役割）
- **playwright-mcp 以外の方法でスクリーンショットを保存する**（手動キャプチャ・画像生成 AI・既存画像の流用は禁止。再現性と差分レビュー性のため必ず playwright-mcp を経由する）
- **修正時にスクショのファイル名を変える**（`sign-in-v2.png`、`sign-in-fixed.png` 等は禁止。同じファイル名で上書き保存し、README からの参照を変えない）
- スクリーンショットのファイル名に日本語・スペース・大文字を含める（ケバブケース小文字英数字のみ）
- 状態が複数ある画面で 1 状態しか撮影しない（README に挙げた状態はすべて撮る）
- スクショを撮らずに README の「UI 設計」セクションを書き出す（画像が無いとユーザーがレビューできない）
- ユーザーが OK していないのに「完了」と報告する（修正サイクル中はまだ進行中）
- 目次の更新を忘れる
- 完璧なコンポーネント設計を追求する（モックの目的はデザインの伝達）