Figma

**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.

> **First, keep this skill fresh — confirm with the user before running:** `npx hyperframes skills update figma`. A fast no-op when everything is current; otherwise it refreshes this skill plus the core domain skills it depends on before you rely on them.

# Figma → HyperFrames

Bring the user's Figma work into a composition. **Split by capability** (design spec §2):

| Phase | What | Transport | Surface | | ----- | ------------------- | ------------------------- | ----------------------------- | | 1 | Static assets | REST | `hyperframes figma asset` | | 2 | Brand tokens/styles | REST | `hyperframes figma tokens` | | 3 | Components → HTML | REST | `hyperframes figma component` | | 4 | Motion → GSAP | connector when available | use its motion context | | 5 | Shaders | connector / manual export | use it or a native export |

REST is used wherever it can be (usable at volume, headless). A compatible Figma connector is optional for motion and shader data; without one, ask for a native export. Every path freezes assets locally so renders stay deterministic. Storyboard reconstructions compose Phase-1 asset exports (REST) with agent-driven timeline assembly — no connector needed. Existing frozen assets, manifest records, and bindings are unaffected by routing changes — the split only changes which credential the next import uses.

## Auth — two credentials, scoped

**Preflight — before the first CLI call, check a token exists**: shell env (`[ -n "$FIGMA_TOKEN" ]`) **or** the project `.env` (the CLI auto-loads it — a `.env` entry counts as configured). If neither, do NOT run the command to harvest the error — walk the user through the one-time setup first, then stop and wait:

1. figma.com/settings → **Security** → **Personal access tokens** → Generate new token. 2. Scopes — read-only is all this integration ever needs (it never writes to Figma): **File content: Read-only** + **File metadata: Read-only**. Add **Library content: Read-only** if you'll run `tokens` on a non-Enterprise plan — the published-styles fallback hits `/v1/files/:key/styles`, which 403s without it (a scope the older setup text omitted). Optionally **Variables: Read-only** for brand variables — Enterprise-only; without it `tokens` degrades to published styles automatically (expected, not an error — say so). A 403 now names the exact missing scope; 429s retry automatically (per-minute limit, honors `Retry-After`). 3. Have the user set `FIGMA_TOKEN` in their shell profile or project `.env`; never ask them to paste the token into the conversation.

While onboarding, also set expectations in one breath: every import lands as a **local frozen file with recorded provenance** — renders never call Figma, re-running a command re-imports only what changed in Figma, and one token works for assets, brand tokens, and components across every file their Figma account can view.

- **Phases 4–5 (motion/shaders):** a compatible Figma connector, with separate authorization from the token. If it is unavailable or unauthenticated, ask the user to connect it or provide a native export, then stop. - Say exactly which credential a failing phase needs — never present the split as broken. - `BAD_TOKEN` (401) mid-flow → the token is expired/revoked; re-mint. `FORBIDDEN` (403) → the message names the exact missing scope (e.g. `library_content:read` for the styles fallback) — add it, or the file isn't visible to the account. `REQUIRES_ENTERPRISE` (403 on variables) → not a failure: styles fallback already ran. `RATE_LIMITED` (429) → the client already retried with backoff (this applies to EVERY read — assets, tokens, styles, node trees, versions — the retry lives in the shared request path; `Retry-After` is honored, capped at 60s); if it still surfaces, wait a minute or import fewer nodes per call.

**Rate-limit awareness (spec §2.1):** connector quotas vary by Figma plan — batch parent-frame requests, skip verification screenshots unless asked, and cache raw responses so re-derivation never spends a second call. REST is per-minute (10+/min, per-endpoint buckets) — fine at volume, back off on 429.

## Routing

Parse the user's figma link with `parseFigmaRef` (URL, `fileKey:nodeId`, bare `fileKey`). Then by intent:

- "use this layer / logo / image" → **Asset** (CLI) - "pull my brand / colors / tokens" → **Tokens** (CLI) - "build a scene from this frame" → **Component** (CLI) - "import this animation / motion" → **Motion** (connector when available, below) - a storyboard section / filmstrip of scene frames → **Storyboard** (below) - shader fill/effect → **