设计工作流技能

模块职责

stitch-design 是 Stitch Design Skills 项目里的设计流程插件，负责把常见的“产品界面设计工作”串成可由 Agent 执行的技能流程。它覆盖从已有前端代码迁移，到新界面生成，再到设计系统沉淀和上传 Stitch 的核心路径。

典型场景包括：

场景	使用的技能	结果
把现有 React / Vue / Web 项目迁移到 Stitch	`stitch::code-to-design`	提取页面 HTML、整理设计系统、上传为 Stitch Design
根据一句需求生成新页面	`stitch::generate-design`	在 Stitch 中生成新的 screen
修改已有设计稿	`stitch::generate-design`	对指定 screen 做编辑或生成变体
把项目里的视觉规范沉淀成设计系统	`stitch::manage-design-system`	上传或应用 `DESIGN.md`
从前端代码中抽取可复用规范	`stitch::code-to-design` / 设计系统流程	生成或更新 `DESIGN.md`
将本地页面导出为静态 HTML 并导入 Stitch	`stitch::code-to-design`	生成可上传的静态页面并创建 Stitch 项目

这个模块不直接替代设计工具，而是让编码 Agent 能够通过 Stitch MCP Server 操作 Stitch：读取代码、分析 UI、生成设计说明、创建或更新 Stitch 项目。

关键代码和接口说明

插件入口：`plugins/stitch-design`

stitch-design 是推荐安装的设计插件，包含设计相关技能。

text
plugins/
  stitch-design/
    skills/
      code-to-design/
      generate-design/
      manage-design-system/

安装后，Agent 可以通过技能名调用对应流程。

技能名	目录	职责
`stitch::code-to-design`	`plugins/stitch-design/skills/code-to-design/`	将前端代码、静态 HTML 或页面截图转换为 Stitch Design
`stitch::generate-design`	`plugins/stitch-design/skills/generate-design/`	根据文本或图片生成界面，编辑已有 screen，生成设计变体
`stitch::manage-design-system`	`plugins/stitch-design/skills/manage-design-system/`	上传 `DESIGN.md`，管理设计系统，并将主题应用到 screen

`stitch::code-to-design`：从代码到 Stitch 设计

适合已有前端项目迁移，例如：

React / Next.js 仪表盘
Vue 管理后台
静态 HTML 落地页
已有组件库页面
需要保留视觉样式的老项目

核心流程通常是：

text
前端代码
  ↓
安装依赖并启动或构建
  ↓
渲染页面 / 抽取 HTML
  ↓
收集 CSS、字体、图片等资源
  ↓
识别颜色、字号、间距、组件模式
  ↓
生成或更新 DESIGN.md
  ↓
通过 Stitch MCP 上传到 Stitch 项目

常见输入：

输入	说明
项目路径	例如 `/path/to/dashboard`
目标 Stitch 项目名	例如 `Dashboard-Migration-2026`
页面范围	首页、登录页、仪表盘、设置页等
视口尺寸	移动端、桌面端、响应式断点
是否生成设计系统	是否从代码中提取 token、组件和规范

示例提示词：

text
Upload the frontend code at ./demo-dashboard into a Stitch project named "Dashboard-Migration-2026".
Extract the design system into DESIGN.md and include the login and dashboard screens.

中文写法也可以：

text
请把 ./demo-dashboard 这个前端项目上传到 Stitch，
项目名为 Dashboard-Migration-2026。
请提取颜色、字体、间距、按钮、卡片等设计规范，生成 DESIGN.md。

`stitch::generate-design`：生成、编辑和变体设计

适合从需求直接生成界面，或者对已有 Stitch screen 做迭代。

支持的常见操作：

操作	示例
文本生成设计	“生成一个约会灵感 App 的浏览页”
图片生成设计	“根据这张截图生成相似风格的移动端页面”
编辑已有 screen	“在登录页增加 Remember Me 复选框”
生成多个变体	“基于首页生成 3 个深色模式高信息密度变体”

示例提示词：

text
Generate a mobile browse tab for a romance and date night ideas app.
Use a warm color palette, card-based layout, and bottom navigation.

编辑已有设计：

text
Edit the login screen:
- Add a "Remember Me" checkbox below the password field.
- Change the primary button color to blue.
- Keep the existing spacing and typography.

生成变体：

text
Generate 3 design variants of the home screen:
1. Dark mode
2. High-density layout
3. Premium editorial style

`stitch::manage-design-system`：管理 DESIGN.md 和主题

manage-design-system 用来把设计系统说明同步到 Stitch，或者将某套主题应用到已有 screens。

常见任务：

text
DESIGN.md
  ↓
上传到 Stitch
  ↓
解析颜色、字体、组件、布局规范
  ↓
应用到指定 screen 或整个项目

示例提示词：

text
Upload ./DESIGN.md to the current Stitch project and apply the theme to all dashboard screens.

中文写法：

text
请将当前项目根目录下的 DESIGN.md 上传到 Stitch，
并把其中定义的主题应用到所有 dashboard 相关页面。

`DESIGN.md`：设计系统交换文件

DESIGN.md 是这个工作流里很重要的中间产物。它适合存放从代码中提取出的设计规范，也适合人工维护后再上传到 Stitch。

建议包含：

markdown
# Design System

## Colors

| Token | Value | Usage |
|---|---|---|
| `color.primary` | `#2563eb` | Primary buttons, active states |
| `color.background` | `#f8fafc` | Page background |
| `color.text.primary` | `#0f172a` | Main text |

## Typography

| Token | Value | Usage |
|---|---|---|
| `font.family.base` | `Inter, sans-serif` | Default UI font |
| `font.size.body` | `16px` | Body text |
| `font.size.heading` | `32px` | Page titles |

## Spacing

| Token | Value |
|---|---|
| `space.1` | `4px` |
| `space.2` | `8px` |
| `space.4` | `16px` |
| `space.6` | `24px` |

## Components

### Button

- Primary button uses `color.primary`.
- Border radius: `8px`.
- Height: `40px`.
- Horizontal padding: `16px`.

### Card

- Background: white.
- Border: `1px solid #e2e8f0`.
- Border radius: `12px`.
- Padding: `24px`.

## Accessibility

- Body text contrast should meet WCAG AA.
- Interactive controls need visible focus states.
- Buttons and inputs should have accessible labels.

在代码转设计流程中，Agent 可以根据项目里的 CSS、Tailwind 配置、组件实现和页面样式生成这个文件。

在设计系统管理流程中，Agent 可以把这个文件上传到 Stitch 并应用到 screens。

静态 HTML 导出接口

code-to-design 经常需要把前端项目先转换为 Stitch 更容易理解的静态页面。这个过程不是要求项目必须是纯 HTML，而是将 React、Vue、Next.js 等运行结果导出或渲染成 HTML/CSS/资源集合。

建议导出的页面满足：

text
dist/
  index.html
  assets/
    app.css
    app.js
    logo.svg
    image.png

更稳定的导出要求：

要求	原因
HTML 可以本地打开或由静态服务器访问	方便 Agent 抽取结构
CSS 尽量完整	保留真实视觉样式
图片、字体路径可访问	避免上传后资源丢失
页面状态固定	避免加载态、空数据态被误识别为正式设计
登录态可绕过或提供 mock 数据	方便截取真实页面

Stitch MCP Server：上传和设计操作通道

这些技能依赖 Stitch MCP Server。Agent 本身不直接访问 Stitch，而是通过 MCP Server 完成：

创建 Stitch 项目
上传设计
上传 DESIGN.md
应用主题
编辑 screens
生成设计变体

使用前需要完成 Stitch MCP 配置，并确保相关环境变量、凭据和 MCP server 已在当前 Agent 环境中可用。

使用示例（可运行）

下面示例以本地创建一个简单静态页面为例，演示从“页面代码”到“上传 Stitch”的完整路径。

1. 安装 Stitch Design 插件

Codex

bash
codex plugin marketplace add google-labs-code/stitch-skills --ref main \
  --sparse .agents/plugins \
  --sparse plugins/stitch-design \
  --sparse plugins/stitch-build \
  --sparse plugins/stitch-utilities

安装插件：

bash
codex plugin install stitch-design

如果你的 Codex 版本使用不同的插件安装命令，请先执行：
bash
codex plugin --help

Claude Code

bash
npx plugins add google-labs-code/stitch-skills --scope project --target claude-code

Cursor

bash
npx plugins add google-labs-code/stitch-skills --scope workspace --target cursor

2. 创建一个可导出的静态页面

bash
mkdir -p demo-stitch-dashboard/assets
cd demo-stitch-dashboard

创建 index.html：

bash
cat > index.html <<'EOF'
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Revenue Dashboard</title>
  <link rel="stylesheet" href="./assets/styles.css" />
</head>
<body>
  <main class="page">
    <aside class="sidebar">
      <div class="brand">Northstar</div>
      <nav>
        <a class="active">Dashboard</a>
        <a>Customers</a>
        <a>Reports</a>
        <a>Settings</a>
      </nav>
    </aside>

    <section class="content">
      <header class="topbar">
        <div>
          <p class="eyebrow">Q1 Overview</p>
          <h1>Revenue Dashboard</h1>
        </div>
        <button class="button">Export report</button>
      </header>

      <section class="stats">
        <article class="card">
          <span>Total Revenue</span>
          <strong>$128,400</strong>
          <em>+12.8% from last month</em>
        </article>
        <article class="card">
          <span>Active Customers</span>
          <strong>8,249</strong>
          <em>+4.2% from last month</em>
        </article>
        <article class="card">
          <span>Conversion Rate</span>
          <strong>7.4%</strong>
          <em>-0.6% from last month</em>
        </article>
      </section>

      <section class="panel">
        <div class="panel-header">
          <h2>Pipeline Health</h2>
          <span>Updated 5 min ago</span>
        </div>
        <div class="bars">
          <div style="--value: 86%">Enterprise</div>
          <div style="--value: 64%">Mid-market</div>
          <div style="--value: 42%">SMB</div>
        </div>
      </section>
    </section>
  </main>
</body>
</html>
EOF

创建 assets/styles.css：

bash
cat > assets/styles.css <<'EOF'
:root {
  --color-primary: #2563eb;
  --color-primary-dark: #1d4ed8;
  --color-bg: #f8fafc;
  --color-surface: #ffffff;
  --color-border: #e2e8f0;
  --color-text: #0f172a;
  --color-muted: #64748b;
  --radius-card: 18px;
  --shadow-card: 0 20px 40px rgba(15, 23, 42, 0.08);
}

* {
  box-sizing: border-box;
}

body {
  margin: 0;
  font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
  color: var(--color-text);
  background: var(--color-bg);
}

.page {
  min-height: 100vh;
  display: grid;
  grid-template-columns: 260px 1fr;
}

.sidebar {
  background: #0f172a;
  color: white;
  padding: 32px 24px;
}

.brand {
  font-size: 24px;
  font-weight: 800;
  margin-bottom: 40px;
}

nav {
  display: grid;
  gap: 10px;
}

nav a {
  color: #cbd5e1;
  padding: 12px 14px;
  border-radius: 12px;
}

nav a.active {
  color: white;
  background: rgba(255, 255, 255, 0.12);
}

.content {
  padding: 40px;
}

.topbar {
  display: flex;
  align-items: center;
  justify-content: space-between;
  margin-bottom: 32px;
}

.eyebrow {
  margin: 0 0 8px;
  color: var(--color-primary);
  font-weight: 700;
  text-transform: uppercase;
  letter-spacing: 0.08em;
  font-size: 12px;
}

h1 {
  margin: 0;
  font-size: 40px;
  line-height: 1.1;
}

.button {
  border: 0;
  background: var(--color-primary);
  color: white;
  height: 44px;
  padding: 0 18px;
  border-radius: 12px;
  font-weight: 700;
  cursor: pointer;
}

.button:hover {
  background: var(--color-primary-dark);
}

.stats {
  display: grid;
  grid-template-columns: repeat(3, minmax(0, 1fr));
  gap: 20px;
  margin-bottom: 24px;
}

.card,
.panel {
  background: var(--color-surface);
  border: 1px solid var(--color-border);
  border-radius: var(--radius-card);
  box-shadow: var(--shadow-card);
}

.card {
  padding: 24px;
  display: grid;
  gap: 10px;
}

.card span {
  color: var(--color-muted);
  font-size: 14px;
}

.card strong {
  font-size: 32px;
}

.card em {
  color: #16a34a;
  font-style: normal;
  font-size: 14px;
}

.panel {
  padding: 28px;
}

.panel-header {
  display: flex;
  justify-content: space-between;
  margin-bottom: 24px;
}

.panel-header h2 {
  margin: 0;
}

.panel-header span {
  color: var(--color-muted);
}

.bars {
  display: grid;
  gap: 16px;
}

.bars div {
  position: relative;
  padding: 14px 16px;
  border-radius: 12px;
  background: #eff6ff;
  overflow: hidden;
  font-weight: 700;
}

.bars div::before {
  content: "";
  position: absolute;
  inset: 0 auto 0 0;
  width: var(--value);
  background: rgba(37, 99, 235, 0.18);
}

@media (max-width: 800px) {
  .page {
    grid-template-columns: 1fr;
  }

  .sidebar {
    display: none;
  }

  .content {
    padding: 24px;
  }

  .topbar,
  .stats {
    grid-template-columns: 1fr;
    display: grid;
    gap: 16px;
  }
}
EOF

启动本地静态服务器：

bash
python3 -m http.server 4173

打开浏览器访问：

text
http://localhost:4173

如果页面可以正常显示，就可以交给 Agent 处理。

3. 让 Agent 转换页面并上传 Stitch

在支持 Agent Skills 的工具里输入：

text
Use stitch::code-to-design.

Convert the static page at http://localhost:4173 into a Stitch design.
Create a Stitch project named "Revenue-Dashboard-Demo".
Extract the design tokens, components, typography, spacing, and layout rules into DESIGN.md.
Upload the resulting design and DESIGN.md to Stitch.

中文提示词：

text
使用 stitch::code-to-design。

请把 http://localhost:4173 这个静态页面转换为 Stitch 设计。
创建 Stitch 项目 Revenue-Dashboard-Demo。
请从页面中提取颜色、字体、间距、圆角、阴影、按钮、卡片和布局规则，
生成 DESIGN.md，并和设计稿一起上传到 Stitch。

完成后应得到：

text
Revenue-Dashboard-Demo
  ├─ Dashboard screen
  └─ DESIGN.md / Design system

4. 手动补充 DESIGN.md 并上传

如果希望先手写设计系统，再应用到 Stitch，可以在 demo-stitch-dashboard 目录下创建 DESIGN.md：

bash
cat > DESIGN.md <<'EOF'
# Revenue Dashboard Design System

## Colors

| Token | Value | Usage |
|---|---|---|
| `color.primary` | `#2563eb` | Primary action buttons, active highlights |
| `color.primary.dark` | `#1d4ed8` | Button hover states |
| `color.background` | `#f8fafc` | App background |
| `color.surface` | `#ffffff` | Cards and panels |
| `color.text` | `#0f172a` | Main text |
| `color.muted` | `#64748b` | Secondary text |
| `color.border` | `#e2e8f0` | Card and panel borders |

## Typography

- Font family: Inter, system UI fallback.
- Page title: 40px, 1.1 line-height, bold.
- Section title: 24px, bold.
- Body text: 16px.
- Supporting text: 14px.

## Spacing

| Token | Value |
|---|---|
| `space.2` | `8px` |
| `space.3` | `12px` |
| `space.4` | `16px` |
| `space.5` | `20px` |
| `space.6` | `24px` |
| `space.8` | `32px` |
| `space.10` | `40px` |

## Components

### Sidebar

- Width: 260px.
- Background: `#0f172a`.
- Navigation item radius: 12px.
- Active item background: `rgba(255, 255, 255, 0.12)`.

### Button

- Height: 44px.
- Horizontal padding: 18px.
- Radius: 12px.
- Background: `color.primary`.
- Text: white, bold.

### Card

- Background: `color.surface`.
- Border: `1px solid color.border`.
- Radius: 18px.
- Shadow: `0 20px 40px rgba(15, 23, 42, 0.08)`.
- Padding: 24px.

### Panel

- Uses the same surface, border, radius, and shadow as cards.
- Padding: 28px.

## Responsive Rules

- Desktop layout uses a 260px sidebar and flexible content area.
- Under 800px, sidebar is hidden and content uses 24px padding.
- Metric cards stack vertically on small screens.
EOF

然后让 Agent 执行：

text
Use stitch::manage-design-system.

Upload ./DESIGN.md to the Stitch project "Revenue-Dashboard-Demo".
Apply this design system to the Dashboard screen.

5. 生成一个新页面并复用设计系统

上传设计系统后，可以继续生成新 screen：

text
Use stitch::generate-design.

In the Stitch project "Revenue-Dashboard-Demo",
create a new "Customer Detail" screen using the existing design system.

The screen should include:
- customer profile summary
- revenue history card
- recent activity list
- risk score panel
- primary action button: "Schedule review"

也可以要求多个变体：

text
Use stitch::generate-design.

Create 3 variants of the Dashboard screen:
1. A compact executive summary
2. A dark mode dashboard
3. A mobile-first dashboard
Keep the same design system tokens unless a variant explicitly requires changes.

注意边界

必须配置 Stitch MCP Server

这些技能依赖 Stitch MCP Server。没有 MCP 配置时，Agent 可能只能分析代码或生成本地文件，无法真正创建 Stitch 项目、上传设计或应用主题。

使用前确认：

Stitch MCP Server 已安装并运行。
Agent 工具能访问 MCP Server。
Stitch 账号凭据和环境变量已配置。
当前工作区允许 Agent 读取目标代码目录。

代码转设计不是源码编译器

stitch::code-to-design 的目标是生成可编辑设计，而不是完整还原应用行为。

适合提取：

页面布局
视觉层级
颜色、字体、间距、圆角、阴影
常见组件形态
静态内容和典型状态

不适合期待完整保留：

复杂交互逻辑
后端 API 调用
实时数据刷新
动画细节
权限流转
路由守卫
业务状态机

如果页面依赖登录或远程数据，建议先提供 mock 数据，或者把目标页面导出成稳定的静态 HTML。

页面状态要固定

上传前最好让页面处在“设计师想看到的状态”。

例如仪表盘页面应避免停留在：

loading skeleton
空状态
报错状态
登录过期状态
数据未加载状态

如果需要这些状态，可以明确告诉 Agent：

text
Please capture four states:
1. Loading
2. Empty
3. Error
4. Loaded dashboard

DESIGN.md 需要可执行而不是只写口号

不推荐：

markdown
The design should feel modern, clean, and premium.

资源路径要可访问

从代码或 HTML 上传设计时，图片、字体、图标最好能被本地服务器访问。

容易出问题的情况：

问题	建议
图片使用内网 URL	下载到本地 assets 后再引用
字体依赖第三方 CDN	提供 fallback 或本地字体
CSS 通过运行时动态注入	先构建或导出静态页面
页面需要登录 cookie	使用 mock 页面或已授权会话
iframe 嵌套复杂页面	尽量展开为普通 HTML

生成设计需要给清楚约束

stitch::generate-design 可以从一句话生成界面，但给出的上下文越明确，结果越稳定。

建议说明：

设备类型：mobile、desktop、tablet
产品类型：SaaS、内容社区、电商、工具类 App
页面目标：转化、浏览、编辑、管理、分析
设计风格：material、editorial、dense、playful、enterprise
必需组件：搜索框、筛选器、卡片、表格、底部导航等
是否使用已有设计系统
是否生成多个变体

示例：

text
Generate a desktop SaaS billing settings page.
Use the existing design system.
Include current plan, usage meter, payment method, invoice table, and upgrade CTA.
Use an enterprise style with high information density.

选择性安装技能时要注意依赖

README 中明确提到：Stitch Design Skills 之间可能存在依赖。如果只安装单个技能，可能会缺少辅助流程。

稳妥做法是安装完整插件：

bash
npx plugins add google-labs-code/stitch-skills --scope project --target claude-code

或至少安装完整 stitch-design 插件，而不是只复制单个 skill 目录。

上传前先小范围验证

大型项目不要一开始就要求 Agent 上传全部页面。建议先选 1 到 3 个代表性页面：

text
Convert only these routes first:
- /login
- /dashboard
- /settings/billing

确认风格、组件识别和 DESIGN.md 质量后，再扩展到全项目。

模块拆解：设计工作流技能

设计工作流技能

模块职责

关键代码和接口说明

插件入口：plugins/stitch-design

stitch::code-to-design：从代码到 Stitch 设计

stitch::generate-design：生成、编辑和变体设计

stitch::manage-design-system：管理 DESIGN.md 和主题

DESIGN.md：设计系统交换文件

静态 HTML 导出接口

Stitch MCP Server：上传和设计操作通道

使用示例（可运行）

1. 安装 Stitch Design 插件

Codex

Claude Code

Cursor

2. 创建一个可导出的静态页面

3. 让 Agent 转换页面并上传 Stitch

4. 手动补充 DESIGN.md 并上传

5. 生成一个新页面并复用设计系统

注意边界

必须配置 Stitch MCP Server

代码转设计不是源码编译器

页面状态要固定

DESIGN.md 需要可执行而不是只写口号

资源路径要可访问

生成设计需要给清楚约束

选择性安装技能时要注意依赖

上传前先小范围验证

插件入口：`plugins/stitch-design`

`stitch::code-to-design`：从代码到 Stitch 设计

`stitch::generate-design`：生成、编辑和变体设计

`stitch::manage-design-system`：管理 DESIGN.md 和主题

`DESIGN.md`：设计系统交换文件