BIGboss248/nextjs-wordpress

Google Stitch UI 原型设计与变体技能（stitch-design）

此技能定义了完整的自动化工作流，用于获取已建立的组件设计规范（design-spec.md），并使用 Google Stitch（StitchMCP） 来搭建屏幕布局、生成空间变体、将高分辨率视觉资产（JPG 截图和原始 HTML 导出文件）下载到代码库中，并用具体的布局基准更新设计规范。

[!IMPORTANT] 输入前置要求： 该技能需要在 docs/design/components/[page name]/[component name]/design-spec.md 处存在一份已完成的设计规范（通常由 component-design 生成）。如果规范不存在，请先运行 /component-design。

[!CAUTION] 二进制文件下载安全规则： 切勿使用 read_url_content 下载 Stitch JPG 截图或 HTML 导出文件。read_url_content 仅限文本，并将响应转换为 Markdown，这会损坏二进制图像并破坏 HTML 结构。所有下载必须使用 run_command 配合 PowerShell 的 Invoke-WebRequest -Uri <url> -OutFile <path>。签名的下载 URL 会快速过期——收到 Stitch 响应后需立即下载。

[!TIP] 零技能内图像生成（令牌节约规则）： 为了节约令牌，此技能不得直接调用 generate_image。如果屏幕需要自定义背景图、插画或图标，请构建并向用户输出结构化提示词，以便他们生成并放置到项目文件中。

---

1. 核心交付物与工作流概览

flowchart TD
    Start["调用 /stitch-design<br/>(目标: docs/design/components/[page]/[component]/design-spec.md)"] --> Step1["步骤 1: 导入设计规范<br/>(读取 design-spec.md 和 docs/project.json)"]
    Step1 --> Step2["步骤 2: Stitch 项目持久化与令牌注入<br/>(检查/重用 docs/project.json 中的 stitch.project_id，注入设计系统)"]
    Step2 --> Step3["步骤 3: 通过 StitchMCP 生成屏幕与变体<br/>(generate_screen_from_text + generate_variants 生成 1 个变体)"]
    Step3 --> Step4["步骤 4: 二进制安全资产下载<br/>(PowerShell Invoke-WebRequest → stitch/screen.jpg, screen.html, variant-1.jpg, variant-1.html)"]
    Step4 --> Step5["步骤 5: 设计规范基准集成<br/>(将 stitch/screen.jpg 和变体基准嵌入 design-spec.md)"]
    Step5 --> Step6["步骤 6: 独立子代理验证<br/>(invoke_subagent 验证文件大小、元数据和规范对齐)"]
    Step6 --> Finish["视觉原型就绪<br/>(Stitch JPG + HTML 保存在代码库中)"]

交付物：Stitch 资产子文件夹

每次 Stitch 运行都会在组件的设计目录内创建或填充 stitch/ 子文件夹：

docs/design/components/[page name]/[component name]/
├── design-spec.md          # 已更新，包含 Stitch 基准和嵌入截图
└── stitch/                 # 下载的 Google Stitch 设计文件
    ├── screen.jpg          # Stitch 生成的主屏幕 JPG 截图
    ├── screen.html         # Stitch 生成的主屏幕原始 HTML 导出
    ├── variant-1.jpg       # Stitch 生成的变体 JPG 截图
    ├── variant-1.html      # Stitch 生成的变体原始 HTML 导出
    └── stitch-meta.json    # Stitch 项目 ID、屏幕 ID、变体 ID 和生成提示词

---

2. 逐步执行工作流

步骤 1：导入设计规范与项目上下文

1. 定位目标组件：
   • 确定组件路径：docs/design/components/[page name]/[component name]/。
   • 读取 design-spec.md 以提取：
     • 执行摘要、用户画像和情感基调。
     • 视觉层次（第一、第二和第三焦点）。
     • 布局网格和断点行为。
     • 设计令牌（颜色、圆角、阴影）。
     • 每个语言环境的排版配对。
2. 读取项目上下文：
   • 读取 docs/project.json 以验证规范设计系统并检查现有的 Stitch 配置。

---

步骤 2：Google Stitch 项目持久化与设计系统注入（StitchMCP）

[!IMPORTANT] 每个仓库单项目规则（零重复项目）： 每个仓库必须为其所有组件和屏幕设计维护 一个共享的 Google Stitch 项目容器。切勿为同一仓库创建多个 Stitch 项目。

1. 首先检查 docs/project.json：
   • 检查 docs/project.json 中是否存在带有 project_id 的 "stitch" 对象。
2. 重用现有项目：
   • 如果存在 stitch.project_id，始终直接重用该 projectId 进行所有屏幕搭建、变体和设计系统更新。不要调用 create_project。
3. 创建并立即持久化（仅当不存在时）：
   • 如果 docs/project.json 中不存在 stitch.project_id：
     • 调用 call_mcp_tool 在 StitchMCP 上使用 list_projects 检查是否已存在与仓库标题匹配的项目。
     • 如果不存在，则调用 create_project，设置 title: "[Project Title] Design System & Components"。
     • 立即将项目属性持久化到 docs/project.json 的 "stitch" 键下：

       "stitch": {
         "project_id": "<projectId>",
         "project_name": "projects/<projectId>",
         "title": "<title>"
       }
       

4. 注入设计令牌：
   • 通过 upload_design_md 或 create_design_system_from_design_md 将项目的规范设计系统（来自 docs/project.json）提供给 Stitch，以建立全局颜色、字体和圆角一致性。

---

步骤 3：通过 StitchMCP 生成屏幕与变体

1. 合成详细设计提示词：
   • 结合来自 design-spec.md 的组件用途、用户画像、情感基调和布局要求。
   • 明确指定视觉令牌：来自 docs/project.json 的背景画布、表面卡片、主色、辅色、状态颜色和排版。
   • 指定目标视口：deviceType: "DESKTOP"（如果是移动优先组件，则为 "MOBILE" 或 "TABLET"）。
2. 生成主屏幕：
   • 在 StitchMCP 上调用 generate_screen_from_text：
     • projectId：活动的 Stitch 项目 ID。
     • prompt：合成的设计提示词。
     • deviceType："DESKTOP"。
   • 提取生成的屏幕 ID 和资源名称（格式：projects/{projectId}/screens/{screenId}）。
3. 生成一个变体：
   • 使用生成的屏幕 ID 在 StitchMCP 上调用 generate_variants，为该设计规范文件生成一个空间/视觉变体（例如，探索替代布局密度、卡片与通栏、或非对称视觉流程）。
   • 记录变体屏幕 ID。

---

步骤 4：二进制安全资产下载协议

[!CAUTION] 需要 PowerShell Invoke-WebRequest： 每次下载命令作为离散的单个操作运行。验证每个下载的文件具有非零字节大小（对于 JPG 文件，大于 10KB）。

1. 确保目录存在：
   • 目标目录：docs/design/components/[page name]/[component name]/stitch/。
2. 下载主屏幕 JPG：
   • 从主屏幕响应中提取 screenshot.downloadUrl。
   • 执行：

     powershell -Command "Invoke-WebRequest -Uri '<screenshot.downloadUrl>' -OutFile 'docs/design/components/[page]/[component]/stitch/screen.jpg'"
     

3. 下载主屏幕 HTML：
   • 从主屏幕响应中提取 htmlCode.downloadUrl。
   • 执行：

     powershell -Command "Invoke-WebRequest -Uri '<htmlCode.downloadUrl>' -OutFile 'docs/design/components/[page]/[component]/stitch/screen.html'"
     

4. 下载变体-1 JPG：
   • 从变体响应中提取 screenshot.downloadUrl。
   • 执行：

     powershell -Command "Invoke-WebRequest -Uri '<variant.screenshot.downloadUrl>' -OutFile 'docs/design/components/[page]/[component]/stitch/variant-1.jpg'"
     

5. 下载变体-1 HTML：
   • 从变体响应中提取 htmlCode.downloadUrl。
   • 执行：

     powershell -Command "Invoke-WebRequest -Uri '<variant.htmlCode.downloadUrl>' -OutFile 'docs/design/components/[page]/[component]/stitch/variant-1.html'"
     

6. 保存 Stitch 元数据（stitch-meta.json）：
   • 写入 docs/design/components/[page]/[component]/stitch/stitch-meta.json：

     {
       "projectId": "<stitchProjectId>",
       "screenId": "<screenId>",
       "screenName": "projects/<projectId>/screens/<screenId>",
       "deviceType": "DESKTOP",
       "generationPrompt": "<synthesizedPrompt>",
       "variantIds": ["<variantScreenId1>"]
     }
     

---

步骤 5：设计规范基准集成

使用 Stitch 结果更新 docs/design/components/[page name]/[component name]/design-spec.md：

1. 嵌入 Stitch 主屏幕和变体：

   ## Google Stitch 布局架构与基准
   
   ### 主屏幕设计
   ![主屏幕设计](stitch/screen.jpg)
   
   ### 变体 1 探索
   ![变体 1 设计](stitch/variant-1.jpg)
   

2. 记录布局架构观察：
   • 记录 Stitch 屏幕中展示的空间网格、视觉权重、空白节奏和排版层次。
   • 比较主屏幕与变体 1，突出每种构图各自的优势。

---

步骤 6：视觉资产提示词（如果适用）

[!NOTE] 如果检查 Stitch 布局后发现需要定制视觉资产（例如，环境背景、自定义图标或图表），请勿调用 generate_image。向用户输出结构化提示词：

### 推荐视觉资产：[资产名称]
- **目标文件路径：** `docs/design/components/[page]/[component]/[filename].png`
- **推荐宽高比：** `16:9` 或 `1:1`
- **生成提示词：**
  > "[详细描述视觉资产的提示词，与 Stitch 布局匹配]"

---

步骤 7：独立子代理验证循环（invoke_subagent）

[!IMPORTANT] 子代理审查协议： 在报告完成之前，始终通过一个独立的子代理验证下载的资产和规范更新。

1. 生成验证子代理

调用 invoke_subagent 并设置：

• TypeName："self"
• Role："Stitch Asset & Download Auditor"
• Model："inherit"
• Prompt：

你是一个独立的 Stitch 资产审计员。你的工作是验证 Google Stitch 资产已干净下载并集成到组件目录中。

目标组件目录：
docs/design/components/[page name]/[component name]/

要审计的交付物：
1. docs/design/components/[page name]/[component name]/stitch/screen.jpg (必须存在，非零字节)
2. docs/design/components/[page name]/[component name]/stitch/screen.html (必须存在，原始 HTML)
3. docs/design/components/[page name]/[component name]/stitch/variant-1.jpg (必须存在，非零字节)
4. docs/design/components/[page name]/[component name]/stitch/variant-1.html (必须存在，原始 HTML)
5. docs/design/components/[page name]/[component name]/stitch/stitch-meta.json (有效的 JSON，包含 projectId、screenId、generationPrompt、variantIds)
6. docs/design/components/[page name]/[component name]/design-spec.md (必须嵌入 stitch/screen.jpg 和 stitch/variant-1.jpg)

根据以下严格标准进行审计：
1. 二进制文件完整性：确认 screen.jpg 和 variant-1.jpg 不为空或损坏（大小 > 10KB）。
2. HTML 完整性：确认 screen.html 和 variant-1.html 是有效的 HTML 文件，且未被损坏为 Markdown。
3. 元数据完整性：确认 stitch-meta.json 具有有效字段。
4. 规范集成：确认 design-spec.md 包含嵌入的截图链接和 Stitch 布局基准注释。
5. 令牌节约：确认未直接调用 generate_image。

请按以下确切格式回复：
VERDICT: PASS | ISSUES_FOUND

ISSUES (如果存在):
- LOCATION: {文件:行号或部分}
- PROBLEM: {不符合或损坏的内容}
- FIX: {具体的修复指示}

SUMMARY: {简要的总体评估}

2. 评估审查并解决

如果发现 ISSUES_FOUND，立即解决它们（例如，重新下载失败的任何资产或修复元数据），然后再完成执行。

---

3. 执行验证检查清单

在完成执行之前，请验证：

• 已从 docs/design/components/[page]/[component]/ 导入 design-spec.md。
• 已从 docs/project.json 验证/重用 Stitch 项目 ID（或已创建并立即持久化）。
• 通过 upload_design_md 或 create_design_system_from_design_md 将设计令牌注入到 Stitch。
• 通过 generate_screen_from_text 生成了主屏幕。
• 通过 generate_variants 恰好生成了一个变体。
• 所有资产使用 PowerShell 的 Invoke-WebRequest -OutFile 下载（零次使用 read_url_content）。
• screen.jpg、screen.html、variant-1.jpg、variant-1.html 已保存到 stitch/ 目录中，且大小非零。
• 已保存 stitch/stitch-meta.json 并包含完整的元数据。
• design-spec.md 已更新，嵌入了屏幕截图和 Stitch 布局基准。
• 未直接调用 generate_image；若需要，已为用户输出图像提示词。
• 已通过 invoke_subagent 调用了独立的子代理审计，并已通过。