用 Figma Code Connect…

当需要把 Figma 设计组件与代码实现建立 Code Connect 映射时，用 get_code_connect_suggestions + send_code_connect_mappings 完成批量连接。

适用场景

解决思路

1. 确认前置条件：Figma MCP server 已连接可访问；用户提供带 node-id 的 Figma URL（格式 https://figma.com/design/:fileKey/:fileName?node-id=1-2），或使用 figma-desktop MCP 时用户在 Figma 桌面应用中直接选中节点（无需 URL）；Figma 组件必须已发布到团队库；Code Connect 仅在 Organization 和 Enterprise 套餐可用；并能访问项目代码库进行组件扫描。
2. Step 1：调用 get_code_connect_suggestions 一次性识别所有未映射组件。该工具会自动从 Figma scenegraph 获取组件信息、识别选区中已发布的组件、检查已有 Code Connect 映射并过滤掉已连接的组件，返回每个未映射组件的名称、属性、缩略图。
3. Option A（figma-desktop MCP，未提供 URL）：若 figma-desktop MCP 已连接且用户未提供 Figma URL，直接调用 get_code_connect_suggestions，无需解析 URL，服务器自动使用当前打开文件中选中的节点；不传 fileKey 参数。
4. Option B（提供了 Figma URL）：解析 URL 提取 fileKey 和 nodeId，再调用 get_code_connect_suggestions。注意 node ID 格式转换：URL 用连字符 node-id=1-2，工具需要冒号 nodeId=1:2。fileKey 取 /design/ 后的片段。例如 get_code_connect_suggestions(fileKey=":fileKey", nodeId="1:2")。
5. 处理响应：若返回 "No published components found in this selection" → 告知用户并停止，组件可能需先发布到团队库；若返回 "All component instances in this selection are already connected to code via Code Connect" → 告知用户已全部映射；否则响应包含未映射组件列表，每项含组件名、Node ID、组件属性（JSON 的 prop 名与值）、缩略图。
6. Step 2：对每个未映射组件在代码库中搜索匹配的代码组件。查找：与 Figma 组件名相同或相似的组件名；与 Figma 层级一致的结构；与 Figma 属性（variants、text、styles）对应的 props；常见组件目录（src/components/、components/、ui/ 等）中的文件。
7. 搜索策略：1) 按名称搜索组件文件；2) 读取候选文件检查结构与 props；3) 将代码组件 props 与 Step 1 返回的 Figma 组件属性对比；4) 检测编程语言（TypeScript、JavaScript）与框架（React、Vue 等）；5) 基于结构相似度选出最佳匹配，权衡 prop 名与 Figma 属性的对应、与 Figma 默认值一致的默认值、CSS 类或样式对象、说明意图的注释；6) 若多个候选同样好，选 prop 接口最接近的，并在工具调用前用 1-2 句注释记录理由。
8. 搜索模式示例：若 Figma 组件是 "PrimaryButton"，搜索 Button.tsx、PrimaryButton.tsx、Button.jsx；检查常见路径 src/components/、app/components/、lib/ui/；查找与 Figma variants 匹配的 variant、size、color 等 props。
9. Step 3：向用户展示匹配结果，让用户选择要创建哪些映射（可全部接受、部分接受或全部拒绝）。展示格式：The following components match the design: - [ComponentName](path/to/component): DesignComponentName at nodeId [nodeId](figmaUrl?node-id=X-Y) ... Would you like to connect these components? You can accept all, select specific ones, or skip.
10. 若某组件找不到精确匹配：展示 2 个最接近的候选，说明差异，请用户确认使用哪个组件或提供正确路径。若用户拒绝所有映射，告知并停止，无需进一步工具调用。
11. Step 4：用户确认选择后，调用 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" }])。
12. 每个映射的关键参数：nodeId（Figma 节点 ID，冒号格式 1:2）；componentName（要连接的组件名，如 "Button"、"Card"）；source（代码组件文件路径，相对项目根目录）；label（该 Code Connect 映射的框架或语言标签）。有效 label 值：Web 类 'React'、'Web Components'、'Vue'、'Svelte'、'Storybook'、'Javascript'；iOS 类 'Swift UIKit'、'Objective-C UIKit'、'SwiftUI'；Android 类 'Compose'、'Java'、'Kotlin'、'Android XML Layout'；跨平台 'Flutter'；文档 'Markdown'。
13. 调用后：成功时工具确认映射已创建；出错时工具报告哪些映射失败及原因（如 "Component is already mapped to code"、"Published component not found"、"Insufficient permissions"）。随后提供汇总，例如：Code Connect Summary: - Successfully connected: 3 ... - Could not connect: 1 ...
14. 最佳实践：主动发现组件——不要只问用户文件路径，主动搜索代码库找匹配组件；精确结构匹配——除名称外还要检查 props 对齐（variant 类型、size 选项等）、组件层级匹配（嵌套元素）、组件用途一致；清晰沟通——说明发现了什么、为何是好的匹配、映射会做什么、props 将如何连接；处理歧义——多个组件可能匹配时展示选项而非猜测，让用户做最终决定；优雅降级——找不到精确匹配时展示接近候选、建议创建组件、请求用户指引。
15. 常见问题处理："No published components found in this selection" → 组件未发布到团队库，需在 Figma 中选中组件或组件集，右键选 "Publish to library" 或使用 Team Library 发布弹窗发布后重试；"Code Connect is only available on Organization and Enterprise plans" → 用户需升级套餐或联系管理员；代码库中找不到匹配组件 → 询问用户组件是否以其他名称或位置存在，可能需先创建组件；"Published component not found"（CODE_CONNECT_ASSET_NOT_FOUND）→ 校验 source 路径正确且相对项目根目录，组件以精确 componentName 正确导出；"Component is already mapped to code"（CODE_CONNECT_MAPPING_ALREADY_EXISTS）→ 组件已连接，如需更新可能需先在 Figma 中移除现有映射；"Insufficient permissions to create mapping"（CODE_CONNECT_INSUFFICIENT_PERMISSIONS）→ 用户需对包含组件的文件有编辑权限，联系文件所有者或团队管理员；URL 错误导致映射失败 → 校验 URL 格式为 https://figma.com/design/:fileKey/:fileName?node-id=1-2，node-id 参数必需，且调用工具时将 1-2 转为 1:2；找到多个相似组件 → 向用户展示所有候选及其文件路径，让用户选择，不同组件可能用于不同场景（如 Button.tsx vs LinkButton.tsx）。

适用边界 · 注意事项

• 任务需要用 Plugin API 脚本写入 Figma 画布时，应改用 figma-use 技能。
• 任务是从代码或描述在 Figma 中构建/更新整页屏幕时，应改用 figma-generate-design 技能。
• 任务是从 Figma 实现产品代码时，应改用 figma-implement-design 技能。