feat(skills): reroute /figma by capability - REST/CLI for phases 1-3, MCP for 4-5 (M4)

[vanceingalls]

What

M4: the /figma skill rewritten from MCP-first to the capability split, plus storyboard guidance — with all four catalog surfaces updated in lockstep (CLAUDE.md, README.md, docs/guides/skills.mdx, skills/hyperframes/SKILL.md router, skills-manifest.json).

• Routing by capability (spec §2): assets/tokens/components → the hyperframes figma CLI over REST (FIGMA_TOKEN); motion/shaders → agent-driven MCP (no REST equivalent exists). Two-credential guidance: every failure says which credential that phase needs.
• Rate-limit tactics baked into the skill (spec §2.1/§2.2): recursive:true batching on MCP, raw-response caching so retranslation never spends a second call, verification screenshots opt-in, REST 429 backoff.
• Binding flow (spec §7.1): tokens before components; unknown-library bindings → one ask per library per project; never match by hex.
• Storyboards — field-tested against two real client boards:
  • The cardinal rule: storyboard frames are keyframes, not slides. Frames sharing an element describe that element's state through time — diff adjacent frames into element chains (match by name, else geometry similarity), tween elements between states, crossfade in place only when pixels genuinely differ, enter/exit unmatched children, tween backgrounds as a color track. One asset per chain, never one still per frame. (Proven live: a 4-frame logo rise reconstructed as one element with four keyframes.)
  • Parsing grammar: frame-sized nodes (incl. loose full-frame rectangles) = scenes, x-position = time order, TEXT below the strip = director notes paired by x-overlap (motion intent, never on-screen copy).
  • Note-verb → transition vocabulary (EXPLOSION→burst, SLIDES/SCROLL→directional, MORPH/REVEALS→crossfade, CYCLE→hold) and batch-export mechanics (chunk ~4 ids per render call; big frames timeout past ~12).
  • Stills-in-sequence demoted to explicit fallback for frames that don't decompose.
• Shader honesty: default path is user-native export (MCP flattens shaders to base color; source needs a paid Full seat) — never attempt MCP pixel capture of a shader.

Verified

Both storyboard recipes executed live against real files before being written down: a 26-scene stills animatic (60s) and a 19-scene element-chain reconstruction (37s, 13 element exports instead of 19 slides), both lint/validate clean.

---

Stack (6/6): #1868 → #1869 → #1870 → #1871 → #1872 → this PR

🤖 Generated with Claude Code

[vanceingalls]

• feat(skills): reroute /figma by capability - REST/CLI for phases 1-3, MCP for 4-5 (M4) #1873 👈 (View in Graphite)
• feat(core,cli): figma component import with binding-aware node-to-html mapper (M3) #1872
• feat(core,cli): figma tokens import with alias-aware binding records (M2) #1871
• feat(core,cli): figma REST client, asset import command, binding index (M0+M1) #1870
• feat(core): figma motion → GSAP translator + /figma skill v1 #1869
• feat(core): figma module foundations — types, parseFigmaRef, freeze, manifest, asset snippet #1868
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[miga-heygen]

Review — feat(skills): reroute /figma by capability (M4, stack 6/6)

Verdict: LGTM with nits

The skill rewrite is excellent. The phase table is immediately legible, the REST-vs-MCP split is well-reasoned (REST where it can, MCP where it must), two-credential scoping is clear with good failure guidance, and the storyboard section is genuinely impressive — the "frames are keyframes, not slides" cardinal rule and the element-chain diffing algorithm read like hard-won production lessons. Rate-limit tactics baked into a skill definition is a nice touch. All four catalog surfaces (CLAUDE.md, README.md, skills.mdx, hyperframes SKILL.md) updated in lockstep.

Findings

1. figma.ts HELP text is stale — the component subcommand is now registered in the subCommands map (this PR adds that line), but the HELP string still only lists asset and tokens. A user running hyperframes figma with no args sees no mention of component. Suggest adding a component entry to the HELP block.

2. Storyboard batch export typo — SKILL.md, storyboard rule 6: "Batch exports (elements or stills)::" has a double colon. Cosmetic.

3. Storyboard transport gap — The phase table covers phases 1–5 but storyboards (which compose phases 1+3 for export + a custom animatic pipeline) aren't explicitly placed in the table. The routing section handles this, but an agent seeing the phase table alone might wonder which credential storyboards need. Consider a one-liner note: "Storyboard animatics compose Phase-1 asset exports (REST) with agent-driven timeline assembly."

4. skills.mdx trailing whitespace — The /figma row in docs/guides/skills.mdx extends well past the table column, making the raw markdown harder to read. Not a rendering issue, just noisy.

Ponytail

+97/-27 is mostly the SKILL.md rewrite (90 of the 97 additions). The skill grew from ~40 lines to ~110 — justified by the 5-phase structure, storyboard grammar, and rate-limit guidance that didn't exist before. The catalog-surface updates are 1-line-each mechanical sync. The figma.ts change is a single subcommand registration. No dead code, no duplication. The HELP text omission (finding 1) is the only real weight — fixing it would add ~1 line.

net: -0 lines possible (the growth is all load-bearing)

---

Review by Miga

[james-russo-rames-d-jusso]

Reviewed at b7054993d2 (stack 6/6, chain #1868→…→#1872→this).
Body carries 🤖 footer + AI-trailer per HF convention; noted.

Summary — Reshapes the /figma skill from "MCP-first" to a capability split (REST/CLI for phases 1-3, MCP-only for phases 4-5) and wires the component subcommand into the CLI dispatch map. Small surface (97+/27-), mostly docs + one-line dispatch. Routing determinism is straightforward (all four catalog surfaces updated in lockstep, no dynamic detection). One documentation-completeness gap.

Looks good to me modulo the nits below.

Concerns

🟠 packages/cli/src/commands/figma.ts:27-30 — subcommand added to dispatch map but not to HELP text.

This PR adds component: () => import(...) at line 43 and updates the meta description to "assets, tokens, and components (REST)", but the HELP string block still only lists asset and tokens:

SUBCOMMANDS:
  asset   Render a node ...
  tokens  Import variables/styles ...

Running hyperframes figma with no args prints a help block that doesn't advertise the new command — users have to read the skill doc or the PR body to discover it. Similarly the examples array at lines 13-20 has no component example; if _examples.ts feeds hyperframes figma --help or the docs site, component won't show. One-line add: a SUBCOMMANDS entry for component and an examples[] entry ("Import a frame as an editable HTML component", hyperframes figma component 'https://...'). Not a merge blocker, but the whole point of M4 is discoverability of the split.

Nits

🟡 skills/figma/SKILL.md — MCP rate-limit claim "6 tool calls/month" is load-bearing and worth a source link. The number drives the "batch with recursive:true" recommendation throughout the skill. If the plan tier changes upstream or Figma updates the quota, the skill's cache-first stance becomes wrong silently. A footnote citing Figma's public plan matrix (or a comment "@2026-07 Starter tier") would make the drift visible when it happens.

🟡 skills/figma/SKILL.md (Storyboards §, note-verb table) — the "MORPH / REVEALS → crossfade" and "CYCLE THROUGH / EACH ONE → longer hold on that scene" mappings collapse motion that Phase-3 components could animate correctly. Item 8 of the same section addresses this ("a note describing motion inside a scene → Phase-3 component import, not a flat PNG"), but the table above still tells the agent "crossfade" first. Consider a "or upgrade to Phase-3 if pixels differ inside a single scene" nudge on the crossfade rows.

🟡 skills/figma/SKILL.md (Motion §, step 4) — "bake: export_video → freeze MP4 → embed as <video class="clip">" is silent on shader-fallback determinism. The Phase-5 §sat below says "Figma's MCP render path does not execute shaders (they flatten to the base color)". If Motion step 4 falls back to export_video for a shader-driven track, that export flatten-to-base-color happens silently. Worth cross-linking Phase-5's "don't attempt MCP pixel capture of a shader" into step 4 explicitly.

🟡 docs/guides/skills.mdx:87 — trailing whitespace on the updated /figma row that the sibling rows don't have. Markdown-table linting will flag this on the next docs build; the raw diff shows a long tail of spaces after "into a composition." on this row only.

Questions

↩️ Migration path for users mid-flow on the old MCP-first path. A user who ran the old /figma skill yesterday against a Figma file — do they need to re-import (Phase 1) any frozen assets? The skill wording says "Split by capability (design spec §2)" but doesn't call out backwards-compat: are existing .media/figma-bindings.jsonl / manifest records compatible, or does someone need to nuke .media/figma-cache/ because the raw-response shape differs? If the answer is "yes, compat is trivial", one line ("existing frozen assets are unaffected — the split changes only which credential the next import uses") in the SKILL doc would head off support questions.

↩️ Rate-limit claim "REST is per-minute (10+/min)" — is this the file-level or endpoint-level bucket? Figma's public docs distinguish /v1/images (image renders) from /v1/files (tree/version), each with its own token-bucket. The skill treats them uniformly. If the agent hits 429 on /v1/images while a /v1/files call would still succeed, the current guidance ("back off on 429") applies the wrong backoff to the wrong endpoint. Not blocking; the current wording is defensible.

What I didn't verify

• The skills-manifest.json hash values (a02c588600879115, 2bd5cdf9f851b4d2) — trusted-as-recomputed by the manifest builder rather than hand-verified.
• The two "verified live" storyboard reconstructions (26-scene animatic, 19-scene element-chain) referenced in the PR body — outside-of-diff artifact.
• Whether the README.md + CLAUDE.md + docs/guides/skills.mdx triplet is genuinely the exhaustive set of catalog surfaces (PR body claims "all four" but lists five including SKILL.md router and manifest — trusted).

— Rames D Jusso

[vanceingalls]

Review feedback addressed (pushed in the absorbed update):

Fixed

• HELP text + examples (miga Initial repo setup #1, Rames 🟠): component is now in the SUBCOMMANDS block and the examples[] array; the help also gained FIRST-TIME SETUP (token mint + read-only scope checklist) and WHAT TO EXPECT blocks.
• Storyboard :: typo (miga initial code #2): fixed.
• Storyboard transport note (miga feat(core): add compiler entry point and runtime composition fixes #3): added — storyboard animatics compose Phase-1 REST exports with agent-driven timeline assembly, no MCP needed.
• skills.mdx trailing whitespace (miga feat(studio): consolidate into single OSS-ready NLE editor #4, Rames 🟡): trimmed.
• MCP quota provenance (Rames 🟡): claim now dated ("figma plan matrix as of 2026-07 — re-verify if quotas look off") and the REST note says per-endpoint buckets.
• Crossfade rows collapse Phase-3-able motion (Rames 🟡): MORPH/REVEALS and CYCLE rows now carry the "or Phase-3 import if the motion is inside one scene" nudge inline.
• Motion step 4 shader silence (Rames 🟡): explicit exception added — shader-driven tracks must NOT bake via export_video (flattens to base color); ask for a native figma export instead. Named-ease fallback behavior also documented with a pointer to the mapping table.
• Migration path (Rames Q): one-liner added — existing frozen assets, manifest records, and bindings are unaffected; the split only changes which credential the next import uses.

Since this review, the skill also gained a token preflight (checks shell env or project .env before the first CLI call, walks the user through setup instead of harvesting the error) and per-step narration guidance — plus a new docs page docs/guides/figma.mdx.

🤖 Generated with Claude Code

[miga-heygen]

Re-review — feat(skills): reroute /figma by capability (M4, stack 6/6)

Verdict: LGTM

Three follow-up commits (e5cc6314, 934e23b5, 7b98354b) address review findings cleanly and add a polished first-run experience. The PR is in good shape.

Previous concerns

#	Finding	Status
1	figma.ts HELP text missing component subcommand	Fixed — component now listed with description in the reworked HELP block
2	Double colon typo in SKILL.md storyboard rule 6	Fixed — single colon
3	Storyboard transport gap in phase table	Fixed — added the exact one-liner: "Storyboard animatics compose Phase-1 asset exports (REST) with agent-driven timeline assembly — no MCP needed."
4	skills.mdx trailing whitespace on /figma row	Unchanged — cosmetic, not blocking

New content review

cliError.ts — Clean shared error boundary. Splits on \n to extract title vs body for errorBox, which pairs well with the multi-line NO_TOKEN message. process.exit(1) is standard CLI practice. Non-Error throws rethrow correctly.

figma.ts HELP rework — The HELP block went from a bare env-var hint to a full first-time setup walkthrough (mint → scopes → export) plus a "what to expect" section on provenance/idempotency. This is the kind of CLI output that saves a support thread.

client.ts error enhancements — FORBIDDEN (generic 403) added to the error code union, slotted correctly after the enterpriseGated check so Enterprise 403s still route to REQUIRES_ENTERPRISE. The NO_TOKEN, BAD_TOKEN, and new FORBIDDEN messages are all actionable with specific fix instructions. Error codes in the client match the troubleshooting table in the new Mintlify guide 1:1.

docs/guides/figma.mdx — 117-line Mintlify guide covering all five phases, one-time setup with <Steps>, asset/token/component examples with CLI output, motion/shader/storyboard summary, provenance explanation, and a troubleshooting table. Well-structured user-facing documentation that mirrors the SKILL.md content without duplicating verbatim.

withFigmaErrors wiring — All three subcommands (asset.ts, tokens.ts, component.ts) consistently wrapped. The tokens.ts styles-fallback message got a helpful clarification ("style values resolve at component-import time").

Ponytail

+330/-71 across 14 files. The growth is the Mintlify guide (~117 lines), the reworked HELP/error messages, and the cliError.ts boundary. All load-bearing — no padding, no dead code.

CI: all required checks pass.

---

Review by Miga

[miguel-heygen]

LGTM. Stamping after Miga R2 verified the prior Figma-stack blockers are addressed; live checks are green, with only Graphite stack mergeability pending where applicable.

[james-russo-rames-d-jusso]

R2 verification — reviewed at 934e23b5 (post-force-push). 🟢

R1 was safe, only a docs-completeness nit. On re-read at HEAD, the nit was misframed — I'll withdraw it.

R1 nit (CLI-fallback when MCP unavailable + REST rate-limited) — withdrawn

At HEAD:

• skills/figma/SKILL.md:14-18 explicitly says Phases 4-5 (Motion, Shaders) are MCP-only — no REST equivalent exists at Figma's end, so there is no CLI to fall back to.
• skills/figma/SKILL.md:30 documents the actual terminal state: "If MCP tools error unauthenticated, tell the user to connect the Figma connector and stop." That's the right shape — it's not a graceful-degrade path, it's a hard prerequisite.
• REST rate-limiting on Phases 1-3 is already covered: SKILL.md:34 (per-minute backoff on 429) + docs/guides/figma.mdx:115 (RATE_LIMITED error → "wait a minute and retry; chunk batch renders").

So the "MCP unavailable + REST rate-limited" case I imagined doesn't exist as a joint failure the docs need to cover — the two transports carry disjoint capabilities. My R1 was pattern-matching on "always document the fallback" without checking whether the fallback actually exists in this domain. Withdrawn.

R2 findings

None. Docs are consistent, rate-limit + credential-failure semantics are covered at all four catalog surfaces (CLAUDE.md, README.md, docs/guides/skills.mdx, SKILL.md), storyboard guidance is field-tested per PR body. Miga's R1 verdict (4621673047, LGTM with nits) holds.

Verdict

✅ LGTM. Clean docs PR. CI all green (perf, preview-regression, regression shards 1-8, player-perf); Graphite mergeability pending (standard for stacked PRs); Mintlify skipped (only skill/SKILL.md + one .mdx changed, no docs.json route add — appears to be intentionally out-of-scope for the Mintlify build).

— Rames D Jusso

The base branch was changed.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
hyperframes	🟢 Ready	View Preview	Jul 4, 2026, 1:21 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.