figma-use

figma-use

Figma 命令行工具。提供两种模式：命令和 JSX。

# Commands
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 fill 1:23 "$Colors/Primary"

# JSX (props directly on elements, NOT style={{}})
echo '<Frame p={24} bg="#3B82F6" rounded={12}>
  <Text size={18} color="#FFF">Hello</Text>
</Frame>' | figma-use render --stdin --x 100 --y 100

开始之前

figma-use status  # Check connection

如果尚未连接，请启动启用了远程调试的 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 patch 进行修复，然后重启 Figma。在钥匙串提示中点击 始终允许。Figma 更新后请重新运行。

无法修补？ 使用 figma-use daemon start --pipe — 启动带有调试管道的 Figma，无需修补。

使用 --remote-debugging-port=9222 启动 Figma，即可开始使用。

使用非默认端口？ 如果 Figma 使用其他端口，请为任何命令传入 --port <N>（或设置 FIGMA_PORT 环境变量）。错误信息会显示正确的端口。

open -a Figma --args --remote-debugging-port=9333
figma-use get components --port 9333

两种模式

命令式 — 执行单个操作：

figma-use create frame --width 400 --height 300 --fill "#FFF" --radius 12
figma-use set fill <id> "#FF0000"
figma-use node move <id> --x 100 --y 200

声明式 — 渲染 JSX 树：

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

stdin 同时支持纯 JSX 和带导入语句的完整模块语法：

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

const Button = defineComponent(
  'Button',
  <Frame bg="#3B82F6" p={12} rounded={6}>
    <Text color="#FFF">Click</Text>
  </Frame>
)

export default () => (
  <Frame flex="row" gap={8}>
    <Button />
    <Button />
  </Frame>
)

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

使用 <Instance> 创建组件实例：

<Frame flex="row" gap={8}>
  <Instance component="59763:10626" />
  <Instance component="59763:10629" />
</Frame>

⚠️ 始终使用 --x 和 --y 来定位渲染内容。不要把所有内容都堆叠在 (0, 0)。

图标

通过名称获取 Iconify 提供的 15 万多个图标：

figma-use create icon mdi:home
figma-use create icon lucide:star --size 48 --color "#F59E0B"
figma-use create icon heroicons:bell-solid --component  # as Figma component

在 JSX 中：

<Icon name="mdi:home" size={24} color="#3B82F6" />

图片

从 URL 加载图片：

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

导出 JSX

将 Figma 节点转换回 JSX 代码：

figma-use export jsx <id>           # Minified
figma-use export jsx <id> --pretty  # Formatted

# Format options
figma-use export jsx <id> --pretty --semi --tabs

# Match vector shapes to Iconify icons (requires: npm i whaticon)
figma-use export jsx <id> --match-icons
figma-use export jsx <id> --match-icons --icon-threshold 0.85 --prefer-icons lucide,tabler

往返工作流：

# Export → edit → re-render
figma-use export jsx <id> --pretty > component.tsx
# ... edit the file ...
figma-use render component.tsx --x 500 --y 0

以 JSX 形式比较两个节点：

figma-use diff jsx <from-id> <to-id>

导出 Storybook（实验性）

将当前页面上的所有组件导出为 Storybook stories：

figma-use export storybook                      # Output to ./stories/
figma-use export storybook --out ./src/stories  # Custom output dir
figma-use export storybook --match-icons        # Match vectors to Iconify icons
figma-use export storybook --no-semantic-html   # Disable semantic HTML conversion

语义化 HTML： 默认情况下，组件会根据名称转换为语义化 HTML 元素：

• Input/*、TextField/* → <input type="text">
• Textarea/* → <textarea>
• Checkbox/* → <input type="checkbox">
• Radio/* → <input type="radio">
• Button/* → <button>
• Select/*、Dropdown/* → <select>

使用 --no-semantic-html 禁用此功能，并保留 <Frame> 元素。

生成 .stories.tsx 文件：

• ComponentSets → 带 props 的 React 组件，以及带 args 的 stories
• VARIANT 属性 → 联合类型 props（variant?: 'Primary' | 'Secondary'）
• TEXT 属性 → 可编辑的字符串 props（label?: string）
• 按 / 前缀分组的组件 → Button/Primary、Button/Secondary → Button.stories.tsx

带有 variant 和 label 的 Button 输出示例：

// Button.tsx
export interface ButtonProps {
  label?: string
  variant?: 'Primary' | 'Secondary'
}
export function Button({ label, variant }: ButtonProps) {
  if (variant === 'Primary')
    return (
      <Frame>
        <Text>{label}</Text>
      </Frame>
    )
  // ...
}

// Button.stories.tsx
export const Primary: StoryObj<typeof Button> = {
  args: { label: 'Click', variant: 'Primary' }
}

将变量用作令牌

在任何颜色选项中使用 var:Name 或 $Name 引用 Figma 变量：

figma-use create rect --width 100 --height 100 --fill 'var:Colors/Primary'
figma-use set fill <id> '$Brand/Accent'

在 JSX 中：

<Frame bg="$Colors/Primary" />
<Text color="var:Text/Primary">Hello</Text>

样式简写

尺寸与位置：

简写	全称	值
w, h	width, height	数字或 "fill"
minW, maxW	minWidth, maxWidth	数字
minH, maxH	minHeight, maxHeight	数字
x, y	position	数字

布局：

简写	全称	值
flex	flexDirection	"row", "col"
gap	spacing	数字
wrap	layoutWrap	true
justify	justifyContent	"start", "center", "end", "between"
items	alignItems	"start", "center", "end"
p, px, py	padding	数字
pt, pr, pb, pl	padding sides	数字
position	layoutPositioning	"absolute"
grow	layoutGrow	数字
stretch	layoutAlign	true → STRETCH

外观：

简写	全称	值
bg	fill	十六进制值或 $Variable
stroke	strokeColor	十六进制值
strokeWidth	strokeWeight	数字
strokeAlign	strokeAlign	"inside", "outside"
opacity	opacity	0..1
blendMode	blendMode	"multiply" 等

圆角：

简写	全称	值
rounded	cornerRadius	数字
roundedTL/TR/BL/BR	individual corners	数字
cornerSmoothing	squircle smoothing	0..1（iOS 风格）

效果：

简写	全称	值
shadow	dropShadow	"0px 4px 8px rgba(0,0,0,0.25)"
blur	layerBlur	数字
overflow	clipsContent	"hidden"
rotate	rotation	角度

文本：

简写	全称	值
size	fontSize	数字
weight	fontWeight	"bold" 或数字
font	fontFamily	字符串
color	textColor	十六进制值

网格（CSS Grid 布局）：

简写	全称	值
display	layoutMode	"grid"
cols	gridTemplateColumns	"100px 1fr auto"
rows	gridTemplateRows	"auto auto"
colGap	columnGap	数字
rowGap	rowGap	数字

组件（通过 .figma.tsx）

首次调用会创建主组件，其余调用会创建实例：

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

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

export default () => (
  <Frame gap={16} flex="row">
    <Card />
    <Card />
  </Frame>
)

figma-use render ./Card.figma.tsx --x 100 --y 200
figma-use render --examples  # Full API reference

变体（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
      p={size === 'Large' ? 16 : 8}
      bg={variant === 'Primary' ? '#3B82F6' : '#E5E7EB'}
      rounded={8}
    >
      <Text color={variant === 'Primary' ? '#FFF' : '#111'}>
        {variant} {size}
      </Text>
    </Frame>
  )
)

创建包含所有组合的真实 ComponentSet。

差异对比

比较画框并生成补丁：

figma-use diff create --from <id1> --to <id2>

--- /Card/Header #123:457
+++ /Card/Header #789:013
 type: FRAME
 size: 200 50
-fill: #FFFFFF
+fill: #F0F0F0

⚠️ 上下文行需要以空格为前缀： size: 200 50，而非 size: 200 50

应用并验证：

figma-use diff apply patch.diff            # Fails if old values don't match
figma-use diff apply patch.diff --dry-run  # Preview
figma-use diff apply patch.diff --force    # Skip validation

视觉差异（红色 = 已更改的像素）：

figma-use diff visual --from <id1> --to <id2> --output diff.png

⚠️ **完成初始渲染后，请使用差异对比或直接命令。**不要重新渲染完整的 JSX 树。

查询（XPath）

使用 XPath 选择器查找节点：

figma-use query "//FRAME"                              # All frames
figma-use query "//FRAME[@width < 300]"                # Frames narrower than 300px
figma-use query "//COMPONENT[starts-with(@name, 'Button')]"  # Name starts with
figma-use query "//FRAME[contains(@name, 'Card')]"     # Name contains
figma-use query "//SECTION/FRAME"                      # Direct children
figma-use query "//SECTION//TEXT"                      # All descendants
figma-use query "//*[@cornerRadius > 0]"               # Any node with radius
figma-use query "//FRAME[@width > 100 and @width < 500]"  # Range

属性：name、width、height、x、y、cornerRadius、opacity、visible、characters、fontSize、layoutMode、itemSpacing

XPath 函数：contains()、starts-with()、string-length()、not()、and、or

常用命令

# Create
figma-use create frame --width 400 --height 300 --fill "#FFF" --layout VERTICAL --gap 16
figma-use create text --text "Hello" --font-size 24 --fill "#000"
figma-use create rect --width 100 --height 50 --fill "#F00" --radius 8

# Find
figma-use query "//FRAME[@name = 'Header']"
figma-use find --name "Button"
figma-use find --type FRAME
figma-use selection get

# Explore
figma-use node ancestors <id>              # Get parent chain (useful for navigation)
figma-use node bindings <id>               # Get variable bindings for fills/strokes
figma-use page bounds                      # Find free space for new objects
figma-use variable find "Text/Neutral"     # Search variables by name

# Modify
figma-use set fill <id> "#FF0000"
figma-use set radius <id> 12
figma-use set text <id> "New text"
figma-use set text-resize <id> height   # Wrap text (height auto, fixed width)
figma-use set layout <id> --mode VERTICAL --gap 12 --padding 16
figma-use set layout <id> --mode GRID --cols "1fr 1fr 1fr" --rows "auto" --gap 16
figma-use node move <id> --x 100 --y 200
figma-use node resize <id> --width 300 --height 200
figma-use node delete <id> [id2...]
figma-use arrange                              # Tidy up overlapping frames on canvas
figma-use node to-component <id>

# Export
figma-use export node <id> --output design.png
figma-use export screenshot --output viewport.png

# Navigate
figma-use page list
figma-use page set "Page Name"
figma-use viewport zoom-to-fit <id>

# Daemon (faster sequential commands)
figma-use daemon start                     # Background daemon
figma-use daemon start --pipe              # Launch Figma with debug pipe (no patching)
figma-use daemon stop
figma-use daemon status

完整参考：REFERENCE.md

分析

用于了解设计系统的探索工具：

# Repeated patterns — potential components
figma-use analyze clusters
figma-use analyze clusters --min-count 5

# Color palette
figma-use analyze colors                   # Usage frequency
figma-use analyze colors --show-similar    # Find similar colors to merge

# Typography
figma-use analyze typography               # All font combinations
figma-use analyze typography --group-by size

# Spacing
figma-use analyze spacing --grid 8         # Check 8px grid compliance

# Accessibility snapshot — extract interactive elements
figma-use analyze snapshot                 # Full page
figma-use analyze snapshot <id> -i         # Interactive only (buttons, inputs, etc.)
figma-use analyze snapshot --depth 6       # Limit depth

使用场景：

• 组件提取——找出应作为组件的复制粘贴元素
• 设计审查——识别不一致之处，以及相似但不同的元素
• 创建设计系统——发现现有的颜色、字体排版和间距模式
• 新手入门——了解陌生设计文件的结构

输出会显示计数、示例和警告（例如，不符合网格的间距、硬编码颜色）。

检查（实验性）

检查设计是否存在一致性和无障碍问题：

figma-use lint                          # Recommended preset
figma-use lint --page "Components"      # Lint specific page
figma-use lint --preset strict          # Stricter rules
figma-use lint --preset accessibility   # A11y only (contrast, touch targets)
figma-use lint --rule color-contrast    # Single rule
figma-use lint -v                       # With fix suggestions
figma-use lint --json                   # For CI/CD
figma-use lint --list-rules             # Show all rules

预设： recommended、strict、accessibility、design-system

17 条规则：

• 设计令牌：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

发现错误时返回退出码 1 — 可用于 CI 流水线。

输出

默认输出易于阅读的内容 — 建议使用此格式以节省令牌。仅在需要以编程方式解析特定字段时使用 --json。

节点 ID

格式：session:local（例如 1:23）。在实例内部：I<instance-id>;<internal-id>。

通过 figma-use selection get 或 figma-use node tree 获取 ID。

颜色

十六进制：#RGB、#RRGGBB、#RRGGBBAA 变量：var:Colors/Primary 或 $Colors/Primary

---

最佳实践

始终进行视觉检查

figma-use export node <id> --output /tmp/check.png

创建后始终缩放查看

figma-use viewport zoom-to-fit <id>

分别放置多个渲染结果

echo '...' | figma-use render --stdin --x 0 --y 0
echo '...' | figma-use render --stdin --x 500 --y 0    # Not at same position!

批量创建后进行排列

创建多个画框/区段后，运行 arrange 将它们分散排列：

figma-use arrange --mode grid --gap 60       # Grid layout (default)
figma-use arrange --mode squarify --gap 60   # Smart packing for mixed sizes

在页面间复制

figma-use node clone <id> [id2...] --json | jq -r '.[].id'
figma-use node set-parent <new-id> --parent <target-page-id>
figma-use node move <new-id> --x 50 --y 50

替换节点

# Replace with component (creates instance)
figma-use node replace-with <id> --target <component-id>

# Replace with JSX from stdin
echo '<Icon name="lucide:x" size={16} />' | figma-use node replace-with <id> --stdin

转换为组件

figma-use node to-component <id>
figma-use node to-component "1:2 1:3 1:4"  # Multiple

实例内部 ID

figma-use set text "I123:456;789:10" "New text"  # I<instance>;<internal>

行布局需要宽度

# ❌ Collapses to 1×1
<Frame flex="row" gap={8}>

# ✅ Explicit width
<Frame w={300} flex="row" gap={8}>

区段

figma-use create section --name "Buttons" --x 0 --y 0 --width 600 --height 200
figma-use node set-parent <id> --parent <section-id>

⚠️ 删除区段会删除所有子项！

以评论驱动的工作流

等待设计师反馈并作出响应：

figma-use comment watch --json

评论到达时的输出：

{
  "id": "123456",
  "message": "Make this button bigger",
  "user": { "handle": "designer" },
  "client_meta": { "node_id": "1:23" }
}

Agent 工作流 — 每条评论运行一次，然后重新启动：

1. figma-use comment watch --json — 阻塞等待新评论
2. 解析 JSON，获取 message 和 target_node（评论所针对的确切元素）
3. 处理请求（修改设计等）
4. 回复：figma-use comment add "Done!" --reply <comment-id>
5. 解决：figma-use comment resolve <comment-id>
6. 退出。外部运行器会为下一条评论重新启动。

选项：

• --timeout 60 — 如果 60 秒内没有评论则退出（返回 {"timeout":true}）
• --interval 5 — 每 5 秒轮询一次（默认：3 秒）

矢量路径 — 迭代工作流

绘制、截图、调整、重复 — 就像设计师不断调整贝塞尔曲线：

# 1. Draw initial shape
figma-use create vector --path "M 50 0 L 100 100 L 0 100 Z" --fill "#F00"

# 2. Check result
figma-use export node <id> --output /tmp/shape.png

# 3. Adjust: scale, move, flip
figma-use path scale <id> --factor 0.8
figma-use path move <id> --dx 20 --dy -10
figma-use path flip <id> --axis x

# 4. Or replace path entirely
figma-use path set <id> "M 50 0 C 80 30 80 70 50 100 C 20 70 20 30 50 0 Z"

# 5. Screenshot again, repeat until good
figma-use export node <id> --output /tmp/shape.png

对于复杂插画，请导入 SVG：

figma-use import --svg "$(cat icon.svg)"