figma

#!/usr/bin/env node
/**
 * Objective fidelity gate for figma-motion imports (skill step 2b).
 *
 * Compares the HyperFrames render against Figma's own `export_video` output
 * using MOTION-ENERGY deltas: for each sample window [t, t+interval], the
 * frame difference ref(t+i)-ref(t) is compared (PSNR) against
 * render(t+i)-render(t). Static import divergence (fonts, rasterized edges,
 * subpixel geometry — the hybrid-fidelity ceiling) cancels out of both
 * deltas, so the score isolates choreography: trajectories, timing, easing.
 *
 * Calibration (SDS "Unlocked" card, 2026-07): a faithful translation scored
 * min 20.3dB / mean 27.7dB; a diverging one (invented retract keyframes,
 * wrong durations) scored min 5.0dB / mean 23.1dB. Default threshold 15dB
 * sits between with margin on both sides.
 *
 *   node verify-motion.mjs --reference figma-export.mp4 --render out.mp4 \
 *     [--crop WxH+X+Y] [--interval 0.2] [--min-motion-psnr 15]
 *
 * --crop selects the card region inside the (usually larger) composition
 * frame. Measure it from the render (the card's left/top edge + scaled
 * size), don't guess: a wrong crop reads as motion divergence.
 */
import { execFileSync, spawnSync } from "node:child_process";
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

function arg(name, fallback) {
  const i = process.argv.indexOf(`--${name}`);
  return i > -1 ? process.argv[i + 1] : fallback;
}
const reference = arg("reference");
const render = arg("render");
if (!reference || !render) {
  console.error(
    "usage: verify-motion.mjs --reference ref.mp4 --render out.mp4 [--crop WxH+X+Y] [--interval 0.2] [--min-motion-psnr 15]",
  );
  process.exit(2);
}
const crop = arg("crop", null);
const interval = Number(arg("interval", "0.2"));
const minMotion = Number(arg("min-motion-psnr", "15"));

const ffprobe = (file) =>
  Number(
    execFileSync("ffprobe", [
      "-v",
      "error",
      "-show_entries",
      "format=duration",
      "-of",
      "csv=p=0",
      "--",
      file,
    ])
      .toString()
      .trim(),
  );
const refDur = ffprobe(reference);
const renderDur = ffprobe(render);
const end = Math.min(refDur, renderDur) - interval - 0.01;

const dims = execFileSync("ffprobe", [
  "-v",
  "error",
  "-select_streams",
  "v",
  "-show_entries",
  "stream=width,height",
  "-of",
  "csv=p=0",
  "--",
  reference,
])
  .toString()
  .trim()
  .split(",")
  .map(Number);
const [rw, rh] = dims;

let cropFilter = "";
if (crop) {
  const m = crop.match(/^(\d+)x(\d+)\+(\d+)\+(\d+)$/);
  if (!m) {
    console.error("bad --crop, expected WxH+X+Y");
    process.exit(2);
  }
  cropFilter = `crop=${m[1]}:${m[2]}:${m[3]}:${m[4]},`;
}

const dir = mkdtempSync(join(tmpdir(), "verify-motion-"));
const frame = (src, t, vf, dst) => {
  const args = ["-y", "-v", "error", "-ss", String(t), "-i", src, "-frames:v", "1"];
  if (vf) args.push("-vf", vf);
  execFileSync("ffmpeg", args.concat(dst));
};
const diff = (a, b, dst) =>
  execFileSync("ffmpeg", [
    "-y",
    "-v",
    "error",
    "-i",
    a,
    "-i",
    b,
    "-filter_complex",
    "blend=all_mode=difference",
    dst,
  ]);
const psnr = (a, b) => {
  // spawnSync with array args (no shell): psnr stats land on stderr
  const r = spawnSync("ffmpeg", ["-i", a, "-i", b, "-lavfi", "psnr", "-f", "null", "-"], {
    encoding: "utf8",
  });
  const m = (r.stderr || "").match(/average:([\d.]+|inf)/);
  return m ? (m[1] === "inf" ? 99 : Number(m[1])) : NaN;
};

const renderVf = `${cropFilter}scale=${rw}:${rh}`;
const results = [];
for (let t = 0; t <= end; t = Math.round((t + interval) * 1000) / 1000) {
  const t1 = Math.round((t + interval) * 1000) / 1000;
  frame(reference, t, null, join(dir, "ra.png"));
  frame(reference, t1, null, join(dir, "rb.png"));
  frame(render, t, renderVf, join(dir, "oa.png"));
  frame(render, t1, renderVf, join(dir, "ob.png"));
  diff(join(dir, "ra.png"), join(dir, "rb.png"), join(dir, "rd.png"));
  diff(join(dir, "oa.png"), join(dir, "ob.png"), join(dir, "od.png"));
  results.push({
    t,
    motion: psnr(join(dir, "rd.png"), join(dir, "od.png")),
    abs: psnr(join(dir, "rb.png"), join(dir, "ob.png")),
  });
}
rmSync(dir, { recursive: true, force: true });

const min = Math.min(...results.map((r) => r.motion));
const mean = results.reduce((s, r) => s + r.motion, 0) / results.length;
for (const r of results)
  console.log(
    `window ${r.t.toFixed(2)}s→${(r.t + interval).toFixed(2)}s  motion-psnr=${r.motion.toFixed(2)}dB  (abs=${r.abs.toFixed(1)}dB)${r.motion < minMotion ? "  <-- BELOW THRESHOLD" : ""}`,
  );
console.log(
  `\nwindows=${results.length} min-motion=${min.toFixed(2)}dB mean-motion=${mean.toFixed(2)}dB threshold=${minMotion}dB`,
);
if (min < minMotion) {
  console.log(
    "VERDICT: FAIL — choreography diverges from the Figma export (check timings, invented keyframes, durations)",
  );
  process.exit(1);
}
console.log("VERDICT: PASS — motion matches the Figma export within the static-fidelity ceiling");

---
name: figma
description: Bring Figma into a HyperFrames video - rendered assets, brand tokens, components, storyboard frames as reconstructed motion (frames read as states, not slides), shaders and connector-assisted motion. Use when the person pastes a figma.com link or asks to use a Figma design, frame, logo or brand.
---

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

# Figma → HyperFrames

Every import happens at build time and freezes a local file with its source recorded under `.media/`, so renders never call Figma and re-running a command re-imports only what changed. Assets, tokens and components go over REST with a token; motion and shader data need a Figma connector, or a native export from the person.

## Access

`FIGMA_TOKEN` in the shell or the project `.env`. Check it exists before the first command; if not, tell the person how to make one and stop: figma.com → Settings → Security → Personal access tokens, read-only **File content** and **File metadata**, plus **Library content** for `tokens` on non-Enterprise plans. They set it themselves; never ask them to paste it into the chat.

| Error | Meaning |
| --- | --- |
| `BAD_TOKEN` (401) | Expired or revoked: make a new one |
| `FORBIDDEN` (403) | The message names the missing scope, or the file isn't visible to the account |
| `REQUIRES_ENTERPRISE` (403, variables) | Not a failure: the published-styles fallback already ran |
| `RATE_LIMITED` (429) | Already retried with backoff; wait a minute or import fewer nodes per call |

## Commands

- A layer, logo or image: `npx hyperframes figma asset '<url or fileKey:nodeId>' [more refs] --format svg|png --scale 2 --description "<what it is>" [--entity "<brand mark>"]`. SVG for vectors and logos, PNG at 2x for raster. Several nodes of one file in one call render in a single request; `--entity` lets `/media-use` find a brand mark later.
- Brand colours and type: `npx hyperframes figma tokens <fileKey>`. Run it before `component` and paste the printed entries into `data-composition-variables`. Without Enterprise it falls back to published styles. A connector can supply variables there instead: cache its raw response in `.media/figma-cache/` and write the bindings to `.media/figma-bindings.jsonl` (`{kind:"binding", figmaId, sourceFileKey, compositionVariableId:"figma:<name>", version}`).
- A frame as editable HTML at exact geometry: `npx hyperframes figma component '<url or fileKey:nodeId>'`, packaged under `compositions/components/<name>/`. A fill bound to an imported token comes out as `var(--slug, #literal)`, so one variable re-brands every import; an unknown token stays a literal marked `data-figma-unresolved`: import that library's tokens and re-import. Ask once which file a library is; never match by hex.
- Check hero components against Figma's pixels (`figma asset <same node> --format png`). Text drift is the usual cause; report drift you can't fix instead of hand-tweaking the import.

## Motion (connector)

Usage beacon: these phases have no CLI touchpoint, so run `npx hyperframes events --skill=figma-motion` when you begin and `npx hyperframes events --skill=figma-motion --event=skill_completed --outcome=success|error` when done. Same for shaders (`figma-shaders`) and storyboards (`figma-storyboard`).

1. Fetch motion context for the parent frame in one recursive request; cache the raw JSON in `.media/figma-cache/`.
2. Normalise with `motionContextToDocs(raw, { selectorFor, repeat })` from `@hyperframes/core/figma`, never by transcribing keyframes. It reads the motion.dev snippets (the CSS snippets stretch durations), drops loop-wrap tail keyframes and keeps bezier eases. `selectorFor` returns the ids from the component import.
3. `motionToGsap(doc)` → `emitTimelineScript(spec)`, injected after the GSAP and CustomEase tags: paused, finite, a literal `window.__timelines` key. Named eases outside the mapped set fall back to linear; say so.
4. Verify against Figma's own export: `node <SKILL_DIR>/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop WxH+X+Y`. It compares motion between samples, so static drift cancels out, and fails under 15 dB (faithful ≈ 20+, diverging ≈ 5). Measure `--crop` from the render's card edges. A fail means fix the translation, not the threshold.
5. A track that won't translate: export it, freeze the MP4 and place it as `<video class="clip">`.

## Shaders

Figma's export path flattens shaders to their base colour, and shader source is only reachable for library-published styles. Ask the person for a native export of that frame (PNG or MP4) and place it as an asset or clip.

## Storyboards: frames are KEYFRAMES, not slides

Two frames holding the same element describe that element's state through time: animate the element between the states. Playing the frames back to back as stills is the failure mode.

1. Scenes are every frame-sized node in the section, named frames and loose full-frame rectangles alike: filter by size, not type or name. Order by `absoluteBoundingBox.x`.
2. Match children across neighbouring frames by name first, then by similar size and position. Tween geometry between states; crossfade two exports in place when the pixels changed. Export one asset per element, not one still per frame. Unmatched children enter or exit at their scene's beat.
3. Text nodes below the strip are motion notes for the scene above them, not on-screen copy. A note about motion inside a scene ("lines reveal one after another") means import that frame as a component and animate it.
4. Export in batches of about 4 scene frames per call: past about 12 ids `/v1/images` times out.
5. Frames that are one product UI in successive states: rebuild the UI as live DOM: code what changes state, freeze what doesn't, and treat each frame change as an interaction to perform (the cursor moves, clicks, the screen responds), not a tween to apply.
6. Stills are the fallback, only for frames with no shared elements.

Never leave a Figma URL in the composition.