Figma Ops

---
name: figma-ops
description: "Router and composition workflows for Figma via the official Figma MCP: which Figma skill/tool for which job, capture-to-canvas (screenshots or shotcraft crops into a Figma file), moodboard and reference-board composition (grid, plus, loose-plus arrangements with a deterministic layout planner), canvas craft rules the API skills don't cover, and multi-account routing. Triggers on: figma, moodboard, brand board, reference board, put these screenshots in figma, compose in figma, arrange images in figma, plus arrangement, which figma skill, figma account, upload to figma, delete figma page."
license: MIT
when_to_use: "Any Figma request that isn't obviously a single official skill's job: 'put these screenshots in Figma', 'make a moodboard from these references', 'arrange this more organically', 'which Figma skill do I use for X', 'it says I don't have edit access', 'this file is in my other Figma account', 'delete the old pages'."
argument-hint: "[route|compose|verify] [figma-url]"
compatibility: "Official Figma MCP server (Claude Code figma plugin) for canvas work; Node 18+ for scripts/*.mjs; shotcraft optional for live-site capture"
allowed-tools: "Read Write Bash Glob Grep AskUserQuestion"
metadata:
  author: claude-mods
  related-skills: color-ops, icon-ops, frontend-design
---

# Figma Operations

The front door for Figma work. The official Figma plugin ships eleven skills that own
the Plugin API surface; the community ships fifty more for tokens, components, a11y
and docs. **This skill does not replicate any of them.** It does three things they
don't:

1. **Routes** — says which skill or tool to load for a given job (§1).
2. **Composes** — capture → curate → arrange workflows for moodboards, reference
   boards and any "put these images in Figma, beautifully" request (§3–§5).
3. **Guards** — the canvas craft rules that sit *above* the API rules: aspect ratio,
   z-order, overlap budgets, verification loops, page hygiene (§6).

> **Always load `figma-use` before any `use_figma` call.** It is the source of truth
> for the Plugin API and its gotchas. This skill assumes it is loaded and cites its
> references rather than restating them.

## 1. Router — which skill for which job

| The job | Load | Tool it wraps |
|---|---|---|
| Any script that mutates or reads the canvas | `figma-use` (mandatory prerequisite) | `use_figma` |
| Design → code, implement a screen | the design-to-code guidance served as MCP resource `skill://figma/figma-design-to-code/SKILL.md` (not a plugin skill) | `get_design_context`, `get_screenshot` |
| SwiftUI ↔ Figma, either direction | `figma-swiftui` | `get_design_context`, `use_figma` |
| Build a page/screen *from* app code | `figma-generate-design` + `figma-use` | `use_figma`, `generate_figma_design` |
| Tokens, variables, component library | `figma-generate-library` + `figma-use` | `use_figma`, `search_design_system` |
| Map components to code | `figma-code-connect` | Code Connect tools |
| New blank file | `figma-create-new-file` | `create_new_file` |
| Mermaid-class diagram in FigJam | `figma-generate-diagram` | `generate_diagram` |
| FigJam board content | `figma-use-figjam` + `figma-use` | `use_figma` |
| Slides deck | `figma-use-slides` + `figma-use` | `use_figma` |
| Motion / animation | `figma-use-motion`, `figma-implement-motion` | `use_figma`, `get_motion_context` |
| Images or SVGs into a file | **this skill §4** | `upload_assets` |
| Moodboard, reference board, composed arrangement | **this skill §3–§5** | `upload_assets` + `use_figma` |
| Live-site captures as source imagery | `shotcraft` → this skill §4 | — |
| Design-token export/import, a11y audits, variable CRUD | community skills — see [references/skill-map.md](references/skill-map.md) | varies |

Two routing rules the tables can't express:

- **A read-only inspection comes first, always.** Pages, existing frames, fonts, naming
  conventions. `figma-use` §9 has the scripts. Never create before you have looked.
- **`get_metadata` needs editor access, not viewer.** "You don't have edit access" on a
  file you can open in the browser means the share is view-only. Ask for editor, or
  check you are on the right account (§2).

## 2. Multi-account routing

One Figma OAuth token binds to exactly one Figma account. If the user belongs to more
than one org (agency + client, personal + work), the correct setup is **one MCP server
per account** — typically the plugin server for one and a claude.ai connector for the
other. They expose separate tool namespaces; pick the account per call by prefix.

- Confirm identity with `whoami` on each server before assuming which file it can see.
- Do **not** consolidate to one server: every account switch would become an interactive
  OAuth re-auth, impossible from a non-interactive session.
- The durable fact is *mechanism → account* (plugin = X, connector = Y). Connector UUIDs
  change on re-add — never key notes on them.
- A View-only team seat fails the same way as a view-only share. `whoami` lists seats.

## 3. Composition workflow — capture → curate → compose

The phases, each with an exit gate. Post a short checklist before each phase and a
summary after (the phase contract in `figma-generate-library` §1 is the model —
visible progress, decisions surfaced, never silently defaulting).

| Phase | Output | Exit gate |
|---|---|---|
| **0 Brief** | Sources list, art direction (2–3 sentences), palette/vocabulary if any, target file + page | User has confirmed the source list; blockers named (attached-not-sent images, login-walled sites) |
| **1 Capture** | Screenshots / section crops / user-supplied images on disk, at true pixel dimensions | Every file exists; dimensions read from the file header, not assumed |
| **2 Curate** | Shortlist with one line per image saying *what it contributes* | **Every image has been looked at by the agent.** Unvetted images never enter a composition |
| **3 Upload** | Nodes in the target file, named after their source files | Node IDs returned and recorded (§7 ledger) |
| **4 Arrange** | Images resized to true aspect ratio and placed per a chosen pattern (§5) | Screenshot reviewed; collisions and defects fixed *before* adding chrome |
| **5 Dress** | Typography, hairlines, marks, labels — only what the brief's vocabulary calls for | Second screenshot; nothing overlaps text; single accent rule honoured if one exists |
| **6 Hand back** | Rendered PNG sent to the user; page name; what was left open | The user sees the render, not just a description of it |

**Hard gates:**

- No `use_figma` mutation before Phase 0's source list is confirmed.
- No image placed before it has been opened and looked at (Phase 2). The gate exists
  because the mistakes that slip through are obvious to eyes and invisible to exit codes.
- No chrome (labels, rules, marks) before the bare arrangement screenshot is clean.
- Build on a **new page**; never restructure the user's existing page in place. Deleting
  the old pages is a separate, explicit request (§6).

## 4. Capture → canvas

**Sources.** Three kinds, in rising order of value for a moodboard:

1. Full-page screenshots — good for scroll strips, bad for boards (a 16,000px strip
   compressed to board width is an unreadable column; use the viewport shot instead).
2. Section crops — the useful unit. `shotcraft`'s `probe-sections.mjs` finds them
   structurally; `capture.mjs` with `elements[]`/`scrollTo` takes targeted ones.
3. Designed comps the user supplies — usually the strongest material; these are the
   aesthetic *executed*, not referenced.

**Stage first.** `scripts/stage-assets.mjs` takes a folder and/or a shortlist, copies
each image to a staging directory under a meaningful slug (`07-ref-collected-system.png`,
never `IMG_0997.PNG` — the filename becomes the Figma layer name on upload), reads
**true pixel dimensions from the file header**, and emits the planner's input JSON.
It exits 10 until every image has a subject (`--names`) and an arm (`--arms`): the
grouping is a human decision and the script refuses to guess it.

```bash
node scripts/stage-assets.mjs --list shortlist.txt --dir ./refs --out ./staged \
  --names names.json --arms arms.json --json > board.json
```

**Upload.** `upload_assets` with `count: N`, then POST each staged file as
`multipart/form-data` with a `file` field. Record the returned `placedOnNodeId` per
file into `board.json`'s `id` fields (§7 ledger).

**The 400×300 trap.** Uploaded images land as 400×300 frames with `scaleMode: FILL`,
which *crops*. The frame tells you nothing about the image; only the header does.
`resize()` every frame to the planner's `w×h` before placing it.

**Uploads land on whichever page is current for the upload tool** — not necessarily
the page your last script switched to. Find them by ID and `appendChild` them where
they belong.

## 5. Arrangement patterns

Three patterns, in the order a session usually discovers them. Details, coordinates
and the reasoning behind each choice live in
[references/moodboard-composition.md](references/moodboard-composition.md).

| Pattern | When | Character |
|---|---|---|
| **Column grid** | Reference sheet, equal-weight items, "make it aligned" | 3 columns + 2-col spans; every rotation 0; captions left-aligned to column |
| **Rigid plus** | Groups have a *meaning* along each axis (medium ↑↓, temperature ←→) | Four arms from a centre element, ring sizes stepping ~0.72× outward, axes drawn as hairlines with terminal dots |
| **Loose plus** | "Organic", "clustered around the centre", "loosely a plus" | Same grouping, axes *removed*, inner ring overlapping the centre by ~40px and nudged off-axis, second ring tucked onto the inner ring's corners (≤ 250×80), wordmark floating in the eye |

Rules that held across all three:

- **Rotation is opt-in.** Zero degrees unless the user asks for angles; "organic"
  means offset and overlap, not tilt.
- **Group by what images share** — type, aesthetic, or colour — and let the axes
  *mean* something. A plus with arbitrary arms is just a cross.
- **Sizes step toward the centre.** Largest adjacent to the centre, ~0.72× per ring.
- **Overlap has a budget.** Inner ring onto centre ≤ 40px; neighbour corners
  ≤ 250×80. The planner reports every overlap and exits 10 when one exceeds budget.
- **A centre element is allowed to be typographic.** The brand at the centre of its
  influences reads better than a borrowed image there — but once images overlap it,
  strip its chrome (strokes, ticks, metadata) or it reads as a broken box.
- **Vocabulary in the quadrants or corners, never in the cluster.**

Plan coordinates with the script rather than by hand, and generate the placement
script rather than typing it:

```bash
node scripts/plan-layout.mjs --input board.json --mode loose --jitter 24 --seed 7 --json > plan.json
node scripts/emit-placement.mjs --plan plan.json --phase backdrop            # → use_figma
node scripts/emit-placement.mjs --plan plan.json --phase place --backdrop 45:2 --captions
```

`plan-layout` emits backdrop-relative `{id, x, y, w, h}` placements in z-order,
canvas size, and an overlap report (exit 10 over budget). `--jitter` adds seeded
irregularity for "organic" without losing reproducibility — same seed, same plan.
`emit-placement` turns the plan into the exact `use_figma` script, and **refuses
any image whose plan entry is `vetted: false`** — the look-at-it gate as data, not
memory. Full flow in [references/place-and-verify.md](references/place-and-verify.md).

## 6. Canvas craft rules (above the API)

Learned the expensive way; each one cost a round-trip this skill now saves.

- **Hairline stroke on every dark image.** A dark site on a dark ground disappears; a
  1px `SOFT` 45–55% stroke, `strokeAlign: OUTSIDE`, defines the edge. Check `fills`
  before concluding an image "didn't render".
- **Z-order is append order.** Anything that overlaps must be appended *after* what it
  sits on. Send axis lines to the back with `insertChild(0, …)`.
- **Font style names are per-family, verify them.** Inter uses `"Semi Bold"`; Archivo
  uses `"SemiBold"`. `listAvailableFontsAsync()` first, always.
- **Load fonts before *any* text property**, including `textAlignHorizontal` on an
  existing node. Scripts are atomic — a font error means nothing ran, so fix and
  retry safely (`figma-use` gotchas: canonical text-edit recipe).
- **Never filter nodes by size to find your marks.** `width <= 38` also matched the
  9px footer squares and moved them 440px. Track IDs; filter by name or ID.
- **Deleting a label deletes only the text.** Its leader line and dot stay. Remove
  the whole triplet, or rebuild all captions after a re-layout rather than nudging.
- **Verify mechanically, then screenshot.** Read the board back (the read-only script
  in [references/place-and-verify.md](references/place-and-verify.md)) and run
  `scripts/verify-board.mjs --plan plan.json --board readback.json`. It catches what
  eyes don't: frames still at 400×300, drift, inverted z-order, budget breaches,
  missing strokes, rotation. *Then* `get_screenshot` on the board node at
  `maxDimension` 1400–1800 for what programs can't judge: collisions of meaning,
  stranded chrome, whether it is any good. Node-level screenshots (`contentsOnly`)
  are for detail, not verification.
- **Renders go to the user.** `curl` the screenshot URL to `design/exports/` and send
  the file; a description of a board is not a board.
- **Page deletion is explicit and last.** Switch `currentPage` to the survivor first
  (you cannot remove the current page), clone-don't-move when building alternatives,
  and remind the user that version history holds the deleted pages.

## 7. State ledger for long builds

Context gets summarised mid-build. Keep a ledger on disk from Phase 3 onward:

```json
{ "file": "<fileKey>", "page": "44:3", "backdrop": "45:2",
  "images": { "07-ref-collected-system": "44:5" },
  "chrome": { "captions": ["38:2","38:3"], "vocab": ["47:2"] },
  "exports": ["design/exports/board-v3.png"] }
```

Re-read it at the start of every turn; reconstruct by name (`page.query('FRAME[name^=07-]')`)
if it is missing. Idempotency is by node name — never re-upload an image whose name
already exists on the page.

## 8. Decision forks — ask, don't default

Ask when two arrangements are both defensible and the brief doesn't decide; present
each with its cost. Do **not** ask about things the source decides (an image's aspect
ratio, whether a dark image needs a stroke). Rejected work is never built on — if the
user says "not jaunty angles", every rotation goes to zero before the next screenshot,
not just the new ones.

## References

- [references/moodboard-composition.md](references/moodboard-composition.md) — the three
  patterns with coordinates, grouping logic, and what each round taught.
- [references/capture-to-canvas.md](references/capture-to-canvas.md) — shotcraft →
  upload → true-AR placement, end to end, with the dimension reader.
- [references/skill-map.md](references/skill-map.md) — the official + community Figma
  skill landscape and what this skill deliberately leaves to them.
- [references/lessons.md](references/lessons.md) — the session log this skill was
  distilled from, kept as evidence for the rules in §6.
- [references/place-and-verify.md](references/place-and-verify.md) — the last mile:
  fill in node IDs, emit the two `use_figma` scripts, read the board back, verify.
- `scripts/stage-assets.mjs` — folder/shortlist → slug-named copies + true dimensions
  → planner JSON (`vetted: false` by construction). Exits 10 until subjects and arms
  are supplied.
- `scripts/plan-layout.mjs` — deterministic layout planner (grid / plus / loose),
  seeded `--jitter`, overlap budget, captions and `vetted` passed through.
- `scripts/emit-placement.mjs` — plan → exact `use_figma` scripts (backdrop, place,
  optional captions). Refuses unvetted images.
- `scripts/verify-board.mjs` — board read-back vs plan: size, position, rotation,
  z-order, overlap budget, strokes. Exit 10 with findings.
- `scripts/verify-freshness.mjs` — `--offline`: every skill the router names exists
  in the local plugin cache; `--live`: the community index vs `skill-map.md`.
- `assets/plus-layout.example.json` — the real 14-image Agntik fixture.
- `assets/light-board.example.json` — a second real fixture (8 light-ground captures,
  smaller centre, slug IDs, captions) so defaults are validated on more than one board.

The pipeline, end to end: shotcraft (or a folder) → `stage-assets` → look at every
image, set `vetted`, `caption`, `arm` → `plan-layout` → `emit-placement` (backdrop)
→ `upload_assets` → fill IDs → `emit-placement` (place) → read back → `verify-board`
→ `get_screenshot` → dress → send the render.