Figma (mcp-figma)
Drive Figma Desktop from the terminal through the silships figma-cli, published as figma-ds-cli. A coding agent can read, author, modify and export designs, tokens and components through the CLI. It can also optionally pull design context out of Figma through a Figma MCP via Code Mode.
The CLI is the primary surface. The MCP is opt-in. Deep operational detail lives in references/figma-cli-reference.md.
Naming trap (read first). The silships tool publishes to npm as figma-ds-cli, the unambiguous binary.
The npm package literally named figma-cli is an UNRELATED tool (unic/figma-cli, bin figma). Never run npm i -g figma-cli.
The figma-cli command exists only when installed from the silships repo's main branch. That branch exposes both figma-ds-cli and figma-cli. This skill uses figma-ds-cli as the canonical command throughout.
Version trap. npm publishes only figma-ds-cli@1.0.0, a minimal build with no --safe, no daemon, no extract and ~12 commands.
The full surface this skill documents includes safe connect, daemon, extract/import and ~130 commands. That surface is 1.2.0, available only from the silships repo.
Install through scripts/install.sh with --source repo or --source auto. The latter upgrades when npm is stale. Then confirm figma-ds-cli --version is >= 1.2.0.
1. WHEN TO USE
Activation Triggers
Use when the user wants to:
- Drive Figma Desktop from the terminal: create/render frames, components, icons, layouts, or images.
- Work a design system in Figma: tokens, variables, collections,
var:name binding, shadcn primitives.
- Inspect or export from Figma:
extract to DESIGN.md, export PNG/SVG/JSX/CSS/Tailwind/Storybook, screenshots, a11y audits.
- Import a design system INTO Figma: from Tailwind config, CSS variables,
tokens.json, or Storybook.
- Set up or troubleshoot the figma-cli connection or daemon (safe plugin vs yolo patch, daemon health).
- Optionally pull design context FROM Figma into the agent via a Figma MCP (Framelink
figma) through Code Mode.
Keyword Triggers: "figma cli", "figma-ds-cli", "figma desktop", "render in figma", "figma tokens/variables", "extract DESIGN.md", "export from figma", "connect to figma", "figma daemon", "figma mcp".
Use Cases
Connect / setup (CLI). Verify the binary, choose a connect mode (safe plugin vs yolo patch), bring up the daemon, confirm health.
Inspect / export (CLI, read-only). List/find nodes, get properties, extract a DESIGN.md, export assets/CSS/Tailwind/JSX/Storybook, run a11y audits, none of which change the Figma document.
Author / modify (CLI, gated). You can render JSX, create frames/components/icons, set properties, bind variables and generate variants.
Every operation changes the document, is gated and is design-affecting. Before authoring, pair with sk-design-md-generator for a measured Style Reference (extracted design tokens).
This transport moves and renders designs. It does not produce the measured reference itself.
Design-system / tokens (CLI, gated). Create token collections, import from Tailwind/CSS/tokens/Storybook, bind var:name. Ground token and variable choices in a measured reference: the sk-design-md-generator pairing (a measured Style Reference of extracted design tokens) applies before any token authoring, same as author/modify.
Optional MCP context pull (Code Mode). When the agent needs Figma design context as model input (design data, variables, screenshots), call the Framelink figma manual through Code Mode.
When NOT to Use
Skip this skill when:
- The work is generic app coding with no Figma input: use
sk-code.
- The work is extracting a measured Style Reference (design tokens) from a live website's real CSS. That is
sk-design-md-generator, and this skill is the Figma transport.
- The task is browser debugging or visual preview of a built page. That is
mcp-chrome-devtools.
- Figma Desktop is not installed or not open. The CLI drives the live Desktop session and cannot work without it.
2. SMART ROUTING
The mcp-tooling hub routes a Figma request here: the request names figma, figma-ds-cli or Figma Desktop with design work, and the hub's mcp-figma mode signal selects this packet.
The direction splits in two: the terminal CLI answers every create, inspect, export, token and connect task, and the optional Figma MCP through Code Mode is opt-in and only for pulling context out of Figma.
references/figma-cli-reference.md and references/mcp-wiring.md are the first leaves the hub ROUTER.md names for this mode, and references/figma-cli-reference.md is the baseline every scored route loads.
Both connect traps bind before any command: the canonical binary is figma-ds-cli, never the unrelated npm figma-cli, and npm publishes only a minimal 1.0.0 build, so the surface this packet documents comes from scripts/install.sh.
Every mutating or destructive command is gated, and sk-design-md-generator supplies the measured Style Reference first.
Read ROUTER.md before selecting skill-local resources; open only the matched files.
3. HOW IT WORKS
First Step (Always): verify the binary + Figma Desktop
# Canonical binary = figma-ds-cli. The npm package 'figma-cli' is an UNRELATED tool (unic/figma-cli).
BIN=""
command -v figma-ds-cli >/dev/null && BIN="figma-ds-cli"
[ -z "$BIN" ] && command -v figma-cli >/dev/null && BIN="figma-cli" # only if installed from silships repo
[ -z "$BIN" ] && { echo "figma-ds-cli not found, see INSTALL-GUIDE.md (do NOT 'npm i -g figma-cli')"; exit 1; }
"$BIN" --version; "$BIN" --help | head -1
Figma Desktop must be open with a file, since figma-cli drives the live Desktop session (no Figma API key). Node >=18. macOS is the supported baseline.
Connect modes + daemon
- Safe (default):
figma-ds-cli connect --safe runs the FigCli plugin bridge, with no patch. Import plugin/manifest.json once, then keep Plugins → Development → FigCli open each session.
- Yolo (gated):
figma-ds-cli connect patches Figma Desktop app.asar, codesigns on macOS, restarts Figma with CDP on port 9222. May need Full Disk Access/admin and breaks when Figma updates. Never run without explicit consent + a stated rollback (figma-ds-cli unpatch).
- Daemon: local HTTP server on
127.0.0.1:3456 (not a socket), auth via X-Daemon-Token at ~/.figma-ds-cli/.daemon-token, PID ~/.figma-cli-daemon.pid, idle ~60 min, not reboot-persistent. Verbs: daemon status | diagnose | start | stop | restart | reconnect. "Unauthorized" → daemon diagnose then daemon restart (never auto-delete the token).
Command classes (gating)
The full per-command taxonomy lives in references/tool-surface.md. Summary:
- READ-ONLY (safe default):
status, var list/find, get, find, inspect, node tree, extract, export*, export-jsx, export-storybook, analyze*, a11y*, files, --dry-run variants. (Local exports still write files, so require an explicit output path, never silently overwrite.)
- MUTATING (gate): This class includes all
create*/render*/tokens */var create|bind|set|rename|visualize, bind *, set *, layout verbs, duplicate, use/theme, node to-component, slot/sizes/variants/combos, shadcn add, import, lint --fix, screenshot-url, recreate-url and gradient mesh.
- App-level commands are
connect, unpatch, daemon start/stop/restart, config set and init-agent.
- Design-affecting MUTATING verbs cover authoring, tokens, binding and variants. All MUTATING verbs except app-level connection, daemon and config verbs require the
sk-design-md-generator pairing precondition. A measured Style Reference (extracted design tokens) grounds them before you execute them here.
- DESTRUCTIVE (confirm + explicit target + rollback):
var delete-all, var delete-batch, delete/remove, node delete, undo, unwrap, fj delete, plugins uninstall, dev unlink, component prop delete, grid clear, annotate clear.
- ARBITRARY (treat as mutating, review first):
eval, raw, run.
Optional Figma MCP via Code Mode (opt-in)
The skill works fully with the CLI alone.
When you need to pull design context FROM Figma, use the Framelink figma manual already registered in Code Mode (figma-developer-mcp, stdio, needs a Figma personal token).
Before invoking a tool, discover it with search_tools() or tool_info().
Calls go through call_tool_chain() with the name figma.figma_<tool>. Store the token in .env as figma_FIGMA_API_KEY; Code Mode prefixes the manual name.
Find the full details and snippet in references/mcp-wiring.md.
4. RULES
✅ ALWAYS
- ALWAYS verify the binary first. Prefer
figma-ds-cli, and only use figma-cli if it resolves to the silships tool (--version/--help), since the npm figma-cli package is unrelated. Fail closed with install guidance if neither is the silships tool.
- ALWAYS require Figma Desktop open with a file before any CLI or desktop operation, since the CLI drives the live session.
- ALWAYS confirm daemon health before daemon-backed commands (
daemon status/diagnose; endpoint 127.0.0.1:3456, token present).
- ALWAYS prefer
connect --safe for setup, and treat the yolo patch as a gated, consented action.
- ALWAYS gate every DESTRUCTIVE verb behind explicit user confirmation, an explicit target node/file, a command preview, and a one-line rollback (prefer duplicating the file/page/selection first).
- ALWAYS treat
eval, raw, and run as arbitrary mutation, reviewing the code/command before running, even when the prompt sounds exploratory.
- ALWAYS require an explicit output path for local exports (
extract/export/export-jsx) and never silently overwrite existing files.
- ALWAYS pair with
sk-design-md-generator BEFORE any design-affecting operation. Pair in both directions.
- Pair when a Figma read/export feeds a design decision.
- Pair before every design-affecting authoring path: render, create frames/components/icons, bind variables, generate variants and token/variable work.
The mandatory cross-hub pairing (hub ADR-002,
crossHubPairing) makes a measured Style Reference (extracted design tokens) the precondition, not an afterthought. This skill owns the transport. The companion skill produces the measured reference.
⛔ NEVER
- NEVER
npm i -g figma-cli, because that installs the unrelated unic/figma-cli. Install figma-ds-cli (npm) or the silships repo.
- NEVER auto-apply the yolo
app.asar patch without explicit consent and a stated figma-ds-cli unpatch rollback. Never patch during install or routine startup.
- NEVER run a destructive verb via the active-selection fallback, and require an explicit target id/name.
- NEVER expose or paste the daemon token (
~/.figma-ds-cli/.daemon-token) in user-facing output, and keep all local services bound to 127.0.0.1.
- NEVER run or recommend
init-agent by default, because it writes AGENTS.md/.cursor/rules into the working repo.
- NEVER claim the optional Figma MCP works until Code Mode discovery (
list_tools()/tool_info()) confirms the figma manual and its tool names.
⚠️ ESCALATE IF
- ESCALATE IF the binary is missing or ambiguous, asking whether to install
figma-ds-cli (npm) or the silships repo build. Do not guess.
- ESCALATE IF Figma Desktop is not running or daemon diagnosis fails after a reconnect.
- ESCALATE IF a yolo patch, a destructive verb, a broad delete/undo/unwrap, or an arbitrary
eval/raw/run is requested, describing the effect + rollback, then wait for confirmation.
- ESCALATE IF the optional Figma MCP is requested but no Figma token / Code Mode manual is configured, surfacing the
.env (figma_FIGMA_API_KEY) requirement. Do not paste credentials.
- ESCALATE IF CLI and MCP results disagree about a file/node/variable state, and ask which source prevails before mutating.
5. SUCCESS CRITERIA
Connect complete when:
- ✅ The binary was verified (
figma-ds-cli or confirmed-silships figma-cli), Figma Desktop is open, the chosen connect mode ran, and daemon status is healthy.
Read / export complete when:
- ✅ The requested data/asset was captured to an explicit path with no overwrite, and no mutating or destructive command ran.
Author / modify complete when:
- ✅ The
sk-design-md-generator pairing supplied a measured Style Reference (extracted design tokens) first (grounding what to render/bind/tokenize); the user confirmed the target and intent; mutating commands ran; destructive verbs had an explicit target + rollback; the result was verified (e.g. get/verify).
Optional MCP context complete when:
- ✅ Code Mode discovery confirmed the
figma manual + tool names, the token was configured, and the context was pulled without claiming unverified tools.
Always:
- ✅ Figma Desktop was confirmed running; no yolo patch or destructive verb ran unconfirmed; the daemon token was never exposed.
6. INTEGRATION POINTS
Tool Usage Guidelines
- Bash owns all
figma-ds-cli operations (connect, daemon, inspect, export, author, tokens).
- Code Mode (
mcp__code_mode__call_tool_chain) owns the optional Figma MCP calls (Framelink figma).
- Read/Grep/Glob load references and inspect CLI output / exported files.
Cross-Workflow Contracts
sk-design-md-generator produces a measured Style Reference (extracted design tokens) as a mandatory cross-hub pairing (hub ADR-002).
- Apply it whenever a Figma read/export feeds a design decision, including grounding and token, type or layout choices.
- Use it as a precondition before every design-affecting authoring path: render/create, variable binding, variants and token collections.
This skill is the transport. The companion skill produces the measured reference.
sk-code owns adapting extracted tokens / DESIGN.md / exported code into a real application, and verifying it.
mcp-chrome-devtools is used only for a last-mile browser preview of an implemented page, never to operate Figma.
External Tools
- figma-ds-cli (silships, MIT): install from npm (
figma-ds-cli) or the silships repo, and see INSTALL-GUIDE.md. Requires Figma Desktop open. Not vendored into this repo.
- Figma MCP (optional): the Framelink
figma-developer-mcp manual already in this project's Code Mode .utcp_config.json, which needs figma_FIGMA_API_KEY in .env.
Knowledge Base Dependencies
Required: references/figma-cli-reference.md (binary/daemon/connect baseline). Conditional: tool-surface.md (gating), mcp-wiring.md (MCP), troubleshooting.md (errors).
7. REFERENCES AND RELATED RESOURCES
Core References
- figma-cli-reference.md - Binary identity + verification, Node/macOS baseline, Figma Desktop requirement, connect modes, daemon model, and command examples.
- tool-surface.md - The read-only / mutating / destructive command taxonomy, the destructive set, the
eval/raw/run rule, and the export no-overwrite rule.
- mcp-wiring.md - The optional Figma MCP (Framelink
figma) via Code Mode: the registered manual, the .env token, discovery, and a call_tool_chain example.
- troubleshooting.md - Failure modes and fixes (binary collision, Desktop not running, daemon Unauthorized, port conflicts, Code Mode env-var prefix).
Templates and Assets
- utcp-figma-manual.md - Paste-ready Framelink
figma .utcp_config.json manual entry, the .env note, and a call_tool_chain example for the optional Code Mode path.
- env-template.md - The single prefixed
figma_FIGMA_API_KEY .env line for the optional Figma MCP token.
Reference Loading Notes
- References are the primary loaded resources.
figma-cli-reference.md is the baseline (always). Load tool-surface.md for author/modify/token work, mcp-wiring.md only for MCP intent, troubleshooting.md for setup/errors.
- Load the
assets/ snippets only for MCP_CONTEXT intent, alongside mcp-wiring.md.
- Keep
ROUTER.md as the single routing authority.
Related Resources
The router (in ROUTER.md) discovers reference and asset docs dynamically. Start from references/figma-cli-reference.md for the CLI/daemon/connect model, load references/tool-surface.md for the gating taxonomy, references/mcp-wiring.md for the optional Code Mode path, and references/troubleshooting.md for failures. References stay the primary loaded resources.
Assets: assets/utcp-figma-manual.md (paste-ready Framelink figma .utcp_config.json manual + .env note) and assets/env-template.md (the prefixed figma_FIGMA_API_KEY line), loaded only for the optional MCP_CONTEXT path.
Scripts: scripts/install.sh (install + verify), scripts/doctor.sh (report-only diagnostics), scripts/connect-safe.sh, scripts/connect-yolo.sh, scripts/daemon.sh, scripts/unpatch.sh, scripts/print-utcp-snippets.sh.
Examples: examples/README.md - safe worked walkthroughs mirroring the playbook scenarios (safe connect + daemon health, read-only inspect/export, optional MCP context pull). They live outside the references//assets/ discovery roots, so they are linked here rather than auto-loaded by the router.
Related skills: sk-design-md-generator (a measured Style Reference of extracted design tokens, applied whenever a read/export feeds a decision), sk-code (adapting exports into an app), mcp-code-mode (the optional MCP transport), mcp-chrome-devtools (browser preview only), and system-spec-kit when packet documentation or memory continuity applies. When a request or a frame leaves a visual value open (spacing, type, color, radius, shadow or motion), or a value sits off every token and scale, load sk-code-frontend (web-visual-values.md) and decide it there.
A Figma read that feeds code ends at the five-pass check in .skilled/skills/sk-code/sk-code-frontend/references/figma-to-code.md.
Install guide: INSTALL-GUIDE.md.
Upstream: figma-cli is silships/figma-cli (npm figma-ds-cli, MIT). The optional MCP is the community Framelink figma-developer-mcp. This skill documents driving the installed tool from the terminal, and it does not vendor or redistribute it.
1---2name: mcp-figma3description: "Figma CLI orchestrator: drives figma-ds-cli for terminal Figma design work, with an optional Figma MCP via Code Mode."4compatibility: Requires Figma Desktop (open with a file), Node.js >=18, and the silships figma-ds-cli on PATH. macOS is the supported baseline; the optional Figma MCP uses this project's Code Mode.5allowed-tools: [Read, Bash, Grep, Glob, mcp__code_mode__call_tool_chain]6version: 1.2.3.07user-invocable: true8metadata:9 source: https://skillmd.com/skills/michelkerkmeester/mcp-figma10---1112# Figma (mcp-figma)1314Drive **Figma Desktop from the terminal** through the silships **figma-cli**, published as `figma-ds-cli`. A coding agent can read, author, modify and export designs, tokens and components through the CLI. It can also **optionally** pull design context out of Figma through a Figma **MCP via Code Mode**.15The CLI is the primary surface. The MCP is opt-in. Deep operational detail lives in [`references/figma-cli-reference.md`](references/figma-cli-reference.md).1617> **Naming trap (read first).** The silships tool publishes to npm as **`figma-ds-cli`**, the unambiguous binary.18> The npm package literally named **`figma-cli` is an UNRELATED tool** (unic/figma-cli, bin `figma`). Never run `npm i -g figma-cli`.19> The `figma-cli` command exists only when installed from the silships repo's `main` branch. That branch exposes both `figma-ds-cli` and `figma-cli`. This skill uses **`figma-ds-cli`** as the canonical command throughout.20>21> **Version trap.** npm publishes only **`figma-ds-cli@1.0.0`**, a minimal build with **no `--safe`, no `daemon`, no `extract`** and ~12 commands.22> The full surface this skill documents includes safe connect, daemon, extract/import and ~130 commands. That surface is **1.2.0**, available only from the silships repo.23> Install through `scripts/install.sh` with `--source repo` or `--source auto`. The latter upgrades when npm is stale. Then confirm `figma-ds-cli --version` is `>= 1.2.0`.2425---2627## 1. WHEN TO USE2829### Activation Triggers3031**Use when** the user wants to:32- Drive Figma Desktop from the terminal: create/render frames, components, icons, layouts, or images.33- Work a design system in Figma: tokens, variables, collections, `var:name` binding, shadcn primitives.34- Inspect or export from Figma: `extract` to DESIGN.md, export PNG/SVG/JSX/CSS/Tailwind/Storybook, screenshots, a11y audits.35- Import a design system INTO Figma: from Tailwind config, CSS variables, `tokens.json`, or Storybook.36- Set up or troubleshoot the figma-cli connection or daemon (safe plugin vs yolo patch, daemon health).37- Optionally pull design context FROM Figma into the agent via a Figma MCP (Framelink `figma`) through Code Mode.3839**Keyword Triggers**: "figma cli", "figma-ds-cli", "figma desktop", "render in figma", "figma tokens/variables", "extract DESIGN.md", "export from figma", "connect to figma", "figma daemon", "figma mcp".4041### Use Cases4243**Connect / setup (CLI).** Verify the binary, choose a connect mode (safe plugin vs yolo patch), bring up the daemon, confirm health.4445**Inspect / export (CLI, read-only).** List/find nodes, get properties, `extract` a DESIGN.md, export assets/CSS/Tailwind/JSX/Storybook, run a11y audits, none of which change the Figma document.4647**Author / modify (CLI, gated).** You can render JSX, create frames/components/icons, set properties, bind variables and generate variants.48Every operation changes the document, is gated and is design-affecting. Before authoring, pair with `sk-design-md-generator` for a measured Style Reference (extracted design tokens).49This transport moves and renders designs. It does not produce the measured reference itself.5051**Design-system / tokens (CLI, gated).** Create token collections, import from Tailwind/CSS/tokens/Storybook, bind `var:name`. Ground token and variable choices in a measured reference: the `sk-design-md-generator` pairing (a measured Style Reference of extracted design tokens) applies before any token authoring, same as author/modify.5253**Optional MCP context pull (Code Mode).** When the agent needs Figma design context as model input (design data, variables, screenshots), call the Framelink `figma` manual through Code Mode.5455### When NOT to Use5657**Skip this skill when:**58- The work is generic app coding with no Figma input: use `sk-code`.59- The work is extracting a measured Style Reference (design tokens) from a live website's real CSS. That is `sk-design-md-generator`, and this skill is the Figma transport.60- The task is browser debugging or visual preview of a built page. That is `mcp-chrome-devtools`.61- Figma Desktop is not installed or not open. The CLI drives the live Desktop session and cannot work without it.6263---6465## 2. SMART ROUTING6667The `mcp-tooling` hub routes a Figma request here: the request names `figma`, `figma-ds-cli` or Figma Desktop with design work, and the hub's `mcp-figma` mode signal selects this packet.6869The direction splits in two: the terminal CLI answers every create, inspect, export, token and connect task, and the optional Figma MCP through Code Mode is opt-in and only for pulling context out of Figma.7071`references/figma-cli-reference.md` and `references/mcp-wiring.md` are the first leaves the hub `ROUTER.md` names for this mode, and `references/figma-cli-reference.md` is the baseline every scored route loads.7273Both connect traps bind before any command: the canonical binary is `figma-ds-cli`, never the unrelated npm `figma-cli`, and npm publishes only a minimal 1.0.0 build, so the surface this packet documents comes from `scripts/install.sh`.7475Every mutating or destructive command is gated, and `sk-design-md-generator` supplies the measured Style Reference first.7677Read [`ROUTER.md`](./ROUTER.md) before selecting skill-local resources; open only the matched files.7879---8081## 3. HOW IT WORKS8283### First Step (Always): verify the binary + Figma Desktop8485```bash86# Canonical binary = figma-ds-cli. The npm package 'figma-cli' is an UNRELATED tool (unic/figma-cli).87BIN=""88command -v figma-ds-cli >/dev/null && BIN="figma-ds-cli"89[ -z "$BIN" ] && command -v figma-cli >/dev/null && BIN="figma-cli" # only if installed from silships repo90[ -z "$BIN" ] && { echo "figma-ds-cli not found, see INSTALL-GUIDE.md (do NOT 'npm i -g figma-cli')"; exit 1; }91"$BIN" --version; "$BIN" --help | head -192```9394Figma Desktop must be **open with a file**, since figma-cli drives the live Desktop session (no Figma API key). Node `>=18`. macOS is the supported baseline.9596### Connect modes + daemon9798- **Safe (default): `figma-ds-cli connect --safe`** runs the FigCli plugin bridge, with **no patch**. Import `plugin/manifest.json` once, then keep `Plugins → Development → FigCli` open each session.99- **Yolo (gated): `figma-ds-cli connect`** patches Figma Desktop `app.asar`, codesigns on macOS, restarts Figma with CDP on port `9222`. May need Full Disk Access/admin and **breaks when Figma updates**. **Never run without explicit consent + a stated rollback** (`figma-ds-cli unpatch`).100- **Daemon**: local HTTP server on `127.0.0.1:3456` (not a socket), auth via `X-Daemon-Token` at `~/.figma-ds-cli/.daemon-token`, PID `~/.figma-cli-daemon.pid`, idle ~60 min, not reboot-persistent. Verbs: `daemon status | diagnose | start | stop | restart | reconnect`. "Unauthorized" → `daemon diagnose` then `daemon restart` (never auto-delete the token).101102### Command classes (gating)103104The full per-command taxonomy lives in [`references/tool-surface.md`](references/tool-surface.md). Summary:105- **READ-ONLY** (safe default): `status`, `var list/find`, `get`, `find`, `inspect`, `node tree`, `extract`, `export*`, `export-jsx`, `export-storybook`, `analyze*`, `a11y*`, `files`, `--dry-run` variants. (Local exports still write files, so require an explicit output path, never silently overwrite.)106- **MUTATING (gate):** This class includes all `create*`/`render*`/`tokens *`/`var create|bind|set|rename|visualize`, `bind *`, `set *`, layout verbs, `duplicate`, `use/theme`, `node to-component`, `slot/sizes/variants/combos`, `shadcn add`, `import`, `lint --fix`, `screenshot-url`, `recreate-url` and `gradient mesh`.107 - App-level commands are `connect`, `unpatch`, `daemon start/stop/restart`, `config set` and `init-agent`.108 - Design-affecting MUTATING verbs cover authoring, tokens, binding and variants. All MUTATING verbs except app-level connection, daemon and config verbs require the `sk-design-md-generator` pairing precondition. A measured Style Reference (extracted design tokens) grounds them before you execute them here.109- **DESTRUCTIVE** (confirm + explicit target + rollback): `var delete-all`, `var delete-batch`, `delete/remove`, `node delete`, `undo`, `unwrap`, `fj delete`, `plugins uninstall`, `dev unlink`, `component prop delete`, `grid clear`, `annotate clear`.110- **ARBITRARY** (treat as mutating, review first): `eval`, `raw`, `run`.111112### Optional Figma MCP via Code Mode (opt-in)113114The skill works **fully with the CLI alone**.115When you need to pull design context FROM Figma, use the **Framelink `figma` manual already registered in Code Mode** (`figma-developer-mcp`, stdio, needs a Figma personal token).116Before invoking a tool, discover it with `search_tools()` or `tool_info()`.117Calls go through `call_tool_chain()` with the name `figma.figma_<tool>`. Store the token in `.env` as `figma_FIGMA_API_KEY`; Code Mode prefixes the manual name.118Find the full details and snippet in [`references/mcp-wiring.md`](references/mcp-wiring.md).119120---121122## 4. RULES123124### ✅ ALWAYS1251261. **ALWAYS verify the binary first.** Prefer `figma-ds-cli`, and only use `figma-cli` if it resolves to the silships tool (`--version`/`--help`), since the npm `figma-cli` package is unrelated. Fail closed with install guidance if neither is the silships tool.1272. **ALWAYS require Figma Desktop open with a file** before any CLI or desktop operation, since the CLI drives the live session.1283. **ALWAYS confirm daemon health** before daemon-backed commands (`daemon status`/`diagnose`; endpoint `127.0.0.1:3456`, token present).1294. **ALWAYS prefer `connect --safe`** for setup, and treat the yolo patch as a gated, consented action.1305. **ALWAYS gate every DESTRUCTIVE verb** behind explicit user confirmation, an explicit target node/file, a command preview, and a one-line rollback (prefer duplicating the file/page/selection first).1316. **ALWAYS treat `eval`, `raw`, and `run` as arbitrary mutation**, reviewing the code/command before running, even when the prompt sounds exploratory.1327. **ALWAYS require an explicit output path for local exports** (`extract`/`export`/`export-jsx`) and never silently overwrite existing files.1338. **ALWAYS pair with `sk-design-md-generator` BEFORE any design-affecting operation.** Pair in both directions.134 - Pair when a Figma read/export feeds a design decision.135 - Pair before every design-affecting authoring path: render, create frames/components/icons, bind variables, generate variants and token/variable work.136 The mandatory cross-hub pairing (hub ADR-002, `crossHubPairing`) makes a measured Style Reference (extracted design tokens) the precondition, not an afterthought. This skill owns the transport. The companion skill produces the measured reference.137138### ⛔ NEVER1391401. **NEVER `npm i -g figma-cli`**, because that installs the unrelated unic/figma-cli. Install `figma-ds-cli` (npm) or the silships repo.1412. **NEVER auto-apply the yolo `app.asar` patch** without explicit consent and a stated `figma-ds-cli unpatch` rollback. Never patch during install or routine startup.1423. **NEVER run a destructive verb via the active-selection fallback**, and require an explicit target id/name.1434. **NEVER expose or paste the daemon token** (`~/.figma-ds-cli/.daemon-token`) in user-facing output, and keep all local services bound to `127.0.0.1`.1445. **NEVER run or recommend `init-agent` by default**, because it writes `AGENTS.md`/`.cursor/rules` into the working repo.1456. **NEVER claim the optional Figma MCP works** until Code Mode discovery (`list_tools()`/`tool_info()`) confirms the `figma` manual and its tool names.146147### ⚠️ ESCALATE IF1481491. **ESCALATE IF the binary is missing or ambiguous**, asking whether to install `figma-ds-cli` (npm) or the silships repo build. Do not guess.1502. **ESCALATE IF Figma Desktop is not running** or daemon diagnosis fails after a reconnect.1513. **ESCALATE IF a yolo patch, a destructive verb, a broad delete/undo/unwrap, or an arbitrary `eval/raw/run` is requested**, describing the effect + rollback, then wait for confirmation.1524. **ESCALATE IF the optional Figma MCP is requested but no Figma token / Code Mode manual is configured**, surfacing the `.env` (`figma_FIGMA_API_KEY`) requirement. Do not paste credentials.1535. **ESCALATE IF CLI and MCP results disagree** about a file/node/variable state, and ask which source prevails before mutating.154155---156157## 5. SUCCESS CRITERIA158159**Connect complete when:**160- ✅ The binary was verified (`figma-ds-cli` or confirmed-silships `figma-cli`), Figma Desktop is open, the chosen connect mode ran, and `daemon status` is healthy.161162**Read / export complete when:**163- ✅ The requested data/asset was captured to an explicit path with no overwrite, and no mutating or destructive command ran.164165**Author / modify complete when:**166- ✅ The `sk-design-md-generator` pairing supplied a measured Style Reference (extracted design tokens) first (grounding what to render/bind/tokenize); the user confirmed the target and intent; mutating commands ran; destructive verbs had an explicit target + rollback; the result was verified (e.g. `get`/`verify`).167168**Optional MCP context complete when:**169- ✅ Code Mode discovery confirmed the `figma` manual + tool names, the token was configured, and the context was pulled without claiming unverified tools.170171**Always:**172- ✅ Figma Desktop was confirmed running; no yolo patch or destructive verb ran unconfirmed; the daemon token was never exposed.173174---175176## 6. INTEGRATION POINTS177178### Tool Usage Guidelines179180- **Bash** owns all `figma-ds-cli` operations (connect, daemon, inspect, export, author, tokens).181- **Code Mode** (`mcp__code_mode__call_tool_chain`) owns the optional Figma MCP calls (Framelink `figma`).182- **Read/Grep/Glob** load references and inspect CLI output / exported files.183184### Cross-Workflow Contracts185186- **`sk-design-md-generator`** produces a measured Style Reference (extracted design tokens) as a mandatory cross-hub pairing (hub ADR-002).187 - Apply it whenever a Figma read/export feeds a design decision, including grounding and token, type or layout choices.188 - Use it as a precondition before every design-affecting authoring path: render/create, variable binding, variants and token collections.189 This skill is the transport. The companion skill produces the measured reference.190- **`sk-code`** owns adapting extracted tokens / DESIGN.md / exported code into a real application, and verifying it.191- **`mcp-chrome-devtools`** is used only for a last-mile browser preview of an implemented page, never to operate Figma.192193### External Tools194195- **figma-ds-cli** (silships, MIT): install from npm (`figma-ds-cli`) or the silships repo, and see [INSTALL-GUIDE.md](INSTALL-GUIDE.md). Requires **Figma Desktop** open. Not vendored into this repo.196- **Figma MCP (optional)**: the Framelink `figma-developer-mcp` manual already in this project's Code Mode `.utcp_config.json`, which needs `figma_FIGMA_API_KEY` in `.env`.197198### Knowledge Base Dependencies199200**Required**: `references/figma-cli-reference.md` (binary/daemon/connect baseline). **Conditional**: `tool-surface.md` (gating), `mcp-wiring.md` (MCP), `troubleshooting.md` (errors).201202---203204## 7. REFERENCES AND RELATED RESOURCES205206### Core References207208- [figma-cli-reference.md](references/figma-cli-reference.md) - Binary identity + verification, Node/macOS baseline, Figma Desktop requirement, connect modes, daemon model, and command examples.209- [tool-surface.md](references/tool-surface.md) - The read-only / mutating / destructive command taxonomy, the destructive set, the `eval/raw/run` rule, and the export no-overwrite rule.210- [mcp-wiring.md](references/mcp-wiring.md) - The optional Figma MCP (Framelink `figma`) via Code Mode: the registered manual, the `.env` token, discovery, and a `call_tool_chain` example.211- [troubleshooting.md](references/troubleshooting.md) - Failure modes and fixes (binary collision, Desktop not running, daemon Unauthorized, port conflicts, Code Mode env-var prefix).212213### Templates and Assets214215- [utcp-figma-manual.md](assets/utcp-figma-manual.md) - Paste-ready Framelink `figma` `.utcp_config.json` manual entry, the `.env` note, and a `call_tool_chain` example for the optional Code Mode path.216- [env-template.md](assets/env-template.md) - The single prefixed `figma_FIGMA_API_KEY` `.env` line for the optional Figma MCP token.217218### Reference Loading Notes219220- References are the primary loaded resources. `figma-cli-reference.md` is the baseline (always). Load `tool-surface.md` for author/modify/token work, `mcp-wiring.md` only for MCP intent, `troubleshooting.md` for setup/errors.221- Load the `assets/` snippets only for MCP_CONTEXT intent, alongside `mcp-wiring.md`.222- Keep [`ROUTER.md`](./ROUTER.md) as the single routing authority.223224### Related Resources225226The router (in [`ROUTER.md`](./ROUTER.md)) discovers reference and asset docs dynamically. Start from `references/figma-cli-reference.md` for the CLI/daemon/connect model, load `references/tool-surface.md` for the gating taxonomy, `references/mcp-wiring.md` for the optional Code Mode path, and `references/troubleshooting.md` for failures. References stay the primary loaded resources.227228Assets: `assets/utcp-figma-manual.md` (paste-ready Framelink `figma` `.utcp_config.json` manual + `.env` note) and `assets/env-template.md` (the prefixed `figma_FIGMA_API_KEY` line), loaded only for the optional MCP_CONTEXT path.229230Scripts: `scripts/install.sh` (install + verify), `scripts/doctor.sh` (report-only diagnostics), `scripts/connect-safe.sh`, `scripts/connect-yolo.sh`, `scripts/daemon.sh`, `scripts/unpatch.sh`, `scripts/print-utcp-snippets.sh`.231232Examples: [`examples/README.md`](examples/README.md) - safe worked walkthroughs mirroring the playbook scenarios (safe connect + daemon health, read-only inspect/export, optional MCP context pull). They live outside the `references/`/`assets/` discovery roots, so they are linked here rather than auto-loaded by the router.233234Related skills: `sk-design-md-generator` (a measured Style Reference of extracted design tokens, applied whenever a read/export feeds a decision), `sk-code` (adapting exports into an app), `mcp-code-mode` (the optional MCP transport), `mcp-chrome-devtools` (browser preview only), and `system-spec-kit` when packet documentation or memory continuity applies. When a request or a frame leaves a visual value open (spacing, type, color, radius, shadow or motion), or a value sits off every token and scale, load `sk-code-frontend` (`web-visual-values.md`) and decide it there.235236A Figma read that feeds code ends at the five-pass check in `.skilled/skills/sk-code/sk-code-frontend/references/figma-to-code.md`.237238Install guide: [INSTALL-GUIDE.md](INSTALL-GUIDE.md).239240Upstream: figma-cli is [silships/figma-cli](https://github.com/silships/figma-cli) (npm `figma-ds-cli`, MIT). The optional MCP is the community Framelink `figma-developer-mcp`. This skill documents driving the installed tool from the terminal, and it does not vendor or redistribute it.