用途
figma-code-connect 用于创建 Code Connect 模板文件（.figma.ts），把 Figma 组件映射到代码片段。当用户提到 Code Connect、Figma 组件映射等需求时可使用。本技能只编写 .figma.ts 模板文件，不编写 .figma.tsx。
前置条件
- Figma MCP 服务器必须已连接：在开始前确认 Figma MCP 工具（例如 get_code_connect_suggestions）可用。若不可用，引导用户启用 Figma MCP 服务器并重启其 MCP 客户端。
- 组件必须已发布：Code Connect 仅适用于已发布到 Figma 团队库的组件。若组件未发布，告知用户并停止。
- 需要组织版或企业版套餐：Free 或 Professional 套餐不可用 Code Connect。
- URL 必须包含 node-id：Figma URL 必须包含 node-id 查询参数。
- TypeScript 类型：为在 .figma.ts 文件中获得编辑器自动补全与类型检查，需要把 @figma/code-connect/figma-types 加入 tsconfig.json 的 types：
{
"compilerOptions": {
"types": ["@figma/code-connect/figma-types"]
}
}
重要格式说明
只编写 .figma.ts 模板文件——绝不编写 .figma.tsx。本技能产出的是无解析器模板：一个 .figma.ts 文件，其默认导出使用 figma.code... 标签模板。不要编写 .figma.tsx 文件，也不要用 figma.connect()——那是另一套独立的、基于解析器的 Code Connect 格式（以不同方式发布），对本技能而言是错误的产物；写成 .figma.tsx 的输出会被直接拒绝。如果某组件已存在 .figma.tsx，保持其不变，并在其旁边添加你的 .figma.ts 模板。
步骤 1：解析 Figma URL
从 URL 中提取 fileKey 和 nodeId：
| URL 格式 | fileKey | nodeId |
|---|---|---|
| figma.com/design/:fileKey/:name?node-id=X-Y | :fileKey | X-Y → X:Y |
| figma.com/file/:fileKey/:name?node-id=X-Y | :fileKey | X-Y → X:Y |
| figma.com/design/:fileKey/branch/:branchKey/:name | 用 :branchKey | 取自 node-id 参数 |
始终把 nodeId 中的连字符改为冒号：1234-5678 → 1234:5678。
步骤 2：发现未映射组件
调用 MCP 工具 get_code_connect_suggestions，传入 fileKey、nodeId（冒号格式）以及 excludeMappingPrompt: true。该工具会识别选区中尚无 Code Connect 映射的已发布组件。对返回值中的每个组件提取 mainComponentNodeId，后续步骤使用这些解析后的节点 ID（而非 URL 中的原始值）。若返回多个组件，对每个组件重复步骤 3–6。
步骤 3：获取组件属性
调用 MCP 工具 get_context_for_code_connect，传入 fileKey、步骤 2 解析出的 mainComponentNodeId、clientFrameworks（依据 figma.config.json 的 parser 字段）与 clientLanguages（依据项目文件扩展名推断）。响应包含 Figma 组件的属性定义，属性类型包括：TEXT、BOOLEAN、VARIANT、INSTANCE_SWAP、SLOT。
步骤 4：确定代码组件
若用户未指定要连接的代码组件：查看 figma.config.json 的 paths 与 importPaths；在代码库中搜索与 Figma 组件同名的组件；读取候选文件并把其 props 接口与步骤 3 的 Figma 属性比对；若多个匹配，选择 props 接口最接近的一个；若无匹配，展示最接近的两个候选并请用户确认。在进入步骤 5 前与用户确认。
步骤 5：创建模板文件（.figma.ts）
文件命名为 ComponentName.figma.ts——绝不用 .figma.tsx。模板结构如下：
// url=https://www.figma.com/file/{fileKey}/{fileName}?node-id={nodeId}
// source={path to code component from Step 4}
// component={code component name from Step 4}
import figma from 'figma'
const instance = figma.selectedInstance
export default {
example: figma.code`<Component ... />`, // 必填：代码片段
imports: ['import { Component } from "..."'], // 可选：import 语句
id: 'component-name', // 必填：唯一标识
metadata: { // 可选
nestable: true,
props: {}
}
}
属性映射：
| Figma 属性类型 | 模板方法 | 使用场景 |
|---|---|---|
| TEXT | instance.getString('Name') | 标签、标题、占位文本 |
| BOOLEAN | instance.getBoolean('Name', { true: ..., false: ... }) | 切换可见性、条件属性 |
| VARIANT | instance.getEnum('Name', { 'FigmaVal': 'codeVal' }) | 尺寸、变体、状态枚举 |
| INSTANCE_SWAP | instance.getInstanceSwap('Name') | 固定组件槽位的可替换实例 |
| SLOT | instance.getSlot('Name') | 无固定内容的槽位区域 |
| （子图层） | instance.findInstance('LayerName') | 无属性对应的命名子实例 |
| （文本图层） | instance.findText('LayerName') → .textContent | 命名文本图层的文本内容 |
VARIANT 映射必须列全 get_context_for_code_connect 返回的所有取值，遗漏会使输出为 undefined。当多个 VARIANT 组合产生不同代码输出时，需生成穷尽的条件分支。
限定 getSlot 仅用于 SLOT 类型属性，INSTANCE_SWAP 用 getInstanceSwap()。
插值包装规则：字符串值（getString、getEnum、textContent）用引号包裹；实例/片段值（executeTemplate().example）用花括号包裹；槽位片段（getSlot 结果）直接插入 figma.code...；布尔裸属性用条件表达式。
嵌套可配置实例：若子实例未作为组件属性暴露但仍可独立配置，需动态解析而非硬编码，可用 findInstance() 或 findConnectedInstance() 并调用 executeTemplate()。
步骤 6：校验
读回 .figma.ts 文件并检查：文件类型与格式是否正确（ComponentName.figma.ts，非 .figma.tsx，且未使用 figma.connect()）；步骤 3 中每个 Figma 属性是否都被处理；输出的代码是否合法且类型正确；是否存在硬编码子内容；插值包装是否正确。若仍有不确定之处，可查阅 api.md。
适用场景
把 Figma 设计系统中的已发布组件与前端代码库中的组件建立对应关系，使设计稿的组件能在代码侧显示对应的代码片段，便于设计与开发协作。
限制
需要已连接 Figma MCP 服务器；组件必须已发布到团队库；需组织版或企业版套餐；URL 必须含 node-id；仅产出 .figma.ts 无解析器模板，不产出 .figma.tsx 或使用 figma.connect()。