stitch::manage-design-system

设计系统

为项目的设计语言创建一个“事实来源”，确保未来所有屏幕保持一致。

说明

请参阅系统提示词，了解如何处理此技能中提到的所有工具的 MCP 工具前缀 （例如，get_screen、 create_design_system_from_design_md、apply_design_system）。

📥 检索

要分析 Stitch 项目，必须使用 Stitch MCP 工具检索元数据和资源：

1. 查找项目：使用 list_projects 查找目标 projectId。
2. 查找屏幕：针对该 projectId 使用 list_screens 查找具有代表性的屏幕（例如，“首页”“主仪表盘”）。
3. 获取元数据：对目标屏幕调用 get_screen，获取 screenshot.downloadUrl 和 htmlCode.downloadUrl。
4. 下载资源：使用 read_url_content 获取 HTML 代码。

🧠 根据描述进行综合

如果需要从现有屏幕中提取设计系统，请使用 stitch-utilities 插件中的 design-md 技能。

如果没有现有屏幕（新项目），或用户直接提供了描述（例如，“深色主题、蓝色和紫色、圆角、Inter 字体”）：

1. 使用设计映射将用户的模糊描述转换为精确值（参见 stitch-utilities 中的 design-md 技能或 generate-design 技能）。
2. 选择具体的十六进制颜色代码、字体系列和圆角值。
3. 生成 DESIGN.md 文件（结构参见 stitch-utilities 中的 design-md 技能）。
4. 继续执行下方的“在 Stitch 中创建或更新设计系统”步骤。

📝 输出结构

DESIGN.md 文件应遵循 stitch-utilities 插件中 design-md 技能定义的结构。

🚀 在 Stitch 中创建或更新设计系统

生成 .stitch/DESIGN.md 后，请确保也在 Stitch 中创建或更新设计系统。

分两步创建设计系统：

警告

检查点 — 需要用户确认。 上传前，必须暂停并征求用户确认。请总结即将创建的设计系统 （显示名称、主要颜色、字体和圆角），并等待用户明确批准 后再继续。用户确认前，不得上传。

1. 上传 DESIGN.md：

   • 选项 A（推荐 — 上传脚本）：使用经过修改的 upload-to-stitch Python 脚本，该脚本原生支持 .md 文件。它会在进程中对 Markdown 文件进行 Base64 编码，并将其发送到 /v1/projects/{projectId}/screens:batchCreate 端点，从而避开输出令牌限制。

     python3 stitch-skills/plugins/stitch-design/skills/upload-to-stitch/scripts/upload_to_stitch.py \
       --project-id <PROJECT_ID> \
       --file-path /path/to/DESIGN.md \
       --api-key <API_KEY> \
       --generated-by <GENERATED_BY>
     

     将 <GENERATED_BY> 设为生成 DESIGN.md 的技能或工具的标识。通过其他技能调用时，使用调用方技能名称 （例如 stitch::code-to-design）；单独使用时，则使用 Agent／工具名称 （例如 Gemini、Claude Code）。如果省略此项，脚本默认使用 UserUploadedDesignMd。

     此操作会返回 sourceScreen ID 和 screenInstance ID。

   • 选项 B（直接使用 MCP 工具）：如果 DESIGN.md 较小（约 5KB 以下），可以直接调用 upload_design_md MCP 工具，并将经过 Base64 编码的设计 Markdown 内容作为 designMdBase64 传入。

2. 创建设计系统：上传后立即调用 create_design_system_from_design_md 工具，并传入 projectId 和 selectedScreenInstance（其中包含上传步骤返回的 id 和 sourceScreen）。

上传脚本和 create_design_system_from_design_md 均执行完毕后， Stitch 会在项目级别保存设计令牌 — 无需在生成提示词中重复提供这些令牌。

🎨 将设计系统应用到屏幕

使用 apply_design_system 将设计系统应用到现有屏幕。

重要

selectedScreenInstances 必须仅包含 id 和 sourceScreen —— 不要包含位置或尺寸字段（x、y、width、height），否则 请求会因“invalid argument”而失败。通过 get_project 获取屏幕实例 ID。

{
  "projectId": "...",
  "assetId": "...",
  "selectedScreenInstances": [
    {
      "id": "...",
      "sourceScreen": "projects/.../screens/..."
    }
  ]
}

如何获取所需的 ID：

1. 调用 get_project 获取 screenInstances — 每个实例都包含 id 和 sourceScreen。
2. 调用 list_design_systems 获取设计系统的 name（格式为： assets/{assetId}）— 使用 assets/ 之后的部分作为 assetId。
3. 筛除所有 type: "DESIGN_SYSTEM_INSTANCE" 的实例 — 仅传入 实际屏幕。

📋 更新项目元数据

写入 .stitch/DESIGN.md 后，还要创建或更新 .stitch/metadata.json， 以记录 projectId、title、所有已知屏幕和设计系统摘要。 格式请参阅 examples/metadata.json。

架构参考

完整的 designSystem 对象架构及所有可用选项，请参阅 reference/tool-schema.md。

💡 最佳实践

最佳实践请参阅 design-md 技能（位于 stitch-utilities 插件中），了解如何描述设计元素。