HyperFrames Animation

All motion knowledge in one skill: rules (atomic recipes), blueprints (multi-phase scene templates), transitions (scene-to-scene), techniques (broader motion-design patterns), and adapters (per-runtime APIs).

For the composition contract (data attributes, sub-compositions, determinism) see hyperframes-core.

Default: compose atomic rules

Pick 2-4 rules from rules-index.md, glue them together with a single paused GSAP timeline, done. This is faster and produces less code than starting from a blueprint.

Load a blueprint when

The scene matches an existing pre-designed multi-phase template (brand-reveal, social-proof, etc.) and reusing its phase pipeline saves real authoring time
You want runnable ground-truth code for a complex 4-5 phase choreography

Blueprints live in blueprints-index.md. Each entry points to blueprints/<id>.md (recipe). Do not read it speculatively; load it when you've already decided you need scene-level orchestration.

Routing

Want to…	Read
Pick an atomic motion pattern by trigger / tag	`rules-index.md`
Read one rule's full HTML / CSS / GSAP recipe	`rules/<name>.md`
Pick a multi-phase scene template	`blueprints-index.md`
Read one blueprint's full recipe	`blueprints/<id>.md`
Author a scene transition (CSS-driven, between two clips)	`transitions/overview.md`, `transitions/catalog.md`
Look up a broader motion-design technique	`techniques.md`
Analyze an existing composition's animation map	`scripts/animation-map.mjs`
GSAP API — timeline / tweens / position parameters	`adapters/gsap.md`
GSAP — drop-in effect recipes	`rules/gsap-effects.md`
GSAP — transforms / perf	`adapters/gsap-transforms-and-perf.md`
GSAP — eases / stagger	`adapters/gsap-easing-and-stagger.md`
GSAP — timeline / labels	`adapters/gsap-timeline-and-labels.md`
Lottie / dotLottie (After Effects exports, `window.__hfLottie`)	`adapters/lottie.md`
Three.js / WebGL (3D scenes, `AnimationMixer`, `hf-seek`)	`adapters/three.md`
Anime.js (`window.__hfAnime`)	`adapters/animejs.md`
CSS keyframes (`animation-delay` / `play-state` / `fill-mode`)	`adapters/css-animations.md`
Web Animations API (`element.animate()`, `currentTime` seek)	`adapters/waapi.md`
TypeGPU / WebGPU (`navigator.gpu`, WGSL, compute pipelines)	`adapters/typegpu.md`
HTML-as-texture + WebGL/GLSL post-fx (capture live DOM via `drawElementImage`)	`adapters/html-in-canvas-patterns.md`
Named text-animation effects (24 IDs via external `animate-text` skill)	`adapters/animate-text.md`

Picking a runtime

GSAP is the default for 95% of motion work — covers timeline orchestration, transforms, easing, stagger. All atomic rules in this skill are GSAP-based.
Lottie when an asset has its own pre-baked timeline (typically After Effects exports).
Three.js for 3D scenes, camera motion, shader-driven visuals.
Anime.js for lightweight tweening when GSAP is overkill.
CSS for simple repeated motifs, decoration, shimmer — no JavaScript animation cost.
WAAPI for native browser keyframes without a GSAP dependency.
TypeGPU / WebGPU for GPU-rendered canvases (particles, liquid glass, custom shaders).

Multiple runtimes can coexist in one composition. Each registers its instances on the runtime-specific global so HyperFrames can seek all of them in one pass.

Critical Constraints

Prerequisite: hyperframes-core → Non-Negotiable Rules (single paused timeline, data-duration governs length, no Math.random / Date.now / performance.now, no repeat: -1, no gsap.set on later-scene clips, no display / visibility animation, no timeline construction inside async / setTimeout / Promise). Don't restate those here.

Animation-craft additions on top of core's contract:

Pre-calculated layout constants — never derive positions from getBoundingClientRect() at tween time. Tween-time DOM measurements desync because the renderer samples in parallel; compute coordinates once at composition setup and reuse.
Spatial motion uses GSAP transform aliases only (x, y, scale, rotation). Core's allowlist also permits opacity / color / backgroundColor / borderRadius for non-spatial property tweens — but never width / height / top / left for layout changes.

Scripts

node skills/hyperframes-animation/scripts/animation-map.mjs <composition-dir> \
  --out <composition-dir>/.hyperframes/anim-map

Reads every GSAP timeline registered on window.__timelines, enumerates tweens, samples bboxes, computes flags, outputs animation-map.json. Use it to audit choreography (dead zones, stagger consistency, lifecycle warnings) after authoring.

animation-map.mjs resolves helper packages from the current project first, then can bootstrap the bundled HyperFrames package version. Set HYPERFRAMES_SKILL_PKG_VERSION=<version> only when running the skill outside the bundled CLI/skill install and you need to pin that bootstrap version explicitly.