madsouris/sketch-design-from-reference

Sketch MCP 到设计

根据参考效果构建或优化 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" —— 在创建或重构画板、编组、堆叠、页面放置、尺寸调整、固定或容器类型之前执行。

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

前置条件

• Sketch 正在运行并已启用 MCP（设置 → 通用 → 允许 AI 工具与打开的文档交互）。
• 目标文档已打开，或者用户期望你创建/使用新文档。
• 参考素材可用：URL、截图或源代码。
• 范围足够明确：整页 vs 单个画板、目标宽度、深色/亮色模式，以及当文档有多个候选时对应的目标页面/画板。

如果 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 获取页面、顶层画板/图形、图层数量以及现有的布局候选。
2. 在候选画板或相关页面上调用 get_layer_tree_summary 获取层级结构、ID、名称、尺寸、文本片段、符号实例覆盖计数以及堆叠提示。
3. 调用 get_design_assets 和 get_libraries 获取可重用的符号/组件和库资源。
4. 仅在摘要未暴露所需细节时使用有针对性的 run_code。

只有在你确定现有画板与请求的设计匹配时才优先编辑它。否则，创建一个新画板。

步骤 3 — 在绘制像素之前规划结构

在开始绘制之前定义图层计划：

• 顶层区域及其顺序。
• 父/子关系以及兄弟编组。
• 区域宽度、内容最大宽度以及全出血 vs 列内部部分。
• 固定/固定的区域 vs 滚动内容。
• 符号候选、堆叠候选、资源候选以及可重用的堆叠模式。

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

对于每个结构化区域，在绘制前决定 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、list、form、nav 或 card 内容，则创建或保留 Sketch 堆叠，而不是手动定位每个子元素。
7. 资源就是资源。 不要将复杂的图形、照片、截图或品牌标志重新绘制为低保真矢量近似；而是导出/导入或分配图像/SVG 资源。
8. 不要猜测。 不要凭记忆或通用 UI 模式编造布局、文字、颜色、间距或资源。从参考中提取；如果某个值缺失，重新获取或询问用户。
9. 始终使用参考锚点。 将 Sketch 输出与捕获的参考截图进行比较——而不是你对页面的回忆。
10. 完成门控。 不要因为部分存在或页面“看起来相似”就停止。当 references/validation.md 的完成标准通过时才停止。

陷阱

• 为了修复一个小的不匹配而重新创建整个页面会浪费已经调整好的工作，并引入新的错误。根据截图差异进行精细编辑。
• 将图像直接放置在符号实例上可能会破坏层级或在 API 中失败。将图像图层放在主符号中，并通过实例级别的图像覆盖来驱动。
• 跳过截图会隐藏布局、顺序和颜色错误。每个批次都要截图。
• 使用 parent.layers = [...] 重新排序可能会删除子元素或导致对象 ID 重复。使用安全的重新排序模式。
• 如果索引和打包方向理解错误，堆叠顺序可能看起来是反的。使用 get_guide 并设置 topic: "layout"，并通过截图验证。
• 整个页面或区域的脚本难以验证、调试和恢复。按区域、堆叠设置和小的兄弟批次拆分。
• 使用手动画板构建的结构化布局在间距或顺序改变时会漂移。使用 Sketch 堆叠来处理行、列、列表、表单、导航、卡片和重复区域。
• 复杂图形用基本形状重新创建会产生低质量的近似。导出/导入 SVG/PNG 或使用图像覆盖；将形状保留给简单的 UI 基元。
• 仅首次渲染的页面截图可能会遗漏延迟加载的图像和滚动触发的 UI 状态。使用浏览器或代理工具，滚动以触发内容，然后捕获目标视口。
• 过早完成：代理添加带有通用样式的页眉/正文/页脚并停止。执行区域门控和完成标准；继续修复直到主要差异消失。
• 即兴的文字和颜色：改写后的标题、Lorem-style 填充文本或默认的灰色/蓝色，而不是提取的值。逐字使用保真度规范；从参考中重新采样颜色。
• 占位符永久化：灰色框作为“标志”或“英雄图像”保留。在移交之前导出/导入真实资源，除非用户要求占位符。

故障处理

对于桥接/工具调用失败、解析器错误、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 确认）