# Hyperframes Best Practices > Best practices for programmatic video creation using HyperFrames, plain HTML compositions with GSAP animations rendered to MP4, with full Hebrew and RTL support. Covers composition authoring, data-* timing attributes, GSAP timeline contract, layout-before-animation methodology, visual identity gate, Hebrew fonts via Google Fonts (Heebo, Rubik, Assistant), RTL text rendering with dir=\"rtl\", Hebr… - **Type:** Skill - **Install:** `agentstack add skill-squadcodercom-squadcoder-hyperframes-best-practices` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [squadcodercom](https://agentstack.voostack.com/s/squadcodercom) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [squadcodercom](https://github.com/squadcodercom) - **Source:** https://github.com/squadcodercom/squadcoder/tree/main/.squadcoder/skills/hyperframes-best-practices - **Website:** https://squadcoder.com ## Install ```sh agentstack add skill-squadcodercom-squadcoder-hyperframes-best-practices ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # HyperFrames Best Practices > Adapted from the upstream HyperFrames v1.0.x skill at [heygen-com/hyperframes](https://github.com/heygen-com/hyperframes) (Apache-2.0). Hebrew and RTL adaptations by [skills-il](https://agentskills.co.il). HTML is the source of truth for video. A composition is an HTML file with `data-*` attributes for timing, a GSAP timeline for animation, and CSS for appearance. The framework handles clip visibility, media playback, and timeline sync. ## Problem Building HTML-based videos with Hebrew text requires the compiler to fetch Hebrew Google Fonts on demand, explicit `dir="rtl"` on Hebrew containers, mirrored GSAP entrance directions, and Hebrew caption sync via Whisper, none of which HyperFrames documents out of the box. Hebrew voiceover is a separate gap: the built-in Kokoro TTS does not support Hebrew (only 8 languages: en-us, en-gb, es, fr-fr, hi, it, pt-br, ja, zh), so Hebrew narration must be generated by an external TTS service and imported as an `` element. ## Hebrew and RTL For Hebrew and RTL compositions, load [references/hebrew-rtl.md](./references/hebrew-rtl.md). It covers Hebrew font loading (the compiler auto-fetches from Google Fonts), `dir="rtl"` scoping, GSAP x-axis mirroring, Hebrew caption sync via `hyperframes transcribe --language he`, Hebrew voiceover via external TTS, and bidirectional text with ``. ## Approach Before writing HTML, think at a high level: 1. **What**, what should the viewer experience? Identify the narrative arc, key moments, and emotional beats. 2. **Structure**, how many compositions, which are sub-compositions vs inline, what tracks carry what (video, audio, overlays, captions). 3. **Timing**, which clips drive the duration, where do transitions land, what's the pacing. 4. **Layout**, build the end-state first. See "Layout Before Animation" below. 5. **Animate**, then add motion using the rules below. For small edits (fix a color, adjust timing, add one element), skip straight to the rules. ### Visual Identity Gate Before writing ANY composition HTML, you MUST have a visual identity defined. Do NOT write compositions with default or generic colors. Check in this order: 1. **DESIGN.md exists in the project?** → Read it. Use its exact colors, fonts, motion rules, and "What NOT to Do" constraints. 2. **visual-style.md exists?** → Read it. Apply its `style_prompt_full` and structured fields. (Note: `visual-style.md` is a project-specific file. `visual-styles.md` is the style library with 8 named presets, different files.) 3. **User named a style** (e.g., "Swiss Pulse", "dark and techy", "luxury brand")? → Read [visual-styles.md](./visual-styles.md) for the 8 named presets. Generate a minimal DESIGN.md with: `## Style Prompt` (one paragraph), `## Colors` (3-5 hex values with roles), `## Typography` (1-2 font families), `## What NOT to Do` (3-5 anti-patterns). 4. **None of the above?** → Ask 3 questions before writing any HTML: - What's the mood? (explosive / cinematic / fluid / technical / chaotic / warm) - Light or dark canvas? - Any specific brand colors, fonts, or visual references? Then generate a minimal DESIGN.md from the answers. Every composition must trace its palette and typography back to a DESIGN.md, visual-style.md, or explicit user direction. If you're reaching for `#333`, `#3b82f6`, or `Roboto`, you skipped this step. For motion defaults, sizing, entrance patterns, and easing, follow [house-style.md](./house-style.md). The house style handles HOW things move. The DESIGN.md handles WHAT things look like. ## Layout Before Animation Position every element where it should be at its **most visible moment**, the frame where it's fully entered, correctly placed, and not yet exiting. Write this as static HTML+CSS first. No GSAP yet. **Why this matters:** If you position elements at their animated start state (offscreen, scaled to 0, opacity 0) and tween them to where you think they should land, you're guessing the final layout. Overlaps are invisible until the video renders. By building the end state first, you can see and fix layout problems before adding any motion. ### The process 1. **Identify the hero frame** for each scene, the moment when the most elements are simultaneously visible. This is the layout you build. 2. **Write static CSS** for that frame. The `.scene-content` container MUST fill the full scene using `width: 100%; height: 100%; padding: Npx;` with `display: flex; flex-direction: column; gap: Npx; box-sizing: border-box`. Use padding to push content inward, NEVER `position: absolute; top: Npx` on a content container. Absolute-positioned content containers overflow when content is taller than the remaining space. Reserve `position: absolute` for decoratives only. 3. **Add entrances with `gsap.from()`**, animate FROM offscreen/invisible TO the CSS position. The CSS position is the ground truth; the tween describes the journey to get there. 4. **Add exits with `gsap.to()`**, animate TO offscreen/invisible FROM the CSS position. ### Example ```css /* scene-content fills the scene, padding positions content */ .scene-content { display: flex; flex-direction: column; justify-content: center; width: 100%; height: 100%; padding: 120px 160px; gap: 24px; box-sizing: border-box; } .title { font-size: 120px; } .subtitle { font-size: 42px; } /* Container fills any scene size (1920x1080, 1080x1920, etc). Padding positions content. Flex + gap handles spacing. */ ``` **WRONG, hardcoded dimensions and absolute positioning:** ```css .scene-content { position: absolute; top: 200px; left: 160px; width: 1920px; height: 1080px; display: flex; /* ... */ } ``` ```js // Step 3: Animate INTO those positions tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0); tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2); tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3); // Step 4: Animate OUT from those positions tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3); tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1); tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2); ``` ### When elements share space across time If element A exits before element B enters in the same area, both should have correct CSS positions for their respective hero frames. The timeline ordering guarantees they never visually coexist, but if you skip the layout step, you won't catch the case where they accidentally overlap due to a timing error. ### What counts as intentional overlap Layered effects (glow behind text, shadow elements, background patterns) and z-stacked designs (card stacks, depth layers) are intentional. The layout step is about catching **unintentional** overlap, two headlines landing on top of each other, a stat covering a label, content bleeding off-frame. ## Data Attributes ### All Clips | Attribute | Required | Values | | ------------------ | --------------------------------- | ------------------------------------------------------ | | `id` | Yes | Unique identifier | | `data-start` | Yes | Seconds or clip ID reference (`"el-1"`, `"intro + 2"`) | | `data-duration` | Required for img/div/compositions | Seconds. Video/audio defaults to media duration. | | `data-track-index` | Yes | Integer. Same-track clips cannot overlap. | | `data-media-start` | No | Trim offset into source (seconds) | | `data-volume` | No | 0-1 (default 1) | `data-track-index` does **not** affect visual layering, use CSS `z-index`. ### Composition Clips | Attribute | Required | Values | | ---------------------------- | -------- | -------------------------------------------- | | `data-composition-id` | Yes | Unique composition ID | | `data-start` | Yes | Start time (root composition: use `"0"`) | | `data-duration` | Yes | Takes precedence over GSAP timeline duration | | `data-width` / `data-height` | Yes | Pixel dimensions (1920x1080 or 1080x1920) | | `data-composition-src` | No | Path to external HTML file | ## Composition Structure Sub-compositions loaded via `data-composition-src` use a `` wrapper. **Standalone compositions (the main index.html) do NOT use ``**, they put the `data-composition-id` div directly in ``. Using `` on a standalone file hides all content from the browser and breaks rendering. Sub-composition structure: ```html [data-composition-id="my-comp"] { /* scoped styles */ } window.__timelines = window.__timelines || {}; const tl = gsap.timeline({ paused: true }); // tweens... window.__timelines["my-comp"] = tl; ``` Load in root: `` ## Video and Audio Video must be `muted playsinline`. Audio is always a separate `` element: ```html ``` ## Timeline Contract - All timelines start `{ paused: true }`, the player controls playback - Register every timeline: `window.__timelines[""] = tl` - Framework auto-nests sub-timelines, do NOT manually add them - Duration comes from `data-duration`, not from GSAP timeline length - Never create empty tweens to set duration ## Rules (Non-Negotiable) **Deterministic:** No `Math.random()`, `Date.now()`, or time-based logic. Use a seeded PRNG if you need pseudo-random values (e.g. mulberry32). **GSAP:** Only animate visual properties (`opacity`, `x`, `y`, `scale`, `rotation`, `color`, `backgroundColor`, `borderRadius`, transforms). Do NOT animate `visibility`, `display`, or call `video.play()`/`audio.play()`. **Animation conflicts:** Never animate the same property on the same element from multiple timelines simultaneously. **No `repeat: -1`:** Infinite-repeat timelines break the capture engine. Calculate the exact repeat count from composition duration: `repeat: Math.ceil(duration / cycleDuration) - 1`. **Synchronous timeline construction:** Never build timelines inside `async`/`await`, `setTimeout`, or Promises. The capture engine reads `window.__timelines` synchronously after page load. Fonts are embedded by the compiler, so they're available immediately, no need to wait for font loading. **Never do:** 1. Forget `window.__timelines` registration 2. Use video for audio, always muted video + separate `` 3. Nest video inside a timed div, use a non-timed wrapper 4. Use `data-layer` (use `data-track-index`) or `data-end` (use `data-duration`) 5. Animate video element dimensions, animate a wrapper div 6. Call play/pause/seek on media, framework owns playback 7. Create a top-level container without `data-composition-id` 8. Use `repeat: -1` on any timeline or tween, always finite repeats 9. Build timelines asynchronously (inside `async`, `setTimeout`, `Promise`) 10. Use `gsap.set()` on clip elements from later scenes, they don't exist in the DOM at page load. Use `tl.set(selector, vars, timePosition)` inside the timeline at or after the clip's `data-start` time instead. 11. Use `` in content text, forced line breaks don't account for actual rendered font width. Text that wraps naturally + a `` produces an extra unwanted break, causing overlap. Let text wrap via `max-width` instead. Exception: short display titles where each word is deliberately on its own line (e.g., "THE\nIMMORTAL\nGAME" at 130px). ## Scene Transitions (Non-Negotiable) Every multi-scene composition MUST follow ALL of these rules. Violating any one of them is a broken composition. 1. **ALWAYS use transitions between scenes.** No jump cuts. No exceptions. 2. **ALWAYS use entrance animations on every scene.** Every element animates IN via `gsap.from()`. No element may appear fully-formed. If a scene has 5 elements, it needs 5 entrance tweens. 3. **NEVER use exit animations** except on the final scene. This means: NO `gsap.to()` that animates opacity to 0, y offscreen, scale to 0, or any other "out" animation before a transition fires. The transition IS the exit. The outgoing scene's content MUST be fully visible at the moment the transition starts. 4. **Final scene only:** The last scene may fade elements out (e.g., fade to black). This is the ONLY scene where `gsap.to(..., { opacity: 0 })` is allowed. **WRONG, exit animation before transition:** ```js // BANNED, this empties the scene before the transition can use it tl.to("#s1-title", { opacity: 0, y: -40, duration: 0.4 }, 6.5); tl.to("#s1-subtitle", { opacity: 0, duration: 0.3 }, 6.7); // transition fires on empty frame ``` **RIGHT, entrance only, transition handles exit:** ```js // Scene 1 entrance animations tl.from("#s1-title", { y: 50, opacity: 0, duration: 0.7, ease: "power3.out" }, 0.3); tl.from("#s1-subtitle", { y: 30, opacity: 0, duration: 0.5, ease: "power2.out" }, 0.6); // NO exit tweens, transition at 7.2s handles the scene change // Scene 2 entrance animations tl.from("#s2-heading", { x: -40, opacity: 0, duration: 0.6, ease: "expo.out" }, 8.0); ``` ## Animation Guardrails - Offset first animation 0.1-0.3s (not t=0) - Vary eases across entrance tweens, use at least 3 different eases per scene - Don't repeat an entrance pattern within a scene - Avoid full-screen linear gradients on dark backgrounds (H.264 banding, use radial or solid + localized glow) - 60px+ headlines, 20px+ body, 16px+ data labels for rendered video - `font-variant-numeric: tabular-nums` on number columns When no `visual-style.md` or animation direction is provided, follow [house-style.md](./house-style.md) for aesthetic defaults. ## Typography and Assets - **Fonts:** Just write the `font-family` you want in CSS, the compiler embeds supported fonts automatically. If a font isn't supported, the compiler warns. - Add `crossorigin="anonymous"` to external media - For dynamic text overflow, use `window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight })` - All files live at the project root alongside `index.html`; sub-compositions use `../` ## Editing Existing Compositions - Read the full composition first, match existing fonts, colors, animation patterns - Only change what was requested - Preserve timing of unrelated clips ## Output Checklist - [ ] `npx hyperframes lint` and `npx hyperframes validate` both pass - [ ] Contrast warnings addressed (see Quality Checks below) - [ ] Animation choreography verified (see Quality Checks below) ## Quality Checks ### Contrast `hyperframes validate` runs a WCAG contrast audit by default. It seeks to 5 timestamps, screenshots the page, samples background pixels behind every text element, and computes contrast ratios. Failures appear as warnings: ``` ⚠ WCAG AA contrast warnings (3): · .subtitle "secondary text", 2.67:1 (need 4.5:1, t=5.3s) ``` If warnings appear: - On dark backgrounds: brighten the failing color until it clears 4.5:1 (normal text) or 3:1 (large text, 24px+ or 19px+ bold) - On light backgrounds: darken it - Stay within the palette family, don't invent a new color, adjust the existing one - Re-run `hyperframes validate` until clean Use `--no-contrast` to skip if iterating rapidly and you'll check later. ### Animation Map After authoring animations, run the animation map to verify choreography: ```bash node skills/hyperframes/scripts/animation-map.mjs \ --out /.hyperframes/anim-map ``` Outputs a single `animation-map.json` with: - **Per-tween summaries**: `"#card1 animates opacity+y over 0.50s. moves 23px up. fades in. ends at (120, 200)"` - ** … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [squadcodercom](https://github.com/squadcodercom) - **Source:** [squadcodercom/squadcoder](https://github.com/squadcodercom/squadcoder) - **License:** MIT - **Homepage:** https://squadcoder.com Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-squadcodercom-squadcoder-hyperframes-best-practices - Seller: https://agentstack.voostack.com/s/squadcodercom - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.