figma-use

figma-use

Figma 用 CLI です。コマンドモードと JSX モードの 2 つがあります。

# 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

2 つのモード

命令型 — 単一の操作：

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 を含む完全なモジュール構文の両方に対応しています：

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

2 つのノードを JSX として比較します：

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

Storybook のエクスポート（実験的機能）

現在のページにあるすべてのコンポーネントを Storybook のストーリーとしてエクスポートします：

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 と args を持つストーリーを備えた React コンポーネント
• VARIANT プロパティ → Union 型の 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	hex または $Variable
stroke	strokeColor	hex
strokeWidth	strokeWeight	数値
strokeAlign	strokeAlign	"inside", "outside"
opacity	opacity	0..1
blendMode	blendMode	"multiply" など

角：

省略形	完全形	値
rounded	cornerRadius	数値
roundedTL/TR/BL/BR	個別の角	数値
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	hex

グリッド（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 を取得します。

色

16 進数：#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" }
}

エージェントのワークフロー — コメントごとに 1 回実行し、その後再起動します。

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)"