Docs & Knowledge · heygen-com/hyperframes

figma

Name: figma
Author: heygen-com/hyperframes

Import Figma content into a HyperFrames composition — rendered assets, brand tokens, components, storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI), connector-assisted motion when available, and shaders from a connector or native export. Use when the user pastes a figma.com link or asks to bring a Figma design, frame, logo, brand, or animation into a video/composition.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit

Author heygen-comGitHub heygen-com/hyperframes ↗Stars 44283License Apache-2.0（仓库根 LICENSE 为 Apache License Version 2.0；池内值亦为 Apache-2.0）Commit d2f0bc7f34

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Breaks down 'Figma → Composition' into five capability-based phases: Static Assets / Brand Tokens / Components / Motion / Shaders. The first three phases operate via REST + CLI, while the latter two lack REST counterparts and rely strictly on connectors or native exports.

skills/figma/SKILL.md

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

The phase table specifies Transport and Surface row by row, establishing a formal contract for 'which credential is used at which step', laying the groundwork for subsequent strict requirements to clarify which phase lacks which permission upon failure.

REST serves as the default channel (batchable, headless), whereas connectors are optional enhancements solely for motion/shaders; both paths freeze assets locally during import to guarantee rendering determinism.

skills/figma/SKILL.md

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.

Treats 'zero network calls during rendering' as a hard constraint, paying network costs once upfront during import; missing a connector serves as a fallback degradation path rather than an absolute failure.

Step one performs credential pre-checks rather than immediately running commands: FIGMA_TOKEN must exist in the shell environment or project .env with read-only permissions; if absent, guide the user through a one-time setup and halt, strictly forbidding 'running blindly to catch errors'.

skills/figma/SKILL.md

**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).

Shifts credential validation from trial-and-error to pre-flight checks; explicitly defines 401/403/429 semantics (BAD_TOKEN / FORBIDDEN specifying missing scopes / REQUIRES_ENTERPRISE / RATE_LIMITED with automated exponential backoff).

Asset import follows idempotency + freezing + provenance tracking: deduplicated by fileKey:nodeId:format:scale:version, stored in .media/images/, logged to the manifest, and used to rebuild the shared media-use catalog.

skills/figma/SKILL.md

Idempotent per `fileKey:nodeId:format:scale:version`.

Anchored by: 'Renders over REST, sanitizes SVG, freezes under `.media/images/`, appends the manifest with provenance' — a single import must be simultaneously reproducible, auditable, and retrievable by sibling skills.

Combines multiple nodes into a single /v1/images call when fetching assets for an entire frame to bypass per-minute rate limits; conversely, chunks storyboard batch exports (>~12 IDs trigger render timeouts, split into ~4 per chunk).

skills/figma/SKILL.md

All render in a single `/v1/images` call, which is figma's own answer to the per-minute rate limit

Both contrasting parameter-tuning strategies stem from empirical testing with documented rationale to prevent subsequent developers from blindly 'optimizing' them away.

The component phase reconstructs the node tree into geometrically precise, editable HTML and performs token binding strictly 'by ID, never by raw value': bound to imported tokens using var(--slug, literal), while retaining literals and flagging unknown tokens.

skills/figma/SKILL.md

Bound to an **unknown** token → literal + `data-figma-unresolved` flag.

Explicitly prohibits guessing tokens by hex color values to avoid silent misbindings; mandates pixel-level self-verification for hero elements against PNGs exported from the same node via the figma asset CLI.

The motion phase enforces 'mechanical decoding + objective gating': connector-retrieved motion context is decoded via pure helpers (never manually transcribing keyframes, stripping loop-wrap trailing frames), then strictly verified using verify-motion.mjs against reference video motion energy, failing below 15dB.

skills/figma/SKILL.md

it compares motion-energy deltas (static import fidelity cancels out) and fails below 15dB min motion-PSNR

Converts subjective visual similarity into reproducible metrics; requires re-evaluating the translation logic rather than tweaking thresholds when validation fails.

Decodes storyboard sections via mechanical syntax rather than visual guesswork: filters scene units by size, sorts sequence by x-coordinate, derives element chains from adjacent-frame diffing, and exports only one asset per chain; upgrades to 'reconstructing UI + treating frame diffs as interactions' when frames depict the same interface.

skills/figma/SKILL.md

**The cardinal rule: storyboard frames are KEYFRAMES, not slides.**

Establishes a firm guardrail against common failure modes (treating storyboards as linear slideshows) and provides explicit criteria for upgrading element chains into reconstructed apps (code what changes state, freeze what doesn't).

2Core Capabilities

01Figma asset import: REST rendering → SVG sanitization → freezing to .media/images/ → logging to manifest ledger → rebuilding .media/index.md → printing img snippets, idempotent via fileKey:nodeId:format:scale:version

02Batch node asset fetching: merges multiple nodes from the same file into a single /v1/images call; requires --description, exposes --entity for media-use resolution matching

03Brand tokens/variables import & runtime theming: composition variables + figma-tokens.json + .media/figma-bindings.jsonl binding index; automatically degrades to published styles on non-Enterprise plans

04Component import: node tree → geometrically precise editable HTML, packaged into registry entries at compositions/components/<name>/; vectors and boolean operations leverage Phase-1 automatic rasterization

05Motion fidelity gating via verify-motion.mjs: computes frame-diff motion energy PSNR against reference video, default threshold 15dB, supports --crop for card regions

06Storyboard section reconstruction: size-filtered scene units, x-coordinate sorting, adjacent-frame diffing for element chains, mapping director notes to transition vocabularies, and chunked batch export

07Shader pipeline: skips connector pixel capture (which flattens shaders into solid background colors), prompting the user to export natively for asset/clip import instead

08Deterministic finalization: leaves no Figma URLs inside compositions, eliminates repeat: -1, ensures timelines pause properly, and registers literal keyframes

3External Dependencies

Kind	Dependency / Endpoint
cli	hyperframes CLI 的 figma 子命令（asset / tokens / component）与 check 门禁
api	Figma REST 批量渲染导出（host 未在 SKILL.md 出现，只写了路径）
api	Figma REST published-styles 回退（非 Enterprise 变量降级路径，需 library_content:read）
network	用户粘贴的 figma.com 链接（解析 fileKey / nodeId 后走 REST）；取 token 的引导页在 figma.com/settings
network	可选的兼容 Figma 连接器（运动上下文与着色器数据；与本 skill 的 token 分开授权；未指名具体服务）
package	@hyperframes/core/figma 纯 helper（motionContextToDocs 解码、motionToGsap、emitTimelineScript）
cli	ffprobe / ffmpeg（仅 verify-motion.mjs 以数组参数子进程调用，抽帧与 PSNR）
network	GSAP + CustomEase CDN（注入合成 HTML 的 script 标签；产物期由浏览器拉取，按范式不判级）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Graded/per-use authorization, sandbox recommended

For Administrators

Approval workflow, rollback support, full audit

Evidence & Triggers (File Paths & Excerpts)

scripts/: Local script and command execution: node skills/figma/scripts/verify-motion.mjs --reference <export.mp4> --rend
网络端点: Declared external network access: Figma REST read-only endpoints (/v1/images batch export, /v1/files/:key/styles fallback, node tree, variable
本地工作目录: File I/O and artifact output: .media/images/ (frozen Figma rendered assets), .media/manifest.jsonl (provenance ledger), .media/index.md (

Audit Notes: Categorized under the Orange tier primarily due to the credential surface: the skill's declared execution path (SKILL.md defines the directory contents) requires FIGMA_TOKEN as a prerequisite, stating that either the shell env or project .env is supported and that the CLI loads .env automatically, using it to pull node trees, variables, and motion contexts into the local project (and model context) via REST or connectors. Similar precedents (product-launch-video / media-use reading ~/.heygen) fall under Orange. Mitigating factors are also documented: the token requires minimal read-only scopes, the skill strictly prohibits writing to Figma, and token leakage into conversation logs is barred; the included verification script (verify-motion.mjs) never accesses credentials or network interfaces, invoking only local ffmpeg/ffprobe binaries on local files. No TLS downgrades, anti-automation bypasses, arbitrary code execution, or hidden scripts were found (avoiding Red); nor does it feature fixed public endpoint queries characteristic of Yellow. Trigger condition: credentials and REST calls are invoked only when the user explicitly requests an import from Figma.

5Second-Pass Verification

[ok] FIGMA_TOKEN 是否真被读取并用于外发（橙档判定的关键证据） — SKILL.md 第 26 行给出预检（`[ -n "$FIGMA_TOKEN" ]` 或项目 .env），第 28–30 行给出取 token 的一次性设置与「never ask them to paste the token into the conversation」；第 36 行给出 401/403/429 的处置语义。读取与实际 REST 调用发生在官方 hyperframes CLI 侧，本 skill 的目录只声明并约束该行为——与 hyperframes-cli 同口径，故橙档依据记在 SKILL.md 的声明面，并注明执行主体。
[unlocatable] Figma REST 的具体 host 能否在源码内定位 — SKILL.md 只写出路径（`/v1/images`、`/v1/files/:key/styles`），未出现 api.figma.com 或任何 host；连接器也未指名具体服务。故 external_deps.endpoint 按「仅路径」标注，不补写推测域名。
[ok] verify-motion.mjs 的外部接触面（是否有隐藏网络/凭证/越界写入） — 全文 154 行只 import node:child_process / node:fs / node:os / node:path；调用为 execFileSync("ffprobe", …)、execFileSync("ffmpeg", …)、spawnSync("ffmpeg", …) 三处，全部数组参数无 shell；无 fetch、无 process.env、无凭证；写入仅限 mkdtempSync(join(tmpdir(), "verify-motion-")) 下的临时图，结束 rmSync 清理。阈值与标定写在文件头注释里（忠实 min 20.3dB / 发散 min 5.0dB，默认阈值 15dB）。
[ok] 「连接器不执行 shader、会压平」这一关键警告是否自洽（会不会是夸大） — Phase 5 段与 Phase 4 步骤 4 的例外说明互相印证：两处都指向「请用户原生导出」，且 Phase 4 明确 shader 轨道烘焙会静默丢 shader。属同一声明的两处一致陈述，非矛盾。
[ok] 「分镜帧是关键帧而非幻灯片」是否只是口号 — 同一段给出可机械执行的规则：场景单元按尺寸（如 >1400×900）过滤、顺序按 absoluteBoundingBox.x、相邻帧按 name 再按几何相似匹配成元素链、每链一资产、批量导出分块（~4/次，26 场景 ≈52 次单资产调用是反面教材），并给出升级判据（同一 UI 逐帧 → 重建 app、把帧差当作交互）。

6Verdict & Scenarios

Decouples credentials and channels by operational phase: uses headless REST for batchable tasks, reserves connectors strictly for motion/shaders where REST falls short, and offers native export fallbacks when connectors are unavailable

Transforms subjective fidelity into reproducible numeric gating with calibrated criteria (faithful ≈20+dB, divergent ≈5dB, threshold 15dB), mandating translation audits over threshold adjustments upon failure

Provides mechanical syntax for storyboard reconstruction (size filtering / x-sorting / dual name & geometry matching / one asset per chain), turning error-prone 'visual guesswork' into deterministic structural parsing

Enforces token binding by ID rather than raw value, explicitly tagging unmapped tokens for user review to prevent silent misbindings

Provides empirical rationales for bidirectional rate-limit handling (single-batch calls vs. ~4-node chunks) and documents the tradeoffs of alternatives (per-scene calls exhaust rate budgets)

Best for: Ideal for users seeking to systematically bring existing Figma designs into HyperFrames compositions: importing logos, icons, and images; extracting brand tokens to enable token-driven component theming; reconstructing static frames into editable HTML components; converting Figma animations into GSAP code; and translating storyboard strips (scene frames + director notes) into keyframed animations. Also fits workflows requiring motion fidelity validation (motion energy PSNR gates).

Not for: Not suitable for: 1) Environments without a Figma account/workspace or lacking read-only access tokens (halts at Phase 1); 2) Workflows expecting live Figma fetches during rendering (strictly mandates freezing assets locally, forbidding runtime network access); 3) Scenarios expecting automated recreation of Figma shader effects (connectors cannot execute shaders; requires manual native export); 4) Users treating Figma merely as a sequential screenshot slideshow player (storyboard frames must be reconstructed via keyframes by strict design); 5) Environments not using the official hyperframes CLI (all operations rely on this CLI).

Install Agent-Ready

① Verified Mirror 2026-09-28

Option A · Direct DownloadDownload figma.tar.gz

sha256: 22ae9717e5a19361…

Option B · Copy Guide for Agent

install.json

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit d2f0bc7f34.