The work your designer already did in Figma — layout, color, type, motion — becomes the starting point of a composition instead of a thing to rebuild by hand. Point at a Figma URL; the artifact lands as a native HyperFrames piece: a frozen local file, a composition variable, editable HTML, or a paused GSAP timeline.
What you can import
| 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 (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) |
| Storyboards | Scene frames reconstructed as motion — frames read as states, not slides | /figma skill (agent) |
One-time setup
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 |
Step A — Figma token (assets, tokens, components)
Needed for anything you run from the hyperframes figma CLI.
Mint a token
In Figma: Settings → Security → Personal access tokens → Generate new token.
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:
- 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
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. Export it
export FIGMA_TOKEN="figd_…"
.env so future sessions skip this step. The same token covers every Figma file your account can view.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
hyperframes figma asset 'https://www.figma.com/design/KEY/Title?node-id=1-2'
.media/images/, and the command prints a ready-to-paste <img> snippet:
imported image_007 → .media/images/image_007.svg
<img src=".media/images/image_007.svg" alt="image_007" data-figma-id="1:2" />
--format svg|png|jpg|pdf (default svg). SVG for logos and vectors — scalable and animatable. --format png --scale 2 for raster fidelity.- Accepted refs: a full Figma URL with
?node-id=… (right-click a layer → Copy link) or fileKey:nodeId shorthand. Asset and component imports always target a specific node; only tokens takes a bare fileKey.
- Idempotent: the manifest records
fileKey:nodeId:format:scale:version, so re-running reuses the file unless the design actually changed in Figma.
Pull your brand
hyperframes figma tokens KEY
figma-tokens.json sidecar plus a binding index, and prints entries for the composition’s data-composition-variables. Every scene that references a brand role — instead of a hard-coded hex — is on-brand automatically, and stays on-brand when the file changes.
Import tokens before components. That’s what lets an imported component’s colors link to your brand variables instead of baking duplicate literals.
Import a component
hyperframes figma component 'https://www.figma.com/design/KEY/Title?node-id=10-20'
compositions/components/<name>/. Vector and boolean-op nodes that don’t map to clean HTML auto-rasterize through the asset path.
Colors bound to a Figma variable resolve against your imported tokens:
- Bound to an imported token → emitted as
var(--brand-slug, #0066FF) — a later brand refresh propagates into the component.
- Bound to a token you haven’t imported → the literal color is used and the element is flagged
data-figma-unresolved. The command tells you; run tokens on the source (or library) file and re-import to link them.
Matching is by exact Figma ID only — never by hex value — so a coincidentally-shared color can’t create a false brand link.
Motion, shaders, and storyboards
These run through the /figma agent skill:
- Motion — a Figma Motion timeline (keyframes, easing, repeats) translates structurally into a paused, finite GSAP timeline registered on
window.__timelines, seekable frame-by-frame like any hand-authored animation, and editable afterward. Tracks that can’t translate faithfully fall back to a baked video clip — the agent tells you which path it took and why.
- Shaders — Figma’s export path doesn’t execute shaders, so the default is a native Figma export (PNG or Motion MP4) imported as an asset/clip.
- Storyboards — a section of scene frames is decoded, not slideshowed: frames sharing an element are treated as that element’s keyframes over time, diffed into element chains and tweened, with text under the strip read as director notes. When the frames depict one product UI in successive states, the agent escalates further — rebuilds the UI as live DOM and performs each frame delta as a real interaction (cursor, click, navigation), so the result reads as a continuous screen recording. See the
/figma skill for the full grammar.
Provenance and refresh
Every import records where it came from (fileKey, nodeId, version) in .media/manifest.jsonl. Nothing in a rendered composition points at Figma — assets are files, tokens are variables, motion is a timeline. When the Figma file moves on, re-running the same import commands re-pulls only what changed.
Troubleshooting
| Error | Meaning | Fix |
|---|
NO_TOKEN | FIGMA_TOKEN unset | Follow One-time setup |
BAD_TOKEN | Token invalid, expired, or revoked (Figma returns 403 Invalid token for bad PATs, not 401) | Re-mint the token |
FORBIDDEN (403) | Missing a read scope, or no access to the file | The message names the exact scope Figma wants (e.g. library_content:read for the styles fallback) — add it, or check file visibility |
REQUIRES_ENTERPRISE (403) | Variables API needs Figma Enterprise | Not a failure — tokens falls back to published styles (which needs the Library content scope above) |
RATE_LIMITED (429) | Figma’s per-minute limit | The client retries with backoff automatically (honoring Retry-After); if it still surfaces, wait a minute or batch fewer nodes |
| ”Render timeout” on batch export | Too many large frames in one /v1/images call | Chunk to ~4 ids per call |
ref has no node id | Link points at a file, not a node | Copy the link with ?node-id=… (right-click layer → Copy link) |
