Add HyperFrames skills
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011h6NB8JQtfPc6eRCefEzBB
This commit is contained in:
964 files changed
+142321
No files matched your search
@@ -0,0 +1,130 @@
|
||||
---
|
||||
name: hyperframes-lottie
|
||||
description: Lottie and dotLottie adapter patterns for HyperFrames. Use when embedding lottie-web JSON animations, .lottie files, @lottiefiles/dotlottie-web players, registering instances on window.__hfLottie, or making After Effects exports deterministic in HyperFrames.
|
||||
---
|
||||
|
||||
# Lottie for HyperFrames
|
||||
|
||||
HyperFrames can seek both `lottie-web` and dotLottie players through its `lottie` runtime adapter. Lottie is a strong fit because the animation timeline is already encoded in the asset; HyperFrames only needs a player object it can seek.
|
||||
|
||||
## Contract
|
||||
|
||||
- Load assets from local project files, usually under `assets/`.
|
||||
- Set `autoplay: false`.
|
||||
- Use `loop: false` for a one-shot and `loop: true` for a cycle (walk, idle, spinner). A looping animation is seeked to composition time modulo its own length, so it keeps cycling for the whole scene; a one-shot holds its last frame. Always set `loop`: lottie-web treats a missing `loop` as `true`. A numeric `loop` count does not repeat under seeking; bake the repeats into the file.
|
||||
- Register every returned animation or player on `window.__hfLottie`.
|
||||
- Keep the Lottie container dimensions stable with CSS.
|
||||
|
||||
The adapter seeks `lottie-web` with `goToAndStop(timeMs, false)` and dotLottie with frame or percentage APIs depending on player shape.
|
||||
|
||||
## lottie-web Pattern
|
||||
|
||||
```html
|
||||
<div id="logo-lottie" class="lottie-layer"></div>
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/bodymovin/5.12.2/lottie.min.js"></script>
|
||||
<script>
|
||||
const anim = lottie.loadAnimation({
|
||||
container: document.getElementById("logo-lottie"),
|
||||
renderer: "svg",
|
||||
loop: false,
|
||||
autoplay: false,
|
||||
path: "assets/logo-reveal.json",
|
||||
});
|
||||
|
||||
window.__hfLottie = window.__hfLottie || [];
|
||||
window.__hfLottie.push(anim);
|
||||
</script>
|
||||
```
|
||||
|
||||
```css
|
||||
.lottie-layer {
|
||||
width: 100%;
|
||||
height: 100%;
|
||||
}
|
||||
```
|
||||
|
||||
## dotLottie Pattern
|
||||
|
||||
```html
|
||||
<canvas id="product-lottie" class="lottie-canvas"></canvas>
|
||||
<script src="https://unpkg.com/@lottiefiles/dotlottie-web"></script>
|
||||
<script>
|
||||
const player = new DotLottie({
|
||||
canvas: document.getElementById("product-lottie"),
|
||||
src: "assets/product-flow.lottie",
|
||||
autoplay: false,
|
||||
loop: false,
|
||||
});
|
||||
|
||||
window.__hfLottie = window.__hfLottie || [];
|
||||
window.__hfLottie.push(player);
|
||||
</script>
|
||||
```
|
||||
|
||||
```css
|
||||
.lottie-canvas {
|
||||
width: 100%;
|
||||
height: 100%;
|
||||
display: block;
|
||||
}
|
||||
```
|
||||
|
||||
## Multiple Animations
|
||||
|
||||
Push each player into the same registry:
|
||||
|
||||
```js
|
||||
window.__hfLottie = window.__hfLottie || [];
|
||||
window.__hfLottie.push(backgroundAnim);
|
||||
window.__hfLottie.push(iconAnim);
|
||||
window.__hfLottie.push(confettiAnim);
|
||||
```
|
||||
|
||||
HyperFrames seeks them all to the same composition time.
|
||||
|
||||
## Composition Duration
|
||||
|
||||
The render engine needs the composition's total length. GSAP timelines report duration automatically; a Lottie-only composition has no timeline object, so the runtime reads the registered animation's native length directly — `totalFrames / frameRate` for `lottie-web`, or the player's own `duration` for dotLottie. `data-duration` on the root element is optional for Lottie compositions: as long as every animation is registered on `window.__hfLottie` (per the contract above), the runtime has a finite duration to work with. With `loop: true` that length is one cycle, so a looping Lottie in a longer scene needs `data-duration` or a GSAP timeline to set the scene length.
|
||||
|
||||
## Characters
|
||||
|
||||
For a character that walks, gestures or reacts (a mascot, a walk cycle, a jointed puppet), put the acting in one Lottie and the stage in GSAP:
|
||||
|
||||
- **The Lottie owns the body.** Walk, stop, point and idle live in the file's own timeline, so limbs stay jointed and feet stay planted exactly as the animator made them.
|
||||
- **GSAP owns everything around it.** Cards, captions and camera moves go on the paused timeline, timed to the Lottie's beats. Read the beat times from the file's `markers` array (`tm` is in frames, divide by `fr`) or from the animator's notes.
|
||||
- **Every registered animation plays against composition time.** There is no per-animation start offset, so a gesture that should begin at 4 s must begin at 4 s inside its file. Author the whole performance as one Lottie, or offset the action inside the file, rather than stacking separate action files.
|
||||
- **A short cycle is fine.** A 1 s walk cycle with `loop: true` cycles for the whole scene. Move the character across the stage with GSAP `x` only if the cycle walks in place, and match the travel speed to the stride or the feet slide.
|
||||
- **License the character.** Use a file the user or their designer made, or one whose license allows redistribution, and say where it came from. Never ship a character ripped from a site.
|
||||
|
||||
The `lottie-character-walk` registry block is a working example: a jointed flat character walks in on planted feet, stops, and points at a card that GSAP brings in on the point (`npx hyperframes add lottie-character-walk`).
|
||||
|
||||
## Good Uses
|
||||
|
||||
- After Effects exports that are already known to render correctly in lottie-web.
|
||||
- Logo reveals, icon loops, decorative accents, and product UI motion.
|
||||
- Characters: walk cycles, mascots, gestures (see Characters above).
|
||||
- Translating Remotion Lottie usage into plain HyperFrames HTML.
|
||||
|
||||
## Avoid
|
||||
|
||||
- Relying on remote `path` URLs at render time.
|
||||
- Starting playback with `play()`.
|
||||
- Assuming unsupported After Effects effects will survive export. Test the JSON or `.lottie` file in a browser first.
|
||||
- Loading a player asynchronously and registering it after HyperFrames validation has already inspected the page.
|
||||
|
||||
## Validation
|
||||
|
||||
After editing a Lottie composition:
|
||||
|
||||
```bash
|
||||
npx hyperframes lint
|
||||
npx hyperframes check
|
||||
```
|
||||
|
||||
## Credits And References
|
||||
|
||||
- HyperFrames adapter source: `packages/core/src/runtime/adapters/lottie.ts`.
|
||||
- Duration auto-inference: `packages/core/src/runtime/init.ts` (`resolveAdapterDurationFloorSeconds`), `getInferredDurationSeconds` in the adapter above.
|
||||
- lottie-web by Airbnb: https://github.com/airbnb/lottie-web
|
||||
- lottie-web `loadAnimation` options: https://github.com/airbnb/lottie-web/wiki/loadAnimation-options
|
||||
- dotLottie web player methods by LottieFiles: https://developers.lottiefiles.com/docs/dotlottie-player/dotlottie-web/methods
|
||||
Reference in new issue
Block a user