sketch-design-to-code
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseSketch MCP to Code
Sketch MCP 转代码
Generate code from Sketch designs with project-aware reuse, symbol-driven components, and visual verification.
从Sketch设计生成代码,支持感知项目的组件复用、符号驱动的组件开发及视觉验证。
Required Sketch guides
必要的Sketch指南
- with
get_guide— always; MCP prerequisites,topic: "mcp"rules, failure handling, and visual verification.run_code - with
get_guide— Sketch inspection, symbols, overrides, stacks, styles, exports, and content verification.topic: "use"
Fetch guide subtopics on demand when the task needs them: , , , , , and .
troubleshootinglayoutstylingsymbolsassetsprototypingInverse workflow: Sketch from code/URL is sketch-design-from-reference
- (
get_guide)——必须调用;包含MCP前置条件、topic: "mcp"规则、错误处理及视觉验证相关内容。run_code - (
get_guide)——包含Sketch检查、符号、覆盖项、堆叠、样式、导出及内容验证相关内容。topic: "use"
按需获取指南子主题,当任务需要时调用:、、、、和。
troubleshootinglayoutstylingsymbolsassetsprototyping反向工作流:从代码/URL生成Sketch设计的功能为sketch-design-from-reference
Prerequisites
前置条件
- Sketch running with MCP enabled (Settings → General → Allow AI tools to interact with open documents).
- Target document open; user selection or explicit frame ID / share link ().
https://sketch.com/s/<doc-uuid>/f/<frame-uuid> - Project workspace accessible — agent can read source, configs, and package manifests.
- Know the target platform from user or repo signals (e.g. → web,
package.json→ iOS,*.xcodeproj→ Android). Ask if ambiguous.android/
If MCP fails: stop and call with ; follow its MCP connection failure guidance. Do not implement from memory while MCP is unreachable.
get_guidetopic: "troubleshooting"- 运行Sketch并启用MCP(设置→通用→允许AI工具与打开的文档交互)。
- 目标文档已打开;用户已选择目标内容,或提供了明确的框架ID/共享链接()。
https://sketch.com/s/<doc-uuid>/f/<frame-uuid> - 可访问项目工作区——Agent能够读取源码、配置文件及包清单。
- 从用户或仓库信号中明确目标平台(例如对应Web,
package.json对应iOS,*.xcodeproj对应Android)。若存在歧义,请询问用户。android/
如果MCP调用失败:停止操作并调用();遵循其中的MCP连接故障处理指南。当MCP无法访问时,请勿凭记忆实现代码。
get_guidetopic: "troubleshooting"Steps
步骤
Follow these steps in order. The main flow should be enough for ordinary work; load a reference file only when the step needs more detail or examples.
按以下顺序执行步骤。主流程足以应对常规工作;仅当步骤需要更多细节或示例时,才加载参考文件。
Step 1 — Confirm Sketch context
步骤1 — 确认Sketch上下文
- Probe document context with .
get_document_info - Resolve implementation target (priority order):
- Sketch share link — extract from URLs like
/f/<canvas-frame-uuid>; find that layer using the share-link guidance inhttps://sketch.com/s/<doc-uuid>/f/<frame-uuid>withget_guide, and select it. Prefer this over current selection or name matching.topic: "use" - User-selected layer in Sketch.
- Layer IDs or names via /
get_document_info; use targetedget_layer_tree_summaryonly if the dedicated tools cannot resolve the target. Confirm if multiple matches.run_code
- Treat a target frame as a full page or screen unless the user explicitly says it is a partial component, section, or crop.
- Capture reference screenshot: on the target frame (
get_screenshot+targetDocumentID). This is the primary visual reference for implementation and validation.layerID
If selection is empty and no share link resolved, stop and ask the user to select the target frame.
- 调用探查文档上下文。
get_document_info - 确定实现目标(优先级顺序):
- Sketch共享链接——从这类URL中提取
https://sketch.com/s/<doc-uuid>/f/<frame-uuid>;调用/f/<canvas-frame-uuid>(get_guide)中的共享链接指南找到对应图层并选中。优先使用此方式,而非当前选中内容或名称匹配。topic: "use" - 用户在Sketch中选中的图层。
- 通过/
get_document_info获取的图层ID或名称;仅当专用工具无法解析目标时,才使用定向get_layer_tree_summary。若存在多个匹配项,请确认。run_code
- 除非用户明确说明目标框架是局部组件、区块或裁剪区域,否则将其视为完整页面或屏幕。
- 捕获参考截图:对目标框架(+
targetDocumentID)调用layerID。这是实现与验证的主要视觉参考。get_screenshot
如果选中内容为空且未解析到共享链接,请停止操作并要求用户选择目标框架。
Step 2 — Inspect the codebase
步骤2 — 检查代码库
Inspect the project before creating files. Reuse matching components and tokens, match neighboring file layout and state patterns, and keep scope to the selected frame unless the user asked for more.
- Existing UI components? Check , design system packages, and Storybook.
src/components - Design tokens / theme? Check CSS variables, Tailwind ,
@theme, and asset catalogs.tokens.ts - Target stack? Check ,
package.json,Podfile, and framework imports.build.gradle - How to run? Check README, ,
npm run dev, Makefile, and mise config.yarn ios - Folder for new work? Check the user request, feature modules, and pages/routes.
在创建文件前先检查项目。复用匹配的组件与令牌,匹配相邻文件的布局和状态模式,且仅聚焦于选中的框架,除非用户要求更多内容。
- 是否存在现有UI组件?检查、设计系统包及Storybook。
src/components - 设计令牌/主题?检查CSS变量、Tailwind 、
@theme及资源目录。tokens.ts - 目标技术栈?检查、
package.json、Podfile及框架导入。build.gradle - 如何运行?检查README、、
npm run dev、Makefile及mise配置。yarn ios - 新工作的存放目录?检查用户需求、功能模块及页面/路由。
Step 3 — Extract design structure and tokens
步骤3 — 提取设计结构与令牌
Start with dedicated read-only MCP tools before writing custom probes.
- Call for the document ID, pages, page layer counts, and top-level Frames/Graphics with positions and dimensions.
get_document_info - Call on the target page, frame, or layer for hierarchy, IDs, names, dimensions, text snippets, symbol-instance override counts, and stack hints.
get_layer_tree_summary - Use targeted only for details those tools do not expose: exact style values, pins/sizing, masks, symbol master IDs, override-capable layers, export settings, image sources, or custom geometry checks. Keep scripts small and flat: one probe or property concern per call, with a short title and JSON log.
run_code
Collect enough data to explain hierarchy, layout, typography, styling, reusable styles, tokens, symbols, assets, and geometry for the selected frame and relevant descendants. Before coding, produce a short asset classification ledger for major regions and export candidates: actual Bitmap/Image layers, pure illustration/path artwork, icon/logo/symbol artwork, text-bearing UI, and mixed UI that should be split into coded structure plus exported inner artwork. For export candidates, record configured when present; they capture designer intent for file type, scale or absolute-size variants, prefix/suffix naming, and platform folder naming. For layout, identify whether the design uses stacks, pins/resizing, or other relative layout constraints; those define responsive intent. For large trees, shallow-map first, then deep-dive only critical subtrees.
layer.exportFormatsFor extraction examples, asset classification probes, and large-tree strategy, read references/extraction.md.
在编写自定义探查脚本前,先使用专用的只读MCP工具。
- 调用获取文档ID、页面、页面图层数量,以及顶级框架/图形的位置和尺寸。
get_document_info - 对目标页面、框架或图层调用,获取层级结构、ID、名称、尺寸、文本片段、符号实例覆盖项数量及堆叠提示。
get_layer_tree_summary - 仅当上述工具无法暴露细节时,才使用定向:精确的样式值、固定/自适应设置、遮罩、符号原型ID、可覆盖图层、导出设置、图片源或自定义几何检查。保持脚本小巧简洁:每次调用仅处理一个探查或属性问题,并附带简短标题和JSON日志。
run_code
收集足够数据,以说明选中框架及相关子元素的层级结构、布局、排版、样式、可复用样式、令牌、符号、资源及几何信息。编码前,为主要区域和导出候选对象生成简短的资源分类清单:实际位图/图片图层、纯插画/路径图形、图标/Logo/符号图形、含文本的UI,以及应拆分为编码结构加导出内部图形的混合UI。对于导出候选对象,记录已配置的(若存在);这些配置记录了设计师对文件类型、缩放或绝对尺寸变体、前缀/后缀命名及平台目录命名的意图。对于布局,确定设计是否使用堆叠、固定/自适应或其他相对布局约束;这些定义了响应式意图。对于大型图层树,先进行浅层映射,再仅对关键子树进行深入探查。
layer.exportFormats如需提取示例、资源分类探查脚本及大型图层树处理策略,请阅读references/extraction.md。
Step 4 — Plan the component map
步骤4 — 规划组件映射
Produce a brief symbol/component map before coding. Repeated instances of the same Sketch master should normally become one reusable component with data-driven props. Nested symbols should normally become composed components, not flattened code.
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>Call per distinct instance () when symbols or overrides matter. For symbol mapping examples, read references/symbol-to-code.md.
get_symbol_overrideskind: all编码前生成简要的符号/组件映射表。同一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>当符号或覆盖项重要时,对每个不同实例调用()。如需符号映射示例,请阅读references/symbol-to-code.md。
get_symbol_overrideskind: allStep 5 — Export assets
步骤5 — 导出资源
Export icons, bitmaps, logos, pure artwork groups, and other designed assets from exact Sketch layers or symbol sources when the document contains them. Do not invent placeholder icon packs for designed assets, and do not crop production assets from full-frame screenshots; screenshots are for verification. Before choosing fallback export options, inspect each export candidate for configured ; when they exist, prefer passing those formats to so exported files preserve the document's format, size, and naming presets. Put exports in project-conventional paths or a temp directory, log full paths, and verify files exist.
layer.exportFormatssketch.exportFor asset classification details, exact export rules, fidelity checks, and path examples, read references/assets.md.
当文档包含图标、位图、Logo、纯图形组及其他设计资源时,从精确的Sketch图层或符号源导出。请勿为设计资源生成占位图标包,也请勿从全框架截图中裁剪生产资源;截图仅用于验证。选择备用导出选项前,检查每个导出候选对象的已配置;若存在配置,优先将这些格式传递给,以便导出的文件保留文档的格式、尺寸和命名预设。将导出文件放入项目约定路径或临时目录,记录完整路径,并验证文件是否存在。
layer.exportFormatssketch.export如需资源分类详情、精确导出规则、保真度检查及路径示例,请阅读references/assets.md。
Step 6 — Implement code
步骤6 — 实现代码
Translate design → project conventions with 1:1 visual parity vs the Sketch screenshot and extracted context:
- Match spacing, alignment, sizing, and hierarchy.
- Match typography and color usage.
- Preserve responsive/constraint-based layout intent from stacks, pins/resizing, and relative layout metadata when present.
- Prefer tokenized values; avoid unnecessary hardcoded literals.
- Prefer incremental updates over broad rewrites when editing existing UI.
- Follow the asset classification ledger: actual bitmap layers may stay bitmap, pure artwork can be exported, text-bearing UI should be code, and mixed groups should keep layout/text in code while exporting only inner artwork.
- Tokens — CSS/Tailwind , Swift
@themeextensions, AndroidColor, or the project equivalent.colors.xml - Symbol components — props mirror overrides; defaults match master values.
- Screen/page — composes sections; spacing from stack / frame layout. If the design uses stacks or relative layout, implement those constraints responsively. If it does not, match the page layout at the viewport defined by the frame while keeping containers, spacing, and media flexible where doing so does not break the reference.
gap - Assets — reference exported paths from exact Sketch sources; use platform-idiomatic /
img/Image.AsyncImage
Do not over-engineer — no extra abstractions for one-off layers.
将设计转换为符合项目规范的代码,确保与Sketch截图及提取的上下文具备1:1视觉一致性:
- 匹配间距、对齐方式、尺寸及层级结构。
- 匹配排版和颜色使用。
- 保留堆叠、固定/自适应及相对布局元数据中的响应式/约束布局意图(若存在)。
- 优先使用令牌化值;避免不必要的硬编码字面量。
- 编辑现有UI时,优先选择增量更新而非大范围重写。
- 遵循资源分类清单:实际位图图层可保留为位图,纯图形可导出,含文本的UI应实现为代码,混合组应在代码中保留布局/文本,仅导出内部图形。
- 令牌——CSS/Tailwind 、Swift
@theme扩展、AndroidColor或项目等效方案。colors.xml - 符号组件——属性与覆盖项对应;默认值与原型值匹配。
- 屏幕/页面——组合各区块;间距来自堆叠/框架布局。若设计使用堆叠或相对布局,请响应式地实现这些约束。若未使用,则先匹配框架定义的视口页面布局,同时在不破坏参考效果的前提下保持容器、间距和媒体的灵活性。
gap - 资源——引用来自精确Sketch源的导出路径;使用平台惯用的/
img/Image。AsyncImage
请勿过度设计——一次性图层无需额外抽象。
Step 7 — Runnable web apps: setup, run, compare
步骤7 — 可运行Web应用:设置、运行、对比
When the target is a web app:
- Existing runnable? Follow README / scripts / mise. Start dev server (
package.json, etc.).npm run dev - No runnable yet? Ask the user: "There's no web dev setup in this project. Should I scaffold a runnable app (e.g. Vite + React + Tailwind) in a new folder?" If yes, create minimal scaffold, wire the page, document how to run in README.
- Open the page (dev URL or preview).
- Compare browser screenshot vs Sketch on the same frame (see validation.md).
get_screenshot - Iterate targeted fixes → re-screenshot both sides until parity is reasonable.
Log what you verified in the final reply.
当目标为Web应用时:
- 已有可运行环境?遵循README/脚本/mise配置。启动开发服务器(如
package.json)。npm run dev - 尚无运行环境?询问用户:“此项目中无Web开发环境设置。是否需要我在新文件夹中搭建可运行应用(例如Vite + React + Tailwind)?”若同意,创建最小化脚手架,连接页面,并在README中记录运行方法。
- 打开页面(开发URL或预览)。
- 对比浏览器截图与同一框架的Sketch (参见validation.md)。
get_screenshot - 进行针对性修复迭代→重新截取双方截图,直至达到合理的一致性。
在最终回复中记录已验证的内容。
Step 8 — Other platforms
步骤8 — 其他平台
When the target is mobile or native (no browser loop):
- Generate code following platform conventions and existing project structure.
- If the user can run a simulator/emulator, offer to build and compare; otherwise validate structurally using validation.md where applicable.
- State clearly what was not visually verified and what the user should run locally.
当目标为移动端或原生平台(无浏览器循环)时:
- 遵循平台规范及现有项目结构生成代码。
- 若用户可运行模拟器/仿真器,提供构建与对比服务;否则尽可能使用validation.md进行结构验证。
- 明确说明未进行视觉验证的内容,以及用户应在本地运行的操作。
Step 9 — Finalize and validate
步骤9 — 收尾与验证
Before claiming done, run the validation checks against the latest Sketch screenshot and implementation (web: after browser comparison).
- Ensure build/typecheck passes for the stack used.
- Summarize: files added/changed, symbol → component map, how to run (with URL if web).
- Document intentional deviations (technical limits, accessibility improvements).
- Mention remaining symbol reuse opportunities if repetition was left inline.
- Do not assume stale Sketch data — re-query with when values are uncertain.
run_code
For code-specific screenshot checks and mismatch recovery, read references/validation.md.
在完成前,针对最新的Sketch截图和实现进行验证检查(Web端:浏览器对比后)。
- 确保所使用技术栈的构建/类型检查通过。
- 总结:新增/修改的文件、符号→组件映射表、运行方法(Web端需附带URL)。
- 记录有意的偏差(技术限制、无障碍改进)。
- 若存在重复代码未提取为组件,提及剩余的符号复用机会。
- 请勿使用过时的Sketch数据——当值不确定时,重新调用查询。
run_code
如需代码特定的截图检查及不匹配问题修复方法,请阅读references/validation.md。
Rules
规则
Direction-specific rules for Sketch → code. All generic Sketch MCP rules come from with → Critical Rules, from with → Mandatory Constraints, and Visual Verification & Completion — follow them in addition to the points below.
get_guidetopic: "mcp"get_guidetopic: "use"- Project first — read existing code before creating components or folders.
- Symbols → components — overrides → props; never copy-paste three identical button implementations.
- Tokens over hex — prefer document swatches and shared styles; hardcode only when unlinked in Sketch.
- Frame scope — assume a frame is a full page or screen unless the user says it is only a component, section, or crop.
- Responsive intent — follow stacks, pins/resizing, and relative layout when present; otherwise match the frame viewport first and keep layout flexible where practical.
- Minimal diff — implement the requested frame; no drive-by refactors.
- Ask before scaffolding — new runnable web app only when none exists and user agrees (unless they already asked for a standalone implementation folder).
- Live data — re-query Sketch when unsure; do not rely on outdated extraction from earlier in the session.
- Asset classification — bitmap-in-design may stay bitmap; text-bearing UI, cards, forms, navigation, and sections should be implemented as code unless the source is an actual bitmap layer.
- Exact exports — export production assets from selected Sketch layers/groups/symbols, never by cropping a verification screenshot.
Sketch→代码的定向规则。所有通用Sketch MCP规则来自()→关键规则,以及()→强制约束和视觉验证与完成规则——除以下要点外,还需遵循这些规则。
get_guidetopic: "mcp"get_guidetopic: "use"- 项目优先——创建组件或文件夹前先阅读现有代码。
- 符号→组件——覆盖项→属性;切勿复制粘贴三个相同的按钮实现。
- 令牌优先于十六进制值——优先使用文档色板和共享样式;仅当Sketch中未链接时才硬编码。
- 框架范围——除非用户说明仅为组件、区块或裁剪区域,否则默认框架为完整页面或屏幕。
- 响应式意图——若存在堆叠、固定/自适应及相对布局,则遵循这些设置;否则先匹配框架视口,再在可行的前提下保持布局灵活性。
- 最小化差异——仅实现请求的框架;请勿顺带重构其他代码。
- 搭建前询问——仅当无现有可运行Web应用且用户同意时,才新建可运行Web应用(除非用户已明确要求独立实现文件夹)。
- 实时数据——不确定时重新查询Sketch;请勿依赖会话早期的过时提取数据。
- 资源分类——设计中的位图可保留为位图;含文本的UI、卡片、表单、导航及区块应实现为代码,除非源为实际位图图层。
- 精确导出——从选中的Sketch图层/组/符号导出生产资源,切勿从验证截图中裁剪。
Pitfalls
常见陷阱
Code-only pitfalls below. Bridge/script issues are in with → Common Mistakes; document-operation issues are in with → Common Content Mistakes.
get_guidetopic: "mcp"get_guidetopic: "use"- Flattening symbols loses the override model. Use one master → one component; see symbol-to-code.md.
- Flattening text-bearing cards or sections into images makes the result fragile and inaccessible; export only source bitmap layers or non-semantic artwork.
- Rebuilding source bitmap content as HTML/CSS can also be wrong; if Sketch says the content is an Image layer, use the exported bitmap unless the user explicitly asks for reconstruction.
- Cropping assets from screenshots bakes in accidental pixels, scale, masks, and neighboring content. Select and export the exact Sketch layer instead.
- Using in
fsfails becauserun_code. Usefs is not a core packagein shell and export in Sketch script only.mkdir -p - Using the wrong region model misses UI outside the walked subtree. In Step 3, shallow-probe the hierarchy and map every major sibling/parent group before coding.
- Monolithic scripts are hard to debug and recover from. Use one small flat script per probe or concern; do not combine probe, mutation, styling, and export setup in one call.
run_code
以下为纯代码相关陷阱。桥接/脚本问题请查看()→常见错误;文档操作问题请查看()→常见内容错误。
get_guidetopic: "mcp"get_guidetopic: "use"- 扁平化符号会丢失覆盖项模型。遵循一个原型→一个组件的原则;参见symbol-to-code.md。
- 将含文本的卡片或区块扁平化为图片会导致结果脆弱且无法访问;仅导出源位图图层或非语义图形。
- 将源位图内容重建为HTML/CSS也可能出错;若Sketch显示内容为图片图层,请使用导出的位图,除非用户明确要求重建。
- 从截图中裁剪资源会混入意外像素、缩放、遮罩及相邻内容。请选择并导出精确的Sketch图层。
- 在中使用
run_code会失败,因为fs不是核心包。请在shell中使用fs,仅在Sketch脚本中进行导出操作。mkdir -p - 使用错误的区域模型会遗漏遍历子树之外的UI。在步骤3中,先浅层探查层级结构,在编码前映射所有主要同级/父级组。
- 庞大的脚本难以调试和恢复。每次调用使用一个小巧简洁的脚本处理单个探查或问题;请勿将探查、修改、样式设置及导出配置合并到一次调用中。
run_code
Troubleshooting
故障排除
Bridge/tool-call failures: call with and analyze failures before retrying. For Sketch document-operation failures, call the relevant topic (, , or ) for the failed area.
get_guidetopic: "troubleshooting"run_codelayoutsymbolsassets桥接/工具调用失败:调用(),分析失败原因后再重试。对于Sketch文档操作失败,请针对失败领域调用相关主题(、或)。
get_guidetopic: "troubleshooting"run_codelayoutsymbolsassetsEmpty selection / screenshot fails
选中内容为空/截图失败
- Ask user to select target frame, or resolve from share link .
/f/<uuid> - Re-run target resolution with explicit on
layerID.get_screenshot
- 要求用户选择目标框架,或从共享链接解析目标。
/f/<uuid> - 使用明确的重新调用
layerID解析目标。get_screenshot
Implementation doesn't match design
实现效果与设计不匹配
- Re-fetch , deep-dive the mismatching subtree, and compare against references/validation.md.
get_screenshot - Confirm code reflects the extracted hierarchy: all major regions, correct parents, exported assets, and mapped tokens.
- 重新获取,深入探查不匹配的子树,并对照references/validation.md进行比较。
get_screenshot - 确认代码反映了提取的层级结构:所有主要区域、正确的父级、导出的资源及映射的令牌。
Existing project uses different patterns
现有项目使用不同模式
- Follow project patterns over skill examples (e.g. styled-components vs Tailwind).
- Map symbols to whatever component system the repo uses.
- 遵循项目模式而非示例(例如styled-components vs Tailwind)。
- 将符号映射到仓库使用的任意组件系统。
User wanted mobile but repo is web (or vice versa)
用户需要移动端代码但仓库为Web端(反之亦然)
- Stop and confirm platform before large implementation.
- 在大规模实现前停止操作并确认平台。
References
参考资料
- with
get_guide— MCP workflow,topic: "mcp", visual verification, and completion rulesrun_code - with
get_guide— Sketch inspection, stacks, symbols, styles, exports, and content verificationtopic: "use" - Extraction patterns
- Symbol → code mapping patterns
- Asset export patterns
- Validation checklist
- Sketch MCP server docs
- Sketch JavaScript API
- (
get_guide)——MCP工作流、topic: "mcp"、视觉验证及完成规则run_code - (
get_guide)——Sketch检查、堆叠、符号、样式、导出及内容验证topic: "use" - 提取模式
- 符号→代码映射模式
- 资源导出模式
- 验证清单
- Sketch MCP服务器文档
- Sketch JavaScript API