figma-ops

Files (15)

• SKILL.md
• light-board.example.json · assets/
• plus-layout.example.json · assets/
• capture-to-canvas.md · references/
• lessons.md · references/
• moodboard-composition.md · references/
• place-and-verify.md · references/
• skill-map.md · references/
• emit-placement.mjs · scripts/
• plan-layout.mjs · scripts/
• stage-assets.mjs · scripts/
• verify-board.mjs · scripts/
• verify-freshness.mjs · scripts/
• check-invariants.mjs · tests/
• run.sh · tests/

SKILL.md (first lines)

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

From 0xDarkMatter/claude-mods, MIT.

More from 0xDarkMatter/claude-mods