figma-implement-design

实现设计

概述

此技能提供一套结构化工作流，用于将 Figma 设计转换为可投入生产的代码，并确保像素级精准。它可确保与 Figma MCP 服务保持一致集成、正确使用设计令牌，并实现与设计 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 服务必须已连接且可访问
• 用户必须提供符合以下格式的 Figma URL：https://figma.com/design/:fileKey/:fileName?node-id=1-2
  • :fileKey 是文件密钥
  • 1-2 是节点 ID（要实现的特定组件或画框）
• 或者 使用 figma-desktop MCP 时：用户可以直接在 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")

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

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

如果响应过大或被截断：

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 工具类替换为项目首选的工具类或设计系统 token
• 复用现有组件（按钮、输入框、排版、图标包装器），而不是重复实现功能
• 一致地使用项目的颜色系统、排版比例和间距 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"

操作：

1. 解析 URL 以提取 fileKey=kL9xQn2VwM8pYrTb4ZcHjF 和 nodeId=42-15
2. 运行 get_design_context(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42-15")
3. 运行 get_screenshot(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42-15") 作为视觉参考
4. 从资源端点下载任何按钮图标
5. 检查项目是否已有按钮组件
6. 如果有，用新变体扩展它；如果没有，使用项目约定创建新组件
7. 将 Figma 颜色映射到项目设计 token（例如 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 设计都以同等程度的细致和关注细节来实现。

其他资源

• Figma MCP Server 文档
• Figma MCP Server 工具和提示词
• Figma 变量和设计令牌