Figma Preflight

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.

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 (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/):
  • 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.
• 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 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.

python3 "${CLAUDE_SKILL_DIR}/scripts/figma_lock.py" claim <fileKey> --agent <agent> --task <task> [--ttl 1800]
python3 "${CLAUDE_SKILL_DIR}/scripts/figma_lock.py" check <fileKey>
python3 "${CLAUDE_SKILL_DIR}/scripts/figma_lock.py" release <fileKey> --agent <agent> --task <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": <count>}. 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-<uuid> 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 <fileKey>. 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 <fileKey> --agent <agent> --task <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 <fileKey> --agent <agent> --task <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 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.