--- name: figma-preflight description: >- Mandatory read-only gate that runs before any write to a Figma file, through figma_execute (figma-console MCP) or use_figma (official Figma MCP). Runs 8 checks in order (live connection, confirmed target node-id, metadata, variables, design system and icon search, canon references, state coverage, file lock) and either approves the write or returns a fix list. It never mutates the canvas. Also audits cross-screen flow: orphan screens, CTAs without a destination, dead ends. Use when the user asks to create, edit, build or instantiate anything in Figma, or asks "audit the flow", "audita o fluxo", "tem tela órfã?", "esse botão leva pra onde?". license: MIT compatibility: >- Gate for writes through figma-console-mcp (figma_execute, Desktop Bridge plugin in Figma Desktop) or through the official Figma MCP server (use_figma, Full seat, not validated by this repo). The file lock script needs Python 3 (standard library only). Reads the figma-canon skill. The optional local evidence script of figma-bridge-doctor is macOS only. metadata: author: Thiago Xikota version: "1.1.1" --- # figma-preflight Mandatory pre-write checklist. Blocks the write (`figma_execute`, or `use_figma` on path B of Check 0) until all checks pass. This skill is a gate. It approves the write or returns a fix list. It never mutates the canvas. ## Triggers - Auto-fires when user intent is to WRITE to Figma (create, edit, build, instantiate). - Auto-fires before: - any write through the figma-console `figma_execute` tool (Desktop Bridge) - any write through the official Figma MCP server's `use_figma` tool - the canvas build phase of your project's own build skill or workflow, if any - Does NOT fire on read-only operations (orient, inspect, audit). ## Which server each tool belongs to - figma-console MCP server (Southleft): `figma_execute`, `figma_get_status`, and every other `figma_*` tool named here. - Official Figma MCP server: `get_metadata`, `get_variable_defs`, `search_design_system`, `whoami`, `use_figma`. Checks 1 to 4 name the official server's read tools. When only figma-console is connected, read the same kind of data with its own tools. These are alternatives, not one-to-one equivalents: the output shapes differ. | Check | Official Figma MCP tool | figma-console alternative | | --- | --- | --- | | 1, 2 | `get_metadata` | `figma_get_file_data`, `figma_get_file_for_plugin`, `figma_get_selection` (for the active selection) | | 3 | `get_variable_defs` | `figma_get_variables`, `figma_get_token_values`, `figma_get_styles`, `figma_get_text_styles` | | 4 | `search_design_system` | `figma_search_components`, `figma_get_library_components`, `figma_get_design_system_summary` | ## The 8-check gate Run all 8 in order (Check 0 to Check 7). Each must pass before the next runs. Fails closed (blocks the write). ### Check 0: Live connection to Figma Two paths pass this check. Only an MCP call proves the connection: a shell command NEVER does. - **Path A, figma-console (the path this repo validates).** AUTHORITY: `figma_get_status` with `probe:true`, returning `setup.valid=true` plus the correct `connectedFile`. A shell command cannot attest that the plugin is paired: ports 9223 to 9232 are a pure WebSocket with no HTTP endpoint (field note, 2026-08). Write path: `figma_execute` through the Desktop Bridge. - **Path B, official Figma MCP server only.** When the official server is the only live connection (figma-console is not installed, or its Bridge is down): a successful `whoami` plus a successful `get_metadata` on the target (that call also satisfies Check 2). Write path: `use_figma`. Path B is not validated by this repo: keep writes small, read back every change. Follow the official server's own instructions for `use_figma`. - [`figma-bridge-doctor/scripts/figma-status.sh`](../figma-bridge-doctor/scripts/figma-status.sh) (in the `figma-bridge-doctor` skill's `scripts/` directory, macOS only; in Claude Code run it as `bash "${CLAUDE_SKILL_DIR}/../figma-bridge-doctor/scripts/figma-status.sh"`, which needs that skill installed next to this one) is LOCAL evidence only: Figma is running, servers are listening. By design it does not report pairing (it prints `current_file_pairing=ask_figma_get_status`). Use it for diagnosis, not as a verdict. - If neither path confirms the connection, the write MUST be blocked. Bridge recovery goes through the `figma-bridge-doctor` skill: when figma-console is installed, try it before you fall back to path B. > **Advisory pre-check A0 (optional, path A; path B already runs it):** Call `whoami` (official > Figma MCP server) once per session if you do not know which seat the connected account holds OR > you are writing to a file you do not own. A seat mismatch (for example a Dev seat writing to a published library) fails loudly > with a permission error, so this is an *early feedback* convenience, not a silent > failure preventer. **Skip for:** a solo developer on personal drafts, sessions where you already > know the seat, or when you are on the Starter plan's MCP tool call budget. The 7 hard checks > below cover the silent failures. ### Check 1: Target node-id confirmed - Has the user provided a specific node-id OR is there an active Figma selection? - "The header frame" is NOT confirmed. You need an explicit node-id. - If ambiguous: run `get_metadata` and ask the user to disambiguate. ### Check 2: get_metadata run this session - Has `get_metadata` been called on the target page or frame in this session? - If NO: run `get_metadata` now and parse the structure. - If YES: reuse the earlier result from this session. ### Check 3: get_variable_defs (if the write touches styled properties) - Will the write set fills, strokes, spacing, typography or radii? - If YES: `get_variable_defs` MUST have been called on the relevant scope. - If NOT called: run it now. - Required for token-bound writes. ### Check 4: search_design_system (if the write creates new UI) - Will the write create a frame or component that COULD be an existing component? - If YES: `search_design_system` MUST have been run with a relevant query. - Block "new Button" / "new Card" / "new Input" writes if the search was not run. - **ICONS / ILLUSTRATIONS (anti-hallucination, field note, 2026-06):** NEVER hand-draw an icon (`createNodeFromSvg` with invented geometry) before checking what the design ALREADY has. Two sources to scan FIRST: 1. The file's icon component pages (for example an "Icons" page, whatever language it is named in). Instantiate those brand components. Do not redraw. 2. The codebase's real assets. Grep the screen or component source for the actual icon: the `lucide-react-native` import name, a `require('../assets/icons/calendar.png')` asset, or an SVG file. Match the app's REAL icon. A tab bar that uses brand PNG icons must use those assets or their componentized equivalents, never a generic geometric calendar, trophy or user that you drew. If a needed icon has no component, use the real asset (image fill) and FLAG the library gap. Never substitute a look-alike you invented. Block any icon-bearing write where neither the icon library nor the app asset was checked. **The WHOLE feature, not only the node you are about to write (field note, 2026-08).** The check above is per write, and that is how one feature accumulated **dozens of hand-drawn icons under many different names** across several sessions: each individual write looked innocent. When you enter a feature that ALREADY EXISTS, run an adherence sweep before you start: count the nodes with an icon name (`icon-*` or its equivalent in the file's language, for example `icone-*` in Portuguese; `spinner-*`; a glyph in a TEXT node) that are NOT a library instance. If the number is not zero, that is debt to report at the start, not to discover when the designer points at it. The same sweep closes the work: zero ad hoc icons on the page is the proof. "I replaced N icons" is not. ### Check 5: figma-canon refs loaded - Required refs per context (files under [`figma-canon/references/`](../figma-canon/references)): - Any write: `plugin-api-core.md` + `figma-execute-atomicity.md` + `auto-layout-canon.md` - Write touches tokens, variables, annotations or images: + `plugin-api-data.md` - Write hits edge cases (sections, connectors, masters, image fills, rate limits): + `plugin-api-anomalies.md` (for a 429 lockout it points on to `rate-limit-recovery.md`) - New screen: the refs above + `state-coverage.md` + `ai-slop-signatures.md` + `naming-canon.md` - Handoff prep: the refs above + `handoff-format.md` - If not loaded: load now before proceeding. ### Check 6: State coverage planned (if creating a screen) - For new screen creation: which states are required (for example Empty / Loading / Error / Success / Edge; the decision table gives the full set per screen class)? - Use the decision table in [`figma-canon/references/state-coverage.md`](../figma-canon/references/state-coverage.md). - If the states are not explicitly planned: ask the user OR stop and clarify. ### Check 7: Figma file lock claimed (single-driver invariant) One Figma file has one writer at a time. The lock script is [`scripts/figma_lock.py`](scripts/figma_lock.py) in this skill (Python 3, standard library only). The commands below call it as `"${CLAUDE_SKILL_DIR}/scripts/figma_lock.py"`. Claude Code replaces `${CLAUDE_SKILL_DIR}` with this skill's directory (the folder that holds this file) when it loads the skill. Other agents: if the text still shows `${CLAUDE_SKILL_DIR}`, put the absolute path of that folder in its place; never run a command with the variable empty. ```bash python3 "${CLAUDE_SKILL_DIR}/scripts/figma_lock.py" claim --agent --task [--ttl 1800] python3 "${CLAUDE_SKILL_DIR}/scripts/figma_lock.py" check python3 "${CLAUDE_SKILL_DIR}/scripts/figma_lock.py" release --agent --task python3 "${CLAUDE_SKILL_DIR}/scripts/figma_lock.py" sweep ``` How the script behaves: - File-based: one JSON lock per `fileKey` under `~/.cache/figma-maxxing/locks/` (override with `FIGMA_LOCK_DIR`). Every session on the machine must use the same lock directory. A session with a different `FIGMA_LOCK_DIR` does not see the others' locks. - The lock is advisory: it only protects sessions that check it. - The lock is TTL based (`--ttl` in seconds, default 1800), with no PID tracking. A lock tied to the PID of a transient tool shell dies immediately (agent tool shells exit right after every command), which is why this lock is TTL based (field note, 2026-08). - Every command prints one JSON object. Exit code 0 on success, 1 on conflict or when the lock directory stays busy (`{"error": "lock directory is busy"}`), 2 on a usage error (a `fileKey` that is not 1 to 64 letters, digits, `_` or `-`; a `--ttl` that is not positive; `release` without a task). A usage error prints the argparse message, not JSON. - `check` prints `{"held": false}` or `{"held": true, "agent": ..., "task": ..., "claimed_at": ..., "expires_at": ...}`. It always exits 0 and never reserves the file. - `claim` prints `{"claimed": true, "renewed": false, ...}` on a fresh claim. A `claim` by the same agent and task renews the lock (`"renewed": true`). A `claim` on a lock held by someone else exits 1 and prints the holder: `{"claimed": false, "held": true, "agent": ..., ...}`. Expired locks are treated as free. - `release` prints `{"released": true, "held": false}`. If someone else holds the lock it exits 1 and prints the holder. If nothing is held it prints `{"released": false, "held": false}` and exits 0. - `sweep` deletes expired lock files and prints `{"swept": }`. It is housekeeping only: an expired lock is already treated as free. - `--agent` defaults to the environment variable `FIGMA_LOCK_AGENT`, then to the literal `agent`. `--task` defaults to `FIGMA_LOCK_TASK`. A `claim` with no task at all gets a generated `adhoc-` task that you would have to copy from the claim output to release. Always pass an explicit `--agent` (for example `claude-code`) and `--task`. - `release --force` releases a lock held by another task. It exists for the human, not for the agent. Never use it yourself. The gate: - Resolve the `fileKey` from the Figma URL, `figma_get_status`, or the `figma-map.md` written by `figma-orient` (default `docs/figma-map.md`, or the agent's own memory system). - Diagnosis only: `python3 "${CLAUDE_SKILL_DIR}/scripts/figma_lock.py" check `. A free check does not reserve the file. Only a successful claim authorizes you to proceed. - If `held=false`: claim it with `python3 "${CLAUDE_SKILL_DIR}/scripts/figma_lock.py" claim --agent --task --ttl 1800`. - If `held=true` and you ARE the holder (`agent` and `task` match): proceed. - If `held=true` and you are NOT the holder: BLOCK the write. Surface who holds it and tell the user to either wait until `expires_at` or release the conflicting lock manually. Do NOT bypass. - Release in cleanup or `finally`, on success and on failure alike. In a shell script, use `trap`. Keep exactly the same `--agent` and `--task` as the claim (or the same `FIGMA_LOCK_AGENT` and `FIGMA_LOCK_TASK`). An abrupt death without cleanup depends on TTL expiry. Never release the lock of another task. - Release after the write completes: `python3 "${CLAUDE_SKILL_DIR}/scripts/figma_lock.py" release --agent --task `. - One isolated script error (for example `{"error": "lock directory is busy"}`) does not declare the gate broken. Re-test. Only proceed without a lock when [`figma-bridge-doctor/scripts/figma-status.sh`](../figma-bridge-doctor/scripts/figma-status.sh) shows `other_sessions_count=0`, and flag it in your reply. That script is macOS only, and it tells this session's MCP server apart from the others through the agent's process tree (environment variable `FIGMA_AGENT_PROCESS`, default `claude`; see the script's header). Where it cannot run or cannot show `other_sessions_count=0`, do not write without a lock: report the script error to the user and stop. #### Narrow exception: disjoint pages A lock held by someone else normally blocks the write. This exception applies only when BOTH are true: 1. The holder is another live agent session. 2. You PROVE that its writes and yours land on different pages. The proof has three parts: `figma_get_status` shows the plugin's `currentPage` on the holder's page, the `task` of the lock names the holder's subject, and every one of your targets is addressed by node-id on another page. Who may override: - With the designer in the conversation: the designer decides. Ask ONE multiple-choice question (override now, recommended; wait for the lock; or the designer releases it if the other session has finished). - With no way to ask (autonomous run): you may override, under all of these conditions: - write by node-id only - NEVER call `setCurrentPageAsync` - at the end of the batch, run the rival-write audit of the `figma-bridge-doctor` skill (section "After reconnecting in a WRITE session: rival-write audit", full text in [`figma-bridge-doctor/references/rival-write-audit.md`](../figma-bridge-doctor/references/rival-write-audit.md)) on the section you wrote, and report the result - state the override in your reply so it stays in the transcript, including the sentence "I wrote under a lock override" Same page, or no proof that the pages are disjoint, stays BLOCKED. This is NOT a new default of the gate. It codifies two field cases, and the designer can revoke it. ## Output ### Pass ```text PASS figma-preflight: all 8 checks clear. Proceeding to write. - Connection: path A, Bridge connected (port 9223) | path B, official MCP (writes via use_figma) - Target: () - Metadata: cached - Variables: tokens loaded - DS search: components found - Canon loaded: - States planned: - File lock: held by task= until ``` ### Fail ```text FAIL figma-preflight: gap(s) before write can proceed: 1. -> 2. ... Run the fixes, then re-invoke figma-preflight. ``` ## Override The user can override with an explicit: - "skip preflight" (or the same request in the user's language) - "I confirm target is X, proceed" State the override in your reply, in one line ("preflight skipped on request"), so it stays in the transcript. ## Post-approval: write execution rules After the preflight OK, BEFORE generating any JS for `figma_execute` (or `use_figma` on path B): 1. Load the refs required by Check 5 (the single list lives there), plus [`figma-canon/references/naming-canon.md`](../figma-canon/references/naming-canon.md) if there is a new layer. 2. When the write finishes (or aborts): release the lock with `python3 "${CLAUDE_SKILL_DIR}/scripts/figma_lock.py" release --agent --task `. Forgetting to release blocks future sessions until the TTL expires. 3. Never send the known failing patterns: a sync `figma.currentPage = X` assignment, a missing `await` on an async call, `figma.notify()`, `setPluginData`, `createConnector`. The optional precheck hook (`hooks/figma-canon-precheck.py` at the root of the figma-maxxing repo, opt-in) flags these patterns. If it fires: read the message, fix it at the source, do NOT retry blindly. 4. **Check the ancestor chain for `locked` (field note, 2026-08).** In one large bind sweep through the figma-console bridge, a handful of binds under a GROUP with `locked: true` did not take, with no error, while each node read `locked: false`. Figma's typings say `locked` does not affect plugin writes, and the cause is not established. The check is cheap: in a write that sweeps a tree, check the chain (`for (let p=n; p; p=p.parent) if (p.locked) ...`), not only the target, and rely on the read-back in rule 5 either way. 5. **Post-write verification reads the PROPERTY YOU CHANGED, never a proxy.** In that same batch the read-back checked color and opacity and came back green on the nodes that were never written: color and opacity really had not changed, precisely because nothing happened. If you bound a variable, read `boundVariables[prop][i]`. If you created a node, read its id in the parent. An independent count AFTER the batch, compared against the expected number, is the only closure that counts. ## Cross-screen flow For a NEW SCREEN write (not an edit), after the per-screen checks, answer these before the write: 1. Which flow the screen belongs to. 2. Which CTA of which existing screen brings the user here: a real node-id, or a "predecessor to build" stated in your reply so it stays in the transcript. A screen with no entry is born unreachable: refuse it. 3. Every interactive element on the new screen has a destination (node-id), a "plan to build" stated in your reply, or "out of scope" with a specific reason. ### Audit mode Read-only. Use it on requests such as "audit the flow", "is there an orphan screen?", "where does this button lead?". Build the graph of the scope: - device-sized frames = nodes - `reactions[]` = wired edges - CTA text = implicit edges. For example "Filter" implies a Filter screen and "See all" implies a list screen. Match the CTA text in whatever language the file uses, ignoring case and diacritics. Emit a punch list. Never mutate the canvas. - ORPHANS: a screen with no incoming edge (unreachable). - DEAD ENDS: a screen that has CTAs but zero outgoing wired edges. - DANGLING CTAs: an interactive element whose text implies a destination that is missing in the scope. Always quote the CTA text. - WIRED-BUT-BROKEN: a reaction that points to a deleted or missing node. - SEMANTIC MISMATCH: a wired reaction, inside the scope, whose target does not match the CTA text. - CYCLES: informational, not a bug. ### Hard rules (paid for in production) - NEVER auto-create a missing screen: half of the "missing" ones are out of scope on purpose. Surface it, list the candidates, the human decides. After that, the build belongs to your project's own build skill or workflow, if any. - A wire that leads to a screen that does not match its CTA text is a SEMANTIC MISMATCH, not a "misroute". Check the project's product documentation (spec, flow map, handoff doc), if any, before you recommend a re-wire (field note, 2026-05: on one project a session reverted a wire based on a doc claim and the designer had to undo it). - A project's glossary of implicit destinations (product terms that imply a specific screen) lives in the project's repo, not here. Apply it only inside that project's file. - Back-navigation cycles are healthy. Do not report them as a problem. ## Composes with - `figma-canon`: this gate reads the relevant refs as part of Check 5. - figma-console `figma_execute` (Desktop Bridge) and official `use_figma`: preflight runs BEFORE any Figma write. - `figma-bridge-doctor`: owns Bridge recovery when Check 0 fails on path A. - `figma-orient`: preflight uses the orient output as input for Checks 1 and 2. - `figma-click-flow`: the visual arrow overlay is a separate skill. The audit here only analyzes the graph in memory.