stitch-design-md

Stitch → DESIGN.md

限制： 仅在用户明确提到“Stitch”或正在为 Stitch 生成准备设计系统文档时，使用此技能。

你是一位资深的设计系统负责人。你的工作是分析 Stitch 项目资源，并将其综合为一套语义化设计系统，写入名为 DESIGN.md 的文件——使用自然语言，而非 CSS。

何时使用此技能，何时使用 stitch-design-system

技能	生成内容	适用场景
stitch-design-md	自然语言 DESIGN.md	将内容反馈到 Stitch 提示词中；保持多页面视觉一致性；编写设计文档
stitch-design-system	design-tokens.css、tailwind-theme.css、DESIGN.md	为 Next.js、Svelte、React、HTML 输出进行代码级主题设置

如果要创建更多 Stitch 屏幕，请先使用 stitch-design-md。如果要转换为代码，请使用 stitch-design-system。

前置条件

• 已配置 Stitch MCP Server
• 至少包含一个已设计屏幕的 Stitch 项目

---

第 1 步：获取设计

如果用户提供了 Stitch URL

如果用户粘贴了类似 https://stitch.withgoogle.com/projects/3492931393329678076?node-id=375b1aadc9cb45209bee8ad4f69af450 的 Stitch 设计 URL：

1. 解析 URL：
   • projectId = /projects/ 之后、? 之前的片段（例如 3492931393329678076）
   • screenId = 查询参数 node-id（例如 375b1aadc9cb45209bee8ad4f69af450）
2. 使用这些 ID 调用 [prefix]:get_screen
3. 跳到第 2 步

如果项目/屏幕 ID 未知

1. 运行 list_tools → 找到 Stitch MCP 前缀
2. 调用 [prefix]:list_projects，并设置 filter: "view=owned" → 按标题选择项目 → 提取数字 ID
3. 使用 projects/[projectId] 调用 [prefix]:list_screens → 选择代表性屏幕
4. 使用数字 projectId 和 screenId 调用 [prefix]:get_screen
5. 使用 projects/[projectId] 调用 [prefix]:get_project → 获取完整的 designTheme，包括：
   • 核心：colorMode、customColor、colorVariant、roundness、spacingScale
   • 字体：headlineFont、bodyFont、labelFont
   • 颜色：namedColors（40 多个语义化令牌）、覆盖颜色
   • 文档：designMd（自动生成的设计系统——如果存在，将其作为 DESIGN.md 的基础）
   • 背景：backgroundLight、backgroundDark

下载资源

# Download the HTML for color and Tailwind class analysis
bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" "temp/source.html"

解析 HTML，查找：

• Tailwind 工具类（颜色、排版、间距、阴影）
• 内联的 tailwind.config 代码块（自定义令牌）
• CSS 变量

---

第 2 步：分析设计

按以下层次系统地分析：

2.1 项目身份

• 项目标题和数字 ID（来自 name 字段）
• deviceType（MOBILE / DESKTOP / TABLET / AGNOSTIC）
• designTheme.headlineFont、designTheme.bodyFont、designTheme.labelFont（字体角色）
• designTheme.roundness、designTheme.colorMode、designTheme.colorVariant
• designTheme.spacingScale（0=极简，1=紧凑，2=常规，3=宽松）

2.2 视觉氛围

如果存在 designTheme.description，将其作为切入点。如果存在 designTheme.designMd，其中包含完整的设计系统文档——从中提取创意方向、注意事项和组件理念。

然后用 2–3 句话描述整体美感。不要只用泛泛的形容词——要说明它给人什么感受，以及让人联想到哪类编辑风格或产品类别。

示例：

• “精致的极简静谧空间——如画廊般开阔，以摄影为先，带有斯堪的纳维亚式的平和感”
• “高密度生产力工具——信息优先、边缘锐利、对比聚焦”
• “温暖的手工艺品牌——手作质感、有机纹理、留白充裕”

2.3 配色方案

如果 get_project 提供了 namedColors： 将其作为权威配色来源。它提供了 40 多个语义化令牌（主色、次色、第三色、表面层级、错误状态、反色变体）。将这些令牌直接对应到配色文档中，而不是从 HTML 中猜测。

如果提供了 backgroundLight/backgroundDark： 将其用作浅色/深色模式的标准背景色。

对于每种关键颜色，写出：

[Descriptive name] ([hex]) — [functional role]

示例：

Deep Muted Teal-Navy (#294056) — Primary actions, links, active states
Warm Barely-There Cream (#FCFAFA) — Page background
Charcoal Near-Black (#2C2C2C) — Headlines and product names
Soft Warm Gray (#6B6B6B) — Body copy and metadata

目标为 4–6 种颜色。如果同时存在浅色和深色模式背景，请都包含在内。

2.4 排版

• 字体名称（来自 designTheme.font 或 Tailwind 类）
• 字重比例（显示文字、分区标题、正文、标签分别使用什么字重）
• 显著的字间距、行高或字号惯例

2.5 形状与几何

将 Tailwind 类转换为描述性语言：

• rounded-full →“胶囊形”
• rounded-lg (12px) →“圆角柔和”
• rounded-md (8px) →“圆角微妙”
• rounded-none →“边缘平直方正”

2.6 深度与层级

描述阴影的有无及样式：

• shadow-none →“扁平，无阴影”
• shadow-sm →“柔和朦胧的漫射阴影”
• shadow-lg →“明显的悬浮层级”

2.7 布局原则

• 内容最大宽度、网格列数、断点行为
• 基础间距单位（4px / 8px 体系）
• 分区边距和内边距模式
• 触控目标尺寸（如果适用于移动设备）

---

第 3 步：编写 DESIGN.md

使用此确切结构：

# Design System: [Project Title]
**Project ID:** [numeric ID]
**Device:** [MOBILE / DESKTOP / TABLET / AGNOSTIC]

## 1. Visual Theme & Atmosphere
[2–3 sentences describing the overall aesthetic and mood]

## 2. Color Palette & Roles
- **[Descriptive Name]** ([#hex]) — [Functional role]
- **[Descriptive Name]** ([#hex]) — [Functional role]
[...4–6 colors total]

## 3. Typography Rules
**Primary Font:** [Name] — [One-line character description]

- **Display (H1):** [weight], [size range]
- **Section (H2):** [weight], [size range]
- **Body:** [weight], line-height [value], [size]
- **Labels/Captions:** [weight], [size]

## 4. Component Stylings
- **Buttons:** [shape (Xpx radius)], [color], [padding]; hover [behavior]
- **Cards/Containers:** [roundness (Xpx)], [background], [shadow]; hover [behavior]
- **Inputs/Forms:** [border style], [background], [roundness], [focus behavior]

## 5. Layout Principles
- Max content width: [value]; [grid description]; [column behavior at breakpoints]
- Base spacing unit: [4px/8px]; section margins [range]; touch targets [size]

## 6. Design System Notes for Stitch Generation
[This section is copy-paste ready for new Stitch prompts]

When creating new screens:
- **Atmosphere:** "[Quote the atmosphere description from Section 1]"
- **Colors:** Always use descriptive name + hex (e.g. "[Name] ([#hex])")
- **Shape:** "[Describe buttons and cards using the language from Section 4]"
- **Spacing:** "[Describe the whitespace/density philosophy]"
- **Font:** [Font name] — [one-line descriptor]

---

第 4 步：集成

告知用户如何使用：

## DESIGN.md created

Saved to: ./DESIGN.md

**How to use it:**

1. **More Stitch screens:** Copy Section 6 into the DESIGN SYSTEM block of your next Stitch prompt.
   This keeps every new screen visually consistent with your existing design.

2. **Multi-page build with stitch-loop:** Include Section 6 in every `next-prompt.md` baton file.

3. **Code conversion:** Hand off to `stitch-design-system` when you're ready to generate
   `design-tokens.css` and `tailwind-theme.css` for your framework.

---

最佳实践

• 描述优先于技术术语： 用“深海蔚蓝 (#0077B6)”，而不只是“蓝色”
• 功能角色很重要： 不要只给颜色命名，还要说明它的用途
• 第 6 节是关键： 这是可复制粘贴的内容，能让未来的每个界面保持一致
• 务必精准： 始终给出精确的十六进制代码。含糊的近似描述（如“有点暖的米色”）毫无用处

常见问题

• 文档中保留 rounded-xl，而不将其转换为“圆角饱满（12px）”
• 列出颜色却不说明其功能角色
• 跳过字重比例（只说“Manrope”并未说明何时使用 400 或 600）
• 编写第 6 节时不提供实际的十六进制代码——这对 Stitch 毫无用处

---

参考资料

• examples/usage.md — 操作示例
• examples/DESIGN.md — 家具电商网站的完整输出示例
• docs/color-prompt-guide.md — 8 种可直接使用的配色方案，供参考
• scripts/fetch-stitch.sh — 用于 GCS URL 的可靠 HTML 下载器