Website To Framevideo

Website to FrameVideo

Capture a website, then produce a professional video from it.

Users say things like:

• "Capture https://... and make me a 25-second product launch video"
• "Turn this website into a 15-second social ad for Instagram"
• "Create a 30-second product tour from https://..."

The workflow has 7 steps. Each produces an artifact that gates the next. By default it's collaborative — gates marked 💬 stop and ask the user. If the user signals autonomous mode ("decide for me", "surprise me"), 💬 user-preference gates are skipped; see step-2-brief.md for how that propagates.

Autonomous mode is NOT "skip all gates." Auto mode covers user-preference questions (TTS provider, voice, color emphasis, beat count, music yes/no, captions yes/no — where the agent decides on the user's behalf). It does NOT cover quality-verification gates. The following remain non-skippable in auto mode:

• Asset Audit (Step 3) — viewing contact sheets and justifying USE/SKIP for each asset
• Per-beat HTML read (Step 5) — structured evidence block per beat
• DoD checklist (Step 6) — including animation-map, per-warning WCAG verification, audio/motion playback
• Honest disclosure section (Step 6) — "What I did NOT verify" must appear in your final summary

If you find yourself reasoning "auto mode says bias toward action, so I'll skip X" — and X is a verification gate, not a preference question — that reasoning is wrong. Bias toward action applies to deciding _what to build_, not to deciding _whether to verify_.

---

Step 0: Capture & Understand the Brand

Read: references/step-0-capture.md

Capture the site, then read the extracted data to understand the brand and product — what it does, who it's for, what voice it speaks in, what mood it lives in. The captured assets are a brand toolkit for later, not the building blocks the video is made from.

Gate: Site summary printed — strategy-first (what the product does, who it's for, brand voice) before the asset / color / font inventory.

---

Step 1: Brand Identity

Read: references/step-1-design.md

Write DESIGN.md — a brand cheat sheet covering the visual identity: colors, typography, component styles, layout principles. Use design-styles.json for exact computed values.

Speed option: For fast-pacing videos (billboard-per-beat), DESIGN.md can be a 50-line summary of colors + fonts + do's/don'ts — not a 300-line document. The sub-agent prompt in Step 5 pastes brand values directly, so DESIGN.md depth only matters for complex compositions.

Gate: DESIGN.md exists (any length) with at minimum: color palette, font choices, and do's/don'ts.

---

Step 2: Strategy & Messaging

Read: references/step-2-brief.md, references/capabilities.md (scan the Table of Contents — deep-dive sections only as needed)

Align with the user on what the video must communicate before talking visuals or assets. Parse the user's prompt — they probably already gave you the video type and style. Ask only what's missing: the ONE thing this video must say, the narrative arc, and the audience.

Gate: Video type, duration, format, and — critically — the message and narrative arc are locked. Without those, Step 3 can't write a concept-first storyboard.

---

Step 3: Storyboard + Script 💬

Read: references/step-3-storyboard.md

Write the storyboard concept-first: message → narrative arc → beats that serve the arc → techniques per beat → brand accents pass at the end. Then write the narration script to match. Present both to the user with a beat-by-beat summary. Iterate until they approve.

Gate: STORYBOARD.md + SCRIPT.md exist AND the user has approved the plan.

---

Step 4: VO, Timing + Captions 💬

Read: references/step-4-vo.md

If Step 2 said no narration — ask about background music, then skip to Step 5. Otherwise: ask the user which TTS provider (Chanjing TTS, ElevenLabs, or Kokoro), generate audio, transcribe, map timestamps to beats. Then ask about captions.

Gate: Either (a) no narration was requested and storyboard has manual beat timings, or (b) narration.wav + transcript.json exist and beat timings updated with real durations.

---

Step 5: Build Compositions

Read: The framevideo skill (load it — every rule matters) Read: references/step-5-build.md

Build index.html and compositions following the architecture and pacing chosen in the storyboard (Step 3). Sub-agents run framevideo lint and framevideo snapshot on each beat before reporting back.

Gate: Every compositions/beat-N.html has been read top-to-bottom by the main agent against DESIGN.md and STORYBOARD.md. The per-beat checklist lives in step-5-build.md.

---

Step 6: Validate & Deliver

Read: references/step-6-validate.md

Lint, validate, take snapshots scaled to video length (formula: max(beats × 3, ceil(duration_seconds / 2))), and review each one. Fix issues before delivering. Deliver the localhost Studio project URL — only render to MP4 on explicit user request.

Deliver something you're proud of. Before handing off, ask yourself: would I post this on social media with my name on it? If not, fix what's wrong.

Gate: npx framevideo lint and npx framevideo validate pass with zero errors, and the final response includes the active Studio project URL.

---

Quick Reference

Video Types

Typical constraints by video type — use as a starting point, not a formula. Beat count should follow from the content and the narration, not from a target range.

Beat count is not in this table intentionally — it should come from the storyboard, not from "social ad = 3-4 beats." A social ad for a complex product might need 5 well-timed beats. A brand reel with one strong visual thesis might need 3.

Format

• Landscape: 1920x1080 (default)
• Portrait: 1080x1920 (Instagram Stories, TikTok)
• Square: 1080x1080 (Instagram feed)

Reference Files

SFX Credits

All sound effects in this directory are sourced from Pixabay and used under the Pixabay Content License.

The Pixabay license allows free use for commercial and non-commercial purposes without attribution, but attribution is appreciated and given here for transparency.

Files

The following .mp3 files are bundled with this skill:

• chime.mp3
• click.mp3 / click-soft.mp3
• error.mp3
• glitch-1.mp3 / glitch-2.mp3 / glitch-3.mp3
• impact-bass-1.mp3 / impact-bass-2.mp3
• key-press.mp3
• notification.mp3
• ping.mp3
• pop.mp3
• riser.mp3
• sparkle.mp3
• typing.mp3
• whoosh.mp3 / whoosh-short.mp3 / whoosh-cinematic.mp3

See manifest.json for per-file metadata (duration, energy character, recommended use).

License

All files are distributed under the Pixabay Content License, which permits:

• Commercial and non-commercial use
• Modification and remixing
• Redistribution as part of derivative works (such as videos rendered with FrameVideo)

without any attribution requirement.

Beat Builder Guide

You are building ONE beat of a multi-beat video composition. This file tells you what to read, how to build, how to verify, and how to report back.

Step 1: Read and understand

Required (every beat):

1. Load the `framevideo` skill — composition rules, data attributes, timeline contract, deterministic rendering. Read the whole skill. 2. [capabilities.md](capabilities.md) — full inventory of FrameVideo capabilities (24 sections). Read the Table of Contents first, then deep-dive sections your beat needs. 3. The beat spec the main agent gave you — concept, choreography, assets, brand values, timing.

Read based on what your beat needs (pick relevant ones):

Other skills you can load if needed:

• /gsap or /gsap-core, /gsap-timeline, /gsap-plugins — deeper GSAP reference
• /animate-text — curated text animation catalog with exact JSON specs
• /framevideo-registry — if you need to install and wire registry blocks
• /framevideo-contrast — audit color contrast (WCAG)
• /lottie, /three, /waapi, /animejs, /css-animations — if beat uses these engines

Always open the captured assets folder before designing the beat:

• capture/assets/svgs/ — brand logos, icons, decorative marks. SVGs are infinitely scalable and stroke-animatable (path drawing, dash offset). A logo SVG drawing itself onto frame can carry an entire beat.
• capture/assets/ — hero illustrations, screenshots, product art, gradients, photography. These are first-class beat subjects, not background decoration. A breathing hero illustration with a single line of kinetic type is a complete shot.
• VIEW every image before placing text on it. Check safe zones, contrast, actual content, where the focal point sits.

If your beat spec names a captured asset, USE it. Don't substitute a CSS recreation. The user captured these from the real brand site precisely so the video carries the brand's actual visual identity.

Step 2: Build the composition

Save to the path the main agent specified (usually compositions/beat-N-name.html).

<template>
  <style>
    * {
      margin: 0;
      padding: 0;
      box-sizing: border-box;
    }
    /* your styles */
  </style>

  <div
    id="beat-N-name"
    data-composition-id="beat-N-name"
    data-width="1920"
    data-height="1080"
    style="width:1920px; height:1080px; position:relative; overflow:hidden; background:#YOUR_BG;"
  >
    <!-- your elements -->
  </div>

  <script>
    (function () {
      var BEAT = 5.5; // MUST match data-duration on the host div in index.html
      window.__timelines = window.__timelines || {};
      var tl = gsap.timeline({ paused: true });

      // your GSAP animations

      window.__timelines["beat-N-name"] = tl;
    })();
  </script>
</template>

Critical: data-composition-id, data-width, data-height on the root div MUST match the host div in index.html.

Step 3: Lint

npx framevideo lint .

Fix ALL errors. Zero errors required.

Step 4: Snapshot and verify

npx framevideo snapshot . --frames 3

READ the contact sheet (snapshots/contact-sheet.jpg). For each frame:

• Is content visible? (not black, blank, or loading)
• Is text readable, properly positioned, correct font/color?
• Are assets at the right size and position?
• Does the animation state match the beat spec at this timestamp?

If anything is wrong: fix, re-snapshot, re-check. You are done ONLY when every frame matches the spec.

Step 5: Report back honestly

After lint passes, snapshots are taken, and you've fixed every issue you saw — report back to the main agent with concrete observations. Not "0 errors, looks good." That phrasing is what got prior videos shipped with mismatched brand colors, missing logos, and headlines too small to read.

The main agent will OPEN your composition file and read it top-to-bottom to cross-check against DESIGN.md and STORYBOARD.md — does the brand bg/accent hex actually appear in your CSS, are the captured assets the storyboard called for actually referenced, is the headline ≥80px, does the GSAP timeline cover the full beat duration. You cannot pass that check by claiming things you didn't do; the file is on disk, the truth is in the file.

So in your report, name the hex codes you used, the captured asset paths you placed, the headline font-size, and the GSAP timeline's last tl.fromTo(...) timestamp. Brief, concrete, true. If anything diverges from DESIGN.md or the storyboard, say so explicitly — the main agent can decide whether to accept the divergence or send you back to fix it. Surprises caught at this hand-off cost minutes; surprises caught at Step 6 cost iterations.

FLAG protocol — required phrasing for non-blocking issues

When you find any of these, surface them as FLAGS in your report, not as conditional suggestions:

• Visual states that briefly look broken (empty containers, hanging elements, gap moments)
• Spec ambiguities you had to resolve by guessing
• Linter bugs you worked around
• Tween values you changed from the spec because they wouldn't fit

Forbidden phrasing: "if the X feels too long, you could...", "consider tweaking Y", "might want to..."

Required phrasing — concrete, actionable, with line numbers:

FLAG: at beat-local t=1.2s the doc card is visible but its inner content is still
       opacity 0 — a 0.4s empty-panel window.
       RECOMMENDED FIX: pull title typewriter from 1.6s → 1.4s
       in compositions/beat-5-name.html line 234.

The main agent MUST EITHER apply each FLAG's fix OR write a one-sentence rejection with reason. Silently dropping a FLAG is a verification failure that gets caught at Step 6 (or worse, in the user's preview).

Spec ambiguity — escalate, don't paper over

If STORYBOARD.md gives you a transition or transformation but doesn't establish the start state, do NOT guess. Examples of ambiguity worth flagging:

• "Row 1 transitions from Huly Blue to Huly Orange at 3.5s" — but Row 1's initial color isn't specified
• "Headline grows" — but the start size isn't specified
• "Cards slide in" — but the off-screen position isn't specified
• "Subhead appears after the headline" — but exact timing offset isn't specified

Required action: FLAG the ambiguity in your report verbatim:

FLAG: STORYBOARD.md beat 3 says "Row 1 transitions blue → orange at 3.5s" but
       Row 1's initial color is not specified anywhere. I interpreted Row 1 starts
       blue and tweened to orange. CONFIRM or correct.

The main agent then confirms or corrects before Step 6 advances. Picking an interpretation silently means the build looks "fine" while diverging from intent — and the user only notices in motion.

Sub-agent diagnoses are unverified claims, not facts

When a sub-agent reports "this is a linter false positive" / "this is a known bug" / "this attribute doesn't work as documented" — those are HYPOTHESES, not findings. Sub-agents diagnose from one symptom; they don't have repo-wide context.

Before propagating any sub-agent diagnosis (e.g., applying the same "workaround" to another beat, or telling the user "this is a known bug"), do ONE of:

1. Verify by reading the source. Open the file the sub-agent claims is buggy. Confirm the bug exists. Example: "I read packages/core/src/lint/utils.ts:42 and confirmed the regex matches url(\"data:image/svg+xml...\") incorrectly. The workaround is to base64-encode the URI." 2. Disclose the unverified claim. Don't suppress it — surface it. Example: "Sub-agent for beat 2 diagnosed root_missing_composition_id as a linter false positive on inline SVG data URIs. I applied the same workaround to beat 4 WITHOUT verifying the underlying claim. Worth filing as a regression against packages/core/src/lint/utils.ts to confirm."

Forbidden: silently adopting the workaround pattern and presenting "lint passes" as evidence. If the workaround came from an unverified diagnosis, "lint passes because the diagnosis was correct AND I worked around it" and "lint passes because the diagnosis was wrong but the workaround happened to make the symptom disappear" are both possible. Without verification, you don't know which. The next session inherits the workaround AND the unverified diagnosis.

When you accept a sub-agent's divergence from spec — UPDATE the spec

If a sub-agent reports "I diverged from STORYBOARD.md because..." AND you accept the divergence, you MUST update STORYBOARD.md to reflect the actual implementation. Otherwise the spec lies about the artifact.

Examples:

• Sub-agent: "Storyboard says 'HULY' uppercase but the actual logo asset is lowercase 'huly'. I used lowercase." Accept → edit STORYBOARD.md beat N to say "huly" lowercase. Note the change inline.
• Sub-agent: "Storyboard says cells at 56px but they read too small at 1920×1080. I used 96px." Accept → edit STORYBOARD.md beat N's cell size to 96px.
• Sub-agent: "Storyboard says SFX at t=4.7s but the visual moment lands at t=5.2s; I aligned SFX to the visual." Accept → edit STORYBOARD.md SFX line to t=5.2s.

Forbidden: accepting the divergence silently and leaving the storyboard with the wrong spec. The next session reading STORYBOARD.md will trust it as ground truth. The spec is a contract; if you break the contract, update the contract.

---

Continuous motion — the most important rule

A beat is a SHOT in a film, not a webpage with entrance animations. Your GSAP timeline should have events spread across the ENTIRE beat duration — not just entrance tweens in the first 1-2 seconds followed by nothing. If an element is on screen, it should be doing something. After elements enter, add continuous hold motion: camera dolly, parallax layers moving at different speeds, secondary elements appearing mid-beat, real depth shifts.

You are building a SHOT, not a webpage

The storyboard tells you the shot framing (close-up / medium / wide / etc.) and the camera move. Implement them. A beat is a moment, not a screenshot. The distinction is what the camera is doing, not whether the subject is a UI element or a logo — a tight push-in on a real product screenshot is a shot; a centered card on a parked camera is a webpage.

Patterns that turn a shot back into a webpage:

These are defaults to avoid, not absolute prohibitions. If the storyboard genuinely calls for "the kanban app interface" or "the browser chrome" as the subject of a specific beat (a product tour, a "this is how it works" demo, a stylized window mockup for the closer), then build it. The rule is: don't reach for these patterns by default when the storyboard didn't ask for them.

• ⚠ macOS / browser window chrome reproduced in CSS — traffic-light dots, URL bars, browser tabs. Fine when the storyboard makes the chrome the subject (e.g. "stylized macOS window framing the product UI" for a closer). NOT fine when it's a frame you added around a card "to make it look like an app."
• ⚠ Full webpage layout (sidebar + header + footer + main content area) — fine when the beat is genuinely a product tour shot. NOT fine when the beat was supposed to be about _the kanban moment_ and you defaulted to drawing the whole app around it.
• ❌ Parked-camera composition — centered card with 60–120px margins on all sides and no camera move. Almost always wrong. Either give it a real push-in / dolly / parallax, or reframe.
• ❌ "Hold with breathing" implemented as y: ±1–2px or scale: 1.01 — invisible at 1920×1080+ scale. If continuous motion is required, use camera dolly (scale 1.0 → 1.05), parallax pan (x/y ±30–80px), or progressive reveals.
• ❌ Hover-state simulations — videos have no hover. If the brand uses hover effects, show the BEFORE and AFTER as discrete frames in the timeline.
• ❌ Counter pulses + dot pulses + tiny scale wobbles as the only motion during the hold — these are "I ran out of ideas" filler.

The test: if the storyboard says _"this beat is the product tour, viewer sees the app interface"_, building a CSS dashboard with chrome is correct. If the storyboard says _"this beat is the kanban moment, single card sliding home"_, drawing the full app around it is wrong. Read the beat spec carefully.

Patterns that ARE shots (do these freely):

• ✅ Captured SVG logo drawing itself stroke-by-stroke (DrawSVG / path dashoffset) — a complete opener or stinger.
• ✅ Captured hero illustration with camera dolly — push-in from 1.0 → 1.08 over 4s, focal element holds frame.
• ✅ Captured product screenshot with parallax layers — separate the foreground UI from background panels and move them at different speeds, or use HTML-in-Canvas for an iPhone/MacBook mockup.
• ✅ Captured asset as the bed, kinetic type as the punchline — the brand's hero image holds the frame while a one-line message arrives, splits, reflows.
• ✅ Composed-from-divs UI moment when the beat is specifically about that UI's interaction (a card sliding into a column, a search result resolving) — this is the legit case for CSS-only composition.

Required motion magnitudes (anything smaller is invisible at video scale):

Required cinematography per beat (the storyboard should give you these; if it doesn't, escalate):

• A shot type (close-up / medium / wide / over-the-shoulder / Dutch)
• A camera move (dolly in/out, push, parallax pan, orbit, rack focus)
• A depth strategy (what's foreground / midground / background)
• A purpose (what specific feeling or noticing the shot delivers)

If any are missing from the beat spec, the beat is under-defined. Don't fill the gap with "centered layout + breathing" — re-read the spec, and if it's genuinely missing, ask the main agent.

Rules

• SCRIPT PLACEMENT: scripts inside <template>, never after </template>. Scripts outside see no DOM.
• GSAP FROM TRAP: never gsap.from(el, {opacity:0}) with CSS opacity:0. It animates 0→0. Use tl.fromTo().
• STYLE: avoid CSS opacity:0 on GSAP-animated elements. Use GSAP fromTo for initial states.
• ASSET PATHS: project-root-relative. capture/assets/file.png ✅ ../capture/assets/file.png ❌
• SVG VIA IMG: <img src="logo.svg"> can't inherit CSS color. Inline SVG or filter: brightness(0) invert(1).
• CSS CENTERING: no transform: translate(-50%, -50%) with GSAP transforms. Use flexbox or xPercent/yPercent.
• QUERYSELECTOR: document.getElementById("id") with null guards. No method calls without null check.
• CHARACTER SPANS: display:inline-block on spaces collapses them. Use   or per-word spans.
• COUNTERS: no onUpdate for numeric counters — use discrete tl.set(el, {textContent: "42"}, 2.5) at timestamps. onUpdate and tl.call() ARE supported for canvas/WebGL rendering loops and character-by-character typing — see capabilities.md §10.
• TIMELINE: window.__timelines["beat-N-name"] = tl synchronously. Key = data-composition-id.
• DETERMINISTIC: no Math.random(), Date.now(), requestAnimationFrame, repeat:-1.
• Always tl.fromTo() not tl.from() for entrances.
• Never stack two transform tweens on same element at same time.
• FONTS: copy the @font-face block VERBATIM from DESIGN.md's Fonts section. Do NOT guess which .woff2 file belongs to which family — capture filenames are content-hashed (14d7ce3e41dcbb66-s.p.woff2) and there is no visible mapping. If DESIGN.md doesn't include exact src: paths per family, STOP and ask the main agent to add them; never pair an arbitrary .woff2 file with a family name from memory.

Easing — pick per intent

Do NOT default to power2.out on everything.

Staggered items: power4.out with stagger: 0.08 to 0.15.

FrameVideo — Complete Capabilities Inventory

Everything possible in FrameVideo as of today's workspace, synthesized from direct source reads of all 7 packages, 16 skills, and the full registry.

How to read this file. Scan the Table of Contents below first. Do NOT read this file linearly — it is a 700+ line inventory; reading top-to-bottom every session wastes context. When the storyboard or a specific beat needs a particular capability (HTML-in-Canvas, shader transitions, audio-reactive, dynamic counters, etc.), jump straight to that section.

You are NOT limited to what was captured from the website. You can create shaders from scratch, search for and download registry blocks, build Three.js scenes, write custom WebGL effects, use any web API — anything a browser can render.

For implementation patterns (working code), see techniques.md. This file is the WHAT; techniques.md is the HOW.

Essential Rules

• Deterministic: No Math.random(), no Date.now(), no requestAnimationFrame, no repeat: -1. The render engine seeks to exact timestamps.
• Timeline contract: window.__timelines["composition-id"] = tl must be set synchronously. The timeline length defines the composition duration.
• Sub-compositions: External .html files loaded via data-composition-src. Auto-nested timelines, scoped CSS, scoped scripts.
• Linter: 60+ rules. Run npx framevideo lint before render. Catches missing timelines, overlapping clips, broken paths, GSAP errors.

Table of Contents

---

1. Composition fundamentals

Data attributes recognized by the runtime

• Root composition: data-composition-id, data-start, data-duration, data-width, data-height, data-composition-src (external sub-comp), data-composition-duration, data-composition-variables (JSON), data-variable-values (override)
• Every clip: id, data-start, data-duration, data-track-index, class="clip", optional data-media-start, data-volume, data-playback-start
• Sub-composition host: data-composition-id, data-composition-src OR inline <template id="${compId}-template">
• Parser also reads: data-type (composition|text), data-end, data-keyframes (JSON), data-x|y|scale|opacity, data-color|font-size|font-weight|font-family|text-shadow|outline|highlight*, data-layer (z-index, deprecated for timeline but used for audio mixer layers), data-resolution, data-composition-width|height

Timeline contract

• gsap.timeline({ paused: true }) registered on window.__timelines["<composition-id>"]
• Master clock (TransportClock + WebAudioTransport) drives the timeline via tl.totalTime(t, false) or tl.seek(t, false)
• Framework auto-nests sub-comp timelines
• Duration sourced from data-duration on root, not from GSAP length
• Synchronous timeline construction required (no async/await/setTimeout)
• Looping handled by <framevideo-player>, not GSAP repeat: -1

Resolution presets

VALID_CANVAS_RESOLUTIONS: 1920×1080 default, 1080×1920 portrait, 1080×1080 square, 4K, 1440×2560, plus normalizeResolutionFlag for --resolution CLI flag.

---

2. Animation engines (6 deterministic frame adapters)

The runtime registers these adapters in order; each implements discover() / seek({time}) / pause / play? / revert:

GSAP plugins (documented patterns)

• TextPlugin — text mutation in tl.call (skills/gsap/references/effects.md)
• MotionPathPlugin — curve-constrained tweens (skills/framevideo/references/techniques.md)
• CustomEase — bezier eases imported from Remotion-style timing
• ScrollTrigger / Flip / SplitText / Draggable / Inertia / Observer / ScrambleText / CustomWiggle / CustomBounce / ScrollSmoother / GSDevTools — work natively if loaded and tweens are on the registered paused timeline, but no special FrameVideo adapter
• Producer injects ScrollTrigger CDN automatically when needed (packages/producer/src/services/htmlCompiler.ts)

---

3. Shader transitions — @framevideo/shader-transitions

14 named WebGL fragment shaders. All share the same uniforms: u_from, u_to, u_progress, u_resolution, u_accent, u_accent_dark, u_accent_bright.

The 14 shaders

Public API

HyperShader.init({
  bgColor: "#0b0f14",
  accentColor: "#f59e42",
  scenes: ["scene1", "scene2"],
  transitions: [{ time: 3, shader: "sdf-iris", duration: 0.65, ease: "power2.inOut" }],
  timeline: gsap.timeline({ paused: true }),
  compositionId: "main",
  previewCaptureFps: 30,
});

• Capability probe: isHtmlInCanvasCaptureSupported() (Chrome layoutSubtree/drawElementImage)
• Tuning: ?__fv_shader_capture_scale= (0.25–1), ?__fv_shader_loading= (internal|player|none)
• Cache: IndexedDB for PNG snapshots; max 2 textured transitions live at once
• Fallback (applyFallbackTransition): smoothstep opacity tween when capture / texImage2D fails
• Engine mode skips GL/capture when window.__FV_VIRTUAL_TIME__ set (producer uses metadata)

You can also write custom GLSL shaders from scratch — any fragment shader works with the standard uniforms.

---

4. CSS scene transitions (30+ named patterns)

Documented in skills/framevideo/references/transitions/ across 14 category files. All GSAP-driven, none mixable with shader transitions in same composition.

By category

Timing presets

---

5. Visual effects + textures

Marker/emphasis patterns (css-patterns.md)

Grain / noise

• grain-overlay (registry component): SVG feTurbulence data-URL + CSS keyframe jitter, steps(1), default opacity 0.15
• Layered radial-gradient grain (preferred pattern): no SVG, no canvas-taint, fast everywhere

Light / film

• Light leak transitions (CSS + shader variants)
• Overexposure burn — brightness() ramp + flash overlay
• Film burn — multi-layer amber/orange/red radials
• Vignette — radial-gradient overlay
• Paper texture (in registry/examples/warm-grain/)

Glow

• Caption text glow: textShadow radius keyed to treble bands (always on active words only, never parents)
• Radial glow backgrounds: CSS gradients / blurred blobs

---

6. Caption techniques

Animation styles

• Baseline: per-word karaoke highlight (every energy level)
• Intensity tiers: accent + glow + 15% scale (high energy) → 3% scale (low energy)
• Exits by energy (dynamic-techniques.md): scatter, drop, collapse, fade+slide, fade
• Tone mappings (captions.md): scale-pop back.out(1.7), fade+slide power3.out, typewriter, bounce, elastic.out, word-by-word

Per-word styling triggers

• Brand/product names
• ALL CAPS
• Numbers / stats
• Emotional keywords
• CTAs
• Marker highlight modes (5 listed above)

Audio sources for caption timing

Positioning helpers

• Landscape: bottom 80–120px centered
• Portrait: ~600–700px from bottom
• window.__framevideo.fitTextFontSize(text, {maxWidth, fontFamily, fontWeight}) for dynamic sizing

---

7. Audio-reactive animation

Data shape

window.AUDIO_DATA = {
  fps: 30,
  totalFrames: 900,
  frames: [{ bands: [0.42, 0.18, ...] }]  // bands normalized 0–1 per band across track
};

Index 0 = bass, higher = treble. Bands range 0–1, normalized across full track length.

Mappings documented

Any GSAP-tweenable property is fair game — including clipPath, filter, SVG attrs, CSS variables.

Extraction

python3 .../extract-audio-data.py audio.mp3 --fps 30 --bands 8

Pre-extracted only — no Web Audio at render time.

Banned in audio-reactive

EQ bars, spectrum UI, generic waveforms, note clip-art, generic particles, rainbow cycling, white strobe on beats, abstract pulsing orbs.

---

8. HTML-in-canvas

Documented in skills/framevideo/references/html-in-canvas-patterns.md (504 lines).

Capability

• Chrome's experimental layoutSubtree + drawElementImage rasterizes live DOM into canvas
• Feature detection: isHtmlInCanvasCaptureSupported()
• Used by shader-transitions for scene textures
• Combined with Three.js: CanvasTexture + post-processing

Available patterns

• HTML on a Three.js plane (displacement, distortion, liquid sim)
• HTML in shaders (texture sampling for VFX)
• Recursive HTML-in-canvas-in-shader-in-HTML

Experimental VFX blocks using this

• vfx-iphone-device (GLTF iPhone + MacBook, HTML screens)
• vfx-liquid-background (liquid sim displaces HTML)
• vfx-liquid-glass
• vfx-magnetic
• vfx-portal
• vfx-shatter
• vfx-text-cursor (chromatic edges, canvas post)

---

9. Three.js / WebGL custom scenes

Integration pattern

window.addEventListener("fv-seek", (e) => {
  const time = e.detail.time;
  mixer.setTime(time);
  shaderUniforms.u_time.value = time;
  renderer.render(scene, camera);
});

• Load: import * as THREE from "https://cdn.jsdelivr.net/npm/three@0.181.2/+esm"
• Deterministic: every frame must derive from time, never requestAnimationFrame / Date.now()
• Includes: AnimationMixer, custom GLSL shaders, post-processing, GLTF models, lights, cameras, materials

---

10. SVG / canvas / variable fonts (other authored techniques)

(From skills/framevideo/references/techniques.md)

---

11. Media: video, audio, TTS

Video compositing

• <video muted playsinline data-start="..." data-duration="..." data-track-index="..." src="...">
• FrameVideo extracts frames at render via videoFrameInjector (avoids unreliable headless <video> playback)
• Linter forbids <video> with audio at the same time — split into separate <video muted> + <audio>
• Video frame extraction uses FFmpeg
• HDR videos: PQ or HLG transfer detection + x265 with mastering metadata

Audio mixer

• <audio id="..." data-start="..." data-duration="..." data-volume="0.8" data-track-index="2" src="...">
• Multiple tracks mixed with amix normalize=0 + per-track adelay + volume
• Master audioGain from EngineConfig
• Output: AAC 192kbps

TTS (Kokoro-82M, local)

• 54 bundled voices with prefixes: a American EN, b British EN, e Spanish, f French, h Hindi, i Italian, j Japanese, p Brazilian Portuguese, z Mandarin
• Default voice: af_heart
• Speed: 0.1–3.0 (default 1.0)
• Languages: en-us, en-gb, es, fr-fr, hi, it, pt-br, ja, zh (non-EN needs system espeak-ng)
• Output: WAV; no pitch/volume CLI flags
• No API key required

Transcription

• Whisper.cpp models: tiny, base, small, medium, large-v3, small.en, medium.en (default small)
• Groq API: whisper-large-v3 with word granularities
• OpenAI API: whisper-1 verbose_json
• Imports: SRT, VTT, JSON formats
• Quality gates: music-token detection, garbage cleaning, retry with medium.en

Background removal

• u2net ONNX models
• Devices: auto / cpu / coreml / cuda
• Quality presets: fast / balanced / best
• Outputs: transparent WebM, ProRes MOV, PNG sequence
• Optional dual output (foreground + extracted background)

---

12. Registry — 51 blocks + 4 components + 8 examples

Blocks by category

Social overlays (8): instagram-follow, tiktok-follow, yt-lower-third, x-post, reddit-post, spotify-card, macos-notification, blue-sweater-intro-video

Showcases (5): app-showcase (3D phones), north-korea-locked-down (map + annotation), apple-money-count (counter + SFX), vpn-youtube-spot (app-store scroll), nyc-paris-flight (map + plane path)

Data viz (2): data-chart (animated bar+line, NYT-style), flowchart + flowchart-vertical (decision tree with SVG connectors, typing correction)

Logo / branding (1): logo-outro (build + glow + tagline + URL pill)

3D / experimental VFX (8): ui-3d-reveal, vfx-iphone-device (GLTF), vfx-liquid-background, vfx-liquid-glass, vfx-magnetic, vfx-portal, vfx-shatter, vfx-text-cursor

Single shader transitions (14): one block per named shader — domain-warp-dissolve, ridged-burn, whip-pan, sdf-iris, ripple-waves, gravitational-lens, cinematic-zoom, chromatic-radial-split, glitch, swirl-vortex, thermal-distortion, flash-through-white, cross-warp-morph, light-leak

Transition galleries (13 showcase pieces): transitions-3d, transitions-blur, transitions-cover, transitions-destruction, transitions-dissolve, transitions-distortion, transitions-grid, transitions-light, transitions-mechanical, transitions-other, transitions-push, transitions-radial, transitions-scale

Components (4 reusable snippets)

• grain-overlay — SVG feTurbulence + CSS keyframes
• shimmer-sweep — Light sweep gradient mask on text
• grid-pixelate-wipe — Grid squares stagger fade scene wipe
• texture-mask-text — Luminance-masked letterforms with 66 mask PNGs (Masonry, Stone, Ground/Road, Wood, Metal, Organic/Soft texture categories)

Examples (8 starter projects)

warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph

Install: npx framevideo add <name> for blocks/components, framevideo init <dir> --example <name> for examples.

---

13. CLI — 25 commands

Website capture (framevideo capture <url>)

Detects these libraries on captured sites (for context labeling): GSAP / ScrollTrigger, Three.js, Lottie, Anime.js, PixiJS, Babylon.js, Rive, Matter.js, Lenis, Framer Motion, Tailwind CSS, WebGL (shader fingerprinting). Captured outputs feed the website-to-framevideo skill workflow.

---

14. Linter — 60+ rules

Across 8 files in packages/core/src/lint/rules/:

Plus async URL checks (lintMediaUrls, lintScriptUrls — HEAD probes).

validateCompositionGsap also forbids: Math.random, Date.now, new Date, setTimeout, setInterval, requestAnimationFrame, repeat: -1.

Note: onUpdate callbacks, tl.call(), and GSAP event callbacks (onComplete, onStart, etc.) are NOT banned by the linter — they are required for canvas/WebGL rendering and character-by-character typing patterns. The linter only catches the determinism violations listed above.

---

15. Player — <framevideo-player> web component

Attributes

src, srcdoc, width, height, controls, muted, volume, poster, playback-rate, audio-src, shader-capture-scale, shader-loading (internal|player|none), loop, autoplay, speed-presets

Public API

seek(t) (synchronous when same-origin — uses iframe.contentWindow.__player.seek directly), play(), pause(), currentTime, duration, paused, ready, playbackRate, iframeElement

Events

ready, timeupdate, play, pause, ended, volumechange, ratechange, shadertransitionstate, playbackerror, error, audioownershipchange

Media mirror

Parent audio/video elements with data-start are proxied; _mirrorParentMediaTime corrects drift; _audioOwner promotes to parent if autoplay blocked.

Runtime auto-inject

Loads RUNTIME_CDN_URL (@framevideo/core/dist/framevideo.runtime.iife.js) if missing __fv/__player but timelines exist.

---

16. Engine + Producer — rendering pipeline

Output formats

mp4, webm, mov, png-sequence — with HDR (PQ / HLG / SDR / auto-detect), transparency (ProRes MOV / WebM / PNG), or standard 8-bit SDR

Encoding controls

• --fps: 24 / 30 / 60
• --quality: draft / standard / high
• --crf: integer (mutually exclusive with --video-bitrate)
• --video-bitrate: e.g. 8M
• --gpu: NVENC, VideoToolbox, VAAPI, QSV
• --browser-gpu: auto / software / hardware
• --workers: parallel render workers
• --max-concurrent-renders: 1–10 (sets PRODUCER_MAX_CONCURRENT_RENDERS)
• --resolution: preset (1080p, 4k, portrait, etc.)
• --docker: render inside Dockerfile.test image (reproducibility)
• --hdr / --sdr: force HDR or SDR pipeline

Engine subsystems

• Frame capture: BeginFrame on Linux headless-shell (fast, no alpha) or Page.captureScreenshot (alpha + supersample)
• Video frame injector: pre-extracts video to images, swaps <video> for <img> during capture (LRU cache by path + byte budget)
• Audio mixer: FFmpeg-based; per-track delay, volume, master gain, AAC 192k output
• Chunk encoder: H.264 / H.265 / VP9 / ProRes presets with optional GPU
• Streaming encoder: streamingEncodeMaxDurationSeconds for long renders
• HDR compositing: rgba16float WebGPU readback (headed Chrome), PQ OETF helpers
• Layer compositor: groups DOM by z-order; splits HDR elements into separate layers
• Alpha blit: matrix3d affine extraction, blitRgba8OverRgb48le, blitRgb48leAffine
• Parallel coordinator: concurrency, coresPerWorker, minParallelFrames, largeRenderThreshold
• Browser pool: optional with timeout configs

Producer-only

• RenderConfig with hdrMode (auto / force-hdr / force-sdr), outputResolution mapped to deviceScaleFactor
• File server injects FV_EARLY_STUB, FV_BRIDGE_SCRIPT, virtual-time so window.__fv bridges window.__player.renderSeek
• HDR-aware shader transition compositing via window.__fv.transitions metadata

---

17. Studio — in-browser NLE

Full editor in packages/studio/:

• NLELayout: NLE preview + timeline + controls
• Timeline: clip rendering, drag to move (data-start), resize (data-duration), data-track-index reassignment, asset drop, file drop
• PlayerControls: scrub, play, pause, frame step (stepFrameTime), STUDIO_PREVIEW_FPS
• useTimelinePlayer: resolves __player / __timeline / __timelines
• LeftSidebar: compositions list, asset browser
• RenderQueue + useRenderQueue: queue multiple renders
• LintModal: in-app lint output
• MediaPreview + AudioWaveform: waveform rendering
• CaptionOverlay, CaptionTimeline, CaptionPropertyPanel: caption editor
• useCaptionSync: word-level sync
• useElementPicker: click-to-inspect picker mode
• Built with Tailwind v3 (separate from Tailwind v4 browser runtime used by compositions).

---

18. Determinism guarantees

• No Math.random() (use seeded PRNGs; mulberry32 is the pattern in skills)
• No Date.now() / new Date()
• No setTimeout / setInterval in timeline construction
• No requestAnimationFrame (timeline-driven; engine seeks per frame)
• No repeat: -1 (calculate exact repeats: Math.ceil(duration / cycleDuration) - 1)
• No onComplete/onStart/onRepeat callbacks (engine doesn't fire them). Exception: onUpdate and tl.call() ARE supported — they're required for canvas/WebGL rendering, character-by-character typing, and counter patterns. See §10 (Canvas 2D procedural art) for the documented pattern.
• No gsap.set on clips from later scenes (use tl.set(selector, vars, position))
• Synchronous timeline construction (no async)
• Master clock can clamp at composition end

---

19. Variables / parameterization

Compositions support typed runtime variables:

<html
  data-composition-variables='[
  {"name":"brand","type":"string","default":"Stripe"},
  {"name":"primary","type":"color","default":"#635BFF"},
  {"name":"duration","type":"number","default":15},
  {"name":"darkMode","type":"boolean","default":false},
  {"name":"layout","type":"enum","options":["hero","split","stacked"]}
]'
></html>

Access via window.__framevideo.getVariables(). Override at render time:

npx framevideo render --variables '{"brand":"Linear","primary":"#5E6AD2"}'
npx framevideo render --variables-file vars.json
npx framevideo render --strict-variables  # error if unused / mismatched

validateVariables() checks values against declarations at the CLI/tooling boundary.

---

20. Sub-compositions

Two loading mechanisms:

• External file: data-composition-src="compositions/act-1.html" — fetched at runtime
• Inline template: <template id="<id>-template"> — extracted by loadInlineTemplateCompositions

Each sub-comp:

• Has its own data-composition-id
• Has its own window.__timelines[<id>]
• Auto-nested into the root timeline
• Scoped CSS via scopeCssToComposition ([data-composition-id="<id>"] selector)
• Wrapped scripts via wrapScopedCompositionScript
• Reads data-variable-values merged with own defaults into window.__fvVariablesByComp[<id>]
• External scripts load with EXTERNAL_SCRIPT_LOAD_TIMEOUT_MS timeout. Failed loads emit external_composition_load_failed / external_composition_script_load_issue diagnostics.

---

21. Global runtime APIs (window.*)

Control bridge actions: play, pause, seek, set-muted, set-playback-rate, enable-pick-mode, disable-pick-mode, set-volume, set-media-output-muted.

---

22. Skills available — 16

---

23. References inventory (skills/framevideo/references/)

16 reference docs covering:

• text-effects.md — 24 named text animation effects (per-character, per-word, per-line, whole) — vocabulary reference for the separate pixel-point/animate-text skill (load it via npx skills add pixel-point/animate-text or /animate-text). Specs live in that upstream skill, not in this repo.
• transitions.md + transitions/catalog.md + 14 category subfiles
• css-patterns.md (marker patterns)
• dynamic-techniques.md (caption animation)
• motion-principles.md (easing as emotion, choreography)
• typography.md (banned-font list, pairing rules, variable fonts)
• narration.md (script + VO pacing)
• captions.md (caption authoring contract)
• audio-reactive.md (band mappings + extraction)
• transcript-guide.md (whisper, Groq, OpenAI workflows)
• techniques.md (the big technique catalog — SVG, canvas 2D, 3D, kinetic, lottie, variable fonts, MotionPath, audio-reactive)
• beat-direction.md, design-picker.md, prompt-expansion.md, video-composition.md
• visual-styles.md (8 named visual styles: Swiss Pulse, Velvet Standard, Deconstructed, Maximalist Type, Data Drift, Soft Signal, Folk Frequency, Shadow Cut — available via the visual-style skill)

---

24. Documentation pages (docs/)

27 mdx pages in docs/guides/ and docs/packages/:

Guides: 4k-rendering, claude-design, common-mistakes, deploy, gsap-animation, hdr, html-in-canvas, framevideo-vs-remotion, open-design, performance, prompting, remove-background, rendering, timeline-editing, troubleshooting, video-editor-cheatsheet, website-to-video, etc.

Packages: cli.mdx, core.mdx, engine.mdx, player.mdx, producer.mdx, studio.mdx

Step 0: Capture

The capture pipeline downloads the site and extracts structured data for the rest of the workflow to read. Step 0 is a single command plus a sanity check. All analysis (reading files, viewing contact sheets, deriving brand voice, picking assets) happens in Steps 1–3, not here.

Run the capture

No API keys required for the base capture. However, before running, ask the user:

"For the best results, it is recommended to set a Gemini API key — it gives me AI-powered descriptions of every captured image, which helps me choose the right assets for each scene. It costs about $0.001 per image. You can skip this if you want, but the video quality will be better with it. To set it up: add GEMINI_API_KEY=your-key to a .env file in the project root. You can get a free key at ai.google.dev."

If the user provides the key or already has one set, proceed. If they skip it, proceed anyway — the capture works without it, but asset-descriptions.md will have DOM-context descriptions only (position, size, alt text) instead of AI vision descriptions.

Create a project directory for your video if it doesn't exist yet, then capture the website into a capture/ subfolder within it:

npx framevideo capture <URL> -o <project-dir>/capture

Example: npx framevideo capture https://stripe.com -o videos/stripe-launch/capture

Keeping capture artifacts (screenshots/, assets/, extracted/, AGENTS.md, CLAUDE.md) in a dedicated capture/ subfolder keeps them isolated from later build files (SCRIPT.md, STORYBOARD.md, DESIGN.md, compositions/, index.html, narration.wav, transcript.json, renders/, snapshots/), which all live at <project-dir>/ root.

For exploratory captures that aren't becoming a video yet, -o captures/<name> at the repo root is fine — the isolation convention only matters when you're building a video on top of the capture.

Confirm it succeeded

Wait for the capture to complete. Print one line summarizing what was captured:

"Captured N screenshots, M assets, K SVGs, F fonts. Ready for Step 1."

If the command exited non-zero, the counts are all zero, or required directories (extracted/, assets/, screenshots/) are missing, surface the error and stop — don't advance to Step 1 with a broken capture.

What lives in capture/ (reference table — DO NOT read these here)

Each downstream step reads only what it needs. Don't pre-fetch everything in Step 0; that bloats context and produces summaries that get stale by the time they're used.

Gate

Capture exits 0. Asset / screenshot / font counts non-zero. Proceed to Step 1.

Step 1: Write DESIGN.md (the brand-truth cheat sheet)

DESIGN.md is a brand-truth cheat sheet — colors and fonts you'll weave into your composed builds. It is NOT a layout spec, not a moodboard, not a 400-line design system audit.

DESIGN.md is the brand inflection sub-agents apply when building each beat: which color is "primary," which font is for headlines, what tone the brand carries — the load-bearing knobs they flip while building.

Target length: 250–350 lines. Step 5 sub-agents read DESIGN.md to brand each beat — the more precise the component CSS values you encode here, the more brand-faithful the result. Going under 200 lines tends to produce generic dark-cinematic output because sub-agents have no brand component DNA to work from; going over 350 means you're over-investing in prose.

Fast-pacing exception: For billboard-per-beat videos (short social ads where each beat is a single hero element on full-bleed background), a 50-line DESIGN.md with just colors + fonts + 3-5 do's/don'ts is enough. The Step 5 sub-agent prompt pastes brand values inline, so DESIGN.md depth only matters when the beats render full UIs.

User preferences always override brand rules. If the user says "make it bright even though the site is dark" or "use serif fonts even though the brand is sans" — follow the user. DESIGN.md describes the captured website. The video might deliberately break that.

Read these now — they're the inputs DESIGN.md is built from. Don't guess colors or sizes from screenshots:

• capture/extracted/tokens.json — top brand colors (HEX) and font families with weight ranges.
• capture/extracted/design-styles.json — computed CSS values from the live DOM: typography hierarchy (font-size, weight, line-height, letter-spacing per text role), button variants (background, padding, radius, shadow), card/container/nav styles, spacing scale, border-radius scale, box-shadow values with usage counts. Primary data source for Sections 3–6 below.

Font availability check — do this before writing anything else. Read capture/extracted/fonts-manifest.json. The capture pipeline reads the OpenType name table embedded in every downloaded font file, so even hash-renamed Next.js/Webpack fonts are identified by their real family name (Inter, JetBrains Mono, Geist Mono, etc.). No guessing required.

The manifest gives you two views:

• families[] — one entry per distinct family with the weights captured, whether it's a variable font, and the files belonging to it
• files[] — one entry per downloaded font with family, subfamily, weight, style, and any variation axes

How to use it:

• For each family you'll reference in DESIGN.md, name it by what's in families[].family (e.g. "Inter", not "f266e704 hashed font"). The hashed filenames are the @font-face src paths — they stay as-is on disk; only the display name comes from the manifest.
• If a family has variable: true and variationAxes includes "wght", you can use any weight 100-900 via font-variation-settings: 'wght' <value> even if only one static weight appears in the captured files. Note this in DESIGN.md so sub-agents know they have the full weight range available.
• If the manifest's unidentified[] is non-empty, those files failed name-table extraction (rare — heavily subset fonts that strip metadata). Flag them as unknown in DESIGN.md and suggest a fallback rather than guessing.
• Commercial fonts hosted on brand CDNs (GT Walsheim, Söhne, Graphik, Canela) won't be in the manifest because they aren't downloaded. Detect this by checking what the site uses (from design-styles.json) against what's in the manifest — anything used but missing is a CDN-hosted font. Flag explicitly: "Söhne not in capture; use Inter 600 as substitute."

Sub-agents try to use the fonts you list. The manifest tells you exactly what's available — there's no excuse for claiming "Charlie Display 700" when no such file exists.

---

The 5 sections to write

## 1. Visual Theme (one paragraph)

3–5 sentences describing the brand's visual personality. Cover: dark-first or light-first, contrast strategy, dominant visual elements (gradients, illustrations, photography, UI mockups), overall mood, what makes it distinctive vs. generic.

This is the only prose section. Make it specific to _this_ brand — not template-filling. A sentence that could describe any well-designed website is not useful.

Example:

Stripe's visual language is light-first and clean, with deep navy (#061B31) and pure white as the foundation. The accent stack — Stripe Purple (#533AFD) for CTAs, Vibrant Orange (#FF6118) for energetic emphasis — keeps interactive elements unmistakable. Type is sohne-var Light (300) for display, weight 400 for body; the brand achieves hierarchy through size and weight, never color shifts. The mood is confident financial-tech — premium without theatrical drama. Distinctive: gradient overlays at 135° between purple and orange appear as subtle washes over white backgrounds, never as bold focal elements.

---

## 2. Quick Reference

A flat lookup of the values sub-agents grab while composing beats. Two sub-sections — keep them tight.

Colors

List 8–12 colors with brand-specific names + HEX + role. Not generic ("Accent 1") but evocative ("Stripe Purple", "Deep Navy", "Slate Border"). The name carries meaning; "blue 4" doesn't.

For each text-on-surface combination the brand uses, compute the WCAG AA contrast ratio and flag failing pairings explicitly. A real failure mode from prior runs: the brand's secondary-text color (#68686A) on its dark panel color (#18191B) = 3.16:1, which fails AA's 4.5:1 minimum. Sub-agents faithfully reproduced the brand's color choice and the result was unreadable. Encode the safe / unsafe pairings here so sub-agents pick text colors by surface context, not by "this is the brand's secondary text color." The /framevideo-contrast skill audits ratios — run it before finalizing DESIGN.md.

Example:

#### Colors

- **Stripe Purple** (`#533AFD`): Primary CTA, interactive elements, focus rings — the brand's action signal
  - On Pure White: 6.2:1 ✅ — On Deep Navy: 3.8:1 ⚠ AA-only-Large
- **Deep Navy** (`#061B31`): Primary text on light surfaces, also a dark surface tier
  - As text on Pure White: 17.4:1 ✅ — As surface: see Slate-on-Navy pairings below
- **Pure White** (`#FFFFFF`): Page background, card surfaces
- **Light Gray** (`#F5F7FA`): Surface tier 2 (cards on white pages, alternating sections)
- **Slate Blue** (`#273951`): Secondary text on LIGHT surfaces
  - On Pure White: 12.6:1 ✅ — On Light Gray: 11.8:1 ✅ — On Deep Navy: 1.4:1 ❌ DO NOT USE
- **Light Slate** (`#64748D`): Metadata, captions on light surfaces only
  - On Pure White: 4.8:1 ✅ — On Light Gray: 4.5:1 ✅ — On Deep Navy: 3.0:1 ❌ — On Dark Panel: 2.9:1 ❌
  - **For dark-surface metadata, use `#9A9A9E` instead: 6.4:1 on Deep Navy ✅, 6.1:1 on Dark Panel ✅**
- **Subtle Border** (`#D4DEE9`): Card borders, dividers (not text — borders don't need AA)
- **Vibrant Orange** (`#FF6118`): Energy accent — gradient endpoints, highlight bursts (never primary text)
- **Error Red** (`#FF0022`): Validation errors. On Pure White: 4.5:1 ✅
- **Success Green** (`#4CD963`): Confirmation states. On Pure White: 1.7:1 ❌ — must be paired with a darker outline or use as accent on dark surfaces

Where the brand's own palette fails WCAG, document the substitute (like the #9A9A9E override above). Sub-agents pick the safe color by surface — and if the deviation matters to the brand identity, the user can revisit at Step 6.

Fonts

List font families with their role AND the exact file path per family + weight from fonts-manifest.json. Sub-agents will copy the @font-face block verbatim — if you only name the family without the path, sub-agents have to guess which .woff2 file belongs to which family and get it wrong half the time (a real failure mode from prior runs: agents pointed @font-face for "ES Build Neutral" at the Inter .woff2 files and the wordmark rendered in Inter).

Example:

````markdown

Fonts

• Display: "ES Build Neutral" — wordmarks, headlines
• 600: capture/assets/fonts/14d7ce3e41dcbb66-s.p.woff2
• 700: capture/assets/fonts/e8b276476c0ac6fa-s.p.woff2
• Body: "Inter" (variable 100–900, captured ✓) — body, labels, UI
• 400: capture/assets/fonts/9a8d3f06c4e89f2b-s.p.woff2
• 600: capture/assets/fonts/1b0b3615811be75b-s.p.woff2
• Mono: "JetBrains Mono" — code, metadata
• 400: capture/assets/fonts/c7d2e9f5a1b3c8d4-s.p.woff2
• Fallback stack: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif

`@font-face` block to paste in every composition (sub-agents copy this verbatim — do not invent file paths):

@font-face {
  font-family: "ES Build Neutral";
  src: url("capture/assets/fonts/14d7ce3e41dcbb66-s.p.woff2") format("woff2");
  font-weight: 600;
  font-display: block;
}
@font-face {
  font-family: "Inter";
  src: url("capture/assets/fonts/9a8d3f06c4e89f2b-s.p.woff2") format("woff2");
  font-weight: 400;
  font-display: block;
}
/* + any other family/weight combinations the storyboard's beats need */

````

The brand uses size for hierarchy, weight for emphasis. Display 1: 48px/600, Display 2: 32px/600, Body: 14px/400. (Adjust to the actual brand's hierarchy.)

````

The exact @font-face block lets sub-agents copy verbatim instead of constructing one from inference. If a beat needs a weight that isn't in the manifest, flag it explicitly here: e.g., "ES Build Neutral 900 NOT in capture; use ES Build Neutral 700 as substitute, or fall back to Inter 700."

That's the whole typography section. If sub-agents need exact line-heights or letter-spacing, they read design-styles.json directly.

---

## 3. Component Stylings (the build-step's spec sheet)

This is the section sub-agents consult most when building beats in Step 5. Without exact per-component CSS, sub-agents fall back to generic "dark bg + glow + centered text" patterns regardless of brand — which is why every video starts looking the same. Encode the brand's actual component DNA here.

Target 6-12 distinct components. Document what the site actually uses; skip categories the brand doesn't have. For each component, name it descriptively ("Stripe Primary Button" not "Button 1") and provide exact CSS-level properties: background, text color, padding, border-radius, border, font size/weight, height, box-shadow, and any hover/active/disabled states.

Buttons (always required)

Cover every variant the site uses — typically Primary, Secondary/Ghost, and Icon. Example:

#### Primary Button (Stripe Purple)

- **Background:** `#533AFD`
- **Text color:** `#FFFFFF`
- **Font:** sohne-var 16px / 400
- **Padding:** `15.5px 24px 16.5px 24px`
- **Border radius:** `4px`
- **Border:** none
- **Height:** `48px` (with padding)
- **Box shadow:** none
- **Hover:** background `#4329E8`, opacity `0.95`
- **Active:** background `#3720D4`, scale `0.98`
- **Disabled:** background `#C9C3F0`, cursor `not-allowed`

#### Secondary Button (outline)

- **Background:** `#FFFFFF`
- **Text color:** `#533AFD`
- **Border:** `1px solid #533AFD`
- **Padding / radius / font:** same as Primary
- **Hover:** background `#F3F0FF`, border `#4329E8`

#### Ghost Button (text-only link)

- **Background:** transparent
- **Text color:** `#533AFD`
- **Font:** sohne-var 14px / 400
- **Padding:** `12px 0`
- **Hover:** background `rgba(83, 58, 253, 0.08)`, optional underline

Cards & Containers (always required if the site uses any)

Document each distinct card type — Standard, Feature Highlight, Glass, Pricing, Testimonial — whatever this brand actually uses. Example:

#### Standard Card

- **Background:** `#FFFFFF`
- **Border:** `1px solid #D4DEE9`
- **Border radius:** `5px`
- **Padding:** `32px`
- **Box shadow:** `0 1px 2px rgba(0, 0, 0, 0.04)` (default), `0 4px 12px rgba(0, 0, 0, 0.08)` (hover)
- **Hover:** border `#B8CCDB`

#### Feature Highlight Card (gradient backdrop)

- **Background:** linear-gradient(180deg, rgba(83, 58, 253, 0.05) 0%, rgba(255, 97, 24, 0.03) 100%)
- **Border:** `1px solid #E5EDF5`
- **Padding:** `36px`
- **Box shadow:** none

Distinctive components (anything else the brand actually shows)

Logo marquees, testimonial carousels, pricing tables, gradient overlays, glassmorphism panels, bento grids, code blocks, terminal UIs, dashboard mockups — name and document anything visually distinctive. Sub-agents will reach for these specs when the storyboard calls for a beat featuring the X.

#### Glass Container (frosted overlay)

- **Background:** `rgba(255, 255, 255, 0.9)`
- **Border:** `1px solid rgba(255, 255, 255, 0.2)`
- **Backdrop filter:** `blur(8px)`
- **Use:** floating chat widgets, modal overlays, hero callouts only — the only place transparent fills appear in the system

The rule: if a sub-agent in Step 5 has to invent CSS values for a component this brand actually uses, you under-documented this section. The values should be lookup-able, not guessable.

---

## 4. Spacing & Layout

The brand's rhythm. Three sub-sections, kept tight.

Spacing scale

Identify the base unit (typically 4px or 8px) and the full scale with usage context. Example:

**Base unit:** `4px`

| Token | Value   | Used for                                                  |
| ----- | ------- | --------------------------------------------------------- |
| xs    | `4px`   | Inline icon gaps, tight badge padding                     |
| sm    | `8px`   | Button-group gaps, small component padding                |
| md    | `16px`  | Card padding, form-field gaps, standard component spacing |
| lg    | `32px`  | Section vertical spacing, large card padding              |
| xl    | `60px`  | Major section separation                                  |
| 2xl   | `100px` | Page-level rhythm, hero section padding                   |

Never use odd values (`13px`, `17px`) — the system only uses multiples of 4.

Border-radius scale

Every radius the site uses, with what uses it.

- `0px`: Form labels, technical UI markers
- `4px`: Primary buttons, inputs, small badges
- `8px`: Standard cards, dropdowns
- `12px`: Feature cards, larger callouts
- `40px`: Icon buttons (square pill)
- `9999px`: Pill-shaped CTAs, status chips

Whitespace philosophy (one paragraph)

How does this brand use whitespace — generous and architectural? Tight and information-dense? Section gaps in the 60–100px range, or 20–40px? Document the brand's actual rhythm.

Generous whitespace as confidence. Section gaps are always `60–100px`. Content never touches viewport edges — minimum `40px` horizontal padding on mobile, `80–160px` on desktop. The brand uses negative space as active design, not emptiness.

---

## 5. Iteration Guide (the load-bearing section)

5–10 numbered rules that encode the most important brand decisions. Each rule is a single actionable sentence stating what to do, with the specific values from this site. These are the "if in doubt, do this" rules sub-agents consult while composing beats.

The single most common failure mode is writing generic rules that could apply to any well-designed website. A rule that doesn't name a specific value, a specific color, or a specific component this brand actually uses is doing nothing.

Test for any rule you write: can you swap this brand for a different brand and have the rule still make sense? If yes, it's too generic. If no, ship it.

❌ Generic vs ✅ site-specific

One worked example (Framer — 5 rules)

### Iteration Guide

1. **All interactive elements use Framer Blue (`#0000EE`)** — links, primary buttons, active states, focus indicators. Secondary uses `#0099FF` for hover. **No other interactive color exists in the system.**

2. **Typography: GT Walsheim Medium for headings, Inter for body.** Hierarchy enforced through size only, never color. H2 `62px`, H5 `85px`, body `14px`, labels `12px`/500. Text defaults to `#000000` on white, `#FFFFFF` on dark.

3. **Spacing is base-4** — every margin / padding / gap is a multiple of `4px`. Section gaps `60–100px`. **Never use odd values like `13px` or `17px`** — the system has no place for them.

4. **Cards: white (`#FFFFFF`), `1px` border `#EFEFEF`, `8px` radius, `16–20px` padding, no shadow by default.** Dark-mode cards swap to `#1A1A1A` background with `#242424` border. Shadow only appears on hover.

5. **Glass containers** use `rgba(255,255,255,0.9)` background, `1px` border `rgba(255,255,255,0.2)`, optional `backdrop-filter: blur(8px)`. **These are the only place transparent fills appear** — everywhere else uses solid color.

If your draft has a rule like "all interactive elements require visible focus states for accessibility" — delete it. Not wrong, just not load-bearing for _this_ brand.

---

Rules

• Use exact values from capture/extracted/tokens.json. Cross-reference with screenshots when needed.
• Name colors and components descriptively — "Stripe Purple" not "Accent 1."
• When you can't extract exact values, estimate from visual inspection and note it.
• No "Assets" section — capture/extracted/asset-descriptions.md is the asset index.
• No "Motion" section — the storyboard specifies motion per-beat.
• No separate "Components" section — Quick Reference is where components live.
• No "Depth & Elevation" tables — shadow language is implied by the brand's mood (heavy shadows for premium, no shadows for flat/clean); sub-agents pick appropriate values without a table.

---

Quick User Check (before moving to Step 2)

30-second sanity check before Step 2:

"Here's what I extracted as [Brand Name]'s visual identity:

>

- Colors: [primary], [accent], [2-3 others with roles]

- Fonts: [headline font], [body font]

- Tone: [1 sentence on the brand feel]

>

Does this match how you want the video to feel? Any corrections or overrides before I start the storyboard?"

If the user has corrections ("use the blue, not the gray" / "ignore the dark mode" / "we just rebranded, use [these values] instead") — update DESIGN.md now. One minute here saves thirty minutes of rebuilding.

---

What makes a useful DESIGN.md

A sub-agent reading just your Quick Reference + Iteration Guide should be able to:

1. Pick the right color for any primary action, secondary action, body text, error state 2. Pick the right font/weight/size for any headline, body, metadata 3. Know which 2-3 rules they cannot break without losing the brand

That's the test. If they can answer those three questions from a 60–120 line doc, you've nailed it. If they need to read 400 lines of mood-board prose to find a color, you've buried the signal.