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设计结构，在你的代码库中搜索匹配的组件，并建立映射关系，以维持设计与代码的一致性。

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.
Access to the project codebase for component scanning

必须已连接并可访问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仅适用于已发布的组件或组件集。
有权访问项目代码库以进行组件扫描

Required Workflow

必要工作流程

Follow these steps in order. Do not skip steps.

请按顺序执行以下步骤，请勿跳过。

Step 1: Get Node ID and Extract Metadata

步骤1：获取节点ID并提取元数据

Option A: Parse from Figma URL

选项A：从Figma URL解析

When the user provides a Figma URL with file key and node ID, first run

get_metadata

to fetch the node structure and identify all Figma components.

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

Note: When using the local desktop MCP (

figma-desktop

fileKey

is not passed as a parameter to tool calls. The server automatically uses the currently open file, so only

nodeId

is needed.

Example:

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

当用户提供包含文件密钥和节点ID的Figma URL时，首先运行

get_metadata

来获取节点结构并识别所有Figma组件。

重要提示：从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/
```
后的分段）
提取节点ID：从URL中获取
```
1-2
```
，然后转换为
```
1:2
```
供工具使用

注意：使用本地桌面MCP（

figma-desktop

）时，工具调用无需传递

fileKey

参数。服务器会自动使用当前打开的文件，因此仅需

nodeId

。

示例：

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

Option B: Use Current Selection from Figma Desktop App (figma-desktop MCP only)

选项B：使用Figma桌面应用的当前选择（仅适用于figma-desktop MCP）

When using the

figma-desktop

MCP and the user has NOT provided a URL, the tools automatically use the currently selected node from the open Figma file in the desktop app.

Note: Selection-based prompting only works with the

figma-desktop

MCP server. The remote server requires a link to a frame or layer to extract context. The user must have the Figma desktop app open with a node selected.

This returns:

Node structure and hierarchy in XML format
Node types (identify
```
<symbol>
```
nodes as Figma components)
Node IDs, layer names, positions, and sizes
Child nodes that may also be components

Identify components: For each node or child node returned, if the type is

<symbol>

, that indicates it's a Figma component that can be code connected.

当使用

figma-desktop

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

注意：基于选择的提示仅适用于

figma-desktop

MCP服务器。远程服务器需要框架或图层的链接来提取上下文。用户必须在Figma桌面应用中打开文件并选中节点。

此操作将返回：

XML格式的节点结构和层级
节点类型（将
```
<symbol>
```
节点识别为Figma组件）
节点ID、图层名称、位置和尺寸
可能也是组件的子节点

识别组件：对于返回的每个节点或子节点，如果类型为

<symbol>

，则表示这是可通过Code Connect关联的Figma组件。

Step 2: Check Existing Code Connect Mappings

步骤2：检查现有Code Connect映射

For each Figma component identified (nodes with type

<symbol>

), check if it's already code connected using

get_code_connect_map

Example:

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

If the component is already connected:

Skip to the next component
Inform the user that this component is already mapped

If not connected:

Proceed to Step 3 to analyze the component and create a mapping

对于每个识别出的Figma组件（类型为

<symbol>

的节点），使用

get_code_connect_map

检查它是否已关联到代码。

示例：

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

如果组件已关联：

跳至下一个组件
告知用户此组件已完成映射

如果未关联：

继续执行步骤3，分析组件并创建映射

Step 3: Get Design Context for Un-Connected Components

步骤3：获取未关联组件的设计上下文

For components that are not yet code connected, run

get_design_context

to fetch detailed component structure.

Example:

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

This returns:

Component structure and hierarchy
Layout properties and styling
Text content and variants
Design properties that map to code props

对于尚未关联的组件，运行

get_design_context

以获取详细的组件结构。

示例：

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

此操作将返回：

组件结构和层级
布局属性和样式
文本内容和变体
可映射到代码属性的设计属性

Step 4: Scan Codebase for Matching Component

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

Using the output from

get_design_context

, scan the codebase to find a component with similar structure.

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 Figma design properties
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_design_context

的输出，扫描代码库以找到结构相似的组件。

查找要点：

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

搜索策略：

搜索名称匹配的组件文件
读取候选文件以检查结构和属性
比较代码组件的属性与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 5: Offer Code Connect Mapping

步骤5：提供Code Connect映射选项

Present your findings to the user and offer to create the Code Connect mapping.

What to communicate:

Which code component you found that matches the Figma component
File path of the component
Component name
Language and framework detected

Example message:

I found a matching component in your codebase:
- File: src/components/Button.tsx
- Component: Button
- Language: TypeScript/JavaScript
- Framework: React

Would you like me to create a Code Connect mapping for this component?

If no exact match is found:

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

向用户展示你的发现，并提供创建Code Connect映射的选项。

需传达的信息：

找到的与Figma组件匹配的代码组件
组件的文件路径
组件名称
检测到的语言和框架

示例消息：

我在你的代码库中找到了匹配的组件：
- 文件：src/components/Button.tsx
- 组件：Button
- 语言：TypeScript/JavaScript
- 框架：React

是否需要我为此组件创建Code Connect映射？

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

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

Step 6: Create the Code Connect Mapping

步骤6：创建Code Connect映射

If the user accepts, run

add_code_connect_map

to establish the connection.

Tool parameters:

add_code_connect_map(
  nodeId="1:2",
  source="src/components/Button.tsx",
  componentName="Button",
  clientLanguages="typescript,javascript",
  clientFrameworks="react"
)

Key parameters:

```
nodeId
```
: The Figma node ID (with colon format:
```
1:2
```
)
```
source
```
: Path to the code component file (relative to project root)
```
componentName
```
: Name of the component to connect (e.g., "Button", "Card")
```
clientLanguages
```
: Comma-separated list of languages (e.g., "typescript,javascript", "javascript")
```
clientFrameworks
```
: Framework being used (e.g., "react", "vue", "svelte", "angular")
```
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'

如果用户确认，运行

add_code_connect_map

来建立关联。

工具参数：

add_code_connect_map(
  nodeId="1:2",
  source="src/components/Button.tsx",
  componentName="Button",
  clientLanguages="typescript,javascript",
  clientFrameworks="react"
)

关键参数：

```
nodeId
```
：Figma节点ID（冒号格式：
```
1:2
```
）
```
source
```
：代码组件文件的路径（相对于项目根目录）
```
componentName
```
：要关联的组件名称（例如「Button」、「Card」）
```
clientLanguages
```
：逗号分隔的语言列表（例如「typescript,javascript」、「javascript」）
```
clientFrameworks
```
：使用的框架（例如「react」、「vue」、「svelte」、「angular」）
```
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'

Step 7: Repeat for All Un-Connected Components

步骤7：为所有未关联组件重复操作

After successfully connecting one component, return to Step 2 and repeat the process for all other un-connected Figma components identified in the node tree from Step 1.

Workflow for multiple components:

From the metadata obtained in Step 1, identify all nodes with type
```
<symbol>
```
For each component node:
- Check if already code connected (Step 2)
- If not connected, proceed with Steps 3-6
- Track which components have been processed
After processing all components, provide a summary:
- Total components found
- Components successfully connected
- Components skipped (already connected)
- Components that could not be connected (with reasons)

Example summary:

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

成功关联一个组件后，返回步骤2，对步骤1中节点树里识别出的所有其他未关联Figma组件重复此流程。

多组件工作流程：

从步骤1获取的元数据中，识别所有类型为
```
<symbol>
```
的节点
对于每个组件节点：
- 检查是否已关联到代码（步骤2）
- 如果未关联，执行步骤3-6
- 跟踪已处理的组件
处理完所有组件后，提供总结：
- 找到的组件总数
- 成功关联的组件
- 跳过的组件（已关联）
- 无法关联的组件（含原因）

示例总结：

Code Connect总结：
- 找到的组件总数：5
- 成功关联：3
  - Button (1:2) → src/components/Button.tsx
  - Card (1:5) → src/components/Card.tsx
  - Input (1:8) → src/components/Input.tsx
- 已关联：1
  - Icon (1:3) → src/icons/Icon.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
```
(from URL)
Convert node ID:
```
42-15
```
→
```
42:15
```

Run

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

to get node structure

Metadata shows: Node type is
```
<symbol>
```
(Figma component), name is "Button"

Run

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

to check existing mappings

Result: No existing mapping found

Run

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

to get detailed structure

Design context shows: Button component with
```
variant
```
(primary/secondary) and
```
size
```
(sm/md/lg) properties
Search codebase for Button components: Find
```
src/components/Button.tsx
```
Read
```
Button.tsx
```
and confirm it has
```
variant
```
and
```
size
```
props
Offer mapping: "I found Button.tsx with matching variant and size props. Connect?"
User confirms: "Yes"
Detect that it's a TypeScript React component

Run

add_code_connect_map(nodeId="42:15", source="src/components/Button.tsx", componentName="Button", clientLanguages="typescript,javascript", clientFrameworks="react")

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

用户说：「将这个Figma按钮关联到我的代码：https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15」

操作：

解析URL：fileKey=
```
kL9xQn2VwM8pYrTb4ZcHjF
```
，nodeId=
```
42-15
```
（来自URL）
转换节点ID：
```
42-15
```
→
```
42:15
```

运行

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

获取节点结构

元数据显示：节点类型为
```
<symbol>
```
（Figma组件），名称为「Button」

运行

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

检查现有映射

结果：未找到现有映射

运行

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

获取详细结构

设计上下文显示：Button组件具有
```
variant
```
（primary/secondary）和
```
size
```
（sm/md/lg）属性
在代码库中搜索Button组件：找到
```
src/components/Button.tsx
```
读取
```
Button.tsx
```
并确认它具有
```
variant
```
和
```
size
```
属性
提供映射选项：「我找到了带有匹配variant和size属性的Button.tsx。是否关联？」
用户确认：「是」
检测到这是TypeScript React组件

运行

add_code_connect_map(nodeId="42:15", source="src/components/Button.tsx", componentName="Button", clientLanguages="typescript,javascript", clientFrameworks="react")

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

Example 2: Multiple Candidates Scenario

示例2：多候选组件场景

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

Actions:

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

Run

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

to get node structure

Metadata shows: Node type is
```
<symbol>
```
(Figma component), name is "ProductCard"

Run

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

to check existing mappings

Result: No existing mapping found

Run

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

Design context shows: Card with title, description, image, and action button
Search codebase: Find two candidates:
- ```
src/components/Card.tsx
```
  (basic card)
- ```
src/components/ProductCard.tsx
```
  (card with image and CTA)
Read both files and compare structure
Present to user: "Found two card components:

Card.tsx: Basic card with title and description
ProductCard.tsx: Card with image, title, description, and action button (closer match)

Which should I connect?"

User: "ProductCard.tsx"
Detect that it's a TypeScript React component

Run

add_code_connect_map(nodeId="10:50", source="src/components/ProductCard.tsx", componentName="ProductCard", clientLanguages="typescript,javascript", clientFrameworks="react")

Result: User-selected ProductCard component is successfully connected to the Figma design.

用户说：「关联这个卡片：https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Components?node-id=10-50」

操作：

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

运行

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

获取节点结构

元数据显示：节点类型为
```
<symbol>
```
（Figma组件），名称为「ProductCard」

运行

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

检查现有映射

结果：未找到现有映射

运行

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

设计上下文显示：包含标题、描述、图片和操作按钮的卡片
搜索代码库：找到两个候选组件：
- ```
src/components/Card.tsx
```
  （基础卡片）
- ```
src/components/ProductCard.tsx
```
  （含图片和CTA的卡片）
读取两个文件并比较结构
向用户展示：「找到两个卡片组件：

Card.tsx：包含标题和描述的基础卡片
ProductCard.tsx：包含图片、标题、描述和操作按钮的卡片（更匹配）

我应该关联哪一个？」

用户：「ProductCard.tsx」
检测到这是TypeScript React组件

运行

add_code_connect_map(nodeId="10:50", source="src/components/ProductCard.tsx", componentName="ProductCard", clientLanguages="typescript,javascript", clientFrameworks="react")

结果： 用户选择的ProductCard组件成功关联到Figma设计。

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_metadata(fileKey="8yJDMeWDyBz71EnMOSuUiw", nodeId="5:20")

to get node structure

Metadata shows: Node type is
```
<symbol>
```
(Figma component), name is "CheckIcon"

Run

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

to check existing mappings

Result: No existing mapping found

Run

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

Design context shows: CheckIcon with color and size variants
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

add_code_connect_map(nodeId="5:20", source="src/icons/CheckIcon.tsx", componentName="CheckIcon", clientLanguages="typescript,javascript", clientFrameworks="react")

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

用户说：「关联这个图标：https://figma.com/design/8yJDMeWDyBz71EnMOSuUiw/Icons?node-id=5-20」

操作：

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

运行

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

获取节点结构

元数据显示：节点类型为
```
<symbol>
```
（Figma组件），名称为「CheckIcon」

运行

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

检查现有映射

结果：未找到现有映射

运行

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

设计上下文显示：具有颜色和尺寸变体的CheckIcon
在代码库中搜索CheckIcon：未找到匹配项
搜索通用Icon组件：找到
```
src/icons/
```
目录，其中包含其他图标
向用户报告：「我未找到CheckIcon组件，但找到了图标目录src/icons/。你希望：

先创建新的CheckIcon.tsx组件，再关联
关联到其他现有图标
如果CheckIcon存在于其他位置，请提供路径」

用户提供路径：「src/icons/CheckIcon.tsx」
从文件中检测语言和框架

运行

add_code_connect_map(nodeId="5:20", source="src/icons/CheckIcon.tsx", componentName="CheckIcon", clientLanguages="typescript,javascript", clientFrameworks="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: "Failed to map node to Code Connect. Please ensure the component or component set is published to the team library"

问题：「无法将节点映射到Code Connect。请确保组件或组件集已发布到团队库」

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中选择组件或组件集
右键点击并选择「发布到库」，或使用团队库发布弹窗
发布组件
发布完成后，使用相同的节点ID重试Code Connect映射

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: Code Connect map creation fails with "component not found"

问题：Code Connect映射创建失败，提示「组件未找到」

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: Wrong language or framework detected

问题：检测到错误的语言或框架

Cause: The clientLanguages or clientFrameworks parameters don't match the actual component implementation. Solution: Inspect the component file to verify the language (TypeScript, JavaScript) and framework (React, Vue, etc.). Update the parameters accordingly. For TypeScript React components, use

clientLanguages="typescript,javascript"

and

clientFrameworks="react"

原因：clientLanguages或clientFrameworks参数与组件的实际实现不匹配。 解决方案：检查组件文件以验证语言（TypeScript、JavaScript）和框架（React、Vue等）。相应更新参数。对于TypeScript React组件，使用

clientLanguages="typescript,javascript"

和

clientFrameworks="react"

。

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的信息：