figma-code-connect-components

Code Connect 组件

概述

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

技能边界

• 将此技能用于 get_code_connect_suggestions + send_code_connect_mappings 工作流。
• 如果任务需要通过 Plugin API 脚本写入 Figma 画布，请切换到 figma-use。
• 如果任务是根据代码或描述在 Figma 中构建或更新完整页面，请切换到 figma-generate-design。
• 如果任务是根据 Figma 实现产品代码，请切换到 figma-implement-design。

前提条件

• 必须连接并能够访问 Figma MCP 服务
• 用户必须提供包含节点 ID 的 Figma URL：https://figma.com/design/:fileKey/:fileName?node-id=1-2
  • 重要： Figma URL 必须包含 node-id 参数。没有该参数，Code Connect 映射将失败。
• 或者使用 figma-desktop MCP 时：用户可以直接在 Figma 桌面应用中选择节点（无需 URL）
• 重要： Figma 组件必须已发布到团队库。Code Connect 仅适用于已发布的组件或组件集。
• 重要： Code Connect 仅适用于 Organization 和 Enterprise 方案。
• 可访问用于扫描组件的项目代码库

必需工作流

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

步骤 1：获取 Code Connect 建议

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

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

选项 A：使用 figma-desktop MCP（未提供 URL）

如果已连接 figma-desktop MCP 服务，且用户未提供 Figma URL，请立即调用 get_code_connect_suggestions。无需解析 URL——桌面 MCP 服务会自动使用已打开 Figma 文件中当前选中的节点。

注意： 用户必须打开 Figma 桌面应用并选中一个节点。无需传递 fileKey 参数——服务会使用当前打开的文件。

选项 B：已提供 Figma URL

从 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. 向用户展示：

   I found a match:
   - [Button](src/components/Button.tsx): Button at nodeId [42:15](https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15)
   
   Would you like to connect this component?
   

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. 向用户展示：

   The following components match the design:
   - [ProductCard](src/components/ProductCard.tsx): ProductCard at nodeId [10:51](https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Components?node-id=10-51)
   - [Badge](src/components/Badge.tsx): Badge at nodeId [10:52](https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Components?node-id=10-52)
   
   I couldn't find a match for CustomWidget (10:53).
   
   Would you like to connect these components? You can accept all, select specific ones, or skip.
   

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 组件与代码组件时，不要只看名称。请检查：

• 属性是否匹配（variant 类型、大小选项等）
• 组件层级是否匹配（嵌套元素）
• 组件用途是否相同

清晰沟通

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

• 找到了什么
• 为什么它们匹配
• 映射会产生什么效果
• 属性将如何连接

处理歧义

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

优雅降级

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

• 显示相近的候选项
• 建议创建组件
• 请用户提供指导

常见问题与解决方案

问题："No published components found in this selection"

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

1. 在 Figma 中，选择组件或组件集
2. 右键单击并选择 "Publish to library"，或使用 Team Library 发布对话框
3. 发布组件
4. 发布后，使用相同的 node 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 服务工具和提示词