Create video compositions, animations, title cards, overlays, captions, voiceovers, audio-reactive visuals, and scene transitions in HyperFrames HTML. Use when asked to build any HTML-based video content, add captions or subtitles synced to audio, generate text-to-speech narration, create audio-reactive animation (beat sync, glow, pulse driven by music), add animated text highlighting (marker sweeps, hand-drawn circles, burst lines, scribble, sketchout), or add transitions between scenes (crossfades, wipes, reveals, shader transitions). Covers composition authoring, timing, media, and the full video production workflow. For dev-loop CLI commands (init, lint, inspect, preview, render) see the hyperframes-cli skill; for asset preprocessing commands (tts, transcribe, remove-background) see the hyperframes-media skill.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Create video compositions, animations, title cards, overlays, captions, voiceovers, audio-reactive visuals, and scene transitions in HyperFrames HTML. Use when asked to build any HTML-based video content, add captions or subtitles synced to audio, generate text-to-speech narration, create audio-reactive animation (beat sync, glow, pulse driven by music), add animated text highlighting (marker sweeps, hand-drawn circles, burst lines, scribble, sketchout), or add transitions between scenes (crossfades, wipes, reveals, shader transitions). Covers composition authoring, timing, media, and the full video production workflow. For dev-loop CLI commands (init, lint, inspect, preview, render) see the hyperframes-cli skill; for asset preprocessing commands (tts, transcribe, remove-background) see the hyperframes-media skill.
HyperFrames
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.
Approach
Discovery (exploratory requests only)
For open-ended requests ("make me a product launch video", "create something for our brand") where the user hasn't committed to a direction, understand intent before picking colors:
Audience โ who watches this? Developers? Executives? General consumers?
Platform โ where does it play? Social (15s), website hero, product demo, internal?
Variations โ does the user want options, or a single best shot?
For specific requests ("add a title card", "fix the timing on scene 3"), skip discovery.
For exploratory requests, consider offering 2-3 variations that differ meaningfully โ not just color swaps, but different pacing, energy levels, or structural approaches. One safe/expected, one ambitious. Don't mandate this โ it's a tool available when appropriate.
Before writing ANY composition HTML โ verify you have a visual identity from Step 1. If you're reaching for `#333`, `#3b82f6`, or `Roboto`, you skipped it.
Step 1: Design system
If a design spec exists in the project, read it first. Look in precedence order: frame.md โ design.md โ DESIGN.md (design.md and DESIGN.md are different files on Linux โ check both casings; frame.md is always lowercase, no FRAME.md variant). frame.md is the preferred spec for video/hyperframes projects and wins if more than one exists; it uses the same format as design.md. It's the source of truth for brand colors, fonts, and constraints. Use its exact values โ don't invent colors or substitute fonts. Any format works (YAML frontmatter, prose, tables โ just extract the values).
If it names fonts you can't find locally (no fonts/ directory with .woff2 files, not a built-in font), warn the user before writing HTML: "the spec specifies [font name] but no font files found. Please add .woff2 files to fonts/ or I'll fall back to [closest built-in alternative]."
If no frame.md or design.md exists, offer the user a choice:
User named a style or mood? โ Read visual-styles.md for the 8 named presets. Pick the closest match.
Want to browse options visually? โ Run the design picker: read references/design-picker.md for the full workflow. This serves a visual picker page. The user configures mood, palette, typography, and motion in the browser, then copies the generated design.md and pastes it back into the conversation.
Want to skip and go fast? โ Ask: mood, light or dark, any brand colors/fonts? Then pick a palette from house-style.md.
The design spec defines the brand. It does not define video composition rules. Those come from references/video-composition.md and house-style.md. Use brand colors at video-appropriate scale โ not at web-UI opacity.
Step 2: Prompt expansion
Always run on every composition (except single-scene pieces and trivial edits). This step grounds the user's intent against the design spec (frame.md or design.md) and house-style.md and produces a consistent intermediate that every downstream agent reads the same way.
What โ what should the viewer experience? Identify the narrative arc, key moments, and emotional beats.
Structure โ how many compositions, which are sub-compositions vs inline, what tracks carry what (video, audio, overlays, captions).
Rhythm โ declare your scene rhythm before implementing. Which scenes are quick hits, which are holds, where do shaders land, where does energy peak. Name the pattern: fast-fast-SLOW-fast-SHADER-hold. Read references/beat-direction.md for rhythm templates.
Timing โ which clips drive the duration, where do transitions land, what's the pacing.
Layout โ build the end-state first. See "Layout Before Animation" below.
Animate โ then add motion using the rules below.
Build what was asked. A request for "a title card" is not a request for "a title card + 3 supporting scenes + ambient music + captions." Every scene, every element, every tween should earn its place. If additional scenes or elements would genuinely improve the piece, propose them โ don't add them.
For small edits (fix a color, adjust timing, add one element), skip straight to the rules.
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
Identify the hero frame for each scene โ the moment when the most elements are simultaneously visible. This is the layout you build.
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.
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. (In sub-compositions loaded via data-composition-src, prefer gsap.fromTo() โ see load-bearing GSAP rules in references/motion-principles.md.)
Add exits with gsap.to() โ animate TO offscreen/invisible FROM the CSS position.
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
data-variable-values
No
JSON object of per-instance variable overrides on a sub-comp host
On the root <html> element:
Attribute
Required
Values
data-composition-variables
No
JSON array of declared variables (id/type/label/default) โ drives Studio editing UI and provides defaults for getVariables()
Composition Structure
Sub-compositions loaded via data-composition-src use a <template> wrapper. Standalone compositions (the main index.html) do NOT use <template> โ they put the data-composition-id div directly in <body>. Using <template> on a standalone file hides all content from the browser and breaks rendering.
Load in root: <div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>
Variables (Parametrized Compositions)
Render the same composition with different content โ title, theme color, prices, captions โ without editing the source HTML.
Three-step pattern:
Declare variables on the composition's <html> root with data-composition-variables. Each entry needs id, type (one of string, number, color, boolean, enum), label, and default. Enum entries also need options: [{value, label}, ...].
Read the resolved values inside the composition's script with window.__hyperframes.getVariables(). Returns the merged result of declared defaults + per-instance overrides + CLI overrides.
Override at render time with npx hyperframes render --variables '{...}' (top-level) or with data-variable-values='{...}' on the host element (per-instance for sub-comps).
# Dev preview uses declared defaults
npx hyperframes preview
# Render with overrides
npx hyperframes render --variables '{"title":"Q4 Report","theme":"dark"}' --output q4.mp4
# Or from a JSON file
npx hyperframes render --variables-file ./vars.json
Sub-composition per-instance values: the same getVariables() works inside sub-comps loaded via data-composition-src. Each host element passes its own values:
The runtime layers each host's data-variable-values over the sub-comp's declared defaults on a per-instance basis, so the same source can be embedded multiple times with different content.
Rules of thumb:
Always provide a sensible default for every declared variable. Dev preview uses defaults โ without them, the composition won't render correctly until --variables is provided.
Read variables once at the top of the script (const { title } = ...), not inside frame loops or event handlers โ getVariables() allocates a fresh object per call.
Use --strict-variables in CI to fail fast on undeclared keys or type mismatches.
Variable types are validated at render time. string, number, boolean, and color (hex string) check typeof; enum checks the value is in the declared options.
Video and Audio
Video must be muted playsinline. Audio is always a separate <audio> element:
All timelines start { paused: true } โ the player controls playback
Register every timeline: window.__timelines["<composition-id>"] = 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:
Forget window.__timelines registration
Use video for audio โ always muted video + separate <audio>
Nest video inside a timed div โ use a non-timed wrapper
Use data-layer (use data-track-index) or data-end (use data-duration)
Animate video element dimensions โ animate a wrapper div
Call play/pause/seek on media โ framework owns playback
Create a top-level container without data-composition-id
Use repeat: -1 on any timeline or tween โ always finite repeats
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.
Use <br> in content text โ forced line breaks don't account for actual rendered font width. Text that wraps naturally + a <br> 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.
ALWAYS use transitions between scenes. No jump cuts. No exceptions.
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.
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.
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:
// 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:
// 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
If no frame.md or design.md exists, follow house-style.md for aesthetic defaults.
Typography and Assets
Built-in fonts: Write the font-family you want in CSS โ the compiler embeds supported fonts automatically.
Custom fonts: If the spec (frame.md or design.md) names a font that isn't built-in, the user must provide .woff2 files in a fonts/ directory. If missing, warn before writing HTML. When files exist, add @font-face declarations pointing to the local files.
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 actual files, don't guess. When editing, extending, or creating companion compositions, read the existing source. Don't reconstruct hex codes from memory. Don't guess GSAP easing patterns. The composition IS the spec โ extract exact values from it.
Match existing fonts, colors, animation patterns from what you read
Only change what was requested
Preserve timing of unrelated clips
Output Checklist
Fast (run immediately, block on results):
npx hyperframes lint and npx hyperframes validate both pass
Design adherence verified if a design spec (frame.md or design.md) exists
Slow (run in parallel while presenting the preview to the user):
npx hyperframes inspect passes, or every reported overflow is intentionally marked
Contrast warnings addressed (see Quality Checks below)
Animation choreography verified (see Quality Checks below)
Quality Checks
Visual Inspect
hyperframes inspect runs the composition in headless Chrome, seeks through the timeline, and maps visual layout issues with timestamps, selectors, bounding boxes, and fix hints. Run it after lint and validate:
Failures usually mean text is spilling out of a bubble/card, a fixed-size label is clipping dynamic copy, or text has moved off the canvas. Fix by increasing container size or padding, reducing font size or letter spacing, adding a real max-width so text wraps inside the container, or using window.__hyperframes.fitTextFontSize(...) for dynamic copy.
Use --samples 15 for dense videos and --at 1.5,4,7.25 for specific hero frames. Repeated static issues are collapsed by default to avoid flooding agent context. If overflow is intentional for an entrance/exit animation, mark the element or ancestor with data-layout-allow-overflow. If a decorative element should never be audited, mark it with data-layout-ignore.
hyperframes layout is the compatibility alias for the same check.
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:
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.
Design Adherence
If a design spec (frame.md or design.md) exists, verify the composition follows it after authoring. Read the HTML and check:
Colors โ every hex value in the composition appears in the spec's palette section (however the user labeled it: Colors, Palette, Theme, etc.). Flag any invented colors.
Typography โ font families and weights match the spec's type spec. No substitutions.
Corners โ border-radius values match the declared corner style, if specified.
Spacing โ padding and gap values fall within the declared density range, if specified.
Depth โ shadow usage matches the declared depth level, if specified (flat = none, subtle = light, layered = glows).
Avoidance rules โ if the spec has a section listing things to avoid (commonly "What NOT to Do", "Don'ts", "Anti-patterns", or "Do's and Don'ts"), verify none are present.
Report violations as a checklist. Fix each one before serving.
If no design spec exists (house-style-only path), verify:
Palette consistency โ the same bg, fg, and accent colors are used across all scenes. No per-scene color invention.
No lazy defaults โ check the composition against house-style.md's "Lazy Defaults to Question" list. If any appear, they must be a deliberate choice for the content, not a default.
Animation Map
After authoring animations, run the animation map to verify choreography:
Read the JSON. Scan summaries for anything unexpected. Check every flag โ fix or justify. Verify the timeline shows the intended choreography rhythm. Re-run after fixes.
Skip on small edits (fixing a color, adjusting one duration). Run on new compositions and significant animation changes.
References (loaded on demand)
references/captions.md โ Captions, subtitles, lyrics, karaoke synced to audio. Tone-adaptive style detection, per-word styling, text overflow prevention, caption exit guarantees, word grouping. Read when adding any text synced to audio timing.
references/audio-reactive.md โ Audio-reactive animation: map frequency bands and amplitude to GSAP properties. Read when visuals should respond to music, voice, or sound.
references/css-patterns.md โ CSS+GSAP marker highlighting: highlight, circle, burst, scribble, sketchout. Deterministic, fully seekable. Read when adding visual emphasis to text.
references/video-composition.md โ Video-medium rules: density, color presence, scale, frame composition, the design spec as brand not layout. Always read โ these override web instincts.
references/typography.md โ Typography: font pairing, OpenType features, dark-background adjustments, font discovery script. Always read โ every composition has text.
references/motion-principles.md โ Motion design principles, image motion treatment, load-bearing GSAP rules. Always read โ every composition has motion.
references/html-in-canvas-patterns.md โ HTML-in-Canvas patterns: live DOM as GPU texture via drawElementImage + layoutsubtree. Shared boilerplate + ~6 effect recipes (iPhone/MacBook mockups, liquid glass, magnetic, portal, shatter, text cursor). Use for 1โ3 hero beats per video.
references/narration.md โ Pacing, tone, script structure, number pronunciation, opening line patterns. Read when the composition includes voiceover or TTS.
references/design-picker.md โ Create a design.md via visual picker. Read when no frame.md or design.md exists and the user wants to create one.
visual-styles.md โ 8 named visual styles with hex palettes, GSAP easing signatures, and shader pairings. Read when user names a style or when generating a design spec.
house-style.md โ Default motion, sizing, and color palettes when no frame.md or design.md is specified.
patterns.md โ PiP, title cards, slide show patterns.
references/transcript-guide.md โ Caption-side transcript handling: input formats, mandatory quality check, cleaning JS, OpenAI/Groq API fallback, "if no transcript exists" flow. (For the transcribe CLI invocation, model selection rules, and the .en gotcha, see the hyperframes-media skill.)
Special thanks to HeyGen for their generous open-source contributions, which helped shape this skill collection.
Adapted by webconsulting.at for this skill collection
