实现设计
概述
此技能提供了一套结构化工作流,用于将 Figma 设计稿像素级精确地转换为可直接生产的代码。它确保与 Figma MCP 服务器一致集成,正确使用设计 Token,并达到与设计稿 1:1 的视觉一致性。
技能边界
- 当任务是向用户仓库中交付代码时,使用此技能。
- 如果用户要求在 Figma 内部创建/编辑/删除节点,请切换到 figma-use。
- 如果用户要求从代码或描述在 Figma 中构建或更新全页屏幕,请切换到 figma-generate-design。
- 如果用户仅要求 Code Connect 映射,请切换到 figma-code-connect-components。
- 如果用户要求编写可复用的 Agent 规则(
CLAUDE.md/AGENTS.md),请切换到 figma-create-design-system-rules。
前置条件
- 必须连接并能够访问 Figma MCP 服务器
- 用户必须提供格式为
https://figma.com/design/:fileKey/:fileName?node-id=1-2的 Figma 链接:fileKey是文件密钥1-2是节点 ID(要实现的特定组件或画框)
- 或者 当使用
figma-desktopMCP 时:用户可以直接在 Figma 桌面应用中选择一个节点(无需 URL) - 项目最好已建立设计系统或组件库(更优)
必需工作流
按顺序执行以下步骤,请勿跳过。
步骤 1:获取节点 ID
选项 A:从 Figma URL 中解析
当用户提供 Figma URL 时,提取文件密钥和节点 ID 作为 MCP 工具的参数。
URL 格式: https://figma.com/design/:fileKey/:fileName?node-id=1-2
提取:
- 文件密钥:
:fileKey(/design/后的段落) - 节点 ID:
1-2(node-id查询参数的值)
注意: 当使用本地桌面 MCP(figma-desktop)时,fileKey 不会作为参数传递给工具调用。服务器会自动使用当前打开的文件,因此只需 nodeId。
示例:
- URL:
https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15 - 文件密钥:
kL9xQn2VwM8pYrTb4ZcHjF - 节点 ID:
42-15
选项 B:使用 Figma 桌面应用中的当前选择(仅限 figma-desktop MCP)
当使用 figma-desktop MCP 且用户未提供 URL 时,工具会自动使用 Figma 桌面应用中当前打开文件里选中的节点。
注意: 基于选择的方式仅适用于 figma-desktop MCP 服务器。远程服务器需要一个指向画框或图层的链接来提取上下文。用户必须打开 Figma 桌面应用并选择一个节点。
步骤 2:获取设计上下文
使用提取的文件密钥和节点 ID 运行 get_design_context。
get_design_context(fileKey=":fileKey", nodeId="1-2")
这将提供包含以下内容的结构化数据:
- 布局属性(自动布局、约束、尺寸)
- 排版规范
- 颜色值和设计 Token
- 组件结构与变体
- 间距和内边距值
如果响应过大或被截断:
- 运行
get_metadata(fileKey=":fileKey", nodeId="1-2")获取高级节点映射 - 从元数据中识别所需的特定子节点
- 使用
get_design_context(fileKey=":fileKey", nodeId=":childNodeId")获取各个子节点
步骤 3:获取视觉参考
使用相同的文件密钥和节点 ID 运行 get_screenshot 获取视觉参考。
get_screenshot(fileKey=":fileKey", nodeId="1-2")
此截图作为视觉验证的权威依据,在整个实现过程中保持可访问。
步骤 4:下载所需资源
下载 Figma MCP 服务器返回的所有资源(图片、图标、SVG)。
重要: 遵循以下资源规则:
- 如果 Figma MCP 服务器返回图片或 SVG 的
localhost来源,请直接使用该来源 - 不要导入或添加新的图标包——所有资源应来自 Figma 负载
- 如果提供了
localhost来源,请不要使用或创建占位符 - 资源通过 Figma MCP 服务器内置的资源端点提供服务
步骤 5:转换为项目约定
将 Figma 输出转换为项目的框架、样式和约定。
关键原则:
- 将 Figma MCP 输出(通常为 React + Tailwind)视为设计和行为的表示,而非最终代码风格
- 用项目偏好的实用工具类或设计系统 Token 替换 Tailwind 实用工具类
- 复用现有组件(按钮、输入框、排版、图标包装器),而不是重复实现功能
- 一致地使用项目的色彩系统、排版比例和间距 Token
- 尊重现有的路由、状态管理和数据获取模式
步骤 6:实现 1:1 视觉一致
力求与 Figma 设计像素级视觉一致。
指导原则:
- 优先保证 Figma 的精确匹配
- 避免硬编码值——尽可能使用 Figma 的设计 Token
- 当设计系统 Token 与 Figma 规范冲突时,优先使用设计系统 Token,但可小幅调整间距或尺寸以匹配视觉效果
- 遵循 WCAG 可访问性要求
- 根据需要添加组件文档
步骤 7:对照 Figma 进行验证
在标记完成前,对照 Figma 截图验证最终 UI。
验证检查清单:
- 布局匹配(间距、对齐、尺寸)
- 排版匹配(字体、字号、字重、行高)
- 颜色完全匹配
- 交互状态按设计工作(悬停、激活、禁用)
- 响应式行为遵循 Figma 约束
- 资源渲染正确
- 符合可访问性标准
实现规则
组件组织
- 将 UI 组件放置在项目指定的设计系统目录中
- 遵循项目的组件命名约定
- 除非动态值确实需要,否则避免使用内联样式
设计系统集成
- 尽可能始终使用项目设计系统中的组件
- 将 Figma 设计 Token 映射到项目设计 Token
- 当存在匹配的组件时,对其进行扩展而不是创建新的
- 记录添加到设计系统的任何新组件
代码质量
- 避免硬编码值——提取为常量或设计 Token
- 保持组件可组合和可复用
- 为组件 props 添加 TypeScript 类型
- 为导出的组件包含 JSDoc 注释
示例
示例 1:实现一个按钮组件
用户说:“实现这个 Figma 按钮组件:https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15”
操作:
- 解析 URL,提取 fileKey=
kL9xQn2VwM8pYrTb4ZcHjF和 nodeId=42-15 - 运行
get_design_context(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42-15") - 运行
get_screenshot(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42-15")获取视觉参考 - 从资源端点下载所有按钮图标
- 检查项目是否已有按钮组件
- 如果有,扩展其新变体;如果没有,使用项目约定创建新组件
- 将 Figma 颜色映射到项目设计 Token(例如
primary-500、primary-hover) - 对照截图验证内边距、边框半径、排版
结果: 匹配 Figma 设计的按钮组件,并与项目设计系统集成。
示例 2:构建仪表盘布局
用户说:“构建这个仪表盘:https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Dashboard?node-id=10-5”
操作:
- 解析 URL,提取 fileKey=
pR8mNv5KqXzGwY2JtCfL4D和 nodeId=10-5 - 运行
get_metadata(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10-5")了解页面结构 - 从元数据中识别主要区域(头部、侧边栏、内容区、卡片)及其子节点 ID
- 对每个主要区域运行
get_design_context(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId=":childNodeId") - 运行
get_screenshot(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10-5")获取整页截图 - 下载所有资源(标志、图标、图表)
- 使用项目布局原语构建布局
- 尽可能使用现有组件实现每个区域
- 对照 Figma 约束验证响应式行为
结果: 匹配 Figma 设计的完整仪表盘,且具有响应式布局。
最佳实践
始终从上下文开始
永远不要基于假设实现。始终先获取 get_design_context 和 get_screenshot。
增量验证
在实现过程中频繁验证,而不仅仅在最后。这有助于及早发现问题。
记录偏差
如果必须偏离 Figma 设计(例如出于可访问性或技术约束),请在代码注释中说明原因。
复用优于重建
在创建新组件之前,始终检查现有组件。代码库的一致性比精确复制 Figma 更重要。
设计系统优先
如有疑问,优先采用项目设计系统模式,而不是逐字逐句翻译 Figma。
常见问题及解决方案
问题:Figma 输出被截断
原因: 设计过于复杂或嵌套层过多,无法在一次响应中返回。
解决方案: 使用 get_metadata 获取节点结构,然后使用 get_design_context 单独获取特定节点。
问题:实现后设计不匹配
原因: 实现代码与原始 Figma 设计之间存在视觉差异。 解决方案: 与步骤 3 的截图进行并排对比。检查设计上下文数据中的间距、颜色和排版值。
问题:资源加载失败
原因: Figma MCP 服务器的资源端点不可访问,或 URL 被修改。
解决方案: 确认 Figma MCP 服务器的资源端点可访问。服务器通过 localhost URL 提供资源。直接使用这些 URL,无需修改。
问题:设计 Token 值与 Figma 不同
原因: 项目设计系统 Token 的值与 Figma 设计中指定的值不同。 解决方案: 当项目 Token 与 Figma 值不同时,为一致性优先使用项目 Token,但要调整间距/尺寸以保持视觉保真度。
理解设计实现
Figma 实现工作流建立了一个从设计到代码的可靠转换流程:
对于设计师: 确保实现将精确匹配他们的设计,达到像素级完美。 对于开发者: 一种结构化的方法,消除了猜测,减少了来回修改。 对于团队: 一致、高质量的实现,同时维护设计系统的完整性。
通过遵循此工作流,您可以确保每个 Figma 设计都以同等程度的专注和细节得到实现。