sketch-design-to-code

Sketch MCP 转代码

根据 Sketch 设计生成代码，复用项目现有内容、通过符号驱动组件，并进行视觉验证。

必需的 Sketch 指南

• 始终使用 get_guide，并设置 topic: "mcp" ——了解 MCP 前置条件、run_code 规则、故障处理和视觉验证。
• 使用 get_guide，并设置 topic: "use" ——了解 Sketch 检查、符号、覆盖、堆叠、样式、导出和内容验证。

任务需要时，再按需获取以下指南子主题：troubleshooting、layout、styling、symbols、assets 和 prototyping。

反向工作流：从代码/URL 生成 Sketch 设计，请参阅 sketch-design-from-reference

前置条件

• Sketch 正在运行并已启用 MCP（Settings → General → Allow AI tools to interact with open documents）。
• 目标文档已打开；提供用户选择的图层，或明确的画板 ID / 分享链接（https://sketch.com/s/<doc-uuid>/f/<frame-uuid>）。
• 可访问项目工作区 —— Agent 能够读取源代码、配置和包清单。
• 根据用户提供的信息或仓库线索（例如，package.json → Web，*.xcodeproj → iOS，android/ → Android）确定目标平台。如有歧义，请询问用户。

如果 MCP 失败：停止并使用 get_guide，设置 topic: "troubleshooting"；遵循其中关于 MCP 连接失败的指导。MCP 不可用时，不要凭记忆实现。

步骤

按顺序执行以下步骤。常规任务通常只需主流程；仅当某一步需要更多细节或示例时，才加载参考文件。

步骤 1 — 确认 Sketch 上下文

1. 使用 get_document_info 探查文档上下文。
2. 确定实现目标（按优先级排序）：

• Sketch 分享链接 —— 从 https://sketch.com/s/<doc-uuid>/f/<frame-uuid> 等 URL 中提取 /f/<canvas-frame-uuid>；按照 get_guide 中 topic: "use" 的分享链接指南查找该图层，并将其选中。优先使用此方式，而非当前选区或名称匹配。
• 用户在 Sketch 中选中的图层。
• 通过 get_document_info / get_layer_tree_summary 获取图层 ID 或名称；只有专用工具无法确定目标时，才使用有针对性的 run_code。如果有多个匹配项，请确认。

3. 除非用户明确说明目标画板是局部组件、区块或裁剪图，否则将其视为完整页面或屏幕。
4. 对目标画板使用 get_screenshot 捕获参考截图（targetDocumentID + layerID）。这是实现和验证时的主要视觉参考。

如果选区为空且无法解析分享链接，请停止并让用户选中目标画板。

步骤 2 — 检查代码库

创建文件前先检查项目。复用匹配的组件和设计令牌，遵循相邻文件的布局与状态模式，并将范围限制在所选画板内，除非用户要求扩展。

• 是否已有 UI 组件？检查 src/components、设计系统包和 Storybook。
• 是否有设计令牌 / 主题？检查 CSS 变量、Tailwind @theme、tokens.ts 和资源目录。
• 目标技术栈是什么？检查 package.json、Podfile、build.gradle 和框架导入。
• 如何运行项目？检查 README、npm run dev、yarn ios、Makefile 和 mise 配置。
• 新建内容应放在哪个文件夹？检查用户请求、功能模块和页面/路由。

第 3 步 — 提取设计结构和设计令牌

开始编写自定义探针前，先使用专用的只读 MCP 工具。

1. 调用 get_document_info，获取文档 ID、页面、页面图层数量，以及带有位置和尺寸信息的顶层 Frames/Graphics。
2. 对目标页面、Frame 或图层调用 get_layer_tree_summary，获取层级结构、ID、名称、尺寸、文本片段、符号实例覆盖数量和堆叠提示。
3. 仅在这些工具未提供所需详情时，使用有针对性的 run_code 查询精确样式值、固定位置/尺寸、蒙版、符号主项 ID、支持覆盖的图层、导出设置、图像源或自定义几何检查。脚本应简短精简：每次调用只检查一个探针或属性，并附上简短标题和 JSON 日志。

收集足够的数据，以说明所选 Frame 及相关后代图层的层级结构、布局、排版、样式、可复用样式、设计令牌、符号、资源和几何信息。编写代码前，为主要区域和导出候选项制作一份简短的资源分类清单：实际的 Bitmap/Image 图层、纯插画/路径图稿、图标/Logo/符号图稿、包含文本的 UI，以及应拆分为代码结构和导出内部图稿的混合 UI。对于导出候选项，记录存在时配置的 layer.exportFormats；这些配置体现了设计师对文件类型、尺寸比例或绝对尺寸变体、前缀/后缀命名及平台文件夹命名的意图。对于布局，判断设计使用的是堆叠、固定位置/调整尺寸，还是其他相对布局约束；这些约束定义了响应式意图。对于大型图层树，先浅层映射，再深入检查关键子树。

有关提取示例、资源分类探针和大型图层树处理策略，请阅读 references/extraction.md。

第 4 步 — 规划组件映射

编写代码前，先制作一份简短的符号/组件映射。同一个 Sketch 主项的重复实例通常应变为一个可复用组件，并使用数据驱动的属性。嵌套符号通常应组合成组件，而不是展平为代码。

Sketch master                  → Code component        → Overrides / props
<Family>/<Variant A>           → <Family><VariantA>    → <override props>
<Family>/<Variant B>           → <Family><VariantB>    → <override props>
<Family>/<Container>           → <Family><Container>   → <override props>
<Family>/<Atom>                → <Family><Atom>        → <override props>

当符号或覆盖项很重要时，对每个不同的实例调用 get_symbol_overrides（kind: all）。有关符号映射示例，请阅读 references/symbol-to-code.md。

第 5 步 — 导出资源

如果文档中包含图标、位图、Logo、纯图稿组及其他设计资源，请从确切的 Sketch 图层或符号源导出。不要为设计资源臆造占位图标包，也不要从整帧截图中裁剪生产资源；截图仅用于验证。选择备用导出选项前，检查每个导出候选项是否配置了 layer.exportFormats；如果存在，优先将这些格式传递给 sketch.export，以便导出的文件保留文档中的格式、尺寸和命名预设。将导出文件放入符合项目惯例的路径或临时目录，记录完整路径，并确认文件存在。

有关资源分类详情、精确导出规则、保真度检查和路径示例，请阅读 references/assets.md。

步骤 6 — 编写代码

将设计转换为符合项目惯例的实现，与 Sketch 截图和提取的上下文保持 1:1 的视觉一致性：

• 匹配间距、对齐、尺寸和层级。
• 匹配字体排印和颜色用法。
• 如果存在堆栈、固定/调整大小和相对布局元数据，请保留其中的响应式/基于约束的布局意图。
• 优先使用令牌化值；避免不必要的硬编码字面值。
• 编辑现有 UI 时，优先进行增量更新，而不是大范围重写。
• 遵循资源分类清单：实际位图图层可以保留为位图，纯美术图稿可以导出，带文字的 UI 应使用代码实现，混合分组应以代码实现布局/文字，仅导出内部美术图稿。

1. 令牌 — CSS/Tailwind @theme、Swift Color 扩展、Android colors.xml 或项目中的等效实现。
2. 符号组件 — 属性与覆盖项对应；默认值与主版本值一致。
3. 屏幕/页面 — 组合各个区块；间距来自堆栈 gap / frame 布局。如果设计使用堆栈或相对布局，请以响应式方式实现这些约束。如果没有使用，则匹配 frame 定义的视口中的页面布局，同时在不破坏参考效果的前提下保持容器、间距和媒体元素的灵活性。
4. 资源 — 引用来自精确 Sketch 源的导出路径；使用符合平台惯例的 img / Image / AsyncImage。

不要过度设计——不要为一次性图层添加额外抽象。

步骤 7 — 可运行的 Web 应用：设置、运行、对比

当目标是 Web 应用时：

1. 是否已有可运行配置？遵循 README / package.json 脚本 / mise。启动开发服务器（npm run dev 等）。
2. 尚无可运行配置？询问用户：“此项目中没有 Web 开发配置。是否应在新文件夹中搭建一个可运行的应用（例如 Vite + React + Tailwind）？”如果同意，则创建最小化脚手架，接入页面，并在 README 中说明如何运行。
3. 打开页面（开发 URL 或预览）。
4. 将浏览器截图与同一 frame 中的 Sketch get_screenshot 进行对比（参见 validation.md）。
5. 针对性修复后重新截取双方截图，反复迭代，直到视觉效果基本一致。

在最终回复中记录已验证的内容。

步骤 8 — 其他平台

当目标是移动端或原生平台（没有浏览器循环）时：

1. 遵循平台惯例和现有项目结构生成代码。
2. 如果用户能运行模拟器/仿真器，则提出构建和对比；否则在适用时使用 validation.md 进行结构验证。
3. 明确说明哪些内容尚未进行视觉验证，以及用户应在本地运行什么。

步骤 9 — 完成并验证

在宣称完成之前，使用最新的 Sketch 截图和实现运行验证检查（Web：在浏览器对比之后）。

• 确保所用技术栈的构建/类型检查通过。
• 总结：新增/修改的文件、符号 → 组件映射、运行方式（如果是 Web，还要提供 URL）。
• 记录有意做出的偏差（技术限制、无障碍改进）。
• 如果重复内容仍以内联方式实现，请说明仍可复用的符号。
• 不要假设 Sketch 数据仍然是最新的——当数值不确定时，使用 run_code 重新查询。

关于代码的截图检查和不匹配恢复，请阅读 references/validation.md。

规则

Sketch → 代码的方向专属规则。所有通用 Sketch MCP 规则都来自 get_guide 的 topic: "mcp" → Critical Rules、get_guide 的 topic: "use" → Mandatory Constraints，以及 Visual Verification & Completion — 除以下要点外，还必须遵守这些规则。

1. 先看项目 — 创建组件或文件夹前，先阅读现有代码。
2. 符号 → 组件 — 覆盖项 → 属性；绝不要复制粘贴三个相同的按钮实现。
3. 优先使用令牌，而非十六进制值 — 优先使用文档色板和共享样式；仅当 Sketch 中未关联时才硬编码。
4. 画板范围 — 除非用户说明它只是组件、区块或裁剪区域，否则应假设画板是完整页面或屏幕。
5. 响应式意图 — 有堆叠、固定或缩放设置以及相对布局时应遵循；否则先匹配画板视口，并在切实可行的情况下保持布局灵活。
6. 最小差异 — 实现用户要求的画板；不要顺手重构。
7. 脚手架须先询问 — 仅当不存在可运行的 Web 应用且用户同意时，才创建新的可运行 Web 应用（除非用户已要求创建独立实现文件夹）。
8. 实时数据 — 不确定时重新查询 Sketch；不要依赖本次会话早先提取的过时数据。
9. 资源分类 — 设计中的位图可以保留为位图；含文本的 UI、卡片、表单、导航和区块应以代码实现，除非源内容实际是位图图层。
10. 精确导出 — 从选定的 Sketch 图层／组／符号导出生产资源，绝不要裁剪验证截图。

易错点

以下易错点仅针对代码。桥接／脚本问题见 get_guide 的 topic: "mcp" → Common Mistakes；文档操作问题见 get_guide 的 topic: "use" → Common Content Mistakes。

• 扁平化符号会丢失覆盖模型。使用一个主符号 → 一个组件；参见 symbol-to-code.md。
• 将含文本的卡片或区块扁平化为图片，会使结果脆弱且缺乏可访问性；仅导出源位图图层或非语义性图稿。
• 将源位图内容重建为 HTML/CSS 也可能有误；如果 Sketch 将内容标记为 Image 图层，则应使用导出的位图，除非用户明确要求重建。
• 从截图裁剪资源会混入意外像素、缩放、蒙版和相邻内容。应选中并导出准确的 Sketch 图层。
• 在 run_code 中使用 fs 会失败，因为 fs is not a core package。应在 shell 中使用 mkdir -p，并且只在 Sketch 脚本中执行导出。
• 使用错误的区域模型会遗漏遍历子树之外的 UI。在第 3 步中，应浅层探查层级结构，并在编码前映射所有主要的同级组／父级组。
• 大型单体 run_code 脚本难以调试和恢复。每次探查或处理事项应使用一个小型扁平脚本；不要在一次调用中合并探查、修改、样式设置和导出配置。

故障排除

桥接／工具调用失败：调用 get_guide 并设置 topic: "troubleshooting"；重试前先分析 run_code 失败原因。Sketch 文档操作失败时，针对出错区域调用相关主题（layout、symbols 或 assets）。

选区为空／截图失败

• 请用户选中目标画板，或通过共享链接 /f/<uuid> 解析目标。
• 在 get_screenshot 中明确指定 layerID，重新解析目标。

实现与设计不符

• 重新获取 get_screenshot，深入检查不匹配的子树，并对照 references/validation.md。
• 确认代码反映了提取的层级结构：包含所有主要区域、父级正确、资源已导出，且令牌映射无误。

现有项目使用不同模式

• 优先遵循项目模式，而非技能示例（例如 styled-components 与 Tailwind）。
• 将符号映射到仓库使用的组件系统。

用户想要移动端，但仓库是 Web（或反之）

• 大规模实现前先暂停并确认平台。

参考资料

• get_guide，参数 topic: "mcp"——MCP 工作流、run_code、视觉验证和完成规则
• get_guide，参数 topic: "use"——Sketch 检查、堆叠、符号、样式、导出和内容验证
• 提取模式
• 符号 → 代码映射模式
• 资源导出模式
• 验证清单
• Sketch MCP 服务文档
• Sketch JavaScript API