Skip to content
Back to search

figma-use

Control Figma from the command line. Full read/write access for AI agents — create shapes, text, components, set styles, export images. 100+ commands.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/dannote/figma-use with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/dannote/figma-use'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dannote--figma-use/badge.svg)](/listings/dannote--figma-use)

HTML

<a href="/listings/dannote--figma-use"><img src="/api/listings/dannote--figma-use/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npm install -g figma-use

Or run directly without installing:

npx figma-use status

Start Figma with remote debugging enabled:

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

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

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

Check connection:

figma-use status

That's it. No plugins to install.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 674 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: figma-use
  3. description: Control Figma via CLI — create shapes, frames, text, components, set styles, layout, variables, export images. Use when asked to create/modify Figma designs or automate design tasks.
  4. ---
  5. # figma-use
  6. CLI for Figma. Two modes: commands and JSX.
  7. ```bash
  8. # Commands
  9. figma-use create frame --width 400 --height 300 --fill "#FFF" --layout VERTICAL --gap 16
  10. figma-use create icon mdi:home --size 32 --color "#3B82F6"
  11. figma-use set fill 1:23 "$Colors/Primary"
  12. # JSX (props directly on elements, NOT style={{}})
  13. echo '<Frame p={24} bg="#3B82F6" rounded={12}>
  14. <Text size={18} color="#FFF">Hello</Text>
  15. </Frame>' | figma-use render --stdin --x 100 --y 100
  16. ```
  17. ## Before You Start
  18. ```bash
  19. figma-use status # Check connection
  20. ```
  21. If not connected — start Figma with remote debugging:
  22. ```bash
  23. # macOS
  24. open -a Figma --args --remote-debugging-port=9222
  25. # Windows
  26. "%LOCALAPPDATA%\Figma\Figma.exe" --remote-debugging-port=9222
  27. # Linux
  28. figma --remote-debugging-port=9222
  29. ```
  30. > Figma 126+ blocks remote debugging. Run `figma-use patch` once to fix, then restart Figma. Click **Always Allow** on the keychain prompt. Re-run after Figma updates.
  31. >
  32. > **Can't patch?** Use `figma-use daemon start --pipe` — launches Figma with debug pipe, no patching needed.
  33. Start Figma with `--remote-debugging-port=9222` and you're ready.
  34. > **Non-default port?** If Figma is on another port, pass `--port <N>` to any command (or set the `FIGMA_PORT` env var). Errors will show the correct port.
  35. > ```bash
  36. > open -a Figma --args --remote-debugging-port=9333
  37. > figma-use get components --port 9333
  38. > ```
  39. ## Two Modes
  40. **Imperative** — single operations:
  41. ```bash
  42. figma-use create frame --width 400 --height 300 --fill "#FFF" --radius 12
  43. figma-use set fill <id> "#FF0000"
  44. figma-use node move <id> --x 100 --y 200
  45. ```
  46. **Declarative** — render JSX trees:
  47. ```bash
  48. echo '<Frame p={24} gap={16} flex="col" bg="#FFF" rounded={12}>
  49. <Text size={24} weight="bold" color="#000">Title</Text>
  50. <Text size={14} color="#666">Description</Text>
  51. </Frame>' | figma-use render --stdin --x 100 --y 200
  52. ```
  53. stdin supports both pure JSX and full module syntax with imports:
  54. ```tsx
  55. import { Frame, Text, defineComponent } from 'figma-use/render'
  56. const Button = defineComponent(
  57. 'Button',
  58. <Frame bg="#3B82F6" p={12} rounded={6}>
  59. <Text color="#FFF">Click</Text>
  60. </Frame>
  61. )
  62. export default () => (
  63. <Frame flex="row" gap={8}>
  64. <Button />
  65. <Button />
  66. </Frame>
  67. )
  68. ```
  69. **Elements:** `Frame`, `Rectangle`, `Ellipse`, `Text`, `Line`, `Star`, `Polygon`, `Vector`, `Group`, `Icon`, `Image`, `Instance`
  70. Use `<Instance>` to create component instances:
  71. ```tsx
  72. <Frame flex="row" gap={8}>
  73. <Instance component="59763:10626" />
  74. <Instance component="59763:10629" />
  75. </Frame>
  76. ```
  77. ⚠️ **Always use `--x` and `--y`** to position renders. Don't stack everything at (0, 0).
  78. ## Icons
  79. 150k+ icons from Iconify by name:
  80. ```bash
  81. figma-use create icon mdi:home
  82. figma-use create icon lucide:star --size 48 --color "#F59E0B"
  83. figma-use create icon heroicons:bell-solid --component # as Figma component
  84. ```
  85. In JSX:
  86. ```tsx
  87. <Icon name="mdi:home" size={24} color="#3B82F6" />
  88. ```
  89. ## Images
  90. Load images from URL:
  91. ```tsx
  92. <Image src="https://example.com/photo.jpg" w={200} h={150} />
  93. ```
  94. ## Export JSX
  95. Convert Figma nodes back to JSX code:
  96. ```bash
  97. figma-use export jsx <id> # Minified
  98. figma-use export jsx <id> --pretty # Formatted
  99. # Format options
  100. figma-use export jsx <id> --pretty --semi --tabs
  101. # Match vector shapes to Iconify icons (requires: npm i whaticon)
  102. figma-use export jsx <id> --match-icons
  103. figma-use export jsx <id> --match-icons --icon-threshold 0.85 --prefer-icons lucide,tabler
  104. ```
  105. Round-trip workflow:
  106. ```bash
  107. # Export → edit → re-render
  108. figma-use export jsx <id> --pretty > component.tsx
  109. # ... edit the file ...
  110. figma-use render component.tsx --x 500 --y 0
  111. ```
  112. Compare two nodes as JSX:
  113. ```bash
  114. figma-use diff jsx <from-id> <to-id>
  115. ```
  116. ## Export Storybook (Experimental)
  117. Export all components on current page as Storybook stories:
  118. ```bash
  119. figma-use export storybook # Output to ./stories/
  120. figma-use export storybook --out ./src/stories # Custom output dir
  121. figma-use export storybook --match-icons # Match vectors to Iconify icons
  122. figma-use export storybook --no-semantic-html # Disable semantic HTML conversion
  123. ```
  124. **Semantic HTML:** By default, components are converted to semantic HTML elements based on their names:
  125. - `Input/*`, `TextField/*` → `<input type="text">`
  126. - `Textarea/*` → `<textarea>`
  127. - `Checkbox/*` → `<input type="checkbox">`
  128. - `Radio/*` → `<input type="radio">`
  129. - `Button/*` → `<button>`
  130. - `Select/*`, `Dropdown/*` → `<select>`
  131. Use `--no-semantic-html` to disable this and keep `<Frame>` elements.
  132. Generates `.stories.tsx` files:
  133. - **ComponentSets** → React component with props + stories with args
  134. - **VARIANT properties** → Union type props (`variant?: 'Primary' | 'Secondary'`)
  135. - **TEXT properties** → Editable string props (`label?: string`)
  136. - Components grouped by `/` prefix → `Button/Primary`, `Button/Secondary` → `Button.stories.tsx`
  137. Example output for Button with variant and label:
  138. ```tsx
  139. // Button.tsx
  140. export interface ButtonProps {
  141. label?: string
  142. variant?: 'Primary' | 'Secondary'
  143. }
  144. export function Button({ label, variant }: ButtonProps) {
  145. if (variant === 'Primary')
  146. return (
  147. <Frame>
  148. <Text>{label}</Text>
  149. </Frame>
  150. )
  151. // ...
  152. }
  153. // Button.stories.tsx
  154. export const Primary: StoryObj<typeof Button> = {
  155. args: { label: 'Click', variant: 'Primary' }
  156. }
  157. ```
  158. ## Variables as Tokens
  159. Reference Figma variables in any color option with `var:Name` or `$Name`:
  160. ```bash
  161. figma-use create rect --width 100 --height 100 --fill 'var:Colors/Primary'
  162. figma-use set fill <id> '$Brand/Accent'
  163. ```
  164. In JSX:
  165. ```tsx
  166. <Frame bg="$Colors/Primary" />
  167. <Text color="var:Text/Primary">Hello</Text>
  168. ```
  169. ## Style Shorthands
  170. **Size & Position:**
  171. | Short | Full | Values |
  172. |-------|------|--------|
  173. | `w`, `h` | width, height | number or `"fill"` |
  174. | `minW`, `maxW` | minWidth, maxWidth | number |
  175. | `minH`, `maxH` | minHeight, maxHeight | number |
  176. | `x`, `y` | position | number |
  177. **Layout:**
  178. | Short | Full | Values |
  179. |-------|------|--------|
  180. | `flex` | flexDirection | `"row"`, `"col"` |
  181. | `gap` | spacing | number |
  182. | `wrap` | layoutWrap | `true` |
  183. | `justify` | justifyContent | `"start"`, `"center"`, `"end"`, `"between"` |
  184. | `items` | alignItems | `"start"`, `"center"`, `"end"` |
  185. | `p`, `px`, `py` | padding | number |
  186. | `pt`, `pr`, `pb`, `pl` | padding sides | number |
  187. | `position` | layoutPositioning | `"absolute"` |
  188. | `grow` | layoutGrow | number |
  189. | `stretch` | layoutAlign | `true` → STRETCH |
  190. **Appearance:**
  191. | Short | Full | Values |
  192. |-------|------|--------|
  193. | `bg` | fill | hex or `$Variable` |
  194. | `stroke` | strokeColor | hex |
  195. | `strokeWidth` | strokeWeight | number |
  196. | `strokeAlign` | strokeAlign | `"inside"`, `"outside"` |
  197. | `opacity` | opacity | 0..1 |
  198. | `blendMode` | blendMode | `"multiply"`, etc. |
  199. **Corners:**
  200. | Short | Full | Values |
  201. |-------|------|--------|
  202. | `rounded` | cornerRadius | number |
  203. | `roundedTL/TR/BL/BR` | individual corners | number |
  204. | `cornerSmoothing` | squircle smoothing | 0..1 (iOS style) |
  205. **Effects:**
  206. | Short | Full | Values |
  207. |-------|------|--------|
  208. | `shadow` | dropShadow | `"0px 4px 8px rgba(0,0,0,0.25)"` |
  209. | `blur` | layerBlur | number |
  210. | `overflow` | clipsContent | `"hidden"` |
  211. | `rotate` | rotation | degrees |
  212. **Text:**
  213. | Short | Full | Values |
  214. |-------|------|--------|
  215. | `size` | fontSize | number |
  216. | `weight` | fontWeight | `"bold"`, number |
  217. | `font` | fontFamily | string |
  218. | `color` | textColor | hex |
  219. **Grid (CSS Grid layout):**
  220. | Short | Full | Values |
  221. |-------|------|--------|
  222. | `display` | layoutMode | `"grid"` |
  223. | `cols` | gridTemplateColumns | `"100px 1fr auto"` |
  224. | `rows` | gridTemplateRows | `"auto auto"` |
  225. | `colGap` | columnGap | number |
  226. | `rowGap` | rowGap | number |
  227. ## Components (via .figma.tsx)
  228. First call creates master, rest create instances:
  229. ```tsx
  230. import { defineComponent, Frame, Text } from 'figma-use/render'
  231. const Card = defineComponent(
  232. 'Card',
  233. <Frame p={24} bg="#FFF" rounded={12}>
  234. <Text size={18} color="#000">
  235. Card
  236. </Text>
  237. </Frame>
  238. )
  239. export default () => (
  240. <Frame gap={16} flex="row">
  241. <Card />
  242. <Card />
  243. </Frame>
  244. )
  245. ```
  246. ```bash
  247. figma-use render ./Card.figma.tsx --x 100 --y 200
  248. figma-use render --examples # Full API reference
  249. ```
  250. ## Variants (ComponentSet)
  251. ```tsx
  252. import { defineComponentSet, Frame, Text } from 'figma-use/render'
  253. const Button = defineComponentSet(
  254. 'Button',
  255. {
  256. variant: ['Primary', 'Secondary'] as const,
  257. size: ['Small', 'Large'] as const
  258. },
  259. ({ variant, size }) => (
  260. <Frame
  261. p={size === 'Large' ? 16 : 8}
  262. bg={variant === 'Primary' ? '#3B82F6' : '#E5E7EB'}
  263. rounded={8}
  264. >
  265. <Text color={variant === 'Primary' ? '#FFF' : '#111'}>
  266. {variant} {size}
  267. </Text>
  268. </Frame>
  269. )
  270. )
  271. ```
  272. Creates real ComponentSet with all combinations.
  273. ## Diffs
  274. Compare frames and generate patch:
  275. ```bash
  276. figma-use diff create --from <id1> --to <id2>
  277. ```
  278. ```diff
  279. --- /Card/Header #123:457
  280. +++ /Card/Header #789:013
  281. type: FRAME
  282. size: 200 50
  283. -fill: #FFFFFF
  284. +fill: #F0F0F0
  285. ```
  286. ⚠️ Context lines need space prefix: ` size: 200 50` not `size: 200 50`
  287. Apply with validation:
  288. ```bash
  289. figma-use diff apply patch.diff # Fails if old values don't match
  290. figma-use diff apply patch.diff --dry-run # Preview
  291. figma-use diff apply patch.diff --force # Skip validation
  292. ```
  293. Visual diff (red = changed pixels):
  294. ```bash
  295. figma-use diff visual --from <id1> --to <id2> --output diff.png
  296. ```
  297. ⚠️ **After initial render, use diffs or direct commands.** Don't re-render full JSX trees.
  298. ## Query (XPath)
  299. Find nodes using XPath selectors:
  300. ```bash
  301. figma-use query "//FRAME" # All frames
  302. figma-use query "//FRAME[@width < 300]" # Frames narrower than 300px
  303. figma-use query "//COMPONENT[starts-with(@name, 'Button')]" # Name starts with
  304. figma-use query "//FRAME[contains(@name, 'Card')]" # Name contains
  305. figma-use query "//SECTION/FRAME" # Direct children
  306. figma-use query "//SECTION//TEXT" # All descendants
  307. figma-use query "//*[@cornerRadius > 0]" # Any node with radius
  308. figma-use query "//FRAME[@width > 100 and @width < 500]" # Range
  309. ```
  310. Attributes: `name`, `width`, `height`, `x`, `y`, `cornerRadius`, `opacity`, `visible`, `characters`, `fontSize`, `layoutMode`, `itemSpacing`
  311. XPath functions: `contains()`, `starts-with()`, `string-length()`, `not()`, `and`, `or`
  312. ## Common Commands
  313. ```bash
  314. # Create
  315. figma-use create frame --width 400 --height 300 --fill "#FFF" --layout VERTICAL --gap 16
  316. figma-use create text --text "Hello" --font-size 24 --fill "#000"
  317. figma-use create rect --width 100 --height 50 --fill "#F00" --radius 8
  318. # Find
  319. figma-use query "//FRAME[@name = 'Header']"
  320. figma-use find --name "Button"
  321. figma-use find --type FRAME
  322. figma-use selection get
  323. # Explore
  324. figma-use node ancestors <id> # Get parent chain (useful for navigation)
  325. figma-use node bindings <id> # Get variable bindings for fills/strokes
  326. figma-use page bounds # Find free space for new objects
  327. figma-use variable find "Text/Neutral" # Search variables by name
  328. # Modify
  329. figma-use set fill <id> "#FF0000"
  330. figma-use set radius <id> 12
  331. figma-use set text <id> "New text"
  332. figma-use set text-resize <id> height # Wrap text (height auto, fixed width)
  333. figma-use set layout <id> --mode VERTICAL --gap 12 --padding 16
  334. figma-use set layout <id> --mode GRID --cols "1fr 1fr 1fr" --rows "auto" --gap 16
  335. figma-use node move <id> --x 100 --y 200
  336. figma-use node resize <id> --width 300 --height 200
  337. figma-use node delete <id> [id2...]
  338. figma-use arrange # Tidy up overlapping frames on canvas
  339. figma-use node to-component <id>
  340. # Export
  341. figma-use export node <id> --output design.png
  342. figma-use export screenshot --output viewport.png
  343. # Navigate
  344. figma-use page list
  345. figma-use page set "Page Name"
  346. figma-use viewport zoom-to-fit <id>
  347. # Daemon (faster sequential commands)
  348. figma-use daemon start # Background daemon
  349. figma-use daemon start --pipe # Launch Figma with debug pipe (no patching)
  350. figma-use daemon stop
  351. figma-use daemon status
  352. ```
  353. Full reference: [REFERENCE.md](https://github.com/dannote/figma-use/blob/master/REFERENCE.md)
  354. ## Analyze
  355. Discovery tools for understanding design systems:
  356. ```bash
  357. # Repeated patterns — potential components
  358. figma-use analyze clusters
  359. figma-use analyze clusters --min-count 5
  360. # Color palette
  361. figma-use analyze colors # Usage frequency
  362. figma-use analyze colors --show-similar # Find similar colors to merge
  363. # Typography
  364. figma-use analyze typography # All font combinations
  365. figma-use analyze typography --group-by size
  366. # Spacing
  367. figma-use analyze spacing --grid 8 # Check 8px grid compliance
  368. # Accessibility snapshot — extract interactive elements
  369. figma-use analyze snapshot # Full page
  370. figma-use analyze snapshot <id> -i # Interactive only (buttons, inputs, etc.)
  371. figma-use analyze snapshot --depth 6 # Limit depth
  372. ```
  373. **Use cases:**
  374. - **Component extraction** — find copy-pasted elements that should be components
  375. - **Design audit** — identify inconsistencies, similar-but-different elements
  376. - **Design system creation** — discover existing colors, typography, spacing patterns
  377. - **Onboarding** — understand structure of unfamiliar design files
  378. Output shows counts, examples, and warnings (e.g., off-grid spacing, hardcoded colors).
  379. ## Lint (Experimental)
  380. Check designs for consistency and accessibility issues:
  381. ```bash
  382. figma-use lint # Recommended preset
  383. figma-use lint --page "Components" # Lint specific page
  384. figma-use lint --preset strict # Stricter rules
  385. figma-use lint --preset accessibility # A11y only (contrast, touch targets)
  386. figma-use lint --rule color-contrast # Single rule
  387. figma-use lint -v # With fix suggestions
  388. figma-use lint --json # For CI/CD
  389. figma-use lint --list-rules # Show all rules
  390. ```
  391. **Presets:** `recommended`, `strict`, `accessibility`, `design-system`
  392. **17 rules:**
  393. - Design tokens: `no-hardcoded-colors`, `consistent-spacing`, `consistent-radius`, `effect-style-required`
  394. - Layout: `prefer-auto-layout`, `pixel-perfect`
  395. - Typography: `text-style-required`, `min-text-size`, `no-mixed-styles`
  396. - Accessibility: `color-contrast`, `touch-target-size`
  397. - Structure: `no-default-names`, `no-hidden-layers`, `no-deeply-nested`, `no-empty-frames`, `no-groups`
  398. - Components: `no-detached-instances`
  399. Exit code 1 if errors found — use in CI pipelines.
  400. ## Output
  401. Human-readable by default — **prefer this to save tokens**. Use `--json` only when you need to parse specific fields programmatically.
  402. ## Node IDs
  403. Format: `session:local` (e.g., `1:23`). Inside instances: `I<instance-id>;<internal-id>`.
  404. Get IDs from `figma-use selection get` or `figma-use node tree`.
  405. ## Colors
  406. Hex: `#RGB`, `#RRGGBB`, `#RRGGBBAA`
  407. Variables: `var:Colors/Primary` or `$Colors/Primary`
  408. ---
  409. ## Best Practices
  410. ### Always verify visually
  411. ```bash
  412. figma-use export node <id> --output /tmp/check.png
  413. ```
  414. ### Always zoom after creating
  415. ```bash
  416. figma-use viewport zoom-to-fit <id>
  417. ```
  418. ### Position multiple renders separately
  419. ```bash
  420. echo '...' | figma-use render --stdin --x 0 --y 0
  421. echo '...' | figma-use render --stdin --x 500 --y 0 # Not at same position!
  422. ```
  423. ### Arrange after batch creation
  424. After creating multiple frames/sections, run `arrange` to spread them out:
  425. ```bash
  426. figma-use arrange --mode grid --gap 60 # Grid layout (default)
  427. figma-use arrange --mode squarify --gap 60 # Smart packing for mixed sizes
  428. ```
  429. ### Copy between pages
  430. ```bash
  431. figma-use node clone <id> [id2...] --json | jq -r '.[].id'
  432. figma-use node set-parent <new-id> --parent <target-page-id>
  433. figma-use node move <new-id> --x 50 --y 50
  434. ```
  435. ### Replace node
  436. ```bash
  437. # Replace with component (creates instance)
  438. figma-use node replace-with <id> --target <component-id>
  439. # Replace with JSX from stdin
  440. echo '<Icon name="lucide:x" size={16} />' | figma-use node replace-with <id> --stdin
  441. ```
  442. ### Convert to component
  443. ```bash
  444. figma-use node to-component <id>
  445. figma-use node to-component "1:2 1:3 1:4" # Multiple
  446. ```
  447. ### Instance internal IDs
  448. ```bash
  449. figma-use set text "I123:456;789:10" "New text" # I<instance>;<internal>
  450. ```
  451. ### Row layout needs width
  452. ```bash
  453. # ❌ Collapses to 1×1
  454. <Frame flex="row" gap={8}>
  455. # ✅ Explicit width
  456. <Frame w={300} flex="row" gap={8}>
  457. ```
  458. ### Sections
  459. ```bash
  460. figma-use create section --name "Buttons" --x 0 --y 0 --width 600 --height 200
  461. figma-use node set-parent <id> --parent <section-id>
  462. ```
  463. ⚠️ Deleting section deletes all children!
  464. ### Comment-driven workflow
  465. Wait for designer feedback and react:
  466. ```bash
  467. figma-use comment watch --json
  468. ```
  469. Output when comment arrives:
  470. ```json
  471. {
  472. "id": "123456",
  473. "message": "Make this button bigger",
  474. "user": { "handle": "designer" },
  475. "client_meta": { "node_id": "1:23" }
  476. }
  477. ```
  478. Agent workflow — run once per comment, then restart:
  479. 1. `figma-use comment watch --json` — blocks until new comment
  480. 2. Parse the JSON, get `message` and `target_node` (exact element under comment)
  481. 3. Process the request (modify design, etc.)
  482. 4. Reply: `figma-use comment add "Done!" --reply <comment-id>`
  483. 5. Resolve: `figma-use comment resolve <comment-id>`
  484. 6. Exit. External runner restarts for next comment.
  485. Options:
  486. - `--timeout 60` — exit after 60s if no comment (returns `{"timeout":true}`)
  487. - `--interval 5` — poll every 5s (default: 3s)
  488. ### Vector paths — iterative workflow
  489. Draw, screenshot, adjust, repeat — like a designer tweaking Bezier curves:
  490. ```bash
  491. # 1. Draw initial shape
  492. figma-use create vector --path "M 50 0 L 100 100 L 0 100 Z" --fill "#F00"
  493. # 2. Check result
  494. figma-use export node <id> --output /tmp/shape.png
  495. # 3. Adjust: scale, move, flip
  496. figma-use path scale <id> --factor 0.8
  497. figma-use path move <id> --dx 20 --dy -10
  498. figma-use path flip <id> --axis x
  499. # 4. Or replace path entirely
  500. figma-use path set <id> "M 50 0 C 80 30 80 70 50 100 C 20 70 20 30 50 0 Z"
  501. # 5. Screenshot again, repeat until good
  502. figma-use export node <id> --output /tmp/shape.png
  503. ```
  504. For complex illustrations, import SVG:
  505. ```bash
  506. figma-use import --svg "$(cat icon.svg)"
  507. ```
README.md · README · 562 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # figma-use
  2. > **⚠️ Figma 126+ blocks remote debugging.** figma-use still works via `figma-use daemon start --pipe`. Or skip Figma entirely with **[OpenPencil](https://github.com/open-pencil/open-pencil)** — an open-source design editor that reads and writes .fig files, with built-in AI and P2P collaboration.
  3. CLI for Figma. Control it from the terminal — with commands or JSX.
  4. ```bash
  5. # Create and style
  6. figma-use create frame --width 400 --height 300 --fill "#FFF" --layout VERTICAL --gap 16
  7. figma-use create icon mdi:home --size 32 --color "#3B82F6"
  8. figma-use set layout 1:23 --mode GRID --cols "1fr 1fr 1fr" --gap 16
  9. # Or render JSX
  10. echo '<Frame style={{display: "grid", cols: "1fr 1fr", gap: 16}}>
  11. <Frame style={{bg: "#3B82F6", h: 100}} />
  12. <Frame style={{bg: "#10B981", h: 100}} />
  13. </Frame>' | figma-use render --stdin --x 100 --y 100
  14. ```
  15. ## Why
  16. Figma's official MCP plugin can read files but can't modify them. This one can.
  17. LLMs know CLI. LLMs know React. This combines both.
  18. CLI commands are compact — easy to read, easy to generate, easy to chain. When a task involves dozens of operations, every saved token matters.
  19. JSX is how LLMs already think about UI. They've seen millions of React components. Describing a Figma layout as `<Frame><Text>` is natural for them — no special training, no verbose schemas.
  20. ## Demo
  21. <table>
  22. <tr>
  23. <td width="50%">
  24. <a href="https://youtu.be/9eSYVZRle7o">
  25. <img src="https://img.youtube.com/vi/9eSYVZRle7o/maxresdefault.jpg" alt="Button components demo" width="100%">
  26. </a>
  27. <p align="center"><b>▶️ Button components</b></p>
  28. </td>
  29. <td width="50%">
  30. <a href="https://youtu.be/efJWp2Drzb4">
  31. <img src="https://img.youtube.com/vi/efJWp2Drzb4/maxresdefault.jpg" alt="Calendar demo" width="100%">
  32. </a>
  33. <p align="center"><b>▶️ Tailwind UI calendar</b></p>
  34. </td>
  35. </tr>
  36. </table>
  37. ## Installation
  38. ```bash
  39. npm install -g figma-use
  40. ```
  41. Or run directly without installing:
  42. ```bash
  43. npx figma-use status
  44. ```
  45. Start Figma with remote debugging enabled:
  46. ```bash
  47. # macOS
  48. open -a Figma --args --remote-debugging-port=9222
  49. # Windows
  50. "%LOCALAPPDATA%\Figma\Figma.exe" --remote-debugging-port=9222
  51. # Linux
  52. figma --remote-debugging-port=9222
  53. ```
  54. Check connection:
  55. ```bash
  56. figma-use status
  57. ```
  58. That's it. No plugins to install.
  59. ## Two Modes
  60. Imperative — one command at a time:
  61. ```bash
  62. figma-use create frame --width 400 --height 300 --fill "#FFF" --radius 12 --layout VERTICAL --gap 16
  63. ```
  64. Or declaratively — describe the structure in JSX and render it:
  65. ```bash
  66. echo '<Frame style={{p: 24, gap: 16, flex: "col", bg: "#FFF", rounded: 12}}>
  67. <Text style={{size: 24, weight: "bold", color: "#000"}}>Card Title</Text>
  68. <Text style={{size: 14, color: "#666"}}>Description</Text>
  69. </Frame>' | figma-use render --stdin --x 100 --y 200
  70. ```
  71. The stdin mode accepts pure JSX only — no variables, no logic. For components, variants, and conditions, use `.figma.tsx` files.
  72. **Elements:** `Frame`, `Rectangle`, `Ellipse`, `Text`, `Line`, `Star`, `Polygon`, `Vector`, `Group`, `Icon`, `Image`
  73. ## Examples
  74. ### Icons
  75. Insert any icon from Iconify by name. No downloading, no importing, no cleanup.
  76. ```bash
  77. figma-use create icon mdi:home
  78. figma-use create icon lucide:star --size 48 --color "#F59E0B"
  79. ```
  80. In JSX:
  81. ```tsx
  82. <Frame style={{ flex: 'row', gap: 8 }}>
  83. <Icon icon="mdi:home" size={24} color="#3B82F6" />
  84. <Icon icon="lucide:star" size={32} color="#F59E0B" />
  85. </Frame>
  86. ```
  87. Browse 150k+ icons: [icon-sets.iconify.design](https://icon-sets.iconify.design/)
  88. ### Images
  89. Load images from URL:
  90. ```tsx
  91. <Image src="https://example.com/photo.jpg" w={200} h={150} />
  92. ```
  93. ### Export to JSX
  94. Convert any Figma node back to JSX:
  95. ```bash
  96. figma-use export jsx 123:456 --pretty
  97. ```
  98. Output:
  99. ```tsx
  100. import { Frame, Icon, Text } from 'figma-use/render'
  101. export default function SaveButton() {
  102. return (
  103. <Frame name="SaveButton" w={120} h={44} bg="#1FAFBB" rounded={8} flex="row" gap={8}>
  104. <Icon name="lucide:save" size={18} color="#FFFFFF" />
  105. <Text size={16} color="#FFFFFF">
  106. Save
  107. </Text>
  108. </Frame>
  109. )
  110. }
  111. ```
  112. Match vector shapes to Iconify icons automatically:
  113. ```bash
  114. npm install whaticon # Optional dependency
  115. figma-use export jsx 123:456 --match-icons --prefer-icons lucide
  116. ```
  117. Compare two nodes as JSX diff:
  118. ```bash
  119. figma-use diff jsx 123:456 789:012
  120. ```
  121. ### Export to Storybook (Experimental)
  122. Export components as Storybook stories:
  123. ```bash
  124. figma-use export storybook --out ./stories
  125. figma-use export storybook --out ./stories --match-icons --prefer-icons lucide
  126. ```
  127. Generates `.stories.tsx` with typed props from component properties.
  128. ### Components
  129. In a `.figma.tsx` file you can define components. First call creates the master, the rest create instances:
  130. ```tsx
  131. import { defineComponent, Frame, Text } from 'figma-use/render'
  132. const Card = defineComponent(
  133. 'Card',
  134. <Frame style={{ p: 24, bg: '#FFF', rounded: 12 }}>
  135. <Text style={{ size: 18, color: '#000' }}>Card</Text>
  136. </Frame>
  137. )
  138. export default () => (
  139. <Frame style={{ gap: 16, flex: 'row' }}>
  140. <Card />
  141. <Card />
  142. <Card />
  143. </Frame>
  144. )
  145. ```
  146. ### Variants
  147. ComponentSet with all combinations:
  148. ```tsx
  149. import { defineComponentSet, Frame, Text } from 'figma-use/render'
  150. const Button = defineComponentSet(
  151. 'Button',
  152. {
  153. variant: ['Primary', 'Secondary'] as const,
  154. size: ['Small', 'Large'] as const
  155. },
  156. ({ variant, size }) => (
  157. <Frame
  158. style={{
  159. p: size === 'Large' ? 16 : 8,
  160. bg: variant === 'Primary' ? '#3B82F6' : '#E5E7EB',
  161. rounded: 8
  162. }}
  163. >
  164. <Text style={{ color: variant === 'Primary' ? '#FFF' : '#111' }}>
  165. {variant} {size}
  166. </Text>
  167. </Frame>
  168. )
  169. )
  170. export default () => (
  171. <Frame style={{ gap: 16, flex: 'col' }}>
  172. <Button variant="Primary" size="Large" />
  173. <Button variant="Secondary" size="Small" />
  174. </Frame>
  175. )
  176. ```
  177. This creates a real ComponentSet in Figma with all 4 variants, not just 4 separate buttons.
  178. ### Grid Layout
  179. CSS Grid for 2D layouts — calendars, dashboards, galleries:
  180. ```tsx
  181. <Frame
  182. style={{
  183. display: 'grid',
  184. cols: '1fr 1fr 1fr', // 3 equal columns
  185. rows: 'auto auto', // 2 rows
  186. gap: 16
  187. }}
  188. >
  189. <Frame style={{ bg: '#FF6B6B' }} />
  190. <Frame style={{ bg: '#4ECDC4' }} />
  191. <Frame style={{ bg: '#45B7D1' }} />
  192. <Frame style={{ bg: '#96CEB4' }} />
  193. <Frame style={{ bg: '#FFEAA7' }} />
  194. <Frame style={{ bg: '#DDA0DD' }} />
  195. </Frame>
  196. ```
  197. Supports `px`, `fr`, and `auto`/`hug`. Separate gaps with `colGap` and `rowGap`.
  198. In CLI:
  199. ```bash
  200. figma-use set layout <id> --mode GRID --cols "100px 1fr 100px" --rows "auto" --gap 16
  201. ```
  202. ### Variables as Tokens
  203. Bind colors to Figma variables by name. The hex value is a fallback:
  204. ```tsx
  205. import { defineVars, Frame, Text } from 'figma-use/render'
  206. const colors = defineVars({
  207. bg: { name: 'Colors/Gray/50', value: '#F8FAFC' },
  208. text: { name: 'Colors/Gray/900', value: '#0F172A' }
  209. })
  210. export default () => (
  211. <Frame style={{ bg: colors.bg }}>
  212. <Text style={{ color: colors.text }}>Bound to variables</Text>
  213. </Frame>
  214. )
  215. ```
  216. In CLI, use `var:Colors/Primary` or `$Colors/Primary` in any color option.
  217. ### Diffs
  218. Compare two frames and get a patch:
  219. ```bash
  220. figma-use diff create --from 123:456 --to 789:012
  221. ```
  222. ```diff
  223. --- /Card/Header #123:457
  224. +++ /Card/Header #789:013
  225. @@ -1,5 +1,5 @@
  226. type: FRAME
  227. size: 200 50
  228. pos: 0 0
  229. -fill: #FFFFFF
  230. +fill: #F0F0F0
  231. -opacity: 0.8
  232. +opacity: 1
  233. ```
  234. Apply the patch to the original frame. On apply, current state is validated against expected — if they don't match, it fails.
  235. Visual diff highlights changed pixels in red:
  236. ```bash
  237. figma-use diff visual --from 49:275096 --to 49:280802 --output diff.png
  238. ```
  239. | Before | After | Diff |
  240. | --------------------------------- | ------------------------------- | ------------------------------- |
  241. | ![before](assets/diff-before.png) | ![after](assets/diff-after.png) | ![diff](assets/diff-result.png) |
  242. ### Inspection
  243. Page tree in readable form:
  244. ```
  245. $ figma-use node tree
  246. [0] frame "Card" (1:23)
  247. 400×300 at (0, 0) | fill: #FFFFFF | layout: col gap=16
  248. [0] text "Title" (1:24)
  249. "Hello World" | 24px Inter Bold
  250. ```
  251. Export any node or screenshot with one command.
  252. ### Arrange
  253. Tidy up canvas layout — especially useful after agents create multiple frames at the same position:
  254. ```bash
  255. figma-use arrange # Grid-arrange all top-level nodes
  256. figma-use arrange --mode row --gap 60 # Horizontal row
  257. figma-use arrange --mode squarify --gap 60 # Smart packing for mixed sizes
  258. ```
  259. Uses d3-hierarchy treemap for `squarify` and `binary` modes — size-aware rectangle packing.
  260. ### Vectors
  261. Import SVG or work with paths directly — read, modify, translate, scale, flip:
  262. ```bash
  263. figma-use path get <id>
  264. figma-use path set <id> "M 0 0 L 100 100 Z"
  265. figma-use path scale <id> --factor 1.5
  266. figma-use path flip <id> --axis x
  267. ```
  268. ### Query
  269. Find nodes using XPath selectors:
  270. ```bash
  271. figma-use query "//FRAME" # All frames
  272. figma-use query "//FRAME[@width < 300]" # Narrower than 300px
  273. figma-use query "//COMPONENT[starts-with(@name, 'Button')]" # Name starts with
  274. figma-use query "//FRAME[contains(@name, 'Card')]" # Name contains
  275. figma-use query "//SECTION/FRAME" # Direct children
  276. figma-use query "//SECTION//TEXT" # All descendants
  277. figma-use query "//*[@cornerRadius > 0]" # Any node with radius
  278. ```
  279. Full XPath 3.1 support — predicates, functions, arithmetic, axes.
  280. ### Analyze
  281. Discovery tools for understanding design systems:
  282. ```bash
  283. # Find repeated patterns (potential components)
  284. figma-use analyze clusters
  285. # Color palette — usage frequency, variables vs hardcoded
  286. figma-use analyze colors
  287. figma-use analyze colors --show-similar # Find colors to merge
  288. # Typography — all font combinations
  289. figma-use analyze typography
  290. figma-use analyze typography --group-by size
  291. # Spacing — gap/padding values, grid compliance
  292. figma-use analyze spacing --grid 8
  293. # Accessibility snapshot — extract interactive elements tree
  294. figma-use analyze snapshot # Full page
  295. figma-use analyze snapshot <id> -i # Interactive elements only
  296. ```
  297. Example output:
  298. ```
  299. [0] 48× frame "Header" pattern (100% match)
  300. 1280×56 | Frame > [Frame×2, Text]
  301. examples: 53171:21628, 53171:21704
  302. #303030 ████████████████████ 1840× (var)
  303. #E5E5E5 ████████████████████ 1726× (var)
  304. #000000 ████████ 238×
  305. ```
  306. ### Lint (Experimental)
  307. Check designs for consistency, accessibility, and best practices:
  308. ```bash
  309. figma-use lint # Recommended rules
  310. figma-use lint --page "Components" # Lint specific page
  311. figma-use lint --preset strict # Stricter for production
  312. figma-use lint --preset accessibility # A11y checks only
  313. figma-use lint -v # With fix suggestions
  314. ```
  315. Output:
  316. ```
  317. ✖ Header/Title (1:234)
  318. ✖ Contrast ratio 2.1:1 is below AA threshold (4.5:1) color-contrast
  319. ⚠ Touch target 32x32 is below minimum 44x44 touch-target-size
  320. ⚠ Card/Body (1:567)
  321. ⚠ Hardcoded fill color #1A1A1A no-hardcoded-colors
  322. ℹ Frame with 3 children doesn't use Auto Layout prefer-auto-layout
  323. ────────────────────────────────────────────────────────────────
  324. ✖ 1 error ⚠ 3 warnings ℹ 1 info
  325. ```
  326. **17 rules** across 6 categories:
  327. | Category | Rules |
  328. | ------------- | ------------------------------------------------------------------------------------------ |
  329. | Design Tokens | `no-hardcoded-colors`, `consistent-spacing`, `consistent-radius`, `effect-style-required` |
  330. | Layout | `prefer-auto-layout`, `pixel-perfect` |
  331. | Typography | `text-style-required`, `min-text-size`, `no-mixed-styles` |
  332. | Accessibility | `color-contrast`, `touch-target-size` |
  333. | Structure | `no-default-names`, `no-hidden-layers`, `no-deeply-nested`, `no-empty-frames`, `no-groups` |
  334. | Components | `no-detached-instances` |
  335. JSON output for CI/CD:
  336. ```bash
  337. figma-use lint --json > report.json
  338. ```
  339. ### Comment-Driven Workflow (Experimental)
  340. AI agents can wait for Figma comments and respond:
  341. ```bash
  342. figma-use comment watch --json # Blocks until new comment
  343. figma-use comment resolve <id> # Mark as done
  344. ```
  345. Returns comment text, author, and `target_node` — the exact element under the comment pin. Agent processes the request, resolves the comment, then runs `watch` again for the next one.
  346. ## Full Command Reference
  347. See [REFERENCE.md](./REFERENCE.md) for the complete list of 100+ commands.
  348. ## MCP Server
  349. For AI agents that support Model Context Protocol:
  350. ```bash
  351. figma-use mcp serve
  352. ```
  353. Exposes 90+ tools. See [MCP.md](./MCP.md) for setup.
  354. ## Configuration
  355. For Storybook export and linting, create a config file:
  356. ```bash
  357. figma-use init
  358. ```
  359. Creates `.figma-use.json`:
  360. ```json
  361. {
  362. "storybook": {
  363. "page": "Components",
  364. "out": "./stories",
  365. "matchIcons": true,
  366. "preferIcons": ["lucide", "tabler"]
  367. },
  368. "lint": {
  369. "preset": "recommended"
  370. },
  371. "format": {
  372. "pretty": true,
  373. "semi": false,
  374. "singleQuote": true
  375. }
  376. }
  377. ```
  378. CLI arguments override config values.
  379. ## For AI Agents
  380. Includes [SKILL.md](./SKILL.md) — a reference for Claude Code, Cursor, and other agents.
  381. ## How It Works
  382. ```
  383. ┌─────────────┐ ┌─────────────┐
  384. │ Terminal │────CDP────▶│ Figma │
  385. │ figma-use │ port 9222 │ │
  386. └─────────────┘ └─────────────┘
  387. ```
  388. figma-use communicates directly with Figma via Chrome DevTools Protocol (CDP). Just start Figma with `--remote-debugging-port=9222` and you're ready.
  389. > **Non-default port?** Pass `--port <N>` to any command, or set the `FIGMA_PORT` env var:
  390. > ```bash
  391. > open -a Figma --args --remote-debugging-port=9333
  392. > figma-use get components --port 9333
  393. > # or
  394. > FIGMA_PORT=9333 figma-use get components
  395. > ```
  396. Commands are executed via `Runtime.evaluate` in Figma's JavaScript context, with full access to the Plugin API.
  397. ### Daemon
  398. Optional daemon keeps the CDP connection warm for faster sequential commands:
  399. ```bash
  400. figma-use daemon start # Background daemon (~25% faster commands)
  401. figma-use daemon stop # Stop daemon
  402. figma-use daemon status # Check if running
  403. ```
  404. ### Pipe Transport
  405. For Figma 126+ without admin access to patch, the daemon can launch Figma with `--remote-debugging-pipe` instead:
  406. ```bash
  407. figma-use daemon start --pipe # Launches Figma, connects via stdio pipes
  408. ```
  409. Set `FIGMA_BIN` for custom binary locations. The daemon holds the pipe connection — all commands route through it automatically.
  410. ## License
  411. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.