Design Loop — 自律サイトビルダー

自律ループを使用して完全なマルチページウェブサイトを構築します。各反復はタスクを読み込み、ページを生成し、統合し、視覚的に検証してから、次のタスクを書き込んで継続します。

概要

Design Loop は「バトン」パターンを使用します。ファイル（.design/next-prompt.md）が反復間のリレーバトンとして機能します。各サイクル：

1. バトンから現在のタスクを読み込む
2. ページを生成する（Claude または Google Stitch 経由）
3. サイト構造に統合する（ナビゲーション、リンク）
4. ブラウザ自動化により視覚的に検証する（利用可能な場合）
5. サイトドキュメントを更新する
6. 次のタスクをバトンに書き込む — ループを継続させる

これはオーケストレーションに依存しません。ループは以下によって駆動できます：

• ヒューマンインザループ：ユーザーが各ページをレビューしてから「次」または「続けて」と言う
• 完全自律：Claude がサイト完成まで継続的に実行
• CI/CD：.design/next-prompt.md の変更時にトリガー

生成バックエンド

バックエンド	セットアップ	品質	速度	最適用途
Claude（デフォルト）	依存関係なし	優秀 — プロダクションレディな HTML/Tailwind	高速	ほとんどのプロジェクト、完全なコード制御
Google Stitch	npm install @google/stitch-sdk + API キー	より高い忠実度の AI デザイン	約 10-20 秒/画面	デザイン重視プロジェクト、ビジュアルポーランド

Stitch の検出

各ループの開始時に、Stitch が利用可能かチェックします：

1. @google/stitch-sdk がインストールされているかチェック：ls node_modules/@google/stitch-sdk 2>/dev/null
2. STITCH_API_KEY が .dev.vars または環境変数に設定されているかチェック
3. .design/metadata.json が存在するかチェック（Stitch プロジェクト ID を含む）

3 つすべて存在する場合は、Stitch を使用します。そうでない場合は Claude 生成にフォールバックします。

Stitch SDK リファレンス

インストール：npm install @google/stitch-sdk。環境変数または .dev.vars に STITCH_API_KEY を設定します。

import { stitch } from "@google/stitch-sdk";

// プロジェクトを作成
const result = await stitch.callTool("create_project", { title: "My Site" });

// 既存プロジェクトを参照
const project = stitch.project("4044680601076201931");

// スクリーンを生成
const screen = await project.generate("A modern landing page with hero section", "DESKTOP");

// アセットを取得
const htmlUrl = await screen.getHtml();    // HTML のダウンロード URL
const imageUrl = await screen.getImage();  // スクリーンショットのダウンロード URL

// 既存スクリーンを編集（精緻化に推奨）
const edited = await screen.edit("Make the background dark and enlarge the CTA button");

// バリアントを生成
const variants = await screen.variants("Try different colour schemes", {
  variantCount: 3,
  creativeRange: "EXPLORE",     // "REFINE" | "EXPLORE" | "REIMAGINE"
  aspects: ["COLOR_SCHEME"],    // "LAYOUT" | "COLOR_SCHEME" | "IMAGES" | "TEXT_FONT" | "TEXT_CONTENT"
});

デバイスタイプ："MOBILE" | "DESKTOP" | "TABLET" | "AGNOSTIC"。モデル選択：generate() の第 3 引数として "GEMINI_3_PRO" | "GEMINI_3_FLASH" を渡します。

その他の操作：stitch.projects() はプロジェクトをリストアップ、project.screens() はスクリーンをリストアップ、project.getScreen("id") は 1 つを取得します。

getHtml() と getImage() はダウンロード URL を返します。画像 URL に =w1280 を追加して全解像度を取得。認証：STITCH_API_KEY が必要（または OAuth の場合は STITCH_ACCESS_TOKEN + GOOGLE_CLOUD_PROJECT）。エラーは StitchError をスロー、コード：AUTH_FAILED、NOT_FOUND、RATE_LIMITED。

Stitch プロジェクト永続化

Stitch 識別子を .design/metadata.json に保存して、将来の反復が参照できるようにします：

{
  "projectId": "4044680601076201931",
  "screens": {
    "index": { "screenId": "d7237c7d78f44befa4f60afb17c818c1" },
    "about": { "screenId": "bf6a3fe5c75348e58cf21fc7a9ddeafb" }
  }
}

Stitch 統合のヒント：

1. プロジェクト ID を .design/metadata.json に永続化 — 毎回新しいプロジェクトを作成しない
2. 完全な再生成ではなく精緻化には screen.edit() を使用
3. Stitch HTML を後処理 — ヘッダー/フッターを共有要素に置き換え
4. プロンプトに DESIGN.md コンテキストを含める — Stitch は明確なデザインシステム指示でより良い結果を生成

はじめに

最初の実行：プロジェクトをブートストラップ

.design/ がまだ存在しない場合、プロジェクトスキャフォルディングを作成します：

1. ユーザーに以下を質問する：

   • サイト名と目的
   • ターゲットオーディエンス
   • 希望する美的性質（ミニマル、大胆、温かみなど）
   • 作成したいページのリスト
   • ブランドカラー（または /design-system で既存サイトから抽出）

2. プロジェクトファイルを作成：

project/
├── .design/
│   ├── SITE.md           # ビジョン、サイトマップ、ロードマップ — プロジェクトの長期メモリ
│   ├── DESIGN.md         # ビジュアルデザインシステム — 一貫性の情報源
│   └── next-prompt.md    # バトン — ページフロントマター付きの現在のタスク
└── site/
    └── public/           # プロダクションページがここにあります

3. SITE.md を作成 — 下記の「SITE.md テンプレート」セクションのテンプレートから
4. DESIGN.md を作成 — ユーザー入力から手動で、または design-system スキルを使用して既存サイトから抽出
5. 最初のバトンを作成 — ホームページ用の .design/next-prompt.md

以降の実行：バトンを読み込む

.design/next-prompt.md が既に存在する場合、これを解析してループを続行します。

バトンファイル

.design/next-prompt.md は YAML フロントマター + プロンプト本体を持ちます：

---
page: about
layout: standard
---
Acme Plumbing のニューカッスルでの 20 年の歴史を説明するアバウトページ。

**DESIGN SYSTEM:**
[.design/DESIGN.md セクション 6 からコピー]

**ページ構造：**
1. ナビゲーション付きヘッダー（index.html と一貫性あり）
2. 会社写真とタグライン付きヒーロー
3. 企業マイルストーンを示すストーリータイムライン
4. フォトグリッド付きチームセクション
5. CTA セクション：「無料見積もりを取得」
6. フッター（index.html と一貫性あり）

フィールド	必須	目的
page	はい	出力ファイル名（.html なし）
layout	いいえ	standard、wide、sidebar — デフォルトは standard

実行プロトコル

ステップ 1：バトンを読み込む

.design/next-prompt.md を読む
抽出：ページ名、レイアウト、プロンプト本体

ステップ 2：コンテキストファイルを確認

生成前に以下を読みます：

ファイル	チェック項目
.design/SITE.md	セクション 4（サイトマップ） — 既存ページを再作成しない
.design/DESIGN.md	カラーパレット、タイポグラフィ、コンポーネントスタイル
site/public/ の既存ページ	マッチするヘッダー/フッター/ナビゲーションパターン

重要：最新ページの HTML を読んで、正確なヘッダー、ナビゲーション、フッターマークアップを抽出します。新しいページは同じ共有要素を使用する必要があります。

ステップ 3：ページを生成

オプション A：Claude 生成（デフォルト）

Tailwind CSS（CDN 経由）を使用して完全な HTML ファイルを生成します。ページは以下である必要があります：

• デザインシステムとマッチ — .design/DESIGN.md と完全に一致
• 同じヘッダー/ナビ/フッターを再利用 — 既存ページからそのままコピー
• 自己完結型 — Tailwind CDN 付きの単一 HTML ファイル、ビルドステップなし
• レスポンシブ — モバイルファースト、すべてのブレークポイントで機能
• ダークモード を含める — デザインシステムが指定している場合
• セマンティック HTML を使用 — 適切な見出し階層、ランドマーク、alt テキスト
• ナビゲーションをワイヤー — すべてのナビリンクは実際のページを指す（既存または計画中）

生成されたファイルを site/public/{page}.html に書き込みます。

オプション B：Stitch 生成（利用可能な場合）

Stitch SDK が利用可能な場合：

1. バトン本体と DESIGN.md システムブロックを組み合わせてプロンプトを構築
2. project.generate(prompt, deviceType) を呼び出してスクリーンを生成
3. screen.getHtml() から HTML をダウンロードして .design/designs/{page}.html に保存
4. screen.getImage() からスクリーンショットをダウンロードして .design/screenshots/{page}.png に保存
5. Stitch HTML を後処理：
   • ヘッダー/ナビ/フッターをプロジェクトの共有要素に置き換え
   • Tailwind 設定の一貫性を確保
   • 内部ナビゲーションリンクをワイヤー
6. 処理後のファイルを site/public/{page}.html に保存
7. .design/metadata.json を新しいスクリーン ID で更新

既存の Stitch スクリーンの反復編集の場合、再生成ではなく screen.edit(prompt) を使用します。

ステップ 4：サイトに統合

新しいページを生成した後：

1. すべての既存ページのナビゲーションを更新 — ナビメニューに新しいページを追加
2. プレースホルダーリンクを修正 — href="#" を実際のページ URL に置き換え
3. ページ間の一貫性を検証 — ヘッダー、フッター、ナビは全ページで同じ
4. 内部リンクをチェック — ページ間にリンク切れがない

ステップ 5：視覚的検証（ブラウザが利用可能な場合）

Playwright CLI または Chrome MCP が利用可能な場合：

1. ローカルサーバーを起動：npx serve site/public -p 3456
2. デスクトップ（1280px）およびモバイル（375px）の幅で新しいページをスクリーンショット
3. スクリーンショットを .design/screenshots/{page}-desktop.png および {page}-mobile.png に保存
4. デザインシステムと視覚的に比較
5. 問題を修正（レイアウト破損、色が間違っている、ナビが一貫していない）
6. サーバーを停止

ブラウザ自動化が利用できない場合、ステップ 6 に進みます。

ステップ 6：サイトドキュメントを更新

.design/SITE.md を編集：

• セクション 4（サイトマップ）でページを完了としてマーク：[x] {page}.html — {description}
• セクション 5（ロードマップ）またはセクション 6（アイデア）から使用済みアイテムを削除
• 生成中に発見した新しいアイデアを追加

ステップ 7：次のバトンを書き込む（重要）

完了する前に .design/next-prompt.md を更新する必要があります。 これがループを継続させます。

1. 次のページを選択：

   • 最初：セクション 5（ロードマップ）で保留中の優先度高アイテムをチェック
   • 次に：セクション 5 で優先度中アイテムをチェック
   • 次に：セクション 6（アイデア）から選択
   • 最終手段：サイトビジョンに適合するものを考案

2. バトンを書き込む：

   • YAML フロントマター（page、オプション layout）
   • ページ目的とコンテンツの説明
   • .design/DESIGN.md セクション 6 からコピーされたデザインシステムブロック
   • 詳細なページ構造（番号付きセクション）

3. サイトが完成した場合（ロードマップのすべてのアイテムが完成、アイデアがない）：

   • page: _complete とビルド内容の概要でバトンを書き込む
   • これはループが終了したことを示します

ループ完了

ループは以下の場合に終了します：

• ロードマップ内のすべてのページが構築された（SITE.md セクション 4 で [x]）
• ユーザーが停止を言う
• バトンに page: _complete が含まれている

完了時に、概要を出力：

• 構築されたページ（リンク付き）
• スクリーンショット（キャプチャされた場合）
• 今後の作業のための残りのアイデア

ページ間の一貫性ルール

マルチページ生成の最大リスクはドリフト — ページが微妙に異なって見えることです。これを防ぎます：

要素	ルール
ヘッダー/ナビ	最新ページから正確な HTML をコピー。再生成しない。
フッター	同じ — そのままコピー、アクティブページインジケーターのみ変更
Tailwind 設定	<script> 設定ブロックを使用する場合、すべてのページで同じである必要があります
カラー値	常に DESIGN.md の正確な 16 進数コードを使用、近似しない
フォントインポート	同じ Google Fonts <link> タグをすべてのページで使用
スペーシングスケール	一貫したパディング/マージン値（DESIGN.md で文書化）

デザインマッピング

バトンプロンプトを書く際に、曖昧なユーザーリクエストを正確なデザイン指示に変換するために使用します。

UI/UX キーワード精緻化

曖昧な用語	専門用語
"トップのメニュー"	"ロゴとメニューアイテム付きのスティッキーナビゲーションバー"
"大きな写真"	"フォーカルポイント画像付きの全幅ヒーローセクション"
"物のリスト"	"ホバー状態と微妙なエレベーション付きのレスポンシブカードグリッド"
"ボタン"	"ホバートランジション付きのプライマリ CTA ボタン"
"フォーム"	"ラベル付き入力フィールド、検証状態、送信ボタン付きのフォーム"
"写真エリア"	"背景画像またはビデオ付きヒーローセクション"
"サイドバー"	"アイコンラベルペアリング付きの折りたたみ式サイドナビゲーション"
"ポップアップ"	"オーバーレイとスムーズなエントリアニメーション付きのモーダルダイアログ"
"フッター関連"	"サイトマップリンク、連絡先情報、法的通知付きのフッター"
"カード"	"一貫したパディング、丸みを帯びたコーナー、シャドウ付きのコンテンツカード"
"タブ"	"アクティブインジケーターとスムーズなコンテンツトランジション付きのタブ付きインターフェース"
"検索"	"アイコン、プレースホルダーテキスト、結果ドロップダウン付きの検索入力"
"価格"	"推奨層がハイライトされた価格比較カード"
"推奨文"	"推奨文カルーセルまたはグリッド、アバター、引用、属性付き"

雰囲気とビブの記述子

基本ビブ	強化説明
"モダン"	"クリーン、ミニマル、寛大なホワイトスペース、高コントラストタイポグラフィ"
"プロフェッショナル"	"洗練、信頼できる、微妙なシャドウ、制限されたプレミアムパレット"
"楽しい/遊び心的"	"ビブラント、丸みを帯びたコーナー、大胆なアクセント色、バウンシーアニメーション"
"ダークモード"	"深いスレートまたはほぼ黒い背景の高コントラストアクセント"
"ラグジュアリー"	"エレガント、スペーシャス、ファイン線、セリフヘッダー、高忠実度写真"
"テック/サイバー"	"未来的、ネオンアクセント、グラスモーフィズム、等幅タイポグラフィ"
"温かい/フレンドリー"	"ソフトカラー、丸みを帯びた形、手書き文字アクセント、招待的画像"
"大胆/インダストリアル"	"強いタイポグラフィ、高コントラスト、幾何学模様、暗い背景"
"オーガニック/ナチュラル"	"アースカラー、ソフトテクスチャ、オーガニック形状、自然写真"
"エディトリアル"	"雑誌のようなレイアウト、強いタイポグラフィック階層、寛大なリーディング"

ジオメトリ、深さ、スペーシング

説明	Tailwind	ビジュアル効果
ピル型	rounded-full	ボタン、タグ、バッジ
ソフトに丸い	rounded-xl	カード、コンテナ、モーダル
やさしく丸い	rounded-lg	入力、小さい要素
シャープ/正確	rounded-none または rounded-sm	技術的、ブルータリスト美学
グラスモーフィズム	backdrop-blur-md bg-white/10 border border-white/20	オーバーレイ、ナビバー
フロスト	backdrop-blur-sm bg-white/80	サブトルガラス効果

エレベーション	説明	Tailwind
フラット	シャドウなし、カラーブロッキングとボーダー	shadow-none
ささやきのようなソフト	拡散、ほぼ見えないリフト	shadow-sm
サブトル	カード高さの穏やかなシャドウ	shadow-md
フローティング	高オフセット、ソフトシャドウ	shadow-lg または shadow-xl
ドラマティック	ヒーロー要素またはモーダル用の強いシャドウ	shadow-2xl
インセット	プレスされたまたはネストされた要素の内シャドウ	shadow-inner

セクション密度	説明	Tailwind
タイト	コンパクト、情報密度の高い	py-8 md:py-12
バランスされた	標準セクションスペーシング	py-12 md:py-16
寛大	呼吸室、プレミアム感	py-16 md:py-24
ドラマティック	ステートメントスペーシング、ラグジュアリー/エディトリアル	py-24 md:py-32

SITE.md テンプレート

新規プロジェクトをブートストラップするときに使用します。.design/SITE.md に書き込みます：

# プロジェクトビジョン

> **AGENT 指示**：すべての反復の前にこのファイルを読んでください。これはプロジェクトの長期メモリです。

## 1. コアアイデンティティ

| フィールド | 値 |
|-------|-------|
| **プロジェクト名** | [名前] |
| **ミッション** | [サイトが達成すること] |
| **ターゲットオーディエンス** | [このサイトを使用する人々] |
| **ボイス＆トーン** | [パーソナリティ記述子 — 温かい、プロフェッショナル、遊び心的など] |
| **地域** | [オーストラリア/米国/英国 — スペル、電話形式、画像に影響] |

## 2. ビジュアル言語

バトンプロンプトを書く際に参照してください。

- **プライマリビブ**：[メイン美学 — 例：「クリーンでモダン」]
- **セカンダリビブ**：[サポーティング美学 — 例：「温かく親しみやすい」]
- **アンチビブ**：[避けるべきもの — 例：「企業的ではない、クラッタリングされていない」]

## 3. 技術セットアップ

- **出力ディレクトリ**：`site/public/`
- **CSS**：CDN 経由の Tailwind CSS（ビルドステップなし）
- **ダークモード**：[はい/いいえ] — はいの場合、クラストグル経由
- **フォント**：[Google Fonts インポート URL]

## 4. ライブサイトマップ

ページが正常に生成されたときに更新します。

- [x] `index.html` — ヒーロー、機能、CTA 付きホームページ
- [ ] `about.html` — 会社のストーリーとチーム
- [ ] `services.html` — サービス提供と価格設定
- [ ] `contact.html` — 連絡先フォームと場所マップ

## 5. ロードマップ（バックログ）

ここから次のタスクを選択します。完成したアイテムを削除します。

### 優先度高
- [ ] アバウトページをチームセクション付きで構築
- [ ] 価格カード付きサービスページを構築

### 優先度中
- [ ] フォーム付きコンタクトページを構築
- [ ] FAQ ページを構築

### 優先度低
- [ ] ブログインデックスページ
- [ ] 個別ブログポストテンプレート

## 6. クリエイティブ自由度

ロードマップが空になった場合、これらのガイドラインに従ってページを追加します：

1. **ブランドに準拠** — 新しいページは確立されたビブに適合する必要があります
2. **コアを強化** — サイトミッションをサポート
3. **命名規則** — 小文字、説明的なファイル名（例：`team.html`）

### 探索するアイデア
- [ ] `testimonials.html` — カスタマーレビューと事例紹介
- [ ] `gallery.html` — 画像グリッド付きプロジェクトポートフォリオ
- [ ] `faq.html` — アコーディオン付き FAQ

## 7. エンゲージメントルール

1. セクション 4 で `[x]` としてマークされているページを再作成しないでください
2. 反復を完了する前に、常に `.design/next-prompt.md` を更新してください
3. セクション 6 から使用済みアイデアを削除
4. 既存ページからヘッダー/ナビ/フッターをコピー — 再生成しないでください
5. すべての内部リンクは実際のページを指す必要があります

DESIGN.md テンプレート

design-system スキルを使用して生成、または手動で作成します。.design/DESIGN.md に書き込みます：

# デザインシステム：[プロジェクト名]

## 1. ビジュアルテーマ＆雰囲気

[気分、密度、美的哲学を説明します。魅力的な言語を使用します]

## 2. カラーパレット＆ロール

| ロール | 名前 | 値 | 用途 |
|------|------|-------|-------|
| プライマリ | [名前] | `#hexcode` | ボタン、リンク、アクティブ状態 |
| プライマリフォアグラウンド | [名前] | `#hexcode` | プライマリ背景のテキスト |
| セカンダリ | [名前] | `#hexcode` | サポーティング要素、バッジ |
| バックグラウンド | [名前] | `#hexcode` | ページ背景 |
| サーフェス | [名前] | `#hexcode` | カード、コンテナ |
| テキストプライマリ | [名前] | `#hexcode` | 見出し、本文テキスト |
| テキストセカンダリ | [名前] | `#hexcode` | キャプション、メタデータ |
| ボーダー | [名前] | `#hexcode` | 仕切り、入力ボーダー |
| アクセント | [名前] | `#hexcode` | ハイライト、通知 |

## 3. タイポグラフィ

| 要素 | フォント | ウェイト | サイズ | 行の高さ |
|---------|------|--------|------|-------------|
| H1 | [フォント] | 700 | 3rem | 1.1 |
| H2 | [フォント] | 600 | 2rem | 1.2 |
| H3 | [フォント] | 600 | 1.5rem | 1.3 |
| 本文 | [フォント] | 400 | 1rem | 1.6 |
| 小 | [フォント] | 400 | 0.875rem | 1.5 |

## 4. コンポーネントスタイル

各コンポーネントを文書化：ボタン（プライマリ、セカンダリ、ホバー）、カード（bg、ボーダー、radius、シャドウ、パディング）、ナビゲーション（スティッキー/スタティック、アクティブインジケーター、モバイルパターン）、フォーム（入力スタイル、ラベル、検証色）。

## 5. レイアウト原則

最大コンテンツ幅、セクションパディング、グリッドシステム、ホワイトスペース哲学。

## 6. 生成のためのデザインシステムノート

**このブロック全体をすべてのバトンプロンプトにコピー：**

**デザインシステム（必須）：**
- プラットフォーム：Web、デスクトップファースト、レスポンシブ
- テーマ：[ライト/ダーク]、[記述子]
- バックグラウンド：[説明] (#hex)
- サーフェス：[説明] (#hex)
- プライマリ：[説明] (#hex) for [ロール]
- テキスト：[説明] (#hex)
- フォント：[フォント名] Google Fonts 経由
- コーナー：[説明]
- シャドウ：[説明]
- スペーシング：[説明]

ファイル構造

project/
├── .design/
│   ├── SITE.md              # プロジェクトビジョン、サイトマップ、ロードマップ
│   ├── DESIGN.md            # ビジュアルデザインシステム（情報源）
│   ├── next-prompt.md       # バトン — 現在/次のタスク
│   ├── metadata.json        # Stitch プロジェクト/スクリーン ID（Stitch 使用の場合）
│   └── screenshots/         # ビジュアル検証キャプチャ
├── site/
│   └── public/              # プロダクションページ
└── .gitignore               # .design/screenshots/ を追加

よくある落とし穴

• .design/next-prompt.md を更新し忘れ（ループが破損）
• SITE.md サイトマップで既に [x] としてマークされているページを再作成
• ヘッダー/ナビを再生成する代わりに既存ページからコピー
• バトンプロンプトでデザインシステムブロックを省略
• ナビで href="#" プレースホルダーが実際の URL に置き換わらずに残す
• ページ全体で一貫していない Tailwind 設定
• 反復ごとに複数ページを生成（常に 1 ページずつ）