figrelay 0.8.1 → 0.9.0

package/README.md

@@ -4,60 +4,16 @@
 [![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/quannh287/figma-relay/blob/main/LICENSE)
 
-> **Let your AI assistant design in Figma — no API token, no rate limits.**
-> Works with Claude CLI · Claude Desktop · Codex · VS Code · Cursor · Antigravity · any MCP client.
+> **Let your AI assistant read and write Figma — no API token, no rate limits.**
+> An MCP server that talks to a Figma Desktop plugin, so the AI can implement a frame in your codebase, draw a screen from a requirement, sync design tokens or bulk-edit layers. Works with any MCP client.
 
-> **Fork of [figma-mcp-console](https://github.com/hoangann2000/figma-mcp-console)** by [@hoangann2000](https://github.com/hoangann2000), forked at v0.5.4. Same setup, published on npm as [`figrelay`](https://www.npmjs.com/package/figrelay); the plugin now shows as **Figma Relay**.
-
-## 🆕 What's new since the fork
-
-- **Prototype tools** — `set_prototype_links`, `get_prototype_links` and `set_flow_starting_point` wire and check prototype flows.
-- **Safer `run_script`** — resending the same `token` returns the original run instead of running the script twice; timeout and disconnect errors say the script may still be writing.
-- **Batch edits, variants, text restyling, page targeting** — fewer calls for common edits, plus a scripting escape hatch.
-- **Many sessions, one plugin** — a timeout reports how many commands are queued, screenshots get 150s, and a busy plugin is no longer dropped as dead.
-- **Smaller tool list** — `create_frame`/`create_rectangle`/`create_ellipse` merged into `create_shape`; hide whole groups with `FIGMA_MCP_DISABLE`.
-- **Server version in the plugin panel**, so a stale binary is easy to spot.
-
-**Coming from `figma-mcp-console`?** Swap the package name to `figrelay@latest`, re-import the plugin from this release, and replace calls to `create_frame`/`create_rectangle`/`create_ellipse` with `create_shape`.
-
-## ✨ What can it do?
-
-- 🖥️ **Figma → Code** — paste a link to a Figma frame, and the AI implements that exact screen in your codebase, exporting the design's icons and images into your project instead of inventing its own
-- 🎨 **Requirement → Figma** — paste a requirement, and the AI draws the screen in Figma, then screenshots its own work and fixes what's off
-- 🔁 **Token sync** — pull design tokens into your theme config, or build a design system in Figma from your code
-- ✏️ **Bulk editing** — rename layers, replace text across a page, reorganize frames
-
----
+Fork of [figma-mcp-console](https://github.com/hoangann2000/figma-mcp-console), published on npm as [`figrelay`](https://www.npmjs.com/package/figrelay); the plugin shows as **Figma Relay**. **Migrating?** Swap the package name to `figrelay@latest`, re-import the plugin from this release, and replace `create_frame`/`create_rectangle`/`create_ellipse` with `create_shape`.
 
 ## ⚡ Quick start
 
-**Prerequisites**
-
-- [ ] [Node.js](https://nodejs.org) 18+ — check with `node --version`
-- [ ] **Figma Desktop** app (the web app can't run development plugins)
+Needs [Node.js](https://nodejs.org) 18+ and the **Figma Desktop** app (the web app cannot run development plugins).
 
-### Step 1 — Add the server to your AI tool
-
-No install needed — `npx` downloads and runs everything automatically.
-
-<details>
-<summary><b>Claude CLI</b></summary>
-
-For one project — run inside that project (registers it there only):
-
-```sh
-claude mcp add figma-console -- npx -y figrelay@latest
-```
-
-For all your projects at once — add it globally instead:
-
-```sh
-claude mcp add --scope user figma-console -- npx -y figrelay@latest
-```
-
-Both work the same at runtime: each Claude session starts its own server instance in that project's directory (so exported assets land in the right project), and all instances share one local bridge to Figma automatically.
-
-Or add to the project's `.mcp.json`:
+**1. Add the server to your AI tool.** Most clients take this block; [docs/mcp-client-setup.md](docs/mcp-client-setup.md) has the config-file path and the one-line CLI command for each.
 
 ```json
 {
@@ -70,134 +26,19 @@ Or add to the project's `.mcp.json`:
 }
 ```
 
-</details>
-
-<details>
-<summary><b>Claude Desktop</b></summary>
-
-**Settings → Developer → Edit Config** (`claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "figma-console": {
-      "command": "npx",
-      "args": ["-y", "figrelay@latest"]
-    }
-  }
-}
-```
-
-Restart Claude Desktop. On Windows use `"command": "cmd"`, `"args": ["/c", "npx", "-y", "figrelay@latest"]`.
-
-</details>
-
-<details>
-<summary><b>Codex CLI</b></summary>
-
-```sh
-codex mcp add figma-console -- npx -y figrelay@latest
-```
-
-Or in `~/.codex/config.toml`:
-
-```toml
-[mcp_servers.figma-console]
-command = "npx"
-args = ["-y", "figrelay@latest"]
-```
-
-</details>
-
-<details>
-<summary><b>VS Code (GitHub Copilot)</b></summary>
-
-Create `.vscode/mcp.json` (or **Command Palette → "MCP: Add Server"**):
-
-```json
-{
-  "servers": {
-    "figma-console": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "figrelay@latest"],
-      "cwd": "${workspaceFolder}"
-    }
-  }
-}
-```
-
-Use it from Copilot Chat in **Agent** mode.
-
-</details>
-
-<details>
-<summary><b>Cursor</b></summary>
-
-Create `.cursor/mcp.json` (or **Settings → MCP → Add new MCP server**):
-
-```json
-{
-  "mcpServers": {
-    "figma-console": {
-      "command": "npx",
-      "args": ["-y", "figrelay@latest"]
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary><b>Antigravity</b></summary>
-
-Agent panel → **MCP Servers → Manage MCP servers → View raw config** (`mcp_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "figma-console": {
-      "command": "npx",
-      "args": ["-y", "figrelay@latest"]
-    }
-  }
-}
-```
-
-Click **Refresh** after saving.
-
-</details>
-
-<details>
-<summary><b>Other MCP clients (opencode, Windsurf, Cline, Gemini CLI, Zed, …)</b></summary>
-
-Standard MCP stdio transport — any client works. Set the command to `npx` with args `["-y", "figrelay@latest"]`.
-
-</details>
-
-### Step 2 — Install the Figma plugin
-
-First, get the plugin folder onto your machine — **pick either option:**
-
-**📦 Option A — Download from GitHub (recommended)**
-
-> 1. Download **[plugin.zip](https://github.com/quannh287/figma-relay/releases/latest)** → **unzip it**
-
-**⌨️ Option B — Get it via command** *(if the download doesn't work)*
-
-> 1. Run **`npx figrelay install-plugin`**
-> 2. It saves the plugin to a folder and **opens it automatically** so you can see `manifest.json`
-
-Then, in both cases:
-
-2. In **Figma Desktop**: **Plugins → Development → Import plugin from manifest…** → select `manifest.json` *(one-time step)*
-3. Run it: **Plugins → Development → Figma Relay** — and **keep the plugin window open** while you work. 🟢 Green dot = connected
-4. Working with several Figma files at once? Run the plugin in **each** file — every window connects to the same local bridge, and the AI picks the right file per call
+| Client | Where the config lives |
+|---|---|
+| Claude CLI | `claude mcp add figma-console -- npx -y figrelay@latest`, or `.mcp.json` |
+| Claude Desktop | Settings → Developer → Edit Config (`claude_desktop_config.json`) |
+| Codex CLI | `codex mcp add figma-console -- npx -y figrelay@latest`, or `~/.codex/config.toml` (TOML) |
+| VS Code (Copilot) | `.vscode/mcp.json` — **different shape**, see the doc |
+| Cursor | `.cursor/mcp.json` |
+| Antigravity | MCP Servers → Manage → View raw config (`mcp_config.json`) |
+| Others | Standard MCP stdio: command `npx`, args `["-y", "figrelay@latest"]` |
 
-### Step 3 — Try it
+**2. Install the Figma plugin.** Download [plugin.zip](https://github.com/quannh287/figma-relay/releases/latest) and unzip it, or run `npx figrelay@latest install-plugin` (saves it to a folder and opens it). Then in Figma Desktop: **Plugins → Development → Import plugin from manifest…** → pick `manifest.json` (one-time), and run **Plugins → Development → Figma Relay**. Keep the plugin window open — 🟢 green dot means connected. Working across several Figma files? Run the plugin in each one.
 
-**Figma → code** — right-click a frame → **Copy link to selection**, then:
+**3. Try it.** Right-click a frame → **Copy link to selection**, then ask:
 
 ```text
 Implement this Figma page in our project: <paste link>. Match layout, spacing,
@@ -205,28 +46,22 @@ type and colors; export its icons/images into the project; screenshot the frame
 and compare when done.
 ```
 
-**Requirement → Figma:**
-
-```text
-Design a SaaS landing page in Figma (desktop, 1440px): hero + CTA, three feature
-cards, pricing with three plans, footer. Light theme, use auto-layout, then
-screenshot and fix anything off.
-```
+Or the other direction: *"Design a SaaS landing page in Figma (desktop, 1440px): hero + CTA, three feature cards, pricing, footer. Light theme, auto-layout, then screenshot and fix anything off."* Asking for a **screenshot and compare** at the end makes the AI check its own work.
 
-> 🎯 Asking the AI to **screenshot and compare** at the end makes it check its own work instead of guessing.
+## 🎓 Agent skills
 
----
+The tools tell the AI *what it can call*; the skills tell it *how to do the job well* — orient before writing, auto-layout over absolute positioning, reuse components and tokens, screenshot and verify. `npx figrelay@latest install-skills` writes them to `.claude/skills/<name>/SKILL.md`; other clients take the same files in their own skills folder. Sources live in [`skills/`](skills/) — edit them to match your conventions.
 
-## 🗂 Multiple files, multiple projects
-
-All AI sessions and all Figma files share **one local bridge** on port 2000 — the first MCP server to start owns it, later ones join it automatically, and if the owner exits another session takes over within a second. Nothing to configure.
-
-- **Several Figma files**: run the plugin in each file (its window shows *Connected · \<file name\>*). With more than one file connected, every tool accepts a `file` parameter (file name, case-insensitive), and `list_files` shows what's connected — so you can say things like *"copy the primary color from **Design System** into the CTA button in **Landing Page**"* in a single session. With one file connected, nothing changes.
-- **Several code projects**: each AI session (one per project) reaches every connected file through the shared bridge. State which file you mean in the prompt and each session works with the right one.
+| Skill | When it fires |
+|---|---|
+| `figrelay-design` | Anything that writes to a canvas — frames, text, components, variants, variables, prototype links |
+| `figrelay-design-to-code` | "Implement this design" — map a frame onto the repo's components and tokens, export assets |
+| `figrelay-generate-design` | New screens built from the file's existing components and styles |
+| `figrelay-generate-library` | Build or update a Figma design system library from the codebase, in reviewed phases |
 
 ## ✂️ Hide tools you don't use
 
-Every listed tool takes up room in the AI's context, even in sessions that never touch Figma. Hide whole groups with `FIGMA_MCP_DISABLE` (or `-disable`): `components`, `styles`, `variables`, `prototype`. Hiding all four cuts the tool list by about a third.
+Every listed tool costs context, even in sessions that never touch Figma. `FIGMA_MCP_DISABLE` (or the `-disable` flag) hides whole groups: `components`, `styles`, `variables`, `prototype`. Hiding all four cuts the tool list by about a third.
 
 ```json
 "figma-console": {
@@ -238,17 +73,7 @@ Every listed tool takes up room in the AI's context, even in sessions that never
 
 ## 🧠 Teach your AI what to export, and where
 
-Exports follow the file extension the AI picks (`.svg` for vector, `.png`/`.jpg` for bitmap, with an optional 0.5–4x scale). It decides based on what you ask — so put your preferences in the project rules file once, and stop repeating yourself:
-
-| AI tool | Rules file |
-|---|---|
-| Claude CLI / Claude Desktop | `CLAUDE.md` |
-| Codex / opencode | `AGENTS.md` |
-| Cursor | `.cursorrules` |
-| VS Code Copilot | `.github/copilot-instructions.md` |
-| Windsurf | `.windsurfrules` |
-
-> **📋 Copy-paste rules** (adjust paths — this fits Next.js):
+Exports follow the extension the AI picks (`.svg` for vector, `.png`/`.jpg` for bitmap, optional 0.5–4x scale), so put your preferences in the project rules file once — `CLAUDE.md`, `AGENTS.md` (Codex/opencode), `.cursorrules`, `.github/copilot-instructions.md` or `.windsurfrules`:
 
 ```markdown
 ## Figma asset rules
@@ -262,19 +87,13 @@ Exports follow the file extension the AI picks (`.svg` for vector, `.png`/`.jpg`
 
 | Problem | Fix |
 |---|---|
-| ❌ "no Figma plugin is connected" | Open the plugin in Figma Desktop (**Plugins → Development → Figma Relay**) and keep its window open — in every file you want the AI to touch |
-| 🕐 Plugin says "Searching for MCP server…" | Normal before your AI client connects — the server starts automatically with it. If it never connects, click the status line to retry, or restart your AI client |
-| 🗂 "N Figma files are connected; pass the file parameter" | More than one plugin window is open — tell the AI which file you mean (or close the extra plugin windows) |
-| 🚫 The MCP server doesn't appear in your AI tool | Check Node.js 18+ is installed (`node -v`) |
-| 📁 Exported files end up in the wrong folder | Exports are written relative to where the server runs. Register it in the project-level config, or tell the AI an explicit export path |
-| 🔤 Font errors when creating text | The Figma file uses a font not installed on your machine — the error message names it |
-
-## 🛠 Contributing
-
-Setup, how to add a tool, and the gotchas that cost time: **[CONTRIBUTING.md](CONTRIBUTING.md)**. Why the non-obvious parts work the way they do: **[docs/design-notes.md](docs/design-notes.md)**.
-
-## 📄 License
+| ❌ "no Figma plugin is connected" | Open the plugin (**Plugins → Development → Figma Relay**) and keep its window open — in every file the AI should touch |
+| 🕐 Plugin says "Searching for MCP server…" | Normal until your AI client connects. If it never does, click the status line to retry, or restart the client |
+| 🗂 "N Figma files are connected; pass the file parameter" | More than one plugin window is open — name the file you mean, or close the extras |
+| 🚫 The server doesn't appear in your AI tool | Check Node.js 18+ (`node -v`) |
+| 📁 Exported files land in the wrong folder | Exports are relative to where the server runs. Register it in the project-level config, or give the AI an explicit path |
+| 🔤 Font errors when creating text | The file uses a font not installed on your machine — the error names it |
 
-[MIT](https://github.com/quannh287/figma-relay/blob/main/LICENSE) — © [Hoang Le Thien An](https://github.com/hoangann2000) (original project), fork maintained by [@quannh287](https://github.com/quannh287)
+## 🛠 More
 
-> This is an independent community project, not affiliated with or endorsed by Figma, Inc. "Figma" is a trademark of Figma, Inc.
+Several Figma files or projects at once: [docs/mcp-client-setup.md](docs/mcp-client-setup.md). Setup, adding a tool and the gotchas that cost time: [CONTRIBUTING.md](CONTRIBUTING.md). Why the non-obvious parts work that way: [docs/design-notes.md](docs/design-notes.md). License: [MIT](https://github.com/quannh287/figma-relay/blob/main/LICENSE) — © [Hoang Le Thien An](https://github.com/hoangann2000) (original project), fork maintained by [@quannh287](https://github.com/quannh287). Independent community project, not affiliated with or endorsed by Figma, Inc.; "Figma" is a trademark of Figma, Inc.

package/bin/plugin/code.js

@@ -4,6 +4,10 @@
 
 figma.showUI(__html__, { width: 280, height: 104 });
 
+// The UI can collapse to a dot; selection changes must not resize it back.
+let collapsed = false;
+let fullHeight = 104;
+
 // Tell the UI which file this plugin window runs in; the UI forwards it to
 // the bridge on every (re)connect so calls can be routed per file when
 // several files run the plugin at once. figma.fileKey is undefined for
@@ -1326,10 +1330,10 @@ async function postSelection() {
   // the paste-URL prompt when a frame needs a key (64) + up to 6 visible rows
   // (the list scrolls beyond that).
   const rows = Math.min(items.length, 6);
-  const h = items.length
+  fullHeight = items.length
     ? 134 + (items.length > 1 ? 22 : 0) + (needsKey ? 64 : 0) + rows * 30
     : 104;
-  figma.ui.resize(280, h);
+  if (!collapsed) figma.ui.resize(280, fullHeight);
 }
 figma.on("selectionchange", postSelection);
 postSelection();
@@ -1338,6 +1342,14 @@ postSelection();
 
 figma.ui.onmessage = async (msg) => {
   if (!msg) return;
+  // Control message from the UI: collapse to a dot. The window has to stay
+  // open for the bridge, so shrinking it is the only way to get the screen
+  // space back. 70 is Figma's minimum width.
+  if (typeof msg.collapsed === "boolean") {
+    collapsed = msg.collapsed;
+    figma.ui.resize(collapsed ? 70 : 280, collapsed ? 36 : fullHeight);
+    return;
+  }
   // Control message from the UI: the user pasted the file URL to enable links.
   if (typeof msg.setFileKey === "string") {
     setFileKey(msg.setFileKey);

package/bin/plugin/ui.html

@@ -57,6 +57,44 @@
     box-shadow: 0 0 0 3px rgba(34, 160, 107, 0.15);
   }
 
+  #collapse {
+    flex: none;
+    margin-left: auto;
+    width: 18px;
+    height: 18px;
+    border: 0;
+    border-radius: 5px;
+    background: transparent;
+    color: #8288a0;
+    font-size: 13px;
+    line-height: 1;
+    cursor: pointer;
+  }
+
+  #collapse:hover {
+    background: #eef0f7;
+    color: #2c2c34;
+  }
+
+  /* Collapsed: the dot only, at Figma's 70px minimum width. */
+  body.mini {
+    padding: 4px;
+  }
+
+  body.mini .card {
+    padding: 4px;
+    display: flex;
+    justify-content: center;
+  }
+
+  body.mini #status,
+  body.mini #collapse,
+  body.mini #hint,
+  body.mini #result,
+  body.mini #credit {
+    display: none;
+  }
+
   #hint {
     color: #6b6f7d;
     margin-top: 5px;
@@ -252,6 +290,7 @@
 <div class="card">
   <div id="status-row">
     <span id="dot"></span><span id="status">Connecting…</span>
+    <button id="collapse" title="Collapse to a dot">&minus;</button>
   </div>
   <div id="hint">Keep open while AI works · run it in every file.</div>
   <div id="result"></div>
@@ -550,7 +589,22 @@
     }
   };
 
-  document.getElementById("status-row").onclick = () => connect();
+  // Collapsed, the whole card is the expand target; expanded, the status row
+  // still retries the connection.
+  let mini = false;
+  function setMini(on) {
+    mini = on;
+    document.body.classList.toggle("mini", on);
+    parent.postMessage({ pluginMessage: { collapsed: on } }, "*");
+  }
+  document.getElementById("collapse").onclick = (e) => {
+    e.stopPropagation();
+    setMini(true);
+  };
+  document.getElementById("status-row").onclick = () => {
+    if (mini) return setMini(false);
+    connect();
+  };
   document.addEventListener("visibilitychange", () => {
     if (!document.hidden && !ws) connect();
   });

package/bin/skills/figrelay-design/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: figrelay-design
+description: Create or modify content on a Figma Design canvas through the Figma Relay MCP server — frames, text, auto layout, components, variants, styles, variables and prototype links. Use whenever the user asks to draw, build, edit, restyle, rename, rearrange or wire anything in a Figma file. Triggers on "in Figma", "add a frame/button/screen", "change this component", "set up tokens/variables", "wire the prototype".
+---
+
+# Writing to a Figma file
+
+The plugin edits **the page that is open in Figma**, which the user can change at
+any moment. Never assume where your work lands.
+
+## 1. Orient before writing
+
+- `list_files` — only when several Figma files are connected; pass `file` to every
+  later call.
+- `list_pages` then `set_current_page` — put the right page in front before creating.
+- `get_metadata` for the page's top-level layers, `get_selection` for what the user
+  is pointing at. In a large file use `find_nodes` (by name, text, type, fill, font)
+  instead of walking the tree with `get_design_context`.
+- `get_design_context` with `compact: true`. The full form costs several thousand
+  tokens for one frame; only drop `compact` when you need raw paint objects.
+
+## 2. Build top-down
+
+1. A root `create_shape` FRAME at an empty spot, sized for the target
+   (390x844 mobile, 1440x900 desktop). Everything else goes inside it via `parent_id`.
+2. `set_auto_layout` on every container — direction, `item_spacing`, padding,
+   sizing modes. Only position with x/y when auto layout genuinely does not fit:
+   absolute children do not reflow when content changes.
+3. `create_text` for copy, `create_shape` / `create_line` for structure.
+   Name every layer the way a designer would ("Header", "CTA / Primary"), never
+   "Rectangle 12".
+4. Style: `set_fills`, `set_strokes`, `set_corner_radius`, `set_effects`,
+   `set_text_properties`.
+
+Reuse before you create: `get_local_components` + `create_instance`,
+`get_local_styles` + `apply_style`, `get_variable_defs` + `set_bound_variable`.
+A hard-coded hex where a token exists is a bug.
+
+## 3. Verify visually
+
+`get_screenshot` on the root frame after each meaningful chunk — not once at the
+end. Compare against the brief, fix with `move_nodes`, `resize_nodes`,
+`set_characters`, `set_fills`, `remove_nodes`, screenshot again. A tall node comes
+back scaled with a warning; screenshot a child instead of reading a thumbnail.
+
+Finish with `set_selection` on the root frame so the user sees the result.
+
+## 4. Components, variables, prototypes
+
+- **Component**: build the frame, then `create_component`. For variants, name each
+  component `Property=Value` (`Size=Large`) *before* `combine_as_variants`.
+  `add_component_property` returns the key `set_instance_properties` needs.
+- **Variables**: `create_variable_collection` → `add_variable_mode` (light/dark) →
+  `create_variable` → `set_variable_value` per mode → `set_bound_variable` on nodes.
+  These are for single edits; a whole token set goes through `run_script`
+  (see below). **Check the mode limit before designing around modes**: on a
+  free/starter plan `add_variable_mode` fails with *"Limited to 1 modes only"* and
+  the light/dark-via-modes pattern is simply unavailable — the fallback is two
+  sibling collections (`tokens · Light`, `tokens · Dark`) and no mode switching.
+  Name variables with slashes (`primary/500`, not `color-primary-500`) — that is
+  what groups them in the Variables panel; flat names are unusable past ~50 tokens.
+- **Prototype**: `set_prototype_links` only joins **top-level frames on the same
+  page**; a nested frame is rejected. Each call replaces that node's reactions, so
+  pass all of a node's links together. Check with `get_prototype_links`,
+  mark the entry with `set_flow_starting_point`.
+
+## Gotchas that cost time
+
+- **Fonts**: `create_text` fails if the family is not installed locally.
+  `list_available_fonts` first when using anything but the file's existing fonts.
+- **Rename, don't rebuild**: `rename_nodes`. Deleting and recreating a component
+  breaks every existing instance.
+- **`resize_nodes` resets auto-layout sizing modes to FIXED.** Resize *before*
+  `set_auto_layout`, or re-apply the sizing modes afterwards — otherwise a frame
+  set to hug ends up locked at the resized height with its content spilling out.
+  It also does not move children unless they have constraints or auto layout.
+- **Instances**: children have derived ids `I<instance-id>;<child-id>` — accepted
+  by every tool, returned by `find_nodes`.
+- **Batch**: most edit tools take `node_ids`; feed `find_nodes` output straight in.
+
+## `run_script` — the bulk path
+
+Default for anything token-shaped (importing 150 variables as 150 calls is absurd)
+and for bulk rebinding. Single edits stay on the atomic tools: they fail with a
+precise error, while a half-failed script leaves the document half-changed.
+
+- **A thrown script keeps everything it already created.** Write find-or-create
+  scripts keyed by name so a retry adopts the orphan instead of duplicating it.
+- **Read the line number before retrying.** The throw is often on the *return*
+  line — e.g. `return { n: figma.getLocalTextStyles().length }` — meaning the work
+  completed and only the summary failed. Inspect the document, then decide.
+- **dynamic-page access**: sync accessors throw. Async-only —
+  `getLocalVariableCollectionsAsync`, `getVariableByIdAsync`,
+  `getLocalTextStylesAsync`, `getLocalEffectStylesAsync`, `getNodeByIdAsync`,
+  `setCurrentPageAsync`, `loadAllPagesAsync`, `node.getMainComponentAsync`,
+  `setTextStyleIdAsync`, `setEffectStyleIdAsync`, `setReactionsAsync`.
+  Still sync: `variables.createVariable`, `createVariableCollection`,
+  `setValueForMode`, `valuesByMode`, `createTextStyle`, `createEffectStyle`,
+  `combineAsVariants`.
+- **Never call an async-only getter inside a `findAll`/`filter` predicate** — it
+  crashes the whole traversal (*"findAll callback crashed"*). Collect the nodes
+  first, then `for...of` with `await`.
+- **Seed a bound paint from the variable's own value** — free insurance, not a
+  cure. Figma normalises the stored colour to the variable's resolved value at
+  bind time, so an in-file binding seeded black still renders correctly
+  (measured). The seed only ever matters where the variable *cannot* resolve —
+  a cross-file or library binding — which is untested. Do it anyway; it costs
+  one property read.
+
+```js
+const col  = (await figma.variables.getLocalVariableCollectionsAsync()).find(c => c.name === 'tokens · Light');
+const mode = col.modes[0].modeId;
+const v = await figma.variables.getVariableByIdAsync(id);
+const paint = { type: 'SOLID', color: v.valuesByMode[mode], opacity: 1 };
+node.fills = [figma.variables.setBoundVariableForPaint(paint, 'color', v)];
+```
+
+### Rebinding and deleting variables
+
+Measured, not guessed:
+
+- **Rebinding is safe and needs no reseed.** `setBoundVariableForPaint(paint, 'color', newVar)`
+  with the stale colour lands on the new variable's value. Mutating
+  `paint.boundVariables.color = {type:'VARIABLE_ALIAS', id}` directly works too.
+- **Renaming never breaks a binding.** Bindings are by id; a renamed collection
+  or variable keeps every consumer. Rename freely.
+- **Deleting a collection leaves silent zombies.** Nodes still bound keep the
+  alias and the last literal colour — they look right and are dead. Worse,
+  `getVariableByIdAsync(deadId)` and `getVariableCollectionByIdAsync` **still
+  return live-looking objects with correct names**, so a null check detects
+  nothing. The only reliable test is list membership:
+  `!(await figma.variables.getLocalVariablesAsync()).some(v => v.id === aliasId)`.
+- **There is no consumer API.** `variable.consumers` is `undefined`, and
+  `Object.keys()` on a variable or collection returns `["id"]` — they are
+  proxies, so don't introspect them. To find consumers, scan the tree via
+  `node.boundVariables?.fills?.some(a => ids.includes(a.id))` (cheaper than
+  digging through each paint's `boundVariables`). A plain property read like
+  this is fine inside a `findAll` predicate; an async getter is not.
+- **`collection.remove()` is immediate with no API undo.** Re-scan and assert
+  zero remaining consumers *before* removing — you get no error if you miss some.
+
+- Split by **logical group**, not node count — the point is error isolation.
+  Scripts creating 300+ variables, or several hundred nodes, run without timing out.
+- Pass a `token` anyway (it costs nothing). A timed-out script **keeps running and
+  keeps writing**, so the token is what lets a retry join the original run instead
+  of duplicating it. Never redo a timed-out script's work blind.
+
+Raw-API-only gotchas (the atomic tools already handle these):
+`figma.combineAsVariants` neither names nor lays out the set — set `name`,
+`layoutMode`, `layoutWrap`, `primaryAxisSizingMode = 'FIXED'`, `resize`, padding
+and spacing yourself, or every variant stacks at 0,0. `layoutAlign = 'STRETCH'`
+does not stretch a child unless `primaryAxisSizingMode` is also `FIXED`.
+`layoutPositioning = 'ABSOLUTE'` must be set *after* `appendChild`.

package/bin/skills/figrelay-design-to-code/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: figrelay-design-to-code
+description: Turn a Figma frame, component or selection into code in this repository — read the design through the Figma Relay MCP server, map it onto existing components and design tokens, export the assets it needs. Use when the user says "implement this design", "build this screen", "code this component", "match the Figma", or pastes/points at a Figma selection.
+---
+
+# Figma → code
+
+Goal: code that matches the design **using this codebase's own components and
+tokens**. A pixel-perfect one-off built from raw divs and hex codes is a failure.
+
+## 1. Read the design
+
+- `get_selection` when the user says "this" / "the selected frame"; otherwise
+  `find_nodes` by layer name. `get_metadata` / `list_pages` if you are lost.
+- `get_design_context` with `compact: true` and a sensible `depth` (2–3 first,
+  deeper only where needed). Full depth on a whole screen buries the real
+  structure in thousands of tokens.
+- `get_screenshot` on the frame. Read the picture and the tree together — the
+  tree gives names and numbers, the picture gives intent.
+
+## 2. Map before you write
+
+- `get_variable_defs` and `get_local_styles` → the design's tokens. Match them to
+  the repo's theme/tokens by **value and name**; write the repo's token, never the
+  raw hex. Report any design token that has no counterpart instead of inventing one.
+  Read the repo's token **source** (theme config, tokens JSON, Tailwind config) —
+  never a built CSS bundle, which is utility output and gets truncated before the
+  `:root` block.
+- `get_local_components` → named components in the design. Grep this repo for the
+  same concept (Button, Card, Modal) and reuse it. Only build new when nothing fits.
+- Auto layout maps onto flex: `direction` → `flex-direction`, `item_spacing` →
+  `gap`, padding → padding, sizing modes → `fixed` / `hug` (fit-content) /
+  `fill` (flex: 1). Absolutely positioned children are the exception, not the rule.
+- Fixed pixel widths in the design usually mean "fill the container" in code.
+  Ask what the responsive behaviour is rather than hard-coding 390px.
+
+## 3. Export assets
+
+`download_assets`, one item per node, chosen per node after checking its type and
+fills:
+
+- **SVG** for pure vector — icons, logos, path illustrations.
+- **PNG at `scale: 2`** for anything with a raster IMAGE fill, a photo, or
+  blur/shadow effects SVG cannot represent.
+- **JPG** only for large photos where size matters.
+
+Paths follow this project's conventions (check `CLAUDE.md` / `AGENTS.md` and
+where existing assets live). Without a convention, defaults are
+`assets/icons/<name>.svg` and `assets/images/<name>.<ext>`. Everything is written
+relative to the directory the MCP server runs in and cannot escape it.
+
+## 4. Verify
+
+Run the app or the component's story, then compare with `get_screenshot` of the
+Figma node side by side. Spacing, font size/weight, radius and colour are the
+usual misses. State plainly what you could not match and why.
+
+## Don't
+
+- Don't copy absolute x/y into CSS. Rebuild with flex from the auto layout.
+- Don't invent token names. Use the repo's, or flag the gap.
+- Don't export a whole frame as one PNG to "save time" — export its real assets.

package/bin/skills/figrelay-generate-design/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: figrelay-generate-design
+description: Assemble full screens in Figma out of the file's existing components, styles and variables through the Figma Relay MCP server — instead of drawing rectangles from scratch. Use when the user asks for a new page/screen/flow "using our design system", "with our components", or wants several screens that stay consistent.
+---
+
+# Generating screens from a design system
+
+Rule: **instantiate, don't draw.** A screen made of raw rectangles is not a
+deliverable when the file has components.
+
+## 1. Inventory first (do not skip)
+
+- `get_local_components` — every COMPONENT / COMPONENT_SET in the file, all pages.
+- `get_local_styles` — paint, text, effect styles.
+- `get_variable_defs` — collections, modes, tokens.
+- `get_metadata` + `list_pages` — where existing screens live; open the right page
+  with `set_current_page`.
+
+Screenshot one existing screen (`find_nodes` → `get_screenshot`) to learn the
+house layout: page padding, section spacing, header/footer pattern. Copy it.
+
+Report what is missing before building. If there is no Card component, say so and
+ask whether to build one or approximate — don't silently fake it.
+
+## 2. Compose
+
+1. Root `create_shape` FRAME at the target size, named like the existing screens,
+   placed to the right of them with a clear gap.
+2. Resize the root first, **then** `set_auto_layout` VERTICAL on it with the house
+   padding and spacing — resizing afterwards resets sizing modes to FIXED.
+   Every section inside is itself an auto-layout frame. Nothing absolute.
+3. `create_instance` for each component, `set_instance_properties` for its variant
+   and text overrides. Swap with `swap_component` rather than detaching.
+   **Never `detach_instance`** to "make it fit" — that is how a design system dies.
+4. Only `create_text` / `create_shape` for genuinely bespoke content, and then
+   style it with `apply_style` / `set_bound_variable`, never a literal hex.
+
+## 3. Verify and iterate
+
+`get_screenshot` per section as you go, not once at the end. Check against the
+house screen: alignment, rhythm, and that every colour came from a style or
+variable. Fix, re-screenshot, then `set_selection` on the root frame.
+
+## Multiple screens
+
+Build the first screen, screenshot it, **get the user's sign-off**, then clone
+the structure for the rest (`clone_node` with `parent_id` and x/y — a clone inside
+a SECTION otherwise lands at 0,0). Wire the flow with `set_prototype_links`
+between the top-level frames and `set_flow_starting_point` on the entry screen.
+
+## Bulk work
+
+Dozens of identical instances, or rebinding every fill in a subtree, is what
+`run_script` is for. Everything smaller stays on the atomic tools — they fail with
+a precise error instead of half-writing the document.

package/bin/skills/figrelay-generate-library/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: figrelay-generate-library
+description: Build or update a Figma design system library from this codebase through the Figma Relay MCP server — tokens as variables, text/paint/effect styles, then components with variants. Runs in phases and stops for review between them. Use when the user asks to "create our design system in Figma", "sync our tokens to Figma", or "turn our component library into Figma components".
+---
+
+# Codebase → Figma library
+
+Long, destructive-by-accident work. **Stop for review after every phase.** Never
+run the whole thing in one go.
+
+## Phase 1 — Discovery (read only)
+
+- In the repo: find the **token source file** (theme config, design-tokens JSON,
+  Tailwind config, CSS custom properties in source form) and the per-component
+  style definitions (`tva({...})`, variant maps, style objects). Grep, don't guess.
+- In Figma: `get_variable_defs`, `get_local_styles`, `get_local_components`,
+  `list_pages` — what already exists.
+- **Check the plan's mode limit** before promising light/dark via modes — see
+  Phase 2.
+
+**Never reverse-engineer a compiled stylesheet.** A built CSS bundle is hundreds
+of KB of utility output, gets truncated by the read cap, and usually hides the
+`:root` block past the cut. The config source has the literal values, and the
+component's variant block has the real spec — `xs: 'px-3.5 h-8'` gives you
+padding 14 / height 32 and the exact token name `bg-primary-500`. That fidelity
+is what makes the library match the app; screenshots and built CSS do not.
+
+Report a plan: tokens found, components found, what already exists in Figma, what
+you propose to create vs update, and anything ambiguous. **Wait for approval.**
+
+## Phase 2 — Foundations (variables and styles)
+
+Do this phase in `run_script`, not the typed variable tools — a hundred tokens is
+a hundred round-trips otherwise. Read the `run_script` rules in
+`figrelay-design` first; the ones that bite hardest here:
+
+- **Modes are a plan limit.** `addMode` on a free/starter plan throws
+  *"Limited to 1 modes only"*. Probe it on the first collection before building
+  anything around light/dark. Fallback: two sibling collections
+  (`tokens · Light`, `tokens · Dark`), components bound to Light, and tell the
+  user plainly that mode switching is off the table. Discovering this 300
+  variables in means redoing the phase.
+- **The script that throws keeps what it made.** The collection created on the
+  line before a failed `addMode` survives. Every script here is find-or-create
+  keyed by name, and adopts an orphan rather than making a second one:
+  `let c = cols.find(x => x.name === target) ?? adopt(cols.find(x => x.name === 'tokens'))`.
+- **Slash names** (`primary/500`, `space/md`) — that is what makes the groups in
+  the Variables panel. Convert `--color-primary-500` on the way in.
+- **Seed bound paints from `valuesByMode`** — cheap insurance. In-file bindings
+  render correctly even seeded black (Figma normalises at bind time); the seed
+  only matters for bindings that cannot resolve.
+- Names mirror the code so a human can trace a token back to its source.
+- Updating an existing collection: set the value on the existing variable.
+  A duplicate collection is the failure mode here.
+- `create_paint_style`, `create_text_style`, `create_effect_style` for what
+  designers pick from the UI.
+
+**Stop and show `get_variable_defs` output.**
+
+### Splitting or merging collections
+
+Needed whenever the mode limit forces one collection into two. Every step below
+is measured; the sequence as a bulk operation is not, so verify as you go.
+
+1. Create the target collection's variables with the same names, copying values
+   from the source via `valuesByMode`.
+2. Build a `name → newVariable` map.
+3. Scan for consumers with `node.boundVariables?.fills?.some(a => ids.includes(a.id))`
+   and rebind each hit. Rebinding preserves the rendered value and needs no
+   reseed; renaming a collection or variable never breaks a binding.
+4. **Re-scan and assert zero consumers of the old collection before removing it.**
+   This is the whole safety net: a node left bound to a removed collection keeps
+   its alias and its last colour, looks perfectly fine, and is dead — and
+   `getVariableByIdAsync` still returns a live-looking object for it, so a null
+   check finds nothing. Test with list membership
+   (`getLocalVariablesAsync().some(v => v.id === aliasId)`), never fetchability.
+5. Only then `collection.remove()` — immediate, with no undo from the API.
+
+## Phase 3 — File structure
+
+One page per group (Foundations, Components, Patterns) via the user's convention;
+`set_current_page` before building. Moving finished components to another page
+later is safe — cross-page instance references hold (verified over 54 instances);
+`set_current_page` in a script is `setCurrentPageAsync`. A labelled section per component, laid out on
+a grid with generous spacing — a library people scroll through, not a pile.
+
+## Phase 4 — Components
+
+Per component, simplest first:
+
+1. Build the base frame, **resize it first, then `set_auto_layout`** — resizing
+   after configuring sizing modes silently resets them to FIXED and you get a
+   component locked at the resized height with its text spilling out. Bind every
+   colour/radius/space to the Phase 2 variables (`set_bound_variable`) or styles
+   (`apply_style`).
+2. Build each variant as its own frame named `Property=Value`
+   (`Variant=Primary`, `Size=Large`), `create_component` each, then
+   `combine_as_variants`.
+3. `add_component_property` for TEXT / BOOLEAN / INSTANCE_SWAP props, bound to the
+   child layer they drive, so the property actually does something.
+4. `get_screenshot` the set and compare against the real rendered component.
+
+Batch by component family, pause between families.
+
+## Phase 5 — QA
+
+- Every component: screenshot vs the real thing in the app.
+- Every fill/radius/spacing: bound to a variable or style, no stray hex
+  (`find_nodes` by fill colour catches leftovers).
+- Naming matches the code, variants resolve, instances still work after edits.
+- Report coverage: what shipped, what was skipped, what needs a designer.
+
+## Never
+
+- Never `remove_nodes` on existing library components to "rebuild cleanly" —
+  it breaks every instance across every file. `rename_nodes` and edit in place.
+- Never run a phase the user has not approved.
+- Never resize a frame after setting its auto-layout sizing modes.
+- Never treat a `run_script` error as "nothing happened" — check the document
+  first; the throw is often on the return line, after all the work succeeded.
+- Never design around variable modes without confirming the plan allows >1.
+- Never scrape compiled CSS for tokens when the config source is in the repo.
+- Never remove a variable collection without first asserting it has no
+  consumers left — the failure is silent and looks correct.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figrelay",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "scripts": {
     "prepublishOnly": "cp ../README.md ./README.md"
   },

package/run.js

@@ -51,6 +51,24 @@ if (process.argv[2] === "install-plugin") {
   process.exit(0);
 }
 
+// Subcommand: install-skills — copy the agent skills into the current project
+// so the AI client picks them up from .claude/skills/<name>/SKILL.md.
+if (process.argv[2] === "install-skills") {
+  const srcDir = path.join(__dirname, "bin", "skills");
+  const destDir = path.join(process.cwd(), ".claude", "skills");
+  if (!fs.existsSync(srcDir)) fail("skills not found in this package");
+  for (const name of fs.readdirSync(srcDir)) {
+    fs.mkdirSync(path.join(destDir, name), { recursive: true });
+    fs.copyFileSync(
+      path.join(srcDir, name, "SKILL.md"),
+      path.join(destDir, name, "SKILL.md"),
+    );
+    process.stdout.write(`  ${name}\n`);
+  }
+  process.stdout.write(`\n✅ Skills installed into ${destDir}\n`);
+  process.exit(0);
+}
+
 if (!fs.existsSync(binPath)) fail(`binary not found for ${plat}-${arch}`);
 try {
   fs.chmodSync(binPath, 0o755);