design-loop

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

自律的なループを通じて、複数ページからなる完全なウェブサイトを構築します。各イテレーションでは、タスクを読み込み、ページを生成して統合し、見た目を確認した後、次のタスクを書き込んで処理を続けます。

概要

Design Loop では、「バトン」パターンを使用します。ファイル（.design/next-prompt.md）がイテレーション間のリレーバトンとして機能します。各サイクルでは、次の処理を行います。

1. バトンから現在のタスクを読み込みます
2. ページを生成します（Claude または Google Stitch を使用）
3. サイト構造に統合します（ナビゲーション、リンク）
4. ブラウザー自動化を使って見た目を確認します（利用可能な場合）
5. サイトのドキュメントを更新します
6. 次のタスクをバトンに書き込み、ループを継続させます

この仕組みは、オーケストレーション方法に依存しません。ループは次の方法で実行できます。

• 人間が介在する方式：ユーザーが各ページを確認してから、「next」または「keep going」と指示します
• 完全自律型：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. .dev.vars または環境変数に STITCH_API_KEY が設定されているか確認します
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";

// Create a project
const result = await stitch.callTool("create_project", { title: "My Site" });

// Reference an existing project
const project = stitch.project("4044680601076201931");

// Generate a screen
const screen = await project.generate("A modern landing page with hero section", "DESKTOP");

// Get assets
const htmlUrl = await screen.getHtml();    // Download URL for HTML
const imageUrl = await screen.getImage();  // Download URL for screenshot

// Edit an existing screen (prefer this for refinements)
const edited = await screen.edit("Make the background dark and enlarge the CTA button");

// Generate variants
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）。エラーが発生すると、コード AUTH_FAILED、NOT_FOUND、RATE_LIMITED を持つ StitchError がスローされます。

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           # Vision, sitemap, roadmap — the project's long-term memory
│   ├── DESIGN.md         # Visual design system — the source of truth for consistency
│   └── next-prompt.md    # The baton — current task with page frontmatter
└── site/
    └── public/           # Production pages live here

3. 下記の「SITE.md テンプレート」セクションのテンプレートを使って SITE.md を作成します
4. ユーザーの入力をもとに DESIGN.md を作成するか、design-system スキルを使って既存のサイトから抽出します
5. ホームページ用の最初のバトン（.design/next-prompt.md）を書き込みます

2回目以降の実行：バトンを読む

.design/next-prompt.md がすでに存在する場合は、その内容を解析してループを続けます。

バトンファイル

.design/next-prompt.md には、YAML フロントマターとプロンプト本文が含まれています。

---
page: about
layout: standard
---
An about page for Acme Plumbing describing the company's 20-year history in Newcastle.

**DESIGN SYSTEM:**
[Copied from .design/DESIGN.md Section 6]

**Page Structure:**
1. Header with navigation (consistent with index.html)
2. Hero with company photo and tagline
3. Story timeline showing company milestones
4. Team section with photo grid
5. CTA section: "Get a Free Quote"
6. Footer (consistent with index.html)

フィールド	必須	用途
page	はい	出力ファイル名（.html を除く）
layout	いいえ	standard、wide、sidebar — 省略時は standard

実行プロトコル

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

Read .design/next-prompt.md
Extract: page name, layout, prompt body

ステップ 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 を使用する：適切な見出し階層、ランドマーク、代替テキストを使用する
• 実際のナビゲーションを設定する：すべてのナビゲーションリンクを実在するページ（既存または予定）にリンクする

生成したファイルを 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. 新しい画面 ID で .design/metadata.json を更新する

既存の 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 と .design/screenshots/{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 に記載された正確な HEX コードを常に使用し、近似値は使いません
フォントのインポート	すべてのページで同じ Google Fonts の <link> タグを使用します
間隔のスケール	パディングとマージンの値に一貫性を持たせます（DESIGN.md に記載）

デザインへのマッピング

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

UI／UX キーワードの具体化

曖昧な表現	専門的な用語
「上部のメニュー」	「ロゴとメニュー項目を備えた固定ナビゲーションバー」
「大きな写真」	「焦点となる画像を配置した全幅のヒーローセクション」
「項目の一覧」	「ホバー状態と控えめな浮き上がり効果を備えた、レスポンシブなカードグリッド」
「ボタン」	「ホバー時のトランジションを備えた、主要なコールトゥアクションボタン」
「フォーム」	「ラベル付き入力フィールド、検証状態、送信ボタンを備えたフォーム」
「画像エリア」	「背景画像または動画を使用したヒーローセクション」
「サイドバー」	「アイコンとラベルを組み合わせた、折りたたみ可能なサイドナビゲーション」
「ポップアップ」	「オーバーレイと滑らかな表示アニメーションを備えたモーダルダイアログ」
「フッターのあれこれ」	「サイトマップのリンク、連絡先情報、法的通知を含むフッター」
「カード」	「パディング、角丸、シャドウに一貫性を持たせたコンテンツカード」
「タブ」	「アクティブ状態のインジケーターと滑らかなコンテンツ切り替えを備えたタブインターフェース」
「検索」	「アイコン、プレースホルダーテキスト、検索結果のドロップダウンを備えた検索入力欄」
「価格設定」	「おすすめのプランを強調表示した、価格比較カード」
「お客様の声」	「アバター、引用、投稿者情報を含む、お客様の声のカルーセルまたはグリッド」

雰囲気と印象の表現

基本的な印象	詳細な説明
「モダン」	「すっきりとしたミニマルなデザイン、ゆとりのある余白、コントラストの強いタイポグラフィ」
「プロフェッショナル」	「洗練された信頼感のあるデザイン、控えめな影、厳選された高級感のある配色」
「楽しい／遊び心のある」	「鮮やかな色、丸みを帯びた角、目を引くアクセントカラー、弾むようなアニメーション」
「ダークモード」	「深いスレート色やほぼ黒の背景に、コントラストの強いアクセントカラー」
「高級感」	「エレガントでゆとりのあるデザイン、細い線、セリフ体の見出し、高精細な写真」
「テック／サイバー」	「未来的なデザイン、ネオンのアクセント、グラスモーフィズム、等幅フォントのタイポグラフィ」
「温かみ／親しみやすさ」	「柔らかな色、丸みのある形、手書き風のアクセント、親しみを感じる画像」
「大胆／インダストリアル」	「力強いタイポグラフィ、高いコントラスト、幾何学的な形、暗い背景」
「オーガニック／ナチュラル」	「アースカラー、柔らかな質感、有機的な形、自然の写真」
「エディトリアル」	「雑誌のようなレイアウト、明確なタイポグラフィの階層、ゆとりのある行間」

形状、奥行き、余白

説明	Tailwind	視覚効果
ピル型	rounded-full	ボタン、タグ、バッジ
柔らかな角丸	rounded-xl	カード、コンテナ、モーダル
緩やかな角丸	rounded-lg	入力欄、小さな要素
シャープ／精密	rounded-none or 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 or 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 に記述してください。

# Project Vision

> **AGENT INSTRUCTION:** Read this file before every iteration. It is the project's long-term memory.

## 1. Core Identity

| Field | Value |
|-------|-------|
| **Project Name** | [Name] |
| **Mission** | [What the site achieves] |
| **Target Audience** | [Who uses this site] |
| **Voice & Tone** | [Personality descriptors — warm, professional, playful, etc.] |
| **Region** | [Australia / US / UK — affects spelling, phone format, imagery] |

## 2. Visual Language

Reference these when writing baton prompts.

- **Primary Vibe**: [Main aesthetic — e.g. "Clean and modern"]
- **Secondary Vibe**: [Supporting aesthetic — e.g. "Warm and approachable"]
- **Anti-Vibes**: [What to avoid — e.g. "Not corporate, not cluttered"]

## 3. Technical Setup

- **Output Directory**: `site/public/`
- **CSS**: Tailwind CSS via CDN (no build step)
- **Dark Mode**: [Yes/No] — if yes, via class toggle
- **Fonts**: [Google Fonts import URL]

## 4. Live Sitemap

Update this when a page is successfully generated.

- [x] `index.html` — Homepage with hero, features, CTA
- [ ] `about.html` — Company story and team
- [ ] `services.html` — Service offerings with pricing
- [ ] `contact.html` — Contact form and location map

## 5. Roadmap (Backlog)

Pick the next task from here. Remove items as they're completed.

### High Priority
- [ ] Build about page with team section
- [ ] Build services page with pricing cards

### Medium Priority
- [ ] Build contact page with form
- [ ] Build FAQ page

### Low Priority
- [ ] Blog index page
- [ ] Individual blog post template

## 6. Creative Freedom

When the roadmap is empty, follow these guidelines to add pages:

1. **Stay on-brand** — new pages must fit the established vibe
2. **Enhance the core** — support the site mission
3. **Naming convention** — lowercase, descriptive filenames (e.g. `team.html`)

### Ideas to Explore
- [ ] `testimonials.html` — Customer reviews and case studies
- [ ] `gallery.html` — Project portfolio with image grid
- [ ] `faq.html` — Frequently asked questions with accordion

## 7. Rules of Engagement

1. Do NOT recreate pages already marked `[x]` in Section 4
2. ALWAYS update `.design/next-prompt.md` before completing an iteration
3. Remove consumed ideas from Section 6
4. Copy header/nav/footer from existing pages — never regenerate
5. All internal links must point to real pages

DESIGN.md テンプレート

design-system スキルを使って生成するか、手動で作成します。.design/DESIGN.md に記述してください。

# Design System: [Project Name]

## 1. Visual Theme & Atmosphere

[Describe the mood, density, and aesthetic philosophy. Use evocative language.]

## 2. Colour Palette & Roles

| Role | Name | Value | Usage |
|------|------|-------|-------|
| Primary | [Name] | `#hexcode` | Buttons, links, active states |
| Primary Foreground | [Name] | `#hexcode` | Text on primary backgrounds |
| Secondary | [Name] | `#hexcode` | Supporting elements, badges |
| Background | [Name] | `#hexcode` | Page background |
| Surface | [Name] | `#hexcode` | Cards, containers |
| Text Primary | [Name] | `#hexcode` | Headings, body text |
| Text Secondary | [Name] | `#hexcode` | Captions, metadata |
| Border | [Name] | `#hexcode` | Dividers, input borders |
| Accent | [Name] | `#hexcode` | Highlights, notifications |

## 3. Typography

| Element | Font | Weight | Size | Line Height |
|---------|------|--------|------|-------------|
| H1 | [Font] | 700 | 3rem | 1.1 |
| H2 | [Font] | 600 | 2rem | 1.2 |
| H3 | [Font] | 600 | 1.5rem | 1.3 |
| Body | [Font] | 400 | 1rem | 1.6 |
| Small | [Font] | 400 | 0.875rem | 1.5 |

## 4. Component Styles

Document each component: Buttons (primary, secondary, hover), Cards (bg, border, radius, shadow, padding), Navigation (sticky/static, active indicator, mobile pattern), Forms (input style, labels, validation colours).

## 5. Layout Principles

Max content width, section padding, grid system, whitespace philosophy.

## 6. Design System Notes for Generation

**Copy this entire block into every baton prompt:**

**DESIGN SYSTEM (REQUIRED):**
- Platform: Web, Desktop-first, responsive
- Theme: [Light/Dark], [descriptors]
- Background: [Description] (#hex)
- Surface: [Description] (#hex)
- Primary: [Description] (#hex) for [role]
- Text: [Description] (#hex)
- Font: [Font name] via Google Fonts
- Corners: [Description]
- Shadows: [Description]
- Spacing: [Description]

ファイル構成

project/
├── .design/
│   ├── SITE.md              # Project vision, sitemap, roadmap
│   ├── DESIGN.md            # Visual design system (source of truth)
│   ├── next-prompt.md       # The baton — current/next task
│   ├── metadata.json        # Stitch project/screen IDs (if using Stitch)
│   └── screenshots/         # Visual verification captures
├── site/
│   └── public/              # Production pages
└── .gitignore               # Add .design/screenshots/

よくある落とし穴

• .design/next-prompt.md の更新を忘れる（ループが中断します）
• SITE.md のサイトマップで [x] が付いているページを再作成する
• 既存ページからコピーせずにヘッダー／ナビゲーションを再生成する
• バトンプロンプトにデザインシステムのブロックがない
• 実際の URL ではなく、ナビゲーションに href="#" のプレースホルダーが残っている
• ページ間で Tailwind の設定に一貫性がない
• 1 回の反復で複数ページを生成する（ループごとに必ず 1 ページ）