code-connect-components

代码连接组件

概述

此技能可帮助你使用 Figma 的 Code Connect 功能，将 Figma 设计组件连接到对应的代码实现。它会分析 Figma 设计结构，在代码库中搜索匹配的组件，并建立映射，以保持设计与代码的一致性。

前提条件

• 必须已连接并可访问 Figma MCP 服务
  • 继续之前，请检查 Figma MCP 工具（例如 get_code_connect_suggestions）是否可用，以确认 Figma MCP 服务已连接。
  • 如果这些工具不可用，则可能尚未启用 Figma MCP 服务。请指导用户启用插件附带的 Figma MCP 服务。之后可能需要重启 MCP 客户端。
• 用户必须提供带节点 ID 的 Figma URL：https://figma.com/design/:fileKey/:fileName?node-id=1-2
  • 重要： Figma URL 必须包含 node-id 参数。没有该参数，Code Connect 映射将会失败。
• 重要： Figma 组件必须已发布到团队库。Code Connect 仅适用于已发布的组件或组件集。
• 重要： Code Connect 仅适用于 Organization 和 Enterprise 计划。
• 能够访问项目代码库，以便扫描组件

必需工作流

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

步骤 1：获取 Code Connect 建议

调用 get_code_connect_suggestions，一次性识别所有未映射组件。此工具会自动：

• 从 Figma 场景图获取组件信息
• 识别所选内容中已发布的组件
• 检查现有的 Code Connect 映射，并筛除已连接的组件
• 返回每个未映射组件的名称、属性和缩略图

从 URL 中提取 fileKey 和 nodeId，然后调用 get_code_connect_suggestions。

重要： 从 Figma URL 提取节点 ID 时，请转换其格式：

• URL 使用连字符：node-id=1-2
• 工具需要使用冒号：nodeId=1:2

解析 Figma URL：

• URL 格式：https://figma.com/design/:fileKey/:fileName?node-id=1-2
• 提取文件键：:fileKey（/design/ 后的部分）
• 从 URL 提取节点 ID：1-2，然后转换为 1:2 供工具使用

get_code_connect_suggestions(fileKey=":fileKey", nodeId="1:2")

处理响应：

• 如果工具返回 “No published components found in this selection” → 告知用户并停止。可能需要先将这些组件发布到团队库。
• 如果工具返回 “All component instances in this selection are already connected to code via Code Connect” → 告知用户所有内容都已完成映射。
• 否则，响应中会包含未映射组件的列表，每项包括：
  • 组件名称
  • 节点 ID
  • 组件属性（包含属性名称和值的 JSON）
  • 组件缩略图（供目视检查）

步骤 2：扫描代码库，查找匹配的组件

对于 get_code_connect_suggestions 返回的每个未映射组件，请在代码库中搜索匹配的代码组件。

查找内容：

• 与 Figma 组件名称相同或相似的组件名称
• 与 Figma 层级结构一致的组件结构
• 与 Figma 属性（变体、文本、样式）相对应的属性
• 常见组件目录中的文件（src/components/、components/、ui/ 等）

搜索策略：

1. 搜索名称匹配的组件文件
2. 阅读候选文件，检查其结构和属性
3. 将代码组件的属性与步骤 1 返回的 Figma 组件属性进行比较
4. 检测编程语言（TypeScript、JavaScript）和框架（React、Vue 等）
5. 根据结构相似度确定最佳匹配，重点考虑：
   • 属性名称及其与 Figma 属性的对应关系
   • 与 Figma 默认值匹配的默认值
   • CSS 类或样式对象
   • 能阐明用途的说明性注释
6. 如果有多个同样合适的候选项，选择属性接口最匹配的候选项，并在调用工具前用 1-2 句话的注释说明理由

搜索模式示例：

• 如果 Figma 组件为“PrimaryButton”，请搜索 Button.tsx、PrimaryButton.tsx、Button.jsx
• 检查常见组件路径：src/components/、app/components/、lib/ui/
• 查找与 Figma 变体匹配的变体属性，例如 variant、size、color

步骤 3：向用户展示匹配结果

展示你的查找结果，让用户选择要创建哪些映射。用户可以接受全部、部分或不接受任何建议的映射。

按以下格式展示匹配结果：

The following components match the design:
- [ComponentName](path/to/component): DesignComponentName at nodeId [nodeId](figmaUrl?node-id=X-Y)
- [AnotherComponent](path/to/another): AnotherDesign at nodeId [nodeId2](figmaUrl?node-id=X-Y)

Would you like to connect these components? You can accept all, select specific ones, or skip.

如果找不到组件的完全匹配项：

• 展示最接近的 2 个候选项
• 说明它们之间的差异
• 请用户确认要使用哪个组件，或提供正确路径

如果用户拒绝所有映射，请告知用户并停止。无需调用后续工具。

步骤 4：创建 Code Connect 映射

用户确认选择后，仅将已接受的映射传递给 send_code_connect_mappings。此工具会在一次调用中批量创建所有映射。

示例：

send_code_connect_mappings(
  fileKey=":fileKey",
  nodeId="1:2",
  mappings=[
    { nodeId: "1:2", componentName: "Button", source: "src/components/Button.tsx", label: "React" },
    { nodeId: "1:5", componentName: "Card", source: "src/components/Card.tsx", label: "React" }
  ]
)

每个映射的关键参数：

• nodeId：Figma 节点 ID（冒号格式：1:2）
• componentName：要连接的组件名称（例如，“Button”“Card”）
• source：代码组件文件的路径（相对于项目根目录）
• label：此 Code Connect 映射的框架或语言标签。有效值包括：
  • Web：'React'、'Web Components'、'Vue'、'Svelte'、'Storybook'、'Javascript'
  • iOS：'Swift UIKit'、'Objective-C UIKit'、'SwiftUI'
  • Android：'Compose'、'Java'、'Kotlin'、'Android XML Layout'
  • 跨平台：'Flutter'
  • 文档：'Markdown'

调用后：

• 成功时：工具会确认映射已创建
• 出错时：工具会报告具体哪些映射创建失败及原因（例如，“组件已映射到代码”“未找到已发布的组件”“权限不足”）

处理完成后，提供摘要：

Code Connect Summary:
- Successfully connected: 3
  - Button (1:2) → src/components/Button.tsx
  - Card (1:5) → src/components/Card.tsx
  - Input (1:8) → src/components/Input.tsx
- Could not connect: 1
  - CustomWidget (1:10) - No matching component found in codebase

示例

示例 1：连接按钮组件

用户说：“将这个 Figma 按钮连接到我的代码：https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15”

操作：

1. 解析 URL：fileKey=kL9xQn2VwM8pYrTb4ZcHjF，nodeId=42-15 → 转换为 42:15

2. 运行 get_code_connect_suggestions(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42:15")

3. 响应显示：Button 组件（未映射），包含 variant（primary/secondary）和 size（sm/md/lg）属性，以及缩略图

4. 在代码库中搜索 Button 组件：找到 src/components/Button.tsx

5. 阅读 Button.tsx，确认它有 variant 和 size 属性

6. 向用户展示：“我找到了一个匹配项：

   • Button：位于 nodeId 42:15 的 Button

   要连接这个组件吗？”

7. 用户确认：“是”

8. 检测到这是一个 TypeScript React 组件

9. 运行 send_code_connect_mappings(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42:15", mappings=[{ nodeId: "42:15", componentName: "Button", source: "src/components/Button.tsx", label: "React" }])

结果： Figma 按钮组件现已连接到代码中的 Button 组件。

示例 2：多个组件，仅部分选择

用户说：“连接此画板中的组件：https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Components?node-id=10-50”

操作：

1. 解析 URL：fileKey=pR8mNv5KqXzGwY2JtCfL4D，nodeId=10-50 → 转换为 10:50

2. 运行 get_code_connect_suggestions(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10:50")

3. 响应显示 3 个未映射组件：ProductCard、Badge 和 CustomWidget

4. 在代码库中搜索：

   • ProductCard：找到 src/components/ProductCard.tsx（属性匹配）
   • Badge：找到 src/components/Badge.tsx（属性匹配）
   • CustomWidget：未找到匹配的组件

5. 向用户展示： “以下组件与设计匹配：

   • ProductCard：位于 nodeId 10:51 的 ProductCard
   • Badge：位于 nodeId 10:52 的 Badge

   我没有找到与 CustomWidget（10:53）匹配的组件。

   要连接这些组件吗？你可以全部接受、选择特定组件，或跳过。”

6. 用户：“只连接 ProductCard，暂时跳过 Badge”

7. 运行 send_code_connect_mappings(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10:50", mappings=[{ nodeId: "10:51", componentName: "ProductCard", source: "src/components/ProductCard.tsx", label: "React" }])

结果： 按照用户的选择，仅连接了 ProductCard。

示例 3：需要创建组件

用户说：“连接这个图标：https://figma.com/design/8yJDMeWDyBz71EnMOSuUiw/Icons?node-id=5-20”

操作：

1. 解析 URL：fileKey=8yJDMeWDyBz71EnMOSuUiw，nodeId=5-20 → 转换为 5:20
2. 运行 get_code_connect_suggestions(fileKey="8yJDMeWDyBz71EnMOSuUiw", nodeId="5:20")
3. 响应显示：CheckIcon 组件（未映射），包含颜色和大小属性
4. 在代码库中搜索 CheckIcon：未找到匹配项
5. 搜索通用 Icon 组件：找到包含其他图标的 src/icons/ 目录
6. 向用户说明：“我没有找到 CheckIcon 组件，但找到了一个图标目录：src/icons/。你想：
   • 先创建新的 CheckIcon.tsx 组件，然后再连接
   • 连接到其他现有图标
   • 提供 CheckIcon 的路径（如果它位于其他位置）”
7. 用户提供路径：“src/icons/CheckIcon.tsx”
8. 从文件检测语言和框架
9. 运行 send_code_connect_mappings(fileKey="8yJDMeWDyBz71EnMOSuUiw", nodeId="5:20", mappings=[{ nodeId: "5:20", componentName: "CheckIcon", source: "src/icons/CheckIcon.tsx", label: "React" }])

结果： CheckIcon 组件已成功连接到 Figma 设计。

最佳实践

主动发现组件

不要只向用户询问文件路径——应主动搜索其代码库，查找匹配的组件。这能带来更好的体验，并发现潜在的映射机会。

准确匹配结构

将 Figma 组件与代码组件进行比较时，不要只看名称。请检查：

• 属性是否一致（变体类型、尺寸选项等）
• 组件层级是否匹配（嵌套元素）
• 组件的用途是否相同

清晰沟通

提出创建映射时，请清楚说明：

• 找到了什么
• 为什么它们匹配
• 映射会实现什么
• 属性将如何关联

处理歧义

如果有多个组件可能匹配，请列出选项，而不是猜测。让用户最终决定要关联哪个组件。

优雅降级

如果找不到完全匹配的组件，请提供有帮助的后续步骤：

• 展示接近的候选项
• 建议创建组件
• 请求用户提供指导

常见问题及解决方案

问题：“No published components found in this selection”

原因： Figma 组件尚未发布到团队库。Code Connect 仅适用于已发布的组件。 解决方案： 用户需要在 Figma 中将组件发布到团队库：

1. 在 Figma 中，选择组件或组件集
2. 右键点击并选择 “Publish to library”，或使用 Team Library 发布弹窗
3. 发布组件
4. 发布后，使用相同的节点 ID 重试 Code Connect 映射

问题：“Code Connect is only available on Organization and Enterprise plans”

原因： 用户的 Figma 套餐不包含 Code Connect 访问权限。 解决方案： 用户需要升级到 Organization 或 Enterprise 套餐，或联系管理员。

问题：在代码库中找不到匹配的组件

原因： 代码库搜索未找到名称或结构匹配的组件。 解决方案： 询问用户组件是否以其他名称存在，或位于其他位置。用户可能需要先创建该组件，也可能是组件位于意料之外的目录中。

问题：“Published component not found” (CODE_CONNECT_ASSET_NOT_FOUND)

原因： 源文件路径不正确、该位置不存在此组件，或 componentName 与实际导出名称不匹配。 解决方案： 确认源路径正确，并且是相对于项目根目录的路径。检查文件是否按指定的确切 componentName 正确导出了该组件。

问题：“Component is already mapped to code” (CODE_CONNECT_MAPPING_ALREADY_EXISTS)

原因： 此组件已存在 Code Connect 映射。 解决方案： 该组件已连接。如果用户想更新映射，可能需要先在 Figma 中移除现有映射。

问题：“Insufficient permissions to create mapping” (CODE_CONNECT_INSUFFICIENT_PERMISSIONS)

原因： 用户没有该 Figma 文件或库的编辑权限。 解决方案： 用户需要拥有包含该组件的文件的编辑权限。请联系文件所有者或团队管理员。

问题：Code Connect 映射因 URL 错误而失败

原因： Figma URL 格式不正确，或缺少 node-id 参数。 解决方案： 确认 URL 符合所需格式：https://figma.com/design/:fileKey/:fileName?node-id=1-2。node-id 参数为必填项。此外，调用工具时，请确保将 1-2 转换为 1:2。

问题：找到多个相似组件

原因： 代码库中有多个可能与 Figma 组件匹配的组件。 解决方案： 向用户列出所有候选项及其文件路径，让用户选择要关联的组件。不同组件可能用于不同场景（例如，Button.tsx 与 LinkButton.tsx）。

了解 Code Connect

Code Connect 在设计与代码之间建立双向链接：

面向设计师： 查看哪些代码组件实现了 Figma 组件 面向开发者： 直接从 Figma 设计跳转到实现它们的代码 面向团队： 维护组件映射的单一可信来源

你创建的映射可以明确展示这些关联，让它们易于查找，从而帮助保持设计与代码同步。

其他资源

如需了解有关 Code Connect 的更多信息：

• Code Connect 文档
• Figma MCP Server 工具和提示词