figma-code-connect-components

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Connect Components

Code Connect 组件

Overview

概述

This skill helps you connect Figma design components to their corresponding code implementations using Figma's Code Connect feature. It analyzes the Figma design structure, searches your codebase for matching components, and establishes mappings that maintain design-code consistency.

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

Skill Boundaries

技能边界

Use this skill for

get_code_connect_suggestions

send_code_connect_mappings

workflows.

If the task requires writing to the Figma canvas with Plugin API scripts, switch to figma-use.
If the task is building or updating a full-page screen in Figma from code or a description, switch to figma-generate-design.
If the task is implementing product code from Figma, switch to figma-implement-design.

本技能适用于

get_code_connect_suggestions

send_code_connect_mappings

工作流。

若任务需要通过Plugin API脚本写入Figma画布，请切换至figma-use技能。
若任务是根据代码或描述在Figma中构建或更新整页界面，请切换至figma-generate-design技能。
若任务是根据Figma设计实现产品代码，请切换至figma-implement-design技能。

Prerequisites

前置条件

Figma MCP server must be connected and accessible
User must provide a Figma URL with node ID:
```
https://figma.com/design/:fileKey/:fileName?node-id=1-2
```
- IMPORTANT: The Figma URL must include the
```
node-id
```
  parameter. Code Connect mapping will fail without it.
OR when using
```
figma-desktop
```
MCP: User can select a node directly in the Figma desktop app (no URL required)
IMPORTANT: The Figma component must be published to a team library. Code Connect only works with published components or component sets.
IMPORTANT: Code Connect is only available on Organization and Enterprise plans.
Access to the project codebase for component scanning

必须连接并可访问Figma MCP服务器
用户必须提供包含node 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计划开放。
拥有项目代码库的访问权限以进行组件扫描

Required Workflow

必备工作流

Follow these steps in order. Do not skip steps.

请按以下步骤操作，请勿跳过步骤。

Step 1: Get Code Connect Suggestions

步骤1：获取Code Connect建议

Call

get_code_connect_suggestions

to identify all unmapped components in a single operation. This tool automatically:

Fetches component info from the Figma scenegraph
Identifies published components in the selection
Checks existing Code Connect mappings and filters out already-connected components
Returns component names, properties, and thumbnail images for each unmapped component

调用

get_code_connect_suggestions

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

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

Option A: Using

figma-desktop

MCP (no URL provided)

选项A：使用

figma-desktop

MCP（未提供URL）

If the

figma-desktop

MCP server is connected and the user has NOT provided a Figma URL, immediately call

get_code_connect_suggestions

. No URL parsing is needed — the desktop MCP server automatically uses the currently selected node from the open Figma file.

Note: The user must have the Figma desktop app open with a node selected.

fileKey

is not passed as a parameter — the server uses the currently open file.

如果

figma-desktop

MCP服务器已连接，且用户未提供Figma URL，请立即调用

get_code_connect_suggestions

。无需解析URL——桌面MCP服务器会自动使用当前打开的Figma文件中选中的节点。

注意： 用户必须打开Figma桌面应用并选中一个节点。无需传递

fileKey

参数——服务器会使用当前打开的文件。

Option B: When a Figma URL is provided

选项B：提供Figma URL时

Parse the URL to extract

fileKey

and

nodeId

, then call

get_code_connect_suggestions

IMPORTANT: When extracting the node ID from a Figma URL, convert the format:

URL format uses hyphens:
```
node-id=1-2
```
Tool expects colons:
```
nodeId=1:2
```

Parse the Figma URL:

URL format:

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

Extract file key:
```
:fileKey
```
(segment after
```
/design/
```
)
Extract node ID:
```
1-2
```
from URL, then convert to
```
1:2
```
for the tool

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

Handle the response:

If the tool returns "No published components found in this selection" → inform the user and stop. The components may need to be published to a team library first.
If the tool returns "All component instances in this selection are already connected to code via Code Connect" → inform the user that everything is already mapped.
Otherwise, the response contains a list of unmapped components, each with:
- Component name
- Node ID
- Component properties (JSON with prop names and values)
- A thumbnail image of the component (for visual inspection)

解析URL以提取

fileKey

和

nodeId

，然后调用

get_code_connect_suggestions

。

重要提示： 从Figma URL提取node ID时，需要转换格式：

URL格式使用连字符：
```
node-id=1-2
```
工具要求使用冒号：
```
nodeId=1:2
```

解析Figma URL：

URL格式：

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

提取file key：
```
:fileKey
```
（
```
/design/
```
后的部分）
提取node ID：从URL中获取
```
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"** → 告知用户所有组件已完成映射。
否则，响应会包含未映射组件的列表，每个组件包含：
- 组件名称
- Node ID
- 组件属性（包含属性名和值的JSON）
- 组件的缩略图（用于视觉检查）

Step 2: Scan Codebase for Matching Components

步骤2：扫描代码库以寻找匹配组件

For each unmapped component returned by

get_code_connect_suggestions

, search the codebase for a matching code component.

What to look for:

Component names that match or are similar to the Figma component name
Component structure that aligns with the Figma hierarchy
Props that correspond to Figma properties (variants, text, styles)
Files in typical component directories (
```
src/components/
```
,
```
components/
```
,
```
ui/
```
, etc.)

Search strategy:

Search for component files with matching names
Read candidate files to check structure and props
Compare the code component's props with the Figma component properties returned in Step 1
Detect the programming language (TypeScript, JavaScript) and framework (React, Vue, etc.)
Identify the best match based on structural similarity, weighing:
- Prop names and their correspondence to Figma properties
- Default values that match Figma defaults
- CSS classes or style objects
- Descriptive comments that clarify intent
If multiple candidates are equally good, pick the one with the closest prop-interface match and document your reasoning in a 1-2 sentence comment before your tool call

Example search patterns:

If Figma component is "PrimaryButton", search for
```
Button.tsx
```
,
```
PrimaryButton.tsx
```
,
```
Button.jsx
```
Check common component paths:
```
src/components/
```
,
```
app/components/
```
,
```
lib/ui/
```
Look for variant props like
```
variant
```
,
```
size
```
,
```
color
```
that match Figma variants

针对

get_code_connect_suggestions

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

搜索要点：

组件名称与Figma组件名称完全匹配或相似
组件结构与Figma层级一致
属性与Figma属性对应（变体、文本、样式）
位于典型的组件目录中（
```
src/components/
```
、
```
components/
```
、
```
ui/
```
等）

搜索策略：

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

搜索示例：

如果Figma组件是"PrimaryButton"，搜索
```
Button.tsx
```
、
```
PrimaryButton.tsx
```
、
```
Button.jsx
```
检查常见组件路径：
```
src/components/
```
、
```
app/components/
```
、
```
lib/ui/
```
寻找与Figma变体匹配的属性，如
```
variant
```
、
```
size
```
、
```
color
```

Step 3: Present Matches to User

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

Present your findings and let the user choose which mappings to create. The user can accept all, some, or none of the suggested mappings.

Present matches in this format:

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.

If no exact match is found for a component:

Show the 2 closest candidates
Explain the differences
Ask the user to confirm which component to use or provide the correct path

If the user declines all mappings, inform them and stop. No further tool calls are needed.

展示你的搜索结果，让用户选择要创建的映射。用户可以全部接受、部分接受或全部拒绝。

展示格式：

以下组件与设计匹配：
- [组件名称](组件路径): 设计组件名称 at nodeId [nodeId](figmaUrl?node-id=X-Y)
- [另一个组件](组件路径): 另一个设计组件 at nodeId [nodeId2](figmaUrl?node-id=X-Y)

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

如果某个组件未找到完全匹配的结果：

展示2个最接近的候选组件
说明差异点
请用户确认使用哪个组件，或提供正确的路径

如果用户拒绝所有映射，告知用户并停止操作，无需再进行工具调用。

Step 4: Create Code Connect Mappings

步骤4：创建Code Connect映射

Once the user confirms their selections, call

send_code_connect_mappings

with only the accepted mappings. This tool handles batch creation of all mappings in a single call.

Example:

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" }
  ]
)

Key parameters for each mapping:

```
nodeId
```
: The Figma node ID (with colon format:
```
1:2
```
)
```
componentName
```
: Name of the component to connect (e.g., "Button", "Card")
```
source
```
: Path to the code component file (relative to project root)
```
label
```
: The framework or language label for this Code Connect mapping. Valid values include:
- Web: 'React', 'Web Components', 'Vue', 'Svelte', 'Storybook', 'Javascript'
- iOS: 'Swift UIKit', 'Objective-C UIKit', 'SwiftUI'
- Android: 'Compose', 'Java', 'Kotlin', 'Android XML Layout'
- Cross-platform: 'Flutter'
- Docs: 'Markdown'

After the call:

On success: the tool confirms the mappings were created
On error: the tool reports which specific mappings failed and why (e.g., "Component is already mapped to code", "Published component not found", "Insufficient permissions")

Provide a summary after processing:

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

用户确认选择后，仅针对已接受的映射调用

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'

调用后处理：

成功：工具会确认映射已创建
失败：工具会报告哪些映射失败及原因（例如"Component is already mapped to code"、"Published component not found"、"Insufficient permissions"）

处理完成后提供总结：

Code Connect总结：
- 成功连接：3个
  - Button (1:2) → src/components/Button.tsx
  - Card (1:5) → src/components/Card.tsx
  - Input (1:8) → src/components/Input.tsx
- 连接失败：1个
  - CustomWidget (1:10) - 代码库中未找到匹配组件

Examples

示例

Example 1: Connecting a Button Component

示例1：连接按钮组件

User says: "Connect this Figma button to my code: https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15"

Actions:

Parse URL: fileKey=
```
kL9xQn2VwM8pYrTb4ZcHjF
```
, nodeId=
```
42-15
```
→ convert to
```
42:15
```

Run

get_code_connect_suggestions(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42:15")

Response shows: Button component (unmapped) with
```
variant
```
(primary/secondary) and
```
size
```
(sm/md/lg) properties, plus a thumbnail image
Search codebase for Button components: Find
```
src/components/Button.tsx
```
Read
```
Button.tsx
```
and confirm it has
```
variant
```
and
```
size
```
props

Present to user:

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?

User confirms: "Yes"
Detect that it's a TypeScript React component

Run

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

Result: Figma button component is now connected to the code Button component.

用户说："Connect this Figma button to my code: https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15"

操作步骤：

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

调用

get_code_connect_suggestions(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42:15")

响应显示：未映射的Button组件，包含
```
variant
```
（primary/secondary）和
```
size
```
（sm/md/lg）属性，以及缩略图
在代码库中搜索Button组件：找到
```
src/components/Button.tsx
```
读取
```
Button.tsx
```
，确认它包含
```
variant
```
和
```
size
```
属性

向用户展示：

我找到一个匹配项：
- [Button](src/components/Button.tsx): Button at nodeId [42:15](https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15)

是否要连接这个组件？

用户确认："Yes"
检测到这是TypeScript React组件

调用

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

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

Example 2: Multiple Components with Partial Selection

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

User says: "Connect components in this frame: https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Components?node-id=10-50"

Actions:

Parse URL: fileKey=
```
pR8mNv5KqXzGwY2JtCfL4D
```
, nodeId=
```
10-50
```
→ convert to
```
10:50
```

Run

get_code_connect_suggestions(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10:50")

Response shows 3 unmapped components: ProductCard, Badge, and CustomWidget
Search codebase:
- ProductCard: Found
```
src/components/ProductCard.tsx
```
  (props match)
- Badge: Found
```
src/components/Badge.tsx
```
  (props match)
- CustomWidget: No matching component found

Present to user:

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.

User: "Just connect ProductCard, skip Badge for now"

Run

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

Result: Only ProductCard is connected, per the user's selection.

用户说："Connect components in this frame: https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Components?node-id=10-50"

操作步骤：

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

调用

get_code_connect_suggestions(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10:50")

响应显示3个未映射组件：ProductCard、Badge和CustomWidget
扫描代码库：
- ProductCard：找到
```
src/components/ProductCard.tsx
```
  （属性匹配）
- Badge：找到
```
src/components/Badge.tsx
```
  （属性匹配）
- CustomWidget：未找到匹配组件

向用户展示：

以下组件与设计匹配：
- [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)

未找到CustomWidget (10:53)的匹配项。

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

用户："Just connect ProductCard, skip Badge for now"

调用

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

结果： 根据用户选择，仅ProductCard完成连接。

Example 3: Component Needs Creation

示例3：需要创建组件的情况

User says: "Connect this icon: https://figma.com/design/8yJDMeWDyBz71EnMOSuUiw/Icons?node-id=5-20"

Actions:

Parse URL: fileKey=
```
8yJDMeWDyBz71EnMOSuUiw
```
, nodeId=
```
5-20
```
→ convert to
```
5:20
```

Run

get_code_connect_suggestions(fileKey="8yJDMeWDyBz71EnMOSuUiw", nodeId="5:20")

Response shows: CheckIcon component (unmapped) with color and size properties
Search codebase for CheckIcon: No matches found
Search for generic Icon components: Find
```
src/icons/
```
directory with other icons
Report to user: "I couldn't find a CheckIcon component, but I found an icons directory at src/icons/. Would you like to:
- Create a new CheckIcon.tsx component first, then connect it
- Connect to a different existing icon
- Provide the path to the CheckIcon if it exists elsewhere"
User provides path: "src/icons/CheckIcon.tsx"
Detect language and framework from the file

Run

send_code_connect_mappings(fileKey="8yJDMeWDyBz71EnMOSuUiw", nodeId="5:20", mappings=[{ nodeId: "5:20", componentName: "CheckIcon", source: "src/icons/CheckIcon.tsx", label: "React" }])

Result: CheckIcon component is successfully connected to the Figma design.

用户说："Connect this icon: https://figma.com/design/8yJDMeWDyBz71EnMOSuUiw/Icons?node-id=5-20"

操作步骤：

解析URL：fileKey=
```
8yJDMeWDyBz71EnMOSuUiw
```
，nodeId=
```
5-20
```
→ 转换为
```
5:20
```

调用

get_code_connect_suggestions(fileKey="8yJDMeWDyBz71EnMOSuUiw", nodeId="5:20")

响应显示：未映射的CheckIcon组件，包含颜色和尺寸属性
在代码库中搜索CheckIcon：未找到匹配项
搜索通用Icon组件：找到
```
src/icons/
```
目录，其中包含其他图标
告知用户："I couldn't find a CheckIcon component, but I found an icons directory at src/icons/. Would you like to:
- Create a new CheckIcon.tsx component first, then connect it
- Connect to a different existing icon
- Provide the path to the CheckIcon if it exists elsewhere"
用户提供路径："src/icons/CheckIcon.tsx"
从文件中检测语言和框架

调用

send_code_connect_mappings(fileKey="8yJDMeWDyBz71EnMOSuUiw", nodeId="5:20", mappings=[{ nodeId: "5:20", componentName: "CheckIcon", source: "src/icons/CheckIcon.tsx", label: "React" }])

结果： CheckIcon组件成功与Figma设计建立连接。

Best Practices

最佳实践

Proactive Component Discovery

主动发现组件

Don't just ask the user for the file path — actively search their codebase to find matching components. This provides a better experience and catches potential mapping opportunities.

不要只询问用户文件路径——主动扫描代码库寻找匹配组件。这能提升用户体验，发现潜在的映射机会。

Accurate Structure Matching

准确匹配结构

When comparing Figma components to code components, look beyond just names. Check that:

Props align (variant types, size options, etc.)
Component hierarchy matches (nested elements)
The component serves the same purpose

对比Figma组件与代码组件时，不要只看名称。还要检查：

属性对应（变体类型、尺寸选项等）
组件层级匹配（嵌套元素）
组件用途一致

Clear Communication

清晰沟通

When offering to create a mapping, clearly explain:

What you found
Why it's a good match
What the mapping will do
How props will be connected

提供映射选项时，清晰说明：

你找到了什么
为什么这是合适的匹配
映射会实现什么效果
属性将如何连接

Handle Ambiguity

处理模糊情况

If multiple components could match, present options rather than guessing. Let the user make the final decision about which component to connect.

如果有多个组件可能匹配，提供选项而非猜测。让用户最终决定连接哪个组件。

Graceful Degradation

优雅降级

If you can't find an exact match, provide helpful next steps:

Show close candidates
Suggest component creation
Ask for user guidance

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

展示接近的候选组件
建议创建组件
寻求用户指导

Common Issues and Solutions

常见问题与解决方案

Issue: "No published components found in this selection"

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

Cause: The Figma component is not published to a team library. Code Connect only works with published components. Solution: The user needs to publish the component to a team library in Figma:

In Figma, select the component or component set
Right-click and choose "Publish to library" or use the Team Library publish modal
Publish the component
Once published, retry the Code Connect mapping with the same node ID

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

在Figma中，选择组件或组件集
右键点击，选择"Publish to library"或使用团队资源库发布弹窗
发布组件
发布完成后，使用相同的node ID重试Code Connect映射

Issue: "Code Connect is only available on Organization and Enterprise plans"

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

Cause: The user's Figma plan does not include Code Connect access. Solution: The user needs to upgrade to an Organization or Enterprise plan, or contact their administrator.

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

Issue: No matching component found in codebase

问题：代码库中未找到匹配组件

Cause: The codebase search did not find a component with a matching name or structure. Solution: Ask the user if the component exists under a different name or in a different location. They may need to create the component first, or it might be located in an unexpected directory.

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

Issue: "Published component not found" (CODE_CONNECT_ASSET_NOT_FOUND)

问题："Published component not found" (CODE_CONNECT_ASSET_NOT_FOUND)

Cause: The source file path is incorrect, the component doesn't exist at that location, or the componentName doesn't match the actual export. Solution: Verify the source path is correct and relative to the project root. Check that the component is properly exported from the file with the exact componentName specified.

原因： 源文件路径错误，组件不存在于该位置，或componentName与实际导出的名称不匹配。 解决方案： 验证源路径是否正确且相对于项目根目录。检查组件是否已从指定文件正确导出，且componentName与实际导出名称一致。

Issue: "Component is already mapped to code" (CODE_CONNECT_MAPPING_ALREADY_EXISTS)

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

Cause: A Code Connect mapping already exists for this component. Solution: The component is already connected. If the user wants to update the mapping, they may need to remove the existing one first in Figma.

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

Issue: "Insufficient permissions to create mapping" (CODE_CONNECT_INSUFFICIENT_PERMISSIONS)

问题："Insufficient permissions to create mapping" (CODE_CONNECT_INSUFFICIENT_PERMISSIONS)

Cause: The user does not have edit permissions on the Figma file or library. Solution: The user needs edit access to the file containing the component. Contact the file owner or team admin.

原因： 用户没有Figma文件或资源库的编辑权限。 解决方案： 用户需要获取文件的编辑权限，或联系文件所有者或团队管理员。

Issue: Code Connect mapping fails with URL errors

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

Cause: The Figma URL format is incorrect or missing the

node-id

parameter. Solution: Verify the URL follows the required format:

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

. The

node-id

parameter is required. Also ensure you convert

1-2

1:2

when calling tools.

原因： Figma URL格式不正确或缺少

node-id

参数。 解决方案： 验证URL符合要求格式：

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

。必须包含

node-id

参数。同时确保调用工具时将

1-2

转换为

1:2

。

Issue: Multiple similar components found

问题：找到多个相似组件

Cause: The codebase contains multiple components that could match the Figma component. Solution: Present all candidates to the user with their file paths and let them choose which one to connect. Different components might be used in different contexts (e.g.,

Button.tsx

LinkButton.tsx

原因： 代码库包含多个可能匹配Figma组件的组件。 解决方案： 向用户展示所有候选组件及其文件路径，让用户选择连接哪个组件。不同组件可能用于不同场景（例如

Button.tsx

LinkButton.tsx

）

Understanding Code Connect

理解Code Connect

Code Connect establishes a bidirectional link between design and code:

For designers: See which code component implements a Figma component For developers: Navigate from Figma designs directly to the code that implements them For teams: Maintain a single source of truth for component mappings

The mapping you create helps keep design and code in sync by making these connections explicit and discoverable.

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

对于设计师： 查看哪个代码组件实现了Figma组件 对于开发者： 从Figma设计直接导航到实现它的代码 对于团队： 维护组件映射的单一可信来源

你创建的映射通过明确这些连接并使其可被发现，帮助保持设计与代码的同步。

Additional Resources

额外资源

For more information about Code Connect:

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

figma-code-connect-components

Original

Translation

Code Connect Components

Code Connect 组件

Overview

概述

Skill Boundaries

技能边界

Prerequisites

前置条件

Required Workflow

必备工作流

Step 1: Get Code Connect Suggestions

步骤1：获取Code Connect建议

Option A: Using figma-desktop MCP (no URL provided)

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

Option B: When a Figma URL is provided

选项B：提供Figma URL时

Step 2: Scan Codebase for Matching Components

步骤2：扫描代码库以寻找匹配组件

Step 3: Present Matches to User

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

Step 4: Create Code Connect Mappings

步骤4：创建Code Connect映射

Examples

示例

Example 1: Connecting a Button Component

示例1：连接按钮组件

Example 2: Multiple Components with Partial Selection

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

Example 3: Component Needs Creation

示例3：需要创建组件的情况

Best Practices

最佳实践

Proactive Component Discovery

主动发现组件

Accurate Structure Matching

准确匹配结构

Clear Communication

清晰沟通

Handle Ambiguity

处理模糊情况

Graceful Degradation

优雅降级

Common Issues and Solutions

常见问题与解决方案

Issue: "No published components found in this selection"

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

Issue: "Code Connect is only available on Organization and Enterprise plans"

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

Issue: No matching component found in codebase

问题：代码库中未找到匹配组件

Issue: "Published component not found" (CODE_CONNECT_ASSET_NOT_FOUND)

问题："Published component not found" (CODE_CONNECT_ASSET_NOT_FOUND)

Issue: "Component is already mapped to code" (CODE_CONNECT_MAPPING_ALREADY_EXISTS)

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

Issue: "Insufficient permissions to create mapping" (CODE_CONNECT_INSUFFICIENT_PERMISSIONS)

问题："Insufficient permissions to create mapping" (CODE_CONNECT_INSUFFICIENT_PERMISSIONS)

Issue: Code Connect mapping fails with URL errors

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

Issue: Multiple similar components found

问题：找到多个相似组件

Understanding Code Connect

理解Code Connect

Additional Resources

额外资源

Option A: Using
`figma-desktop`
MCP (no URL provided)

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