Google Stitch UIプロトタイピング＆バリアントスキル（stitch-design）

Google Stitch UIプロトタイピング＆バリアントスキル（stitch-design） は何をしますか？

このスキルは、確立されたコンポーネント設計仕様書（design-spec.md）をもとに、Google Stitch（StitchMCP） を使用して画面レイアウトをスキャフォールディングし、空間バリアントを生成し、高解像度ビジュアルアセット（JPGスクリーンショットと生のHTMLエクスポート）をコードベースにダウンロードし、設計仕様書を具体的なレイアウトベンチマークで更新するための完全なワークフローを定義します。

[!IMPORTANT] 入力前提条件: このスキルを使用するには、docs/design/components/[ページ名]/[コンポーネント名]/design-spec.md に完成した設計仕様書が必要です（通常は component-design によって生成されます）。仕様書が存在しない場合は、最初に /component-design を実行してください。

[!CAUTION] バイナリダウンロードセーフティルール: StitchのJPGスクリーンショットやHTMLエクスポートをダウンロードするために read_url_content を決して使用しないでください。read_url_content はテキスト専用であり、レスポンスをマークダウンに変換するため、バイナリ画像が破損し、HTML構造が乱れます。すべてのダウンロードは、PowerShellの Invoke-WebRequest -Uri <url> -OutFile <path> を使用した run_command で行う必要があります。署名付きダウンロードURLはすぐに期限切れになるため、Stitchのレスポンスを受け取ったらすぐにダウンロードしてください。

[!TIP] スキル内での画像生成禁止（トークン消費節約ルール）: トークンを節約するため、このスキルは generate_image を直接呼び出してはいけません。画面にカスタムの背景画像、イラスト、アイコンが必要な場合は、構造化されたプロンプトをユーザーに対して出力し、ユーザーがそれらを生成してプロジェクトファイルに配置できるようにしてください。

---

1. 主要成果物とワークフロー概要

flowchart TD
    Start["/stitch-design を起動<br/>（ターゲット: docs/design/components/[page]/[component]/design-spec.md）"] --> Step1["ステップ1: 設計仕様書の読み込み<br/>（design-spec.md と docs/project.json を読む）"]
    Step1 --> Step2["ステップ2: Stitchプロジェクトの永続化とトークンのシード<br/>（docs/project.json 内の stitch.project_id を確認/再利用、デザインシステムをシード）"]
    Step2 --> Step3["ステップ3: StitchMCP による画面とバリアントの生成<br/>（generate_screen_from_text + 1バリアントの generate_variants）"]
    Step3 --> Step4["ステップ4: バイナリセーフなアセットダウンロード<br/>（PowerShell Invoke-WebRequest → stitch/screen.jpg, screen.html, variant-1.jpg, variant-1.html）"]
    Step4 --> Step5["ステップ5: 設計仕様書へのベンチマーク統合<br/>（stitch/screen.jpg とバリアントベンチマークを design-spec.md に埋め込む）"]
    Step5 --> Step6["ステップ6: 独立したサブエージェントによる検証<br/>（invoke_subagent がファイルサイズ、メタデータ、仕様の整合性を検証）"]
    Step6 --> Finish["ビジュアルプロトタイプ準備完了<br/>（Stitch JPG + HTML がコードベースに保存される）"]

成果物：Stitchアセットサブフォルダ

Stitchの実行ごとに、コンポーネントのデザインディレクトリ内に stitch/ サブフォルダが作成または更新されます：

docs/design/components/[ページ名]/[コンポーネント名]/
├── design-spec.md          # Stitchベンチマークと埋め込みスクリーンショットで更新
└── stitch/                 # ダウンロードされたGoogle Stitchデザインファイル
    ├── screen.jpg          # Stitch生成のプライマリ画面のJPGスクリーンショット
    ├── screen.html         # Stitch生成のプライマリ画面の生のHTMLエクスポート
    ├── variant-1.jpg       # Stitch生成のバリアントのJPGスクリーンショット
    ├── variant-1.html      # Stitch生成のバリアントの生のHTMLエクスポート
    └── stitch-meta.json    # StitchプロジェクトID、画面ID、バリアントID、生成プロンプト

---

2. ステップバイステップの実行ワークフロー

ステップ1: 設計仕様書とプロジェクトコンテキストの読み込み

1. ターゲットコンポーネントの特定:
   • コンポーネントパスを特定: docs/design/components/[ページ名]/[コンポーネント名]/
   • design-spec.md を読み取り、以下を抽出:
     • エグゼクティブサマリー、ペルソナ、感情トーン
     • ビジュアル階層（第1、第2、第3フォーカルポイント）
     • レイアウトグリッドとブレークポイントの動作
     • デザイントークン（色、半径、エレベーション）
     • ロケールごとのタイポグラフィペアリング
2. プロジェクトコンテキストの読み取り:
   • docs/project.json を読み取り、正規のデザインシステムを確認し、既存のStitch構成がないか確認します。

---

ステップ2: Google Stitch プロジェクトの永続化とデザインシステムのシード（StitchMCP）

[!IMPORTANT] リポジトリ単一プロジェクトルール（重複プロジェクト禁止）: すべてのリポジトリは、そのすべてのコンポーネントおよび画面デザインに対して、1つの共有Google Stitchプロジェクトコンテナ を正確に維持する必要があります。同じリポジトリに対して複数のStitchプロジェクトを作成しないでください。

1. 最初に docs/project.json を確認:
   • docs/project.json に既存の "stitch" オブジェクトと project_id がないか検査します。
2. 既存のプロジェクトを再利用:
   • stitch.project_id が存在する場合、すべての画面スキャフォールディング、バリアント、デザインシステム更新に対して、その projectId を常に直接再利用します。create_project を呼び出さないでください。
3. 作成と即時永続化（存在しない場合のみ）:
   • docs/project.json に stitch.project_id が存在しない場合:
     • StitchMCP で call_mcp_tool を list_projects で呼び出し、リポジトリタイトルに一致するプロジェクトが既に存在するか確認します。
     • 存在しない場合は、create_project を title: "[プロジェクトタイトル] デザインシステム＆コンポーネント" で呼び出します。
     • すぐにプロジェクトプロパティを docs/project.json の "stitch" 以下に永続化します:

       "stitch": {
         "project_id": "<projectId>",
         "project_name": "projects/<projectId>",
         "title": "<title>"
       }
       

4. デザイントークンのシード:
   • docs/project.json からプロジェクトの正規のデザインシステムを、upload_design_md または create_design_system_from_design_md を介してStitchに提供し、グローバルな色、フォント、半径の一貫性を確立します。

---

ステップ3: StitchMCP による画面とバリアントの生成

1. 詳細なデザインプロンプトの合成:
   • design-spec.md からコンポーネントの目的、ユーザーペルソナ、感情トーン、レイアウト要件を組み合わせます。
   • ビジュアルトークンを明示的に指定: docs/project.json からの背景キャンバス、サーフェスカード、プライマリアクセント、セカンダリアクセント、ステータス色、タイポグラフィ。
   • ターゲットビューポートを指定: deviceType: "DESKTOP"（モバイルファーストのコンポーネントをターゲットにする場合は "MOBILE" または "TABLET"）。
2. プライマリ画面の生成:
   • StitchMCP で generate_screen_from_text を呼び出し:
     • projectId: アクティブなStitchプロジェクトID。
     • prompt: 合成されたデザインプロンプト。
     • deviceType: "DESKTOP"。
   • 生成された画面IDとリソース名（形式: projects/{projectId}/screens/{screenId}）を抽出します。
3. 1つのバリアントを生成:
   • 生成された画面IDを使用して StitchMCP で generate_variants を呼び出し、設計仕様ファイルの1つの空間/ビジュアルバリアントを生成します（例: 代替レイアウト密度、カード vs フルブリード、非対称ビジュアルフローの探索）。
   • バリアント画面IDを記録します。

---

ステップ4: バイナリセーフアセットダウンロードプロトコル

[!CAUTION] PowerShell Invoke-WebRequest 必須: 各ダウンロードコマンドは個別の単一操作として実行してください。各ダウンロードファイルのサイズが0バイトではないこと（JPGの場合は10KB以上）を確認してください。

1. ディレクトリの存在確認:
   • ターゲットディレクトリ: docs/design/components/[ページ名]/[コンポーネント名]/stitch/
2. プライマリ画面JPGのダウンロード:
   • プライマリ画面レスポンスから screenshot.downloadUrl を抽出します。
   • 以下を実行:

     powershell -Command "Invoke-WebRequest -Uri '<screenshot.downloadUrl>' -OutFile 'docs/design/components/[page]/[component]/stitch/screen.jpg'"
     

3. プライマリ画面HTMLのダウンロード:
   • プライマリ画面レスポンスから htmlCode.downloadUrl を抽出します。
   • 以下を実行:

     powershell -Command "Invoke-WebRequest -Uri '<htmlCode.downloadUrl>' -OutFile 'docs/design/components/[page]/[component]/stitch/screen.html'"
     

4. バリアント1 JPGのダウンロード:
   • バリアントレスポンスから screenshot.downloadUrl を抽出します。
   • 以下を実行:

     powershell -Command "Invoke-WebRequest -Uri '<variant.screenshot.downloadUrl>' -OutFile 'docs/design/components/[page]/[component]/stitch/variant-1.jpg'"
     

5. バリアント1 HTMLのダウンロード:
   • バリアントレスポンスから htmlCode.downloadUrl を抽出します。
   • 以下を実行:

     powershell -Command "Invoke-WebRequest -Uri '<variant.htmlCode.downloadUrl>' -OutFile 'docs/design/components/[page]/[component]/stitch/variant-1.html'"
     

6. Stitchメタデータの保存（stitch-meta.json）:
   • docs/design/components/[page]/[component]/stitch/stitch-meta.json に書き込み:

     {
       "projectId": "<stitchProjectId>",
       "screenId": "<screenId>",
       "screenName": "projects/<projectId>/screens/<screenId>",
       "deviceType": "DESKTOP",
       "generationPrompt": "<synthesizedPrompt>",
       "variantIds": ["<variantScreenId1>"]
     }
     

---

ステップ5: 設計仕様書へのベンチマーク統合

docs/design/components/[ページ名]/[コンポーネント名]/design-spec.md をStitchの結果で更新します:

1. Stitchプライマリ画面とバリアントを埋め込む:

   ## Google Stitch レイアウトアーキテクチャとベンチマーク
   
   ### プライマリ画面デザイン
   ![プライマリ画面デザイン](stitch/screen.jpg)
   
   ### バリアント1の探索
   ![バリアント1デザイン](stitch/variant-1.jpg)
   

2. レイアウトアーキテクチャの観察結果を文書化:
   • Stitch画面で示された、空間グリッド、ビジュアルウェイト、ホワイトスペースのリズム、タイポグラフィ階層に注目します。
   • プライマリ画面とバリアント1を比較し、各構成の強みを強調します。

---

ステップ6: ビジュアルアセットプロンプト（該当する場合）

[!NOTE] Stitchレイアウトを検査した結果、特別なビジュアルアセット（例：環境背景、カスタムアイコン、図）が必要であることが判明した場合、generate_image を呼び出さないでください。代わりに、構造化されたプロンプトをユーザーに出力します:

### 推奨ビジュアルアセット: [アセット名]
- **ターゲットファイルパス:** `docs/design/components/[page]/[component]/[filename].png`
- **推奨アスペクト比:** `16:9` または `1:1`
- **生成プロンプト:**
  > "[Stitchレイアウトに一致するビジュアルアセットを説明する詳細なプロンプト]"

---

ステップ7: 独立したサブエージェントによる検証ループ（invoke_subagent）

[!IMPORTANT] サブエージェントレビュープロトコル: 完了を報告する前に、独立したサブエージェントを介してダウンロードされたアセットと仕様の更新を常に検証してください。

1. 検証サブエージェントの起動

invoke_subagent を呼び出します:

• TypeName: "self"
• Role: "Stitch アセット＆ダウンロード監査人"
• Model: "inherit"
• Prompt:

あなたは独立したStitchアセット監査人です。あなたの仕事は、Google Stitchアセットがクリーンにダウンロードされ、コンポーネントディレクトリに統合されたことを検証することです。

ターゲットコンポーネントディレクトリ:
docs/design/components/[ページ名]/[コンポーネント名]/

監査する成果物:
1. docs/design/components/[ページ名]/[コンポーネント名]/stitch/screen.jpg（存在すること、0バイトではないこと）
2. docs/design/components/[ページ名]/[コンポーネント名]/stitch/screen.html（存在すること、生のHTMLであること）
3. docs/design/components/[ページ名]/[コンポーネント名]/stitch/variant-1.jpg（存在すること、0バイトではないこと）
4. docs/design/components/[ページ名]/[コンポーネント名]/stitch/variant-1.html（存在すること、生のHTMLであること）
5. docs/design/components/[ページ名]/[コンポーネント名]/stitch/stitch-meta.json（有効なJSONであり、projectId、screenId、generationPrompt、variantIdsを含むこと）
6. docs/design/components/[ページ名]/[コンポーネント名]/design-spec.md（stitch/screen.jpg と stitch/variant-1.jpg を埋め込んでいること）

以下の厳格な基準に基づいて監査してください:
1. バイナリファイルの整合性: screen.jpg と variant-1.jpg が空または破損していないこと（サイズ > 10KB）を確認。
2. HTMLの整合性: screen.html と variant-1.html が有効なHTMLファイルであり、破損したマークダウンでないことを確認。
3. メタデータの整合性: stitch-meta.json が有効なフィールドを持っていることを確認。
4. 仕様の統合: design-spec.md に埋め込まれたスクリーンショットリンクとStitchレイアウトベンチマークのメモが含まれていることを確認。
5. トークン節約: generate_image が直接呼び出されていないことを確認。

以下の正確な形式で応答してください:
VERDICT: PASS | ISSUES_FOUND

ISSUES（ある場合）:
- LOCATION: {file:line or section}
- PROBLEM: {準拠していない、または壊れている内容}
- FIX: {修正するための具体的な指示}

SUMMARY: {簡潔な全体的な評価}

2. レビューの評価と解決

ISSUES_FOUND の場合、実行を完了する前に問題を直ちに解決してください（例: 失敗したアセットの再ダウンロード、メタデータの修正）。

---

3. 実行検証チェックリスト

実行を完了する前に、以下を検証してください:

• design-spec.md が docs/design/components/[page]/[component]/ から読み込まれました。
• StitchプロジェクトIDが docs/project.json から検証/再利用されました（または作成されてすぐに永続化されました）。
• デザイントークンが upload_design_md または create_design_system_from_design_md を介してStitchにシードされました。
• プライマリ画面が generate_screen_from_text を介して生成されました。
• 正確に1つのバリアントが generate_variants を介して生成されました。
• すべてのアセットがPowerShell Invoke-WebRequest -OutFile を使用してダウンロードされました（read_url_content の使用はゼロ）。
• screen.jpg、screen.html、variant-1.jpg、variant-1.html が stitch/ に保存され、サイズが0ではないこと。
• stitch/stitch-meta.json が完全なメタデータとともに保存されました。
• design-spec.md が埋め込みスクリーンショットとStitchレイアウトベンチマークで更新されました。
• generate_image は直接呼び出されていません。必要な場合は、画像プロンプトがユーザーに出力されました。
• 独立したサブエージェント監査が invoke_subagent を介して呼び出され、合格しました。