sketch-design-from-reference

Sketch 转设计

构建或完善 Sketch 设计，使其与参考内容匹配。本技能适用于在 Sketch 中进行设计；反向工作流为 sketch-design-to-code。

忠实还原优先

目标是与参考内容在视觉上保持一致，而不是制作一个仅有相似版块的合理页面。相似不等于完成。不要在内容出现后就停止；只有并排截图对比达到 references/validation.md 中的完成标准，才能停止。

必需的 Sketch 指南

• 使用 get_guide，参数为 topic: "mcp" — 始终必需；包含 MCP 前置条件、run_code 规则、故障处理和视觉验证。
• 使用 get_guide，参数为 topic: "use" — 涵盖 Sketch 编辑、堆叠、符号、样式、覆盖和原型设计。
• 使用 get_guide，参数为 topic: "layout" — 在创建或重构 Frame、Group、堆叠、页面位置、尺寸、固定方式或容器类型之前获取。

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

前置条件

• Sketch 正在运行且已启用 MCP（Settings → General → Allow AI tools to interact with open documents）。
• 已打开目标文档，或用户希望你创建／使用新文档。
• 有可用的参考内容，例如 URL、截图或源代码。
• 范围足够明确，可以开始操作：整页还是单个 Frame、目标宽度、深色／浅色模式，以及当文档中有多个候选项时的目标页面／Frame。

如果 MCP 不可用，请停止并使用 get_guide 获取 topic: "troubleshooting"。MCP 无法连接时，不要凭记忆猜测布局。

步骤

按顺序执行以下步骤。对于常规工作，主流程应该足够；只有步骤需要更多细节或示例时，才加载参考文件。

步骤 1 — 确认上下文和参考内容

1. 获取必需的指南。
2. 使用 get_document_info 确认目标文档。
3. 对参考内容进行分类：

• URL — 收集页面标题、视口宽度、DOM 结构、源 HTML、可用的关联或捆绑 JavaScript／CSS、计算后的颜色／字体、文案和资源 URL。
• 截图 — 收集尺寸、区域、文本内容、对齐方式和关键颜色。
• 代码 — 收集主题令牌、字体栈、间距比例、组件名称、内联 SVG 和资源导入信息。

4. 提取保真度规范，并在进行任何布局修改前，按目标宽度截取参考锚点截图。规范必须包含区域（从上到下）、原文文案、颜色、排版、布局宽度和资源来源 — 参见 references/reference-extraction.md。

针对特定类型的参考内容进行提取时，请阅读 references/reference-extraction.md。对于对比和完成标准，请在步骤 5 之前阅读 references/validation.md。

步骤 2 — 发现可复用的 Sketch 内容

修改前先检查。从只读 MCP 工具开始：

1. 调用 get_document_info，获取页面、顶层 Frame／图形、图层数量和现有布局候选项。
2. 对候选 Frame 或相关页面调用 get_layer_tree_summary，查看层级、ID、名称、尺寸、文本片段、符号实例覆盖数量和堆叠提示。
3. 调用 get_design_assets 和 get_libraries，查找可复用的符号／组件和资源库资源。
4. 只有在摘要未提供所需详情时，才使用有针对性的 run_code。

只有在确定现有 Frame 与所需设计对应时，才优先编辑该 Frame。否则，请新建 Frame。

步骤 3 — 绘制前规划结构

绘制前先定义图层规划：

• 顶层区域及其顺序。
• 父子关系和同级分组。
• 区域宽度、内容最大宽度，以及整宽区域与栏内区域。
• 固定/置顶区域与可滚动内容。
• 候选符号、堆叠候选项、素材候选项和可复用的堆叠模式。

不要强加默认页面模板。应匹配参考图的信息架构。

对于每个结构化区域，在绘制前确定 Sketch 堆叠模型：方向、间距、内边距、对齐方式、尺寸、换行方式和预期视觉顺序。除非有明确理由必须使用自由布局，否则行、列、导航栏、工具栏、卡片、列表、表单、按钮组和重复内容都应使用堆叠。页面级定位、固定界面元素、叠加层、蒙版或真正的自由布局图稿则使用手动坐标。

步骤 4 — 建立样式标记和基础画板

创建或匹配文档色板/共享样式，覆盖背景、边框、文本、品牌色、弱化文本和重要表面。明确设置页面/画板背景，并清除结构组中意外的填充。有关符号细节，请调用 get_guide，并设置 topic: "symbols"。

使用参考图中的值：计算所得的 CSS、从截图采样的颜色或代码样式标记。有关样式细节，请调用 get_guide，并设置 topic: "styling"。

步骤 5 — 逐步构建布局

使用小型、可撤销的 run_code 编辑。每个脚本只执行一个小操作。

绝不要在一个脚本中构建整个页面、顶层区域或多分区布局。不要在同一次运行中结合探查、创建、设置样式和重新排序。保持脚本扁平：初始化、按 ID 查找目标、执行一次修改、记录 JSON。避免深层辅助函数、嵌套 IIFE 和冗长的控制流。

从外到内构建：

1. 页面画板和背景。
2. 根据图层规划创建顶层区域容器。
3. 在添加详细子项前，为每个区域设置堆叠属性。
4. 在每个区域内分小批次添加文本、形状和符号实例。
5. 确认父级结构无误后，再添加固定/置顶区域。

一次只构建一个顶层区域。完成每个区域的内容批次后：

1. 使用参考图的锚点宽度对画板执行 get_screenshot。
2. 将该区域与参考图锚点对比，并使用 references/validation.md 中的分类列出差异。
3. 开始下一个区域前，先修正主要不匹配之处。

结构编辑后，使用 get_layer_tree_summary 重新查询，或对画板截图。有关安全的重新排序/重新设父级模式，请阅读 references/editing-patterns.md。

步骤 6 — 符号、素材和覆盖项

绘制重复的单次图层组前，先使用现有文档/库符号。重复的 UI 通常应创建为一个符号主件，并使用实例和覆盖项。

绘制细节形状前，先对每个非文本视觉元素进行分类。将照片、截图、插画、复杂 SVG、产品图像、品牌标记、精细图标、渐变和噪点导出/导入为 SVG/PNG/图像素材。在 Sketch 中仅重建简单 UI 基本元素、简单可编辑矢量、分隔线、胶囊形元素和基本形状。

对于图标/徽标/图像，先用简单占位符建立布局，再在几何形状和堆叠顺序稳定后导入/指定真实图像素材。重复素材优先使用专用图层上的符号图像覆盖项。

有关符号覆盖模式，请阅读 references/symbols.md。有关导入/导出详情，请调用 get_guide，并设置 topic: "assets"。

步骤 7 — 仅进行有针对性的修复

当用户报告问题，或截图对比显示存在不匹配时：

1. 修改前，使用 get_layer_tree_summary 或针对性探查检查当前图层。
2. 只更改报告的问题属性：单个画板值、文本样式、颜色、图层顺序、堆栈属性或覆盖项。
3. 重新截图，并确认子级数量未发生变化，除非有意删除。

如果布局出错或图层丢失，请立即说明，并告知用户先撤消/还原，再继续操作。

步骤 8 — 最终验证与交接

在通过完成标准前，不要声称已完成——请参阅 references/validation.md → 完成标准。

1. 在参考锚点宽度下，使用 get_screenshot 捕获完整画板截图。
2. 根据参考锚点截图，对保真度规范中的每个区域运行区域检查。
3. 如果仍存在任何重大偏差，返回步骤 7 并继续迭代。不要以“差不多”的布局交付。
4. 总结使用的符号、创建的令牌/样式、目标画板/框架的名称和 ID、已验证的区域，以及任何剩余的细微偏差。
5. 在任务完成前，不要运行 zoomToFitCanvas。

规则

Sketch → 设计的特定规则。通用 MCP/脚本规则来自 get_guide，参数为 topic: "mcp"；Sketch 内容规则来自 get_guide，参数为 topic: "use"。

1. 修补，不要重建。如果内容已存在，应修复画板、样式、覆盖项或顺序，而不是删除并重新创建主要区域。
2. 在重新排序、重新设置父级、添加或移除操作前后，记录子级数量。
3. 切勿赋值 parent.layers = [...]；使用 layer.index 重新排序，使用 child.parent = newParent 重新设置父级。
4. 匹配参考中的区域结构；除非有意采用不同结构，否则相同的视觉内容应具有相同的父子/同级关系。
5. 每完成一批有意义的修改后都要截图，并根据截图差异决定下一步编辑。
6. 结构化布局默认使用堆栈。如果参考中的同级元素表现为 flex、grid、列表、表单、导航或卡片内容，应创建或保留 Sketch 堆栈，而不是手动定位每个子元素。
7. 素材就是素材。不要将复杂的插画、照片、截图或品牌标识重绘为低保真矢量近似图；应导出/导入或指定图像/SVG 素材。
8. 不要猜测。不要凭记忆或通用 UI 模式臆造布局、文案、颜色、间距或素材。应从参考中提取；如果缺少某个值，请重新获取或询问用户。
9. 始终以参考锚点为准。将 Sketch 输出与捕获的参考截图进行比较，而不是凭记忆中的页面进行比较。
10. 完成检查。不要因为各个区域已存在或页面“看起来相似”就停止。只有通过 references/validation.md 中的完成标准后才能停止。

常见陷阱

• 为修复细微差异而重新创建页面，会浪费已调校的工作并引入新问题。请根据截图差异进行精准修改。
• 直接在符号实例上放置图像，可能会破坏层级结构或导致 API 调用失败。请将图像图层放在主组件中，并通过每个实例的图像覆盖来控制。
• 不截图会掩盖布局、顺序和颜色错误。每批操作后都要截图。
• 使用 parent.layers = [...] 重新排序，可能会删除子图层或重复对象 ID。请改用安全的重新排序模式。
• 如果误解了索引和排列方向，堆叠顺序可能看起来是反的。请使用 get_guide 并设置 topic: "layout"，然后通过截图进行确认。
• 整页或整块区域的脚本难以验证、调试和恢复。请按区域、堆叠设置和少量同级图层批次拆分操作。
• 使用手动创建的画框构建结构化布局，一旦间距或顺序发生变化就容易偏移。请在行、列、列表、表单、导航、卡片和重复区域中使用 Sketch 堆叠。
• 使用基本形状重建复杂图稿，会导致近似效果质量低下。请导出/导入 SVG/PNG，或使用图像覆盖；基本形状仅用于简单 UI 元素。
• 仅在首次绘制后截图，可能会漏掉延迟加载的图像和滚动触发的 UI 状态。请使用浏览器或 Agent 工具，通过滚动触发内容，然后截取目标视口。
• 过早完成：Agent 添加通用样式的页眉/正文/页脚后就停止。请运行区域检查和完成标准，并持续修复，直到主要差异消失。
• 文案和颜色凭空编造：改写标题、使用 lorem 风格占位文案，或使用默认灰色/蓝色，而不是提取参考值。请严格使用保真度规范中的内容，并从参考图中重新采样颜色。
• 占位内容永久保留：将灰色方框留作“徽标”或“主视觉图”。交付前请导出/导入真实资源，除非用户要求使用占位内容。

故障排查

如果桥接/工具调用失败、解析器报错、MCP 连接出现问题或截图失败，请先调用 get_guide 并设置 topic: "troubleshooting"，再重试。

如果文档操作失败：

• 布局/堆叠/顺序问题 → 使用 get_guide 并设置 topic: "layout"。
• 符号覆盖问题 → 使用 get_guide 并设置 topic: "symbols"。
• 导出/导入/图像问题 → 使用 get_guide 并设置 topic: "assets"。

设计构建问题表现

• 脚本执行后子图层数量减少：请告知用户撤销，然后检查操作。不要重复执行批量图层赋值。
• get_screenshot 为空或内容不正确：请重新解析画框/图层 ID，然后在需要时截取页面或父画框。
• 符号覆盖未生效：请重新获取 get_symbol_overrides，根据 commonOverrideIDPrefix + '_' + property 重建覆盖 ID，然后截图。
• 行堆叠中的文本重叠：请检查子图层顺序和间距；每次只修改一个堆叠属性或子图层索引。

参考资料

• get_guide 并设置 topic: "mcp" — MCP 工具、run_code、故障排查、视觉验证和完成规则
• get_guide 并设置 topic: "use" — Sketch 编辑、堆叠、符号、样式、覆盖、资源和内容验证
• get_guide 并设置 topic: "layout" — 堆叠、页面放置、尺寸、固定位置、容器类型、重新排序/重新设定父级关系和布局偏移
• 参考内容提取
• 安全编辑模式
• 符号覆盖模式
• 验证循环
• Sketch JavaScript API
• StackLayout
• 符号覆盖（通过 MCP 中的 get_symbol_overrides 确认）