design-loop

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. 检查 .dev.vars 或环境中是否设置了 STITCH_API_KEY
3. 检查 .design/metadata.json 是否存在（其中包含 Stitch 项目 ID）

如果这三项都满足，则使用 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"。模型选择：将 "GEMINI_3_PRO" | "GEMINI_3_FLASH" 作为第三个参数传给 generate()。

其他操作：stitch.projects() 列出项目，project.screens() 列出屏幕，project.getScreen("id") 获取单个屏幕。

getHtml() 和 getImage() 会返回下载 URL。在图片 URL 后追加 =w1280 可获取完整分辨率。身份验证：需要 STITCH_API_KEY（或者使用 STITCH_ACCESS_TOKEN + GOOGLE_CLOUD_PROJECT 进行 OAuth）。发生错误时会抛出带有以下代码的 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           # 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）

后续运行：读取接力棒

如果 .design/next-prompt.md 已存在，则解析该文件并继续循环。

接力文件

.design/next-prompt.md 包含 YAML frontmatter 和提示词正文：

---
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 中的设计系统
• 复用现有页面的相同页眉／导航／页脚（原样复制）
• 独立完整——单个 HTML 文件，使用 Tailwind CDN，无需构建步骤
• 响应式——移动优先，适用于所有断点
• 如果设计系统有规定，包含深色模式
• 使用语义化 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 中的确切十六进制代码，切勿近似替代
字体导入	所有页面使用相同的 Google Fonts <link> 标签
间距比例	保持内边距和外边距值一致（记录在 DESIGN.md 中）

设计映射

编写交接提示时，使用这些映射将含糊的用户请求转换为明确的设计指示。

UI/UX 关键词优化

含糊表述	专业术语
"顶部的菜单"	"带有 Logo 和菜单项的粘性导航栏"
"大照片"	"带有焦点图像的全宽 Hero 区域"
"事物列表"	"带悬停状态和轻微悬浮效果的响应式卡片网格"
"按钮"	"带悬停过渡效果的主要行动号召按钮"
"表单"	"包含带标签的输入字段、验证状态和提交按钮的表单"
"图片区域"	"带背景图片或视频的 Hero 区域"
"侧边栏"	"带图标与标签配对的可折叠侧边导航"
"弹出窗口"	"带遮罩层和平滑进入动画的模态对话框"
"页脚内容"	"包含站点地图链接、联系信息和法律声明的页脚"
"卡片"	"具有统一内边距、圆角和阴影的内容卡片"
"标签页"	"带活动状态指示器和平滑内容切换效果的标签式界面"
"搜索"	"带图标、占位文本和结果下拉菜单的搜索输入框"
"定价"	"突出显示推荐套餐的价格对比卡片"
"推荐语"	"带头像、引言和署名的推荐语轮播或网格"

氛围与风格描述

基本风格	增强描述
"现代"	"简洁、极简、留白充足、字体对比鲜明"
"专业"	"精致、值得信赖、阴影柔和、受限的高端配色"
"有趣 / 活泼"	"色彩鲜艳、圆角、大胆的强调色、轻快的动画"
"深色模式"	"在深石板色或近黑色背景上使用高对比度强调色"
"奢华"	"优雅、空间宽敞、线条纤细、衬线标题、高保真摄影"
"科技 / 赛博"	"未来感、霓虹强调色、玻璃拟态、等宽字体"
"温暖 / 友好"	"柔和的色彩、圆润的形状、手写风格点缀、亲切的图像"
"大胆 / 工业"	"醒目的字体、高对比度、几何形状、深色背景"
"有机 / 自然"	"大地色调、柔和纹理、有机形状、自然摄影"
"编辑风格"	"杂志式布局、鲜明的字体层级、宽松的行距"

几何形状、纵深与间距

描述	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：

# 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] 的页面
• 重新生成页眉 / 导航栏，而不是从现有页面复制
• 接力提示词中缺少设计系统区块
• 导航栏中留有 href="#" 占位符，而不是实际 URL
• 各页面的 Tailwind 配置不一致
• 每次迭代生成多个页面（始终每轮只生成一个页面）