From ffac2ecbfe542054648338098f1a2f9df5c4f8fb Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Thu, 9 Jul 2026 19:41:43 -0700 Subject: [PATCH] docs(figma): lead setup with "which credential do I need", not a token wall MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The old setup section was one long token-minting flow with the MCP connector as an afterthought — but motion/shaders/storyboards need only the connector (no token at all), and even brand tokens are easier via MCP on any non-Enterprise plan. A reader wanting only motion had to wade past REST scope tables meant for a different path. Restructured into a decision table (what you want → which credential) followed by two equal, independent steps. Step A's scope list now states the 3 boxes to check on a normal (non-Enterprise) account up front, instead of a generic 4-scope table the reader has to interpret themselves. Step B now states the MCP connector's actual capability (variable reads work on any plan, rate-limited by tier — 6 calls/month on Starter) instead of "no scopes to configure," which undersold what it can do. Co-Authored-By: Claude Opus --- docs/guides/figma.mdx | 37 +++++++++++++++++++++++++------------ 1 file changed, 25 insertions(+), 12 deletions(-) diff --git a/docs/guides/figma.mdx b/docs/guides/figma.mdx index e658988505..6d180861ea 100644 --- a/docs/guides/figma.mdx +++ b/docs/guides/figma.mdx @@ -10,7 +10,7 @@ The work your designer already did in Figma — layout, color, type, motion — | Capability | What you get | Surface | | --- | --- | --- | | **Static assets** | A frame/layer rendered to SVG/PNG/JPG/PDF, frozen under `.media/` | `hyperframes figma asset` | -| **Brand tokens** | Figma variables/styles as composition brand variables | `hyperframes figma tokens` | +| **Brand tokens** | Figma variables/styles as composition brand variables | `hyperframes figma tokens` (Enterprise) or the `/figma` skill via MCP (any plan) | | **Components** | A frame as editable HTML with brand-linked colors | `hyperframes figma component` | | **Motion** | A Figma Motion timeline as an editable, paused GSAP timeline | `/figma` skill (agent, MCP) | | **Shaders** | A shader fill/effect as a frozen still or clip | `/figma` skill (agent, MCP) | @@ -20,23 +20,32 @@ Two transports, split by what Figma exposes: assets, tokens, and components run ## One-time setup -The CLI paths need a Figma personal access token in the `FIGMA_TOKEN` environment variable. +There are two credentials, and most people only need to set up one to start: + +| You want to import… | Set up | +| --- | --- | +| A logo, image, or a whole frame as HTML (assets, components) | A **token** — Step A below | +| Brand colors (tokens) | Either works, but on a non-Enterprise plan the **MCP connector** (Step B) gets you there in one click — the token path needs an Enterprise plan for this specific pull | +| Motion, shaders, or a storyboard | The **MCP connector** only — no token, no setup beyond connecting it | + +Do both if your project needs everything; each is independent, so it doesn't matter which you set up first. + +### Step A — Figma token (assets, tokens, components) + +Needed for anything you run from the `hyperframes figma` CLI. In Figma: **Settings → Security → Personal access tokens → Generate new token.** - - The integration never writes to Figma — read-only is all it ever needs: + + Read-only is all it ever needs — the integration never writes to Figma. **On most accounts (not Figma Enterprise), check exactly these three:** - | Scope | Setting | Needed for | - | --- | --- | --- | - | File content | Read-only | assets, components | - | File metadata | Read-only | version tracking, refresh | - | Library content | Read-only | the `tokens` published-styles fallback | - | Variables | Read-only | brand variables — **Figma Enterprise only** | + - **File content** — Read-only + - **File metadata** — Read-only + - **Library content** — Read-only — easy to miss, and without it `tokens` 403s the moment it tries the published-styles fallback - No Enterprise plan? `tokens` falls back to your published styles automatically — but that fallback reads `/v1/files/:key/styles`, which needs the **Library content: Read-only** scope. Without it the command 403s with Figma's own diagnosis (*"requires the library_content:read scope"*); add the scope and re-run. The **Variables** scope stays optional (Enterprise-only). + On a **Figma Enterprise** plan, also check **Variables — Read-only** to pull brand colors directly via `tokens`. Not on Enterprise? Skip it — `tokens` falls back to published styles automatically, or use the MCP connector (Step B) instead, which reaches variables on any plan. ```bash @@ -47,7 +56,11 @@ The CLI paths need a Figma personal access token in the `FIGMA_TOKEN` environmen -Motion and shader import use the **Figma MCP connector** instead — a one-click OAuth from your agent, separate from the token. Connect it when your agent asks; no scopes to configure. +### Step B — Figma MCP connector (motion, shaders, storyboards — and an easier token-free path to brand colors) + +No token, no scopes to pick — connect it once when your agent asks (a one-click OAuth) and it stays connected. + +This is also the easiest way to pull brand colors on **any** Figma plan, including free: the connector's variable-reading tool isn't Enterprise-gated, only rate-limited by plan — Starter/free caps at **6 calls/month**, a paid Full/Dev seat gets 200–600/day. Fine for an occasional brand pull; not for iterating call-by-call. ## Import an asset