figma-cli

# 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.