figma-cli

---
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
1. **Create frames with `render` / `render-batch`** — they have smart positioning.
   NEVER use `eval` to create visual nodes (no positioning, bypasses guards).
2. **"N buttons/cards" = N separate top-level nodes**, not one wrapper frame
   containing N children. Use `render-batch '[...]'` or `shadcn add <c> --count N`.
3. **Never delete the user's existing nodes.**
4. 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.

More agent context in silships/figma-cli

One other file this repository gives its agents.