figma

Figma 技能

通过 mcporter 使用 figma-desktop MCP 服务，掌握 Figma 自动化与集成。此技能支持以编程方式访问 Figma 设计、生成代码、截取屏幕截图和映射 Code Connect。

[!CRITICAL] ⚠️ 重要 - 参数传递：

使用函数调用语法（不要使用标志语法）。参数放在函数调用中，而不是作为标志：

mise x node@20 -- mcporter call 'figma-desktop.get_design_context(nodeId: "123:456", clientLanguages: "typescript", clientFrameworks: "react")'

关键规则：

• 函数调用中的参数使用 camelCase
• 字符串值使用双引号："value"
• 布尔值使用裸写法：true 或 false
• 环境变量在引号外插值："'$VAR'"
• 不使用 --flag 语法，也无需转义 JSON 字符串

前置条件

验证 Figma Desktop 连接

mise x node@20 -- mcporter call 'figma-desktop.get_metadata'

应返回当前选中节点的元数据。如果失败，请确保：

1. Figma Desktop 正在运行
2. 已在 mcporter 中配置 figma-desktop MCP 服务

快速设置

获取设计上下文（一次完成）

获取设计信息和生成代码的最快方式：

mise x node@20 -- ./scripts/get_design_context.sh "123:456"

也可以使用当前选中的节点：

mise x node@20 -- ./scripts/get_design_context.sh

指定框架上下文：

mise x node@20 -- ./scripts/get_design_context.sh "123:456" --languages "typescript" --frameworks "react"

从 URL 提取节点 ID

如果 Figma URL 类似于 https://figma.com/design/:fileKey/:fileName?node-id=1-2：

• nodeId 为 1:2（将 - 替换为 :）

对于分支 URL，例如 https://figma.com/design/:fileKey/branch/:branchKey/:fileName：

• 将 branchKey 用作 fileKey

核心操作

获取设计上下文（生成代码）

用于根据 Figma 设计生成 UI 代码的主要工具：

mise x node@20 -- mcporter call 'figma-desktop.get_design_context(nodeId: "123:456")'

指定技术上下文（推荐）：

mise x node@20 -- mcporter call 'figma-desktop.get_design_context(nodeId: "123:456", clientLanguages: "typescript,css", clientFrameworks: "react")'

使用当前选中的节点：

mise x node@20 -- mcporter call 'figma-desktop.get_design_context()'

强制输出代码（适用于大型设计）：

mise x node@20 -- mcporter call 'figma-desktop.get_design_context(nodeId: "123:456", forceCode: true)'

指定产物类型上下文：

mise x node@20 -- mcporter call 'figma-desktop.get_design_context(nodeId: "123:456", artifactType: "REUSABLE_COMPONENT", taskType: "CREATE_ARTIFACT")'

有效的 artifactType 值：

• WEB_PAGE_OR_APP_SCREEN
• COMPONENT_WITHIN_A_WEB_PAGE_OR_APP_SCREEN
• REUSABLE_COMPONENT
• DESIGN_SYSTEM

有效的 taskType 值：

• CREATE_ARTIFACT
• CHANGE_ARTIFACT
• DELETE_ARTIFACT

获取屏幕截图

截取 Figma 节点的视觉屏幕截图：

mise x node@20 -- mcporter call 'figma-desktop.get_screenshot(nodeId: "123:456")'

使用当前选中的节点：

mise x node@20 -- mcporter call 'figma-desktop.get_screenshot()'

获取元数据（结构概览）

获取节点的 XML 结构概览（节点 ID、图层类型、名称、位置和尺寸）：

mise x node@20 -- mcporter call 'figma-desktop.get_metadata(nodeId: "123:456")'

注意： 大多数情况下优先使用 get_design_context。仅在需要结构概览时使用 get_metadata。

获取变量定义

获取节点的设计令牌/变量（颜色、字体、尺寸、间距）：

mise x node@20 -- mcporter call 'figma-desktop.get_variable_defs(nodeId: "123:456")'

返回类似以下映射：{'icon/default/secondary': '#949494'}

获取 FigJam 内容

用于 FigJam 文件（白板、图表）：

mise x node@20 -- mcporter call 'figma-desktop.get_figjam(nodeId: "123:456")'

包含节点图像：

mise x node@20 -- mcporter call 'figma-desktop.get_figjam(nodeId: "123:456", includeImagesOfNodes: true)'

注意： 仅适用于 FigJam 文件，不适用于标准 Figma 设计文件。

Code Connect

Code Connect 将 Figma 组件映射到代码库中的代码组件。

获取 Code Connect 映射

检查节点现有的映射：

mise x node@20 -- mcporter call 'figma-desktop.get_code_connect_map(nodeId: "123:456")'

返回类似以下映射：

{
  "1:2": {
    "codeConnectSrc": "https://github.com/foo/components/Button.tsx",
    "codeConnectName": "Button"
  }
}

添加 Code Connect 映射

将 Figma 组件映射到代码组件：

mise x node@20 -- mcporter call 'figma-desktop.add_code_connect_map(nodeId: "123:456", source: "src/components/Button.tsx", componentName: "Button", label: "React")'

必需参数：

• source：代码库中组件的路径
• componentName：组件名称
• label：框架/语言标签

有效的 label 值：

• React、Web Components、Vue、Svelte、Storybook、Javascript
• Swift UIKit、Objective-C UIKit、SwiftUI
• Compose、Java、Kotlin、Android XML Layout
• Flutter、Markdown

创建设计系统规则

为你的代码库生成设计系统规则：

mise x node@20 -- mcporter call 'figma-desktop.create_design_system_rules(clientLanguages: "typescript", clientFrameworks: "react")'

辅助脚本

脚本	用途
./scripts/get_design_context.sh	一次性获取设计上下文 - 获取设计信息和生成的代码（可选框架上下文）
./scripts/get_screenshot.sh	截取屏幕截图 - 将节点截图保存到文件
./scripts/get_variables.sh	获取设计令牌 - 提取变量（颜色、字体、尺寸、间距）
./scripts/add_code_connect.sh	添加 Code Connect - 将 Figma 组件映射到代码组件

脚本帮助：

./scripts/get_design_context.sh --help
./scripts/get_screenshot.sh --help
./scripts/get_variables.sh --help
./scripts/add_code_connect.sh --help

常见工作流

1. 实现设计组件

# Get the node ID from Figma URL (node-id=1-2 → nodeId="1:2")
NODE_ID="1:2"

# Get design context with your tech stack
mise x node@20 -- mcporter call 'figma-desktop.get_design_context(nodeId: "'$NODE_ID'", clientLanguages: "typescript,css", clientFrameworks: "react")'

# Get variables/tokens for the component
mise x node@20 -- mcporter call 'figma-desktop.get_variable_defs(nodeId: "'$NODE_ID'")'

2. 在代码中记录组件

# Check existing mappings
mise x node@20 -- mcporter call 'figma-desktop.get_code_connect_map(nodeId: "123:456")'

# Add mapping
mise x node@20 -- mcporter call 'figma-desktop.add_code_connect_map(nodeId: "123:456", source: "src/components/Button/Button.tsx", componentName: "Button", label: "React")'

3. 提取设计系统令牌

# Get all variables for a design system frame
mise x node@20 -- mcporter call 'figma-desktop.get_variable_defs(nodeId: "0:1")'

# Generate design system rules
mise x node@20 -- mcporter call 'figma-desktop.create_design_system_rules(clientLanguages: "typescript,css", clientFrameworks: "react")'

4. 为文档截取屏幕截图

# Get screenshot of a component
mise x node@20 -- mcporter call 'figma-desktop.get_screenshot(nodeId: "123:456")' > component.png

常见问题与解决方案

问题	解决方案
连接被拒绝	确保 Figma Desktop 正在运行，并且已配置 figma-desktop MCP 服务
未找到节点	确认 nodeId 格式为 123:456（使用冒号分隔）。检查文件中是否存在该节点。
大型设计没有输出	使用 forceCode: true 参数强制生成代码
代码语言错误	指定 clientLanguages 和 clientFrameworks 参数
“参数无效”或命令失败	使用函数调用语法，而非标志语法。参数应放在 functionName(param: value) 中
FigJam 工具无法使用	get_figjam 仅适用于 FigJam 文件，不适用于常规 Figma 设计文件
Code Connect 未显示	确保节点是组件实例，而非普通画板

通过架构内省发现函数参数

mcporter CLI 可以对 MCP 服务架构进行内省，以发现正确的参数及其类型。

列出所有可用工具

mise x node@20 -- mcporter list figma-desktop --json | jq -r ".tools[].name"

返回：

get_design_context
get_variable_defs
get_screenshot
get_code_connect_map
add_code_connect_map
get_metadata
create_design_system_rules
get_figjam

检查特定工具的架构

mise x node@20 -- mcporter list figma-desktop --json | jq '.tools[] | select(.name == "get_design_context")'

这会返回完整的 JSON 架构，其中包括：

• inputSchema.properties - 所有可用参数及其类型和说明
• inputSchema.required - 必填参数

仅筛选必填参数：

mise x node@20 -- mcporter list figma-desktop --json | \
  jq '.tools[] | select(.name == "add_code_connect_map") | .inputSchema.required[]'

获取参数说明：

mise x node@20 -- mcporter list figma-desktop --json | \
  jq '.tools[] | select(.name == "get_design_context") | .inputSchema.properties | to_entries[] | "\(.key): \(.value.description)"'

提示

• 从 URL 获取节点 ID： URL 中的 node-id=1-2 会转换为 nodeId: "1:2"（将 - 替换为 :）
• 分支 URL： 对于分支 URL，请将 branchKey 用作 fileKey
• 当前选中的节点： 省略 nodeId，即可使用 Figma Desktop 中当前选中的节点
• 技术上下文： 始终指定 clientLanguages 和 clientFrameworks，以获得更好的代码生成效果
• 大型设计： 如果输出被截断，请使用 forceCode: true
• 在 shell 脚本中使用 jq 解析 JSON
• 不确定参数时使用架构内省 - mcporter list figma-desktop --json | jq 是你的好帮手

可用工具参考

工具	用途	必需参数
get_design_context	根据设计生成 UI 代码	无（使用当前选择）
get_screenshot	截取视觉屏幕截图	无（使用当前选择）
get_metadata	获取 XML 结构概览	无（使用当前选择）
get_variable_defs	获取设计令牌/变量	无（使用当前选择）
get_code_connect_map	获取现有代码映射	无（使用当前选择）
add_code_connect_map	将设计映射到代码组件	source、componentName、label
create_design_system_rules	生成设计系统规则	无
get_figjam	获取 FigJam 内容	无（使用当前选择）