figma-implement-design

实现设计

概述

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

前置条件

• 必须已连接并可访问 Figma MCP 服务
• 用户必须提供如下格式的 Figma URL：https://figma.com/design/:fileKey/:fileName?node-id=1-2
  • :fileKey 是文件 key
  • 1-2 是节点 ID（要实现的具体组件或画框）
• 或者在使用 figma-desktop MCP 时：用户可直接在 Figma 桌面应用中选择节点（无需 URL）
• 项目应已建立设计系统或组件库（推荐）

必需工作流

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

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

如果因 Figma MCP 未连接而导致任何 MCP 调用失败，请暂停并完成设置：

1. 添加 Figma MCP：
   • codex mcp add figma --url https://mcp.figma.com/mcp
2. 启用远程 MCP 客户端：
   • 在 config.toml 中设置 [features].rmcp_client = true，或运行 codex --enable rmcp_client
3. 使用 OAuth 登录：
   • codex mcp login figma

登录成功后，用户需要重启 codex。你应完成回答并告知用户，当他们再次尝试时即可继续执行第 1 步。

第 1 步：获取节点 ID

方案 A：从 Figma URL 中解析

当用户提供 Figma URL 时，提取文件 key 和节点 ID，作为参数传递给 MCP 工具。

URL 格式： https://figma.com/design/:fileKey/:fileName?node-id=1-2

提取：

• 文件 key： :fileKey（/design/ 之后的片段）
• 节点 ID： 1-2（node-id 查询参数的值）

注意： 使用本地桌面 MCP（figma-desktop）时，fileKey 不会作为参数传递给工具调用。该服务会自动使用当前打开的文件，因此只需 nodeId 即可。

示例：

• URL：https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15
• 文件 key：kL9xQn2VwM8pYrTb4ZcHjF
• 节点 ID：42-15

方案 B：使用 Figma 桌面应用中的当前选择（仅限 figma-desktop MCP）

使用 figma-desktop MCP 且用户未提供 URL 时，工具会自动使用桌面应用中打开的 Figma 文件里当前选中的节点。

注意： 基于选择的提示仅适用于 figma-desktop MCP 服务。远程服务需要画框或图层链接来提取上下文。用户必须打开 Figma 桌面应用并选中某个节点。

第 2 步：获取设计上下文

使用提取的文件 key 和节点 ID 运行 get_design_context。

get_design_context(fileKey=":fileKey", nodeId="1-2")

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

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

如果响应过大或被截断：

1. 运行 get_metadata(fileKey=":fileKey", nodeId="1-2") 获取高层级节点映射
2. 从元数据中识别所需的具体子节点
3. 使用 get_design_context(fileKey=":fileKey", nodeId=":childNodeId") 获取各个子节点

第 3 步：捕获视觉参考

使用相同的文件 key 和节点 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 变量和设计令牌