| name | figma-cli |
| description | Build and edit designs directly in Figma Desktop from the terminal using the figma-cli command (controls Figma live over a local connection, no API key). Use whenever the user wants to create, render, or edit Figma frames/components/variants, add or import design tokens/variables (shadcn, Tailwind, DTCG, CSS), extract a design system to DESIGN.md, generate gradients/wallpapers, animate with Figma Motion, run accessibility audits, or connect an AI assistant to their Figma. Triggers on "build/make X in Figma", "add my design system", "create N buttons/cards", "use my variables", "export the design system", "check contrast". |
Using figma-cli
figma-cli controls Figma Desktop directly (no API key). It runs in any
terminal. Open Figma Desktop, then figma-cli connect once per session.
If the figma-cli command is not found, the tool isn't installed yet — see
Installation at the bottom. Never show raw terminal commands to the user;
run them silently and give friendly feedback.
Connect (pick one mode)
figma-cli connect — Yolo (default): patches Figma Desktop once, fully automatic.figma-cli connect --browser — Browser: drives Figma in a Chromium browser via
a local connection; never modifies the Figma app. Use when patching the desktop
app is undesirable (compliance / locked-down machine / no "App Management" permission).figma-cli connect --safe — Safe: official plugin (Plugins → Development → FigCli).
Golden rules
- Create frames with
render / render-batch — they have smart positioning.
NEVER use eval to create visual nodes (no positioning, bypasses guards).
- "N buttons/cards" = N separate top-level nodes, not one wrapper frame
containing N children. Use
render-batch '[...]' or shadcn add <c> --count N.
- Never delete the user's existing nodes.
- After creating, verify:
figma-cli verify "<id>" --measure (returns a
screenshot + real w/h so you catch size bugs by numbers, not by eye).
Design tokens / variables
- Bind colors at creation with
var:name, never raw hex when a system is loaded:
<Frame bg="var:primary"><Text color="var:on-primary">Go</Text></Frame>
- Pin a named collection when the user names one:
render-batch ... --collection figma.
- Import a system:
figma-cli import tailwind.config.js | globals.css | tokens.json.
- Export the open file's system:
figma-cli extract → DESIGN.md.
JSX cheatsheet (render)
- Layout:
flex="row|col" gap={16} p={24} px py pt pr pb pl justify="center|between" items="center"
- Size:
w={320} h={200} w="fill" w="hug" w="60%" (percent resolves vs parent)
- Look:
bg="#fff" stroke="#000" strokeWidth={2} rounded={12} shadow="..." opacity={0.8}
- Text:
<Text size={14} weight="semibold" color="#000" lineHeight={20} truncate maxLines={2} w="fill">
- Icons (real SVG, never emojis):
<Icon name="lucide:home" size={20} color="var:primary" />
- Dividers: a thin child (
<Frame w={1} bg="var:border" />) auto-fills the cross axis.
Text wrapping (most common bug)
For text to wrap, the parent AND every <Text> need w="fill", and the parent
needs flex="col" or flex="row".
Recreating a component from an extracted DESIGN.md (hard rule)
Don't read the structure markdown by hand. Use:
figma-cli spec <Component> → authoritative variant axes + sample size (compact).
Build EXACTLY to those axes (e.g. Variant × Size = a Component Set, not one node).figma-cli spec <Component> --check <nodeId> → enforces it (exit 1 on mismatch:
wrong structure, missing axes, wrong height). Treat non-zero as "not done".
Handy commands
figma-cli connect # connect to Figma Desktop (yolo)
figma-cli render '<Frame>...</Frame>' # one frame
figma-cli render-batch '[ "<Frame>", ... ]' --direction row
figma-cli shadcn add button --count 3 # N distinct shadcn primitives
figma-cli node to-component "<id>" # promote to a component
figma-cli verify "<id>" --measure # screenshot + dimensions
figma-cli a11y audit # contrast / touch / text checks
figma-cli tokens preset shadcn # 244 primitives + semantic (light/dark)
figma-cli var visualize # show colors on canvas
figma-cli motion preset <id> fade-up # animate (Figma Motion, beta)
figma-cli blocks create dashboard-01 # pre-built dashboard layout
Installation
figma-cli is a Node CLI (Node ≥ 18) that talks to Figma Desktop locally. If the
figma-cli binary is missing, get the project from
https://github.com/silships/figma-cli and run npm install in it, then invoke it
as node src/index.js <command> (or link it as figma-cli). Full command
reference and JSX docs live in that repo's README.md and REFERENCE.md.
