figma-use

⚠️ Figma 126+ 已阻止远程调试。 不过，figma-use 仍然可以通过 figma-use daemon start --pipe 命令使用。或者，您也可以完全跳过 Figma，改用 OpenPencil —— 一款开源的设计编辑器，支持读写 .fig 文件，并内置 AI 和 P2P 协作功能。

用于 Figma 的命令行工具。通过终端、命令或 JSX 来控制 Figma。

# 创建并设置样式
figma-use create frame --width 400 --height 300 --fill "#FFF" --layout VERTICAL --gap 16
figma-use create icon mdi:home --size 32 --color "#3B82F6"
figma-use set layout 1:23 --mode GRID --cols "1fr 1fr 1fr" --gap 16

# 或者渲染 JSX
echo '<Frame style={{display: "grid", cols: "1fr 1fr", gap: 16}}>
  <Frame style={{bg: "#3B82F6", h: 100}} />
  <Frame style={{bg: "#10B981", h: 100}} />
</Frame>' | figma-use render --stdin --x 100 --y 100

为什么

Figma 官方的 MCP 插件可以读取文件，但无法修改它们。而这个工具则可以做到。

大模型熟悉命令行，也熟悉 React。这款工具将两者结合了起来。

命令行指令简洁紧凑——易于阅读、生成和串联。当任务涉及数十个操作时，每一个节省下来的字符都至关重要。

JSX 是大模型思考 UI 的方式。它们已经见过数以百万计的 React 组件。用 <Frame><Text> 来描述 Figma 布局对它们来说再自然不过——无需特殊训练，也不需要冗长的模式定义。

演示

▶️ 按钮组件

▶️ Tailwind UI 日历

安装

npm install -g figma-use

或者直接运行而不需安装：

npx figma-use status

启动 Figma 并启用远程调试：

# macOS
open -a Figma --args --remote-debugging-port=9222

# Windows
"%LOCALAPPDATA%\Figma\Figma.exe" --remote-debugging-port=9222

# Linux
figma --remote-debugging-port=9222

检查连接：

figma-use status

仅此而已，无需安装任何插件。

两种模式

命令式——一次执行一条命令：

figma-use create frame --width 400 --height 300 --fill "#FFF" --radius 12 --layout VERTICAL --gap 16

或者声明式——用 JSX 描述结构并渲染：

echo '<Frame style={{p: 24, gap: 16, flex: "col", bg: "#FFF", rounded: 12}}>
  <Text style={{size: 24, weight: "bold", color: "#000"}}>卡片标题</Text>
  <Text style={{size: 14, color: "#666"}}>描述</Text>
</Frame>' | figma-use render --stdin --x 100 --y 200

标准输入模式只接受纯 JSX——没有变量，也没有逻辑。对于组件、变体和条件判断，请使用 .figma.tsx 文件。

元素： Frame、Rectangle、Ellipse、Text、Line、Star、Polygon、Vector、Group、Icon、Image

示例

图标

只需通过名称即可插入 Iconify 中的任意图标。无需下载、导入或清理。

figma-use create icon mdi:home
figma-use create icon lucide:star --size 48 --color "#F59E0B"

在 JSX 中：

<Frame style={{ flex: 'row', gap: 8 }}>
  <Icon icon="mdi:home" size={24} color="#3B82F6" />
  <Icon icon="lucide:star" size={32} color="#F59E0B" />
</Frame>

浏览超过 15 万个图标：icon-sets.iconify.design

图片

从 URL 加载图片：

<Image src="https://example.com/photo.jpg" w={200} h={150} />

导出为 JSX

将任意 Figma 节点转换回 JSX：

figma-use export jsx 123:456 --pretty

输出：

import { Frame, Icon, Text } from 'figma-use/render'
export default function SaveButton() {
  return (
    <Frame name="SaveButton" w={120} h={44} bg="#1FAFBB" rounded={8} flex="row" gap={8}>
      <Icon name="lucide:save" size={18} color="#FFFFFF" />
      <Text size={16} color="#FFFFFF">
        保存
      </Text>
    </Frame>
  )
}

自动将矢量形状匹配到 Iconify 图标：

npm install whaticon  # 可选依赖
figma-use export jsx 123:456 --match-icons --prefer-icons lucide

比较两个节点的 JSX 差异：

figma-use diff jsx 123:456 789:012

导出为 Storybook（实验性）

将组件导出为 Storybook 故事：

figma-use export storybook --out ./stories
figma-use export storybook --out ./stories --match-icons --prefer-icons lucide

会生成带有类型化 props 的 .stories.tsx 文件，这些 props 直接来自组件属性。

组件

您可以在 .figma.tsx 文件中定义组件。第一次调用会创建主组件，其余调用则创建实例：

import { defineComponent, Frame, Text } from 'figma-use/render'

const Card = defineComponent(
  'Card',
  <Frame style={{ p: 24, bg: '#FFF', rounded: 12 }}>
    <Text style={{ size: 18, color: '#000' }}>卡片</Text>
  </Frame>
)

export default () => (
  <Frame style={{ gap: 16, flex: 'row' }}>
    <Card />
    <Card />
    <Card />
  </Frame>
)

变体

包含所有组合的 ComponentSet：

import { defineComponentSet, Frame、Text } from 'figma-use/render'

const Button = defineComponentSet(
  'Button',
  {
    variant: ['Primary', 'Secondary'] as const,
    size: ['Small', 'Large'] as const
  },
  ({ variant, size }) => (
    <Frame
      style={{
        p: size === 'Large' ? 16 : 8,
        bg: variant === 'Primary' ? '#3B82F6' : '#E5E7EB',
        rounded: 8
      }}
    >
      <Text style={{ color: variant === 'Primary' ? '#FFFFFF' : '#111' }}>
        {variant} {size}
      </Text>
    </Frame>
  )
)

export default () => (
  <Frame style={{ gap: 16, flex: 'col' }}>
    <Button variant="Primary" size="Large" />
    <Button variant="Secondary" size="Small" />
  </Frame>
)

这会在 Figma 中创建一个真正的 ComponentSet，包含全部 4 种变体，而不仅仅是 4 个独立的按钮。

网格布局

CSS Grid 适用于二维布局——日历、仪表盘、图库等：

<Frame
  style={{
    display: 'grid',
    cols: '1fr 1fr 1fr', // 3 列等宽
    rows: 'auto auto', // 2 行
    gap: 16
  }}
>
  <Frame style={{ bg: '#FF6B6B' }} />
  <Frame style={{ bg: '#4ECDC4' }} />
  <Frame style={{ bg: '#45B7D1' }} />
  <Frame style={{ bg: '#96CEB4' }} />
  <Frame style={{ bg: '#FFEAA7' }} />
  <Frame style={{ bg: '#DDA0DD' }} />
</Frame>

支持 px、fr 以及 auto/hug。可分别使用 colGap 和 rowGap 设置列与行之间的间距。

在命令行中：

figma-use set layout <id> --mode GRID --cols "100px 1fr 100px" --rows "auto" --gap 16

变量作为标记

通过名称将颜色绑定到 Figma 变量。十六进制值用作回退：

import { defineVars, Frame, Text } from 'figma-use/render'

const colors = defineVars({
  bg: { name: 'Colors/Gray/50', value: '#F8FAFC' },
  text: { name: 'Colors/Gray/900', value: '#0F172A' }
})

export default () => (
  <Frame style={{ bg: colors.bg }}>
    <Text style={{ color: colors.text }}>绑定到变量</Text>
  </Frame>
)

在 CLI 中，可在任何颜色选项中使用 var:Colors/Primary 或 $Colors/Primary。

差异比较

比较两个框架并获取补丁：

figma-use diff create --from 123:456 --to 789:012

--- /Card/Header #123:457
+++ /Card/Header #789:013
@@ -1,5 +1,5 @@
 type: FRAME
 size: 200 50
 pos: 0 0
-fill: #FFFFFF
+fill: #F0F0F0
-opacity: 0.8
+opacity: 1

将补丁应用到原始框架。应用时会验证当前状态是否符合预期——如果不匹配，则会失败。

视觉差异会以红色突出显示更改的像素：

figma-use diff visual --from 49:275096 --to 49:280802 --output diff.png

之前	之后	差异

检查

以可读格式显示页面树：

$ figma-use node tree
[0] 框架 “Card” (1:23)
    400×300 在 (0, 0) | 填充：#FFFFFF | 布局：列间距=16
  [0] 文本 “Title” (1:24)
      “Hello World” | 24px Inter Bold

只需一条命令即可导出任意节点或截图。

排列

整理画布布局——尤其在代理在同一位置创建多个框架后非常有用：

figma-use arrange                              # 网格排列所有顶级节点
figma-use arrange --mode row --gap 60          # 横向排列
figma-use arrange --mode squarify --gap 60     # 智能包装，适用于不同大小的元素

squarify 和 binary 模式使用 d3-hierarchy 树状图进行尺寸感知的矩形打包。

向量

导入 SVG 或直接操作路径——读取、修改、平移、缩放、翻转：

figma-use path get <id>
figma-use path set <id> "M 0 0 L 100 100 Z"
figma-use path scale <id> --factor 1.5
figma-use path flip <id> --axis x

查询

使用 XPath 选择器查找节点：

figma-use query "//FRAME"                              # 所有框架
figma-use query "//FRAME[@width < 300]"                # 宽度小于 300px
figma-use query "//COMPONENT[starts-with(@name, 'Button')]"  # 名称以...开头
figma-use query "//FRAME[contains(@name, 'Card')]"     # 名称包含...
figma-use query "//SECTION/FRAME"                      # 直接子元素
figma-use query "//SECTION//TEXT"                      # 所有后代
figma-use query "//*[@cornerRadius > 0]"               # 任何具有圆角的节点

完全支持 XPath 3.1 — 谓词、函数、算术和轴。

分析

用于理解设计系统的发现工具：

# 查找重复模式（潜在组件）
figma-use analyze clusters

# 颜色 palette — 使用频率、变量与硬编码
figma-use analyze colors
figma-use analyze colors --show-similar    # 查找可合并的颜色

# 排版 — 所有字体组合
figma-use analyze typography
figma-use analyze typography --group-by size

# 间距 — 间隙/填充值、网格合规性
figma-use analyze spacing --grid 8

# 辅助功能快照 — 提取交互元素树
figma-use analyze snapshot                 # 整页
figma-use analyze snapshot <id> -i         # 仅交互元素

示例输出：

[0] 48× 框架 “Header” 模式 (100% 匹配)
    1280×56 | 框架 > [框架×2, 文本]
    示例：53171:21628, 53171:21704

#303030  ████████████████████ 1840× (变量)
#E5E5E5  ████████████████████ 1726× (变量)
#000000  ████████ 238×

代码检查（实验性）

检查设计的一致性、可访问性和最佳实践：

figma-use lint                          # 推荐规则
figma-use lint --page "Components"      # 检查特定页面
figma-use lint --preset strict          # 更严格的生产标准
figma-use lint --preset accessibility   # 仅辅助功能检查
figma-use lint -v                       # 包含修复建议

输出：

✖ Header/Title (1:234)
    ✖ 对比度 2.1:1 低于 AA 标准 (4.5:1)    color-contrast
    ⚠ 触摸目标 32x32 小于最小 44x44             touch-target-size

⚠ Card/Body (1:567)
    ⚠ 硬编码填充颜色 #1A1A1A                          no-hardcoded-colors
    ℹ 包含 3 个子元素的框架未使用自动布局         prefer-auto-layout

────────────────────────────────────────────────────────────────
✖ 1 错误  ⚠ 3 警告  ℹ 1 信息

17 条规则分布在 6 个类别中：

类别	规则
设计令牌	no-hardcoded-colors, consistent-spacing, consistent-radius, effect-style-required
布局	prefer-auto-layout, pixel-perfect
排版	text-style-required, min-text-size, no-mixed-styles
辅助功能	color-contrast, touch-target-size
结构	no-default-names, no-hidden-layers, no-deeply-nested, no-empty-frames, no-groups
组件	no-detached-instances

用于 CI/CD 的 JSON 输出：

figma-use lint --json > report.json

基于评论的工作流（实验性）

AI 代理可以等待 Figma 评论并作出响应：

figma-use comment watch --json   # 阻塞直到收到新评论
figma-use comment resolve <id>   # 标记为已完成

返回评论内容、作者以及 target_node——即评论标记下的确切元素。代理处理请求后，解决评论，然后再次运行 watch 以等待下一个评论。

完整命令参考

完整 100 多条命令列表请参阅 REFERENCE.md。

MCP 服务器

对于支持模型上下文协议的 AI 代理：

figma-use mcp serve

公开 90 多种工具。设置方法请参阅 MCP.md。

配置

对于 Storybook 导出和代码检查，可创建配置文件：

figma-use init

这将创建 .figma-use.json 文件：

{
  "storybook": {
    "page": "Components",
    "out": "./stories",
    "matchIcons": true,
    "preferIcons": ["lucide", "tabler"]
  },
  "lint": {
    "preset": "recommended"
  },
  "format": {
    "pretty": true,
    "semi": false,
    "singleQuote": true
  }
}

CLI 参数会覆盖配置值。

适用于 AI 助手

包含 SKILL.md — Claude Code、Cursor 及其他助手的参考文档。

工作原理

┌─────────────┐            ┌─────────────┐
│   终端      │────CDP────▶│   Figma     │
│  figma-use  │  端口 9222 │             │
└─────────────┘            └─────────────┘

figma-use 通过 Chrome 开发者工具协议 (CDP) 直接与 Figma 通信。只需使用 --remote-debugging-port=9222 启动 Figma，即可准备就绪。

命令通过 Figma 的 JavaScript 上下文中 Runtime.evaluate 执行，可完全访问插件 API。

守护进程

可选的守护进程会保持 CDP 连接处于活跃状态，以加快连续命令的执行速度：

figma-use daemon start    # 后台守护进程（命令速度提升约 25%）
figma-use daemon stop     # 停止守护进程
figma-use daemon status   # 检查是否正在运行

管道传输

对于无法获得管理员权限进行补丁的 Figma 126+ 版本，守护进程可以使用 --remote-debugging-pipe 参数启动 Figma：

figma-use daemon start --pipe   # 启动 Figma，并通过标准输入输出管道连接

可通过设置 FIGMA_BIN 来指定自定义的二进制文件路径。守护进程会维持管道连接，所有命令都会自动通过该连接路由。

许可证

MIT

figma-use 快速上手指南

figma-use 是一款强大的 Figma CLI 工具，允许开发者通过终端命令或 JSX 语法直接控制 Figma。它弥补了官方插件只能读取无法修改文件的短板，特别适合结合 LLM（大语言模型）进行自动化设计和批量操作。

环境准备

在开始之前，请确保满足以下要求：

• 操作系统：macOS、Windows 或 Linux。
• Node.js：已安装 Node.js 环境（推荐 v16+），以便使用 npm 或 npx。
• Figma 桌面端：必须安装 Figma 桌面应用程序（Web 版不支持远程调试）。
• 网络环境：由于需要访问 Iconify 图标库和 npm 仓库，国内用户建议配置镜像源以加速安装。

安装步骤

1. 安装 CLI 工具

你可以选择全局安装或通过 npx 直接运行。

全局安装（推荐）：

# 使用国内镜像源加速安装
npm install -g figma-use --registry=https://registry.npmmirror.com

免安装运行：

npx figma-use status

2. 启动带远程调试功能的 Figma

figma-use 依赖 Figma 的远程调试端口进行通信。你需要通过特定参数启动 Figma 桌面应用。

macOS:

open -a Figma --args --remote-debugging-port=9222

Windows:

"%LOCALAPPDATA%\Figma\Figma.exe" --remote-debugging-port=9222

Linux:

figma --remote-debugging-port=9222

注意：如果你使用的是 Figma 126+ 版本，官方可能限制了部分远程调试功能。如果遇到连接问题，可以尝试使用守护进程模式：figma-use daemon start --pipe，或者考虑使用兼容的开源编辑器 OpenPencil。

3. 验证连接

启动 Figma 后，在终端运行以下命令检查连接状态：

figma-use status

如果显示连接成功，即可开始使用。无需在 Figma 内安装任何插件。

基本使用

figma-use 支持两种主要工作模式：命令式（CLI 命令） 和 声明式（JSX）。

模式一：命令式操作 (Imperative)

适合简单的创建、样式修改和布局调整。命令紧凑，易于由 AI 生成或脚本串联。

创建并样式化一个帧（Frame）：

figma-use create frame --width 400 --height 300 --fill "#FFF" --layout VERTICAL --gap 16

插入图标（支持 Iconify 库，无需下载）：

figma-use create icon mdi:home --size 32 --color "#3B82F6"

设置现有节点的布局为网格：

figma-use set layout 1:23 --mode GRID --cols "1fr 1fr 1fr" --gap 16

(注：1:23 为 Figma 节点 ID，可通过 figma-use node tree 查看)

模式二：声明式渲染 (Declarative JSX)

适合复杂结构、组件定义或利用 LLM 生成 UI。你可以直接将 JSX 代码通过管道传递给工具进行渲染。

渲染一个简单的卡片布局：

echo '<Frame style={{p: 24, gap: 16, flex: "col", bg: "#FFF", rounded: 12}}>
  <Text style={{size: 24, weight: "bold", color: "#000"}}>Card Title</Text>
  <Text style={{size: 14, color: "#666"}}>Description</Text>
</Frame>' | figma-use render --stdin --x 100 --y 200

在 JSX 中使用图标和图片：

<Frame style={{ flex: 'row', gap: 8 }}>
  <Icon icon="mdi:home" size={24} color="#3B82F6" />
  <Image src="https://example.com/photo.jpg" w={200} h={150} />
</Frame>

进阶技巧：导出与反向工程

你可以将 Figma 中的现有设计导出为 JSX 代码，便于复用或转换为 React 组件。

导出节点为 JSX：

figma-use export jsx 123:456 --pretty

自动匹配矢量图形为 Iconify 图标：

# 需先安装可选依赖：npm install whaticon
figma-use export jsx 123:456 --match-icons --prefer-icons lucide

整理画布布局（当多个帧重叠时非常有用）：

figma-use arrange --mode row --gap 60

现在你已经掌握了 figma-use 的核心用法，可以尝试结合 AI 助手编写更复杂的 .figma.tsx 文件来定义组件变体（Variants）和设计系统令牌（Tokens）。