hyperframes

Files (74)

• SKILL.md
• data-in-motion.md
• house-style.md
• bold-energetic.md · palettes/
• clean-corporate.md · palettes/
• dark-premium.md · palettes/
• jewel-rich.md · palettes/
• monochrome.md · palettes/
• nature-earth.md · palettes/
• neon-electric.md · palettes/
• pastel-soft.md · palettes/
• warm-editorial.md · palettes/
• patterns.md
• animejs.md · references/adapters/
• css-animations.md · references/adapters/
• lottie.md · references/adapters/
• three.md · references/adapters/
• typegpu.md · references/adapters/
• waapi.md · references/adapters/
• audio-reactive.md · references/
• authoring.md · references/
• beat-direction.md · references/
• captions.md · references/
• cli.md · references/
• css-patterns.md · references/
• design-picker.md · references/
• dynamic-techniques.md · references/
• from-website.md · references/
• step-1-capture.md · references/from-website/
• step-2-design.md · references/from-website/
• step-3-script.md · references/from-website/
• step-4-storyboard.md · references/from-website/
• step-5-vo.md · references/from-website/
• step-6-build.md · references/from-website/
• step-7-validate.md · references/from-website/
• media.md · references/
• motion-principles.md · references/
• narration.md · references/
• prompt-expansion.md · references/
• quality-checks.md · references/
• registry.md · references/
• add-block.md · references/registry/
• add-component.md · references/registry/
• contribute.md · references/registry/
• demo-html-pattern.md · references/registry/
• discovery.md · references/registry/
• install-locations.md · references/registry/
• templates.md · references/registry/
• wiring-blocks.md · references/registry/
• wiring-components.md · references/registry/
• techniques.md · references/
• transcript-guide.md · references/
• transitions.md · references/
• catalog.md · references/transitions/
• css-3d.md · references/transitions/
• css-blur.md · references/transitions/
• css-cover.md · references/transitions/
• css-destruction.md · references/transitions/
• css-dissolve.md · references/transitions/
• css-distortion.md · references/transitions/
• …and 14 more

SKILL.md (first lines)

# 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.

Attribute API, composition/template structure, variables, and media rules:
[references/authoring.md](references/authoring.md). Read it before writing
your first composition HTML in a session.

## Approach

### Discovery (exploratory requests only)

For open-ended requests ("make me a product launch video") where the user
hasn't committed to a direction, understand intent before picking colors:
audience, platform, priority (motion quality vs accuracy vs speed), and
whether they want variations. If variations, offer 2-3 that differ in
pacing or structure - one safe, one ambitious - not color swaps.

For specific requests ("add a title card", "fix scene 3 timing"), skip
discovery.

### Step 1: Design system

If `design.md` or `DESIGN.md` exists, read it first (both casings - they're
different files on Linux). It's the source of truth for brand colors,
fonts, and constraints - use its exact values. If it names fonts with no
`.woff2` files in `fonts/` and no built-in match, warn the user before
writing HTML.

If no `design.md` exists, offer a choice:

1. **User named a style or mood?** Read [visual-styles.md](./visual-styles.md)
   (8 named presets), pick the closest.
2. **Browse visually?** Run the design picker -
   [references/design-picker.md](references/design-picker.md).
3. **Go fast?** Ask mood, light/dark, brand colors/fonts; pick a palette
   from [house-style.md](./house-style.md).

**design.md defines the brand, not video composition rules.** Those come
from [references/video-composition.md](references/video-composition.md) and
[house-style.md](./house-style.md). Brand colors at video scale, not web-UI
opacity.

### Step 2: Prompt expansion

Run on every composition except single-scene pieces and trivial edits -
grounds intent against design.md/house-style.md into a consistent
intermediate. Process and format:
[references/prompt-expansion.md](references/prompt-expansion.md).

### Step 3: Plan

1. **What** - narrative arc, key moments, emotional beats.
2. **Structure** - how many compositions, sub-comps vs inline, which tracks
   carry what.
3. **Rhythm** - declare the scene rhythm before implementing
   (fast-fast-SLOW-fast-SHADER-hold). Templates:
   [references/beat-direction.md](references/beat-direction.md).
4. **Timing** - which clips drive duration, where transitions land.
5. **Layout** - build the end state first (next section).
6. **Animate** - then add motion.

**Build what was asked.** "A title card" is not "a title card + 3
supporting scenes + music + captions." Propose extras; don't add them.

For small edits, skip straight to the rules.

<HARD-GATE>
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.
</HARD-GATE>

## Layout Before Animation

Position every element where it should be at its **most visible moment** -
fully entered, correctly placed, not yet exiting. Write that as static
HTML+CSS first. No GSAP yet.

Why: if you position elements at their animated start state (offscreen,
opacity 0) and tween toward where you think they land, you're guessing the
final layout, and overlaps stay invisible until render. Build the end state
first and layout bugs are visible before motion exists.

1. **Identify the hero frame** per scene - the moment most elements are
   simultaneously visible. Build that layout.
2. **Write static CSS** for it. `.scene-content` MUST fill the scene:
   `width: 100%; height: 100%; padding: Npx;` with
   `display: flex; flex-direction: column; gap: Npx; box-sizing: border-box`.
   Padding pushes content inward - NEVER `position: absolute; top: Npx` on
   a content container (it overflows when content grows). Reserve absolute
   positioning for decoratives.
3. **Entrances with `gsap.from()`** - animate FROM offscreen TO the CSS
   position. CSS is ground truth; the tween is the journey. (Sub-comps
   loaded via `data-composition-src`: prefer `gsap.fromTo()` - see
   [references/motion-principles.md](references/motion-principles.md).)
4. **Final scene only: exits with `gsap.to()`.** All other scenes end fully
   visible - the transition IS the exit (transition rule 3 below).

If element A exits before element B enters in the same area, give both
correct CSS positions for their own hero frames - the timeline keeps them
from coexisting, and the layout step catches accidental overlap from timing
errors. Intentional layering (glow behind text, card stacks) is fine; the
step exists to catch unintentional overlap - two headlines colliding, a
stat covering a label, content off-frame.

## Timeline Contract

- 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 GSAP timeline length
- Never create empty tweens to set duration

## Rules (Non-Negotiable)

**Deterministic:** no `Math.random()`, `Date.now()`, or time-based logic.
Seeded PRNG (e.g. mulberry32) for pseudo-random.

From scott-fryxell/brayness, MIT.

More from scott-fryxell/brayness