docs(figma): lead setup with "which credential do I need", not a token wall

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 <[email protected]>

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.
 
 <Steps>
   <Step title="Mint a token">
     In Figma: **Settings → Security → Personal access tokens → Generate new token.**
   </Step>
-  <Step title="Pick read-only scopes">
-    The integration never writes to Figma — read-only is all it ever needs:
+  <Step title="Check these scopes">
+    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.
   </Step>
   <Step title="Export it">
     ```bash
@@ -47,7 +56,11 @@ The CLI paths need a Figma personal access token in the `FIGMA_TOKEN` environmen
   </Step>
 </Steps>
 
-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