mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-03 04:38:33 +00:00
feat(skills): reroute /figma by capability - REST/CLI for phases 1-3, MCP for 4-5 (M4) (#1873)
* feat(skills): reroute /figma by capability - REST/CLI for phases 1-3, MCP for 4-5 (M4) Rewrites the skill from MCP-first to the spec 2 split: asset/tokens/ component route through the hyperframes figma CLI (FIGMA_TOKEN), motion/ shaders stay agent-driven over MCP (no REST equivalent). Adds two- credential guidance, Starter rate-limit tactics (recursive:true, raw- response cache, opt-in screenshots), the 7.1 binding flow (tokens before components, one ask per unknown library, never value matching), and the shader manual-export default. Catalog blurbs updated in lockstep. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(cli): register figma component subcommand Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(skills): add storyboard-to-animatic guidance to /figma Field-tested against a real 26-scene storyboard section: the parsing grammar (frame-sized nodes incl. loose rectangles = scenes, x-order = time order, TEXT below the strip = director notes paired by x-overlap), batched still export (chunk ~4 ids per render call - big frames timeout past ~12), a note-verb -> transition vocabulary (EXPLOSION/SLIDE/MORPH/ CYCLE), and the stills-vs-component routing rule for within-scene motion notes. Catalog blurbs updated in lockstep. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(skills): storyboard frames are keyframes, not slides Field-tested against a second real storyboard section: frames sharing an element (matched by name, else geometry similarity) define that element's states through time - tween the element between states, crossfade only when pixels genuinely differ, enter/exit unmatched children, tween frame backgrounds as a color track. Stills demoted to fallback for frames that don't decompose. Validated live: a 4-frame logo-rise reconstructed as one element with four keyframes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(figma): self-explanatory first-run experience + mintlify guide - NO_TOKEN/BAD_TOKEN errors now carry the full one-time setup (mint URL, read-only scope checklist, persist hint) instead of a bare pointer - figma subcommands print clean guidance on typed client errors, not a stack trace (shared withFigmaErrors boundary) - CLI help gains component subcommand, FIRST-TIME SETUP and WHAT TO EXPECT blocks - /figma skill: preflight the token before the first CLI call and walk the user through setup up front; narrate landed-artifact + next action at every step - new docs/guides/figma.mdx (setup, per-phase walkthroughs, provenance, troubleshooting table) wired into docs.json nav Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(figma): review fixes — missing withFigmaErrors imports, 401/403 semantics, docs accuracy - tokens.ts/component.ts called withFigmaErrors without importing it (tsup doesn't typecheck, so every invocation shipped as an immediate ReferenceError); imports added, tsc --noEmit now clean - error boundary widened to all Errors so bad-ref/bad-format input errors print their message instead of a stack trace - 401 no longer claims 'missing scopes' (figma signals that as 403); new FORBIDDEN code maps non-variables 403 to scope/access guidance - docs: asset/component refs require a node id (bare fileKey is tokens-only), example snippet matches real output, FORBIDDEN row - skill: preflight counts a project-.env token as configured (CLI auto-loads it); BAD_TOKEN/FORBIDDEN guidance split Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(cli): present figma errors via standard errorBox Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Vance Ingalls
co-authored by
Claude Fable 5
Claude Fable 5
parent
08c0a03510
commit
566d49382c
@@ -4,6 +4,7 @@ import type { FigmaAssetFormat, FigmaRef } from "./types";
|
||||
export type FigmaClientErrorCode =
|
||||
| "NO_TOKEN"
|
||||
| "BAD_TOKEN"
|
||||
| "FORBIDDEN"
|
||||
| "REQUIRES_ENTERPRISE"
|
||||
| "RATE_LIMITED"
|
||||
| "RENDER_FAILED"
|
||||
@@ -119,7 +120,17 @@ export function createFigmaClient(options: FigmaClientOptions): FigmaClient {
|
||||
if (token === "") {
|
||||
throw new FigmaClientError(
|
||||
"NO_TOKEN",
|
||||
"FIGMA_TOKEN is missing — mint a personal access token at figma.com/settings and export FIGMA_TOKEN",
|
||||
[
|
||||
"FIGMA_TOKEN is missing. One-time setup:",
|
||||
" 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",
|
||||
" Variables: Read-only (optional — brand variables, requires figma Enterprise;",
|
||||
" without it `tokens` falls back to published styles)",
|
||||
' 3. export FIGMA_TOKEN="figd_…" — add it to your shell profile or the project .env',
|
||||
" so future sessions skip this step",
|
||||
"Then re-run this command.",
|
||||
].join("\n"),
|
||||
);
|
||||
}
|
||||
const doFetch: FigmaFetch = options.fetch ?? ((url, init) => fetch(url, init));
|
||||
@@ -130,13 +141,23 @@ export function createFigmaClient(options: FigmaClientOptions): FigmaClient {
|
||||
headers: { "X-Figma-Token": token },
|
||||
});
|
||||
if (res.status === 401)
|
||||
throw new FigmaClientError("BAD_TOKEN", "figma rejected the token (401)", 401);
|
||||
throw new FigmaClientError(
|
||||
"BAD_TOKEN",
|
||||
"figma rejected the token (401) — it is expired or revoked. Re-mint at figma.com/settings → Security, then update FIGMA_TOKEN.",
|
||||
401,
|
||||
);
|
||||
if (res.status === 403 && enterpriseGated)
|
||||
throw new FigmaClientError(
|
||||
"REQUIRES_ENTERPRISE",
|
||||
"figma variables require an Enterprise plan (403) — fall back to styles",
|
||||
403,
|
||||
);
|
||||
if (res.status === 403)
|
||||
throw new FigmaClientError(
|
||||
"FORBIDDEN",
|
||||
"figma denied access (403) — the token is missing a read scope, or your account can't view this file. Check the token has File content: Read-only + File metadata: Read-only (figma.com/settings → Security) and that the file is visible to your account.",
|
||||
403,
|
||||
);
|
||||
if (res.status === 429)
|
||||
throw new FigmaClientError(
|
||||
"RATE_LIMITED",
|
||||
|
||||
Reference in New Issue
Block a user