mcpField
F
figma-implement-design

figma-implement-design

github.com/tech-leads-club设计与 UI7.1k230 次安装今天更新
代码仓库

关于 figma-implement-design

将 Figma 设计转化为项目代码的实现技能，面向需要按现有设计系统和代码规范构建界面的开发者。它要求先通过 Figma MCP 获取设计上下文与截图，再实现并对照验证界面。

主要功能

  1. 01从 Figma 获取设计上下文与截图
  2. 02解析文件与节点标识
  3. 03下载设计资源并沿用项目规范
  4. 04复用组件并映射设计令牌
  5. 05对照截图验证布局与视觉

适用场景

  1. 01按 Figma 设计实现 UI 组件
  2. 02将 Figma 页面转为项目界面
  3. 03检查实现与设计截图的一致性

MCP 相关

要求连接 Figma MCP 服务，以获取设计上下文、节点元数据、截图和资源；可使用远程服务或 figma-desktop MCP。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/tech-leads-club/agent-skills --skill figma-implement-design

安装后在 Claude Code 中输入/figma-implement-design确认已加载。

附带文件LICENSE.txt

详细介绍

实现设计

概述

此技能提供了一套结构化工作流，可将 Figma 设计转换为可用于生产环境的代码，并实现像素级精确还原。它确保与 Figma MCP 服务保持一致集成、正确使用设计令牌，并与设计实现 1:1 的视觉一致性。

先决条件

  • 必须已连接并可访问 Figma MCP 服务
  • 用户必须提供符合以下格式的 Figma URL：https://figma.com/design/:fileKey/:fileName?node-id=1-2
    • :fileKey 是文件密钥
    • 1-2 是节点 ID（要实现的具体组件或画板）
  • 或使用 figma-desktop MCP 时：用户可以直接在 Figma 桌面应用中选择节点（无需 URL）
  • 项目应已有成熟的设计系统或组件库（优先考虑）

必需工作流

请按顺序执行以下步骤。不要跳过任何步骤。

步骤 0：设置 Figma MCP（如果尚未配置）

如果 Figma MCP 未连接导致任何 MCP 调用失败，请暂停并进行设置：

  1. 将 Figma MCP 服务添加到 Agent 的 MCP 配置中：
    • URL：https://mcp.figma.com/mcp
  2. 如果 Agent 有此要求，请启用远程 MCP 客户端。
  3. 按照 Agent 的身份验证流程使用 OAuth 登录。

登录成功后，用户需要重新启动 Agent。用户再次尝试时，你应结束回复并告知他们可以从步骤 1 继续。

步骤 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")

这将提供结构化数据，包括：

  • 布局属性（自动布局、约束、尺寸）
  • 排版规范
  • 颜色值和设计令牌
  • 组件结构和变体
  • 间距和内边距值

如果响应过大或被截断：

  1. 运行 get_metadata(fileKey=":fileKey", nodeId="1-2") 获取高级节点映射
  2. 根据元数据确定所需的具体子节点
  3. 使用 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）视为设计和行为的表示，而非最终代码风格
  • 将 Tailwind 工具类替换为项目首选的工具类或设计系统令牌
  • 复用现有组件（按钮、输入框、排版、图标包装器），而不是重复实现功能
  • 始终使用项目的颜色系统、排版比例和间距令牌
  • 遵循现有的路由、状态管理和数据获取模式
步骤 6：实现 1:1 视觉还原

力求与 Figma 设计实现像素级的视觉还原。

指南：

  • 优先忠实还原 Figma，确保与设计完全一致
  • 避免硬编码值；尽可能使用 Figma 中的设计令牌
  • 当设计系统令牌与 Figma 规范冲突时，优先使用设计系统令牌，但可尽量微调间距或尺寸以匹配视觉效果
  • 遵循 WCAG 无障碍要求
  • 根据需要添加组件文档
步骤 7：对照 Figma 验证

在标记为完成之前，对照 Figma 截图验证最终 UI。

验证清单：

  • 布局匹配（间距、对齐、尺寸）
  • 排版匹配（字体、字号、字重、行高）
  • 颜色完全匹配
  • 交互状态符合设计（悬停、激活、禁用）
  • 响应式行为符合 Figma 约束
  • 资源渲染正确
  • 符合无障碍标准

实施规则

组件组织
  • 将 UI 组件放在项目指定的设计系统目录中
  • 遵循项目的组件命名约定
  • 除非动态值确实需要，否则避免使用内联样式
设计系统集成
  • 始终尽可能使用项目设计系统中的组件
  • 将 Figma 设计令牌映射到项目设计令牌
  • 如果存在匹配的组件，应扩展该组件，而不是新建组件
  • 为添加到设计系统中的任何新组件编写文档
代码质量
  • 避免硬编码值；将其提取为常量或设计令牌
  • 确保组件可组合且可复用
  • 为组件属性添加 TypeScript 类型
  • 为导出的组件添加 JSDoc 注释

示例

示例 1：实现按钮组件

用户说：“实现这个 Figma 按钮组件：https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15”

操作：

  1. 解析 URL，提取 fileKey=kL9xQn2VwM8pYrTb4ZcHjF 和 nodeId=42-15
  2. 运行 get_design_context(fileKey="kL9xQn2VwM8pYrTb4ZZcHjF", nodeId="42-15")
  3. 运行 get_screenshot(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42-15") 作为视觉参考
  4. 从资源端点下载所有按钮图标
  5. 检查项目是否已有按钮组件
  6. 如果有，则为其扩展新的变体；如果没有，则遵循项目约定创建新组件
  7. 将 Figma 颜色映射到项目设计令牌（例如 primary-500、primary-hover）
  8. 对照截图验证内边距、边框圆角和排版

结果： 与 Figma 设计匹配、并集成到项目设计系统中的按钮组件。

示例 2：构建仪表盘布局

用户说：“构建这个仪表盘：https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Dashboard?node-id=10-5”

操作：

  1. 解析 URL 以提取 fileKey=pR8mNv5KqXzGwY2JtCfL4D 和 nodeId=10-5
  2. 运行 get_metadata(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10-5") 以了解页面结构
  3. 从元数据中识别主要区域（页眉、侧边栏、内容区、卡片）及其子节点 ID
  4. 为每个主要区域运行 get_design_context(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId=":childNodeId")
  5. 为整个页面运行 get_screenshot(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10-5")
  6. 下载所有资源（徽标、图标、图表）
  7. 使用项目的布局基元构建布局
  8. 尽可能使用现有组件实现每个区域
  9. 对照 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，不要修改。

问题：设计令牌值与 Figma 不同

原因： 项目的设计系统令牌值与 Figma 设计中指定的值不同。 解决方案： 当项目令牌与 Figma 值不同时，优先使用项目令牌以保持一致，但调整间距/尺寸以维持视觉保真度。

理解设计实现

Figma 实现工作流建立了一个可靠流程，用于将设计转换为代码：

对于设计师： 确信实现将以像素级精度匹配其设计。 对于开发者： 一种结构化方法，可消除猜测并减少来回修改。 对于团队： 一致、高质量的实现，保持设计系统的完整性。

通过遵循此工作流，你可以确保每个 Figma 设计都以同等程度的细致和关注细节来实现。

其他资源

评论

支持 Markdown