diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md
index 60f816e67..807e6f288 100644
--- a/skills/hyperframes/SKILL.md
+++ b/skills/hyperframes/SKILL.md
@@ -9,37 +9,58 @@ HTML is the source of truth for video. A composition is an HTML file with `data-
 
 ## 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?
+- **Priority** — what matters most? Motion quality? Content accuracy? Brand fidelity? Speed?
+- **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.
+
+### Step 1: Design system
+
+If `design.md` or `DESIGN.md` exists in the project, read it first (check both casings — they're different files on Linux). 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: "design.md 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 `design.md` exists, offer the user a choice:
+
+1. **User named a style or mood?** → Read [visual-styles.md](./visual-styles.md) for the 8 named presets. Pick the closest match.
+2. **Want to browse options visually?** → Run the design picker: read [references/design-picker.md](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.
+3. **Want to skip and go fast?** → Ask: mood, light or dark, any brand colors/fonts? Then pick a palette from [house-style.md](./house-style.md).
+
+**design.md defines the brand. It does not define video composition rules.** Those come from [references/video-composition.md](references/video-composition.md) and [house-style.md](./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 `design.md` and `house-style.md` and produces a consistent intermediate that every downstream agent reads the same way.
+
+Read [references/prompt-expansion.md](references/prompt-expansion.md) for the full process and output format.
+
+### Step 3: Plan
+
 Before writing HTML, think at a high level:
 
 1. **What** — what should the viewer experience? Identify the narrative arc, key moments, and emotional beats.
 2. **Structure** — how many compositions, which are sub-compositions vs inline, what tracks carry what (video, audio, overlays, captions).
-3. **Timing** — which clips drive the duration, where do transitions land, what's the pacing.
-4. **Layout** — build the end-state first. See "Layout Before Animation" below.
-5. **Animate** — then add motion using the rules below.
+3. **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](references/beat-direction.md) for rhythm templates.
+4. **Timing** — which clips drive the duration, where do transitions land, what's the pacing.
+5. **Layout** — build the end-state first. See "Layout Before Animation" below.
+6. **Animate** — then add motion using the rules below.
 
-For small edits (fix a color, adjust timing, add one element), skip straight to the rules.
+**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.
 
-### Visual Identity Gate
+For small edits (fix a color, adjust timing, add one element), skip straight to the rules.
 
 <HARD-GATE>
-Before writing ANY composition HTML, you MUST have a visual identity defined. Do NOT write compositions with default or generic colors.
-
-Check in this order:
-
-1. **DESIGN.md exists in the project?** → Read it. Use its exact colors, fonts, motion rules, and "What NOT to Do" constraints.
-2. **visual-style.md exists?** → Read it. Apply its `style_prompt_full` and structured fields. (Note: `visual-style.md` is a project-specific file. `visual-styles.md` is the style library with 8 named presets — different files.)
-3. **User named a style** (e.g., "Swiss Pulse", "dark and techy", "luxury brand")? → Read [visual-styles.md](./visual-styles.md) for the 8 named presets. Generate a minimal DESIGN.md with: `## Style Prompt` (one paragraph), `## Colors` (3-5 hex values with roles), `## Typography` (1-2 font families), `## What NOT to Do` (3-5 anti-patterns).
-4. **None of the above?** → Ask 3 questions before writing any HTML:
-   - What's the mood? (explosive / cinematic / fluid / technical / chaotic / warm)
-   - Light or dark canvas?
-   - Any specific brand colors, fonts, or visual references?
-     Then generate a minimal DESIGN.md from the answers.
-
-Every composition must trace its palette and typography back to a DESIGN.md, visual-style.md, or explicit user direction. If you're reaching for `#333`, `#3b82f6`, or `Roboto` — you skipped this step.
+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>
 
-For motion defaults, sizing, entrance patterns, and easing — follow [house-style.md](./house-style.md). The house style handles HOW things move. The DESIGN.md handles WHAT things look like.
-
 ## Layout Before Animation
 
 Position every element where it should be at its **most visible moment** — the frame where it's fully entered, correctly placed, and not yet exiting. Write this as static HTML+CSS first. No GSAP yet.
@@ -50,7 +71,7 @@ Position every element where it should be at its **most visible moment** — the
 
 1. **Identify the hero frame** for each scene — the moment when the most elements are simultaneously visible. This is the layout you build.
 2. **Write static CSS** for that frame. The `.scene-content` container MUST fill the full scene using `width: 100%; height: 100%; padding: Npx;` with `display: flex; flex-direction: column; gap: Npx; box-sizing: border-box`. Use padding to push content inward — NEVER `position: absolute; top: Npx` on a content container. Absolute-positioned content containers overflow when content is taller than the remaining space. Reserve `position: absolute` for decoratives only.
-3. **Add entrances with `gsap.from()`** — animate FROM offscreen/invisible TO the CSS position. The CSS position is the ground truth; the tween describes the journey to get there.
+3. **Add entrances with `gsap.from()`** — animate FROM offscreen/invisible TO the CSS position. The CSS position is the ground truth; the tween describes the journey to get there. (In sub-compositions loaded via `data-composition-src`, prefer `gsap.fromTo()` — see load-bearing GSAP rules in [references/motion-principles.md](references/motion-principles.md).)
 4. **Add exits with `gsap.to()`** — animate TO offscreen/invisible FROM the CSS position.
 
 ### Example
@@ -259,27 +280,34 @@ tl.from("#s2-heading", { x: -40, opacity: 0, duration: 0.6, ease: "expo.out" },
 - 60px+ headlines, 20px+ body, 16px+ data labels for rendered video
 - `font-variant-numeric: tabular-nums` on number columns
 
-When no `visual-style.md` or animation direction is provided, follow [house-style.md](./house-style.md) for aesthetic defaults.
+If no `design.md` exists, follow [house-style.md](./house-style.md) for aesthetic defaults.
 
 ## Typography and Assets
 
-- **Fonts:** Just write the `font-family` you want in CSS — the compiler embeds supported fonts automatically. If a font isn't supported, the compiler warns.
+- **Built-in fonts:** Write the `font-family` you want in CSS — the compiler embeds supported fonts automatically.
+- **Custom fonts:** If 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 the full composition first — match existing fonts, colors, animation patterns
+- **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 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)
-- [ ] Layout issues addressed (see Quality Checks below)
 - [ ] Animation choreography verified (see Quality Checks below)
 
 ## Quality Checks
@@ -317,6 +345,24 @@ If warnings appear:
 
 Use `--no-contrast` to skip if iterating rapidly and you'll check later.
 
+### Design Adherence
+
+If a `design.md` exists, verify the composition follows it after authoring. Read the HTML and check:
+
+1. **Colors** — every hex value in the composition appears in design.md's palette section (however the user labeled it: Colors, Palette, Theme, etc.). Flag any invented colors.
+2. **Typography** — font families and weights match design.md's type spec. No substitutions.
+3. **Corners** — border-radius values match the declared corner style, if specified.
+4. **Spacing** — padding and gap values fall within the declared density range, if specified.
+5. **Depth** — shadow usage matches the declared depth level, if specified (flat = none, subtle = light, layered = glows).
+6. **Avoidance rules** — if design.md 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.md` exists (house-style-only path), verify:
+
+1. **Palette consistency** — the same bg, fg, and accent colors are used across all scenes. No per-scene color invention.
+2. **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:
@@ -348,10 +394,15 @@ Skip on small edits (fixing a color, adjusting one duration). Run on new composi
 - **[references/tts.md](references/tts.md)** — Text-to-speech with Kokoro-82M. Voice selection, speed tuning, TTS+captions workflow. Read when generating narration or voiceover.
 - **[references/audio-reactive.md](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](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](references/video-composition.md)** — Video-medium rules: density, color presence, scale, frame composition, design.md as brand not layout. **Always read** — these override web instincts.
+- **[references/beat-direction.md](references/beat-direction.md)** — Beat planning: concept, mood, choreography verbs, rhythm templates, transition decisions, depth layers. **Always read for multi-scene compositions.**
 - **[references/typography.md](references/typography.md)** — Typography: font pairing, OpenType features, dark-background adjustments, font discovery script. **Always read** — every composition has text.
-- **[references/motion-principles.md](references/motion-principles.md)** — Motion design principles: easing as emotion, timing as weight, choreography as hierarchy, scene pacing, ambient motion, anti-patterns. Read when choreographing GSAP animations.
-- **[visual-styles.md](visual-styles.md)** — 8 named visual styles (Swiss Pulse, Velvet Standard, Deconstructed, Maximalist Type, Data Drift, Soft Signal, Folk Frequency, Shadow Cut) with hex palettes, GSAP easing signatures, and shader pairings. Read when user names a style or when generating DESIGN.md.
-- **[house-style.md](house-style.md)** — Default motion, sizing, and color palettes when no style is specified.
+- **[references/motion-principles.md](references/motion-principles.md)** — Motion design principles, image motion treatment, load-bearing GSAP rules. **Always read** — every composition has motion.
+- **[references/techniques.md](references/techniques.md)** — 11 visual techniques with code patterns: SVG drawing, Canvas 2D, CSS 3D, kinetic type, Lottie, video compositing, typing effect, variable fonts, MotionPath, velocity transitions, audio-reactive. Read when planning techniques per beat.
+- **[references/narration.md](references/narration.md)** — Pacing, tone, script structure, number pronunciation, opening line patterns. Read when the composition includes voiceover or TTS.
+- **[references/design-picker.md](references/design-picker.md)** — Create a design.md via visual picker. Read when no design.md exists and the user wants to create one.
+- **[visual-styles.md](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 design.md.
+- **[house-style.md](house-style.md)** — Default motion, sizing, and color palettes when no design.md is specified.
 - **[patterns.md](patterns.md)** — PiP, title cards, slide show patterns.
 - **[data-in-motion.md](data-in-motion.md)** — Data, stats, and infographic patterns.
 - **[references/transcript-guide.md](references/transcript-guide.md)** — Transcription commands, whisper models, external APIs, troubleshooting.
diff --git a/skills/hyperframes/house-style.md b/skills/hyperframes/house-style.md
index a5edc4b05..892c2ebed 100644
--- a/skills/hyperframes/house-style.md
+++ b/skills/hyperframes/house-style.md
@@ -1,6 +1,6 @@
 # House Style
 
-Creative direction for compositions when no `visual-style.md` is provided. These are starting points — override anything that doesn't serve the content.
+Creative direction for compositions when no `design.md` is provided. These are starting points — override anything that doesn't serve the content. When a `design.md` exists, its brand values take precedence; house-style fills gaps.
 
 ## Before Writing HTML
 
@@ -44,6 +44,8 @@ Ideas (mix and match, 2-5 per scene):
 
 All decoratives should have slow ambient GSAP animation — breathing, drift, pulse. Static decoratives feel dead.
 
+**Decorative count vs motion count.** The "2-5 per scene" count refers to decorative _elements_. If a project's `design.md` says "single ambient motion per scene", it means one looping motion applied to these decoratives (a shared breath/drift/pulse) — not one element total. A scene with 4 decoratives sharing one breathing motion is correct; a scene with 1 decorative is under-dressed.
+
 ## Motion
 
 See [references/motion-principles.md](references/motion-principles.md) for full rules. Quick: 0.3–0.6s, vary eases, combine transforms on entrances, overlap entries.
diff --git a/skills/hyperframes/references/beat-direction.md b/skills/hyperframes/references/beat-direction.md
new file mode 100644
index 000000000..04b0e12d1
--- /dev/null
+++ b/skills/hyperframes/references/beat-direction.md
@@ -0,0 +1,102 @@
+# Beat Direction
+
+How to plan and direct individual scenes (beats) in a multi-scene composition. Read before writing any multi-scene video.
+
+---
+
+## Per-Beat Direction
+
+Each beat is a WORLD, not a layout. Before writing CSS specs and GSAP instructions, describe what the viewer EXPERIENCES. The difference between a great storyboard and a mediocre one:
+
+**Mediocre:** "Dark navy background. '$1.9T' in white, 280px. Logo top-left. Wave image bottom-right."
+**Great:** "Camera is already mid-flight over a vast dark canvas. The gradient wave sweeps across the frame like aurora borealis — alive, shifting. '$1.9T' SLAMS into existence with such force the wave ripples in response. This isn't a slide — it's a moment."
+
+The first describes pixels. The second describes an experience. Write the second, then figure out the pixels.
+
+Each beat should have:
+
+### Concept
+
+The big idea for this beat in 2-3 sentences. What visual WORLD are we in? What metaphor drives it? What should the viewer FEEL? This is the most important part — everything else flows from it.
+
+### Mood direction
+
+Cultural and design references, not hex codes:
+
+- "Geometric, rhythmic, precise. Think Josef Albers or Bauhaus color studies."
+- "Warm workspace. Nice notebook energy, not technical blueprint."
+- "Cinematic title sequence. The kind of opening where you lean forward."
+
+### Animation choreography
+
+Specific motion verbs per element — not "it animates in" but HOW:
+
+| Energy        | Verbs                                         | Example                               |
+| ------------- | --------------------------------------------- | ------------------------------------- |
+| High impact   | SLAMS, CRASHES, PUNCHES, STAMPS, SHATTERS     | "$1.9T" SLAMS in from left at -5°     |
+| Medium energy | CASCADE, SLIDES, DROPS, FILLS, DRAWS          | Three cards CASCADE in staggered 0.3s |
+| Low energy    | types on, FLOATS, morphs, COUNTS UP, fades in | Counter COUNTS UP from 0 to 135K      |
+
+Every element gets a verb. If you can't name the verb, the element is not yet designed.
+
+### Transition
+
+How this beat hands off to the next. Specify the type and parameters.
+
+**When to pick which:**
+
+| Choose shader transition for                                                    | Choose CSS transition for                                                           | Choose hard cut for                                            |
+| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| Reveals, big reaction shots, product/logo unveils, energy shifts, "wow" moments | Continuous camera-motion beats where the scene feels like one move broken into cuts | Rapid-fire lists, percussive edits on the beat, comedic timing |
+| Any moment the music/VO punctuates with a downbeat or SFX hit                   | Beats that ease from one composition into the next with shared motion vocabulary    | Sequences of 3+ quick tempo-matched switches                   |
+| Brand moments where the transition itself _is_ the visual                       | Minimal/editorial pacing                                                            | Anytime a 0.3-0.8s transition would feel too slow              |
+
+Rule of thumb: if the beat is the _centerpiece_ of the video, shader-transition into it. If the beat is connective tissue, CSS-transition. A brand reel of 5-7 beats usually wants 1-2 shader transitions (the hero reveal + the CTA) and the rest CSS or hard cuts — too many shader transitions flatten their impact.
+
+**CSS transitions** (choose from `skills/hyperframes/references/transitions/catalog.md`):
+
+- Velocity-matched upward: exit `y:-150, blur:30px, 0.33s power2.in` → entry `y:150→0, blur:30px→0, 1.0s power2.out`
+- Whip pan: exit `x:-400, blur:24px, 0.3s power3.in` → entry `x:400→0, blur:24px→0, 0.3s power3.out`
+- Blur through: exit `blur:20px, 0.3s` → entry `blur:20px→0, 0.25s power3.out`
+- Zoom through: exit `scale:1→1.2, blur:20px, 0.2s power3.in` → entry `scale:0.75→1, blur:20px→0, 0.5s expo.out`
+- Hard cut / smash cut (for rapid-fire sequences)
+
+**Shader transitions** (choose from `packages/shader-transitions/README.md`):
+
+- Cross-Warp Morph (organic, versatile) — 0.5-0.8s, power2.inOut
+- Cinematic Zoom (professional momentum) — 0.4-0.6s, power2.inOut
+- Gravitational Lens (otherworldly) — 0.6-1.0s, power2.inOut
+- Glitch (aggressive, high energy) — 0.3-0.5s
+- See `packages/shader-transitions/README.md` for the full API, available shaders, and setup
+
+### Depth layers
+
+What's in foreground, midground, and background. Every beat should have at least 2 layers:
+
+- "BG: dark navy fill + subtle radial glow. MG: stat cards with drop shadow. FG: brand logo bottom-right."
+
+### SFX cues
+
+What sounds at what moment:
+
+- "On the capture pulse — a soft, warm analog shutter click."
+- "Left side carries a faint low drone. On fold: drone cuts. Silence. Then a single clean chime."
+
+---
+
+## Rhythm Planning
+
+Before writing HTML, declare your scene rhythm: 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 — before implementing.
+
+| Video type             | Typical rhythm pattern            |
+| ---------------------- | --------------------------------- |
+| Social ad (15s)        | hook-PUNCH-hold-CTA               |
+| Product demo (30-60s)  | slow-build-BUILD-PEAK-breathe-CTA |
+| Launch teaser (10-20s) | SLAM-proof-SLAM-hold              |
+| Brand reel (20-45s)    | drift-build-PEAK-drift-resolve    |
+
+---
+
+## Velocity-Matched Transitions
+
+Exit the outgoing beat with an accelerating ease (power2.in or power3.in) plus a blur ramp. Enter the incoming beat with a decelerating ease (power2.out or power3.out) plus blur clear. The fastest point of both easing curves meets at the cut — the viewer perceives continuous camera motion, not two discrete animations. Match exit velocity to entry velocity within ~5% tolerance.
diff --git a/skills/hyperframes/references/design-picker.md b/skills/hyperframes/references/design-picker.md
new file mode 100644
index 000000000..261566623
--- /dev/null
+++ b/skills/hyperframes/references/design-picker.md
@@ -0,0 +1,117 @@
+# Design Picker
+
+Two-phase visual picker: mood boards first (pick a complete direction), then fine-tune individual categories.
+
+## Prerequisites
+
+Read these before generating options — they define the rules your options must follow:
+
+- [typography.md](typography.md)
+- [../house-style.md](../house-style.md)
+- [video-composition.md](video-composition.md)
+- [../visual-styles.md](../visual-styles.md)
+- [beat-direction.md](beat-direction.md)
+
+## Building the picker
+
+1. Generate options **deeply contextual to the user's prompt**. Every category — not just architectures — must reflect the specific product, brand, audience, and mood. Generic options that could appear on any picker are a failure.
+
+   **Mood boards** — as many as the creative space warrants (4-8). Every board must tell a different STORY about the brand, not just reshuffle the same elements. Ask: "what are the genuinely different ways to position this product?" A cat food brand might be: playful chaos, premium positioning, comfort/cozy, social-native, flavor showcase, humor-led, sensory/appetizing. Each is a different narrative, not a different font on the same layout.
+
+   **Architectures** — one per mood board minimum, each visually distinct. Use `{{prompt_headline}}` and `{{prompt_sub}}` tokens. If the user provided media assets, use them as background images (use `url(path)` without quotes — single quotes inside `style='...'` break the attribute).
+
+   **Palettes** (5-6) — named after the brand's world, not generic moods. The palette names and colors should feel like they belong to THIS specific product. Always mix dark + light + tinted. **Every palette must be visually distinct at swatch size.** If two palettes share the same background lightness AND a similar accent hue, cut one. Test: would a user see the difference in a 14px swatch chip? If not, they're duplicates.
+
+   **Type pairings** (5-6) — **RUN the font discovery script from typography.md BEFORE generating pairings.** This is not optional. Download Google Fonts metadata, run the script, and pick from its output. You will otherwise reach for the same 8 fonts every time (Bricolage Grotesque, Instrument Serif, Fraunces, Archivo Black, DM Serif Display, Space Grotesk, Fredoka) — that's your training data default, not a contextual choice. Match the brand's energy and audience. Cross-category per typography.md (never two sans-serifs).
+
+2. `mkdir -p .hyperframes` then copy [../templates/design-picker.html](../templates/design-picker.html) to `.hyperframes/pick-design.html`.
+3. Replace these placeholders using Python (don't hand-escape quotes in sed):
+   - `__ARCHITECTURES_JSON__` — array of architecture objects
+   - `__PALETTES_JSON__` — array of palette objects
+   - `__TYPEPAIRS_JSON__` — array of type pairing objects
+   - `__MOODBOARDS_JSON__` — array of mood board objects (see format below)
+   - `__PROMPT_JSON__` — object with prompt context (see format below)
+
+### Architecture data format
+
+Each architecture object must include a `preview_html` field — the HTML that renders in the preview panel. Use token placeholders that the template replaces at runtime: `{{bg}}`, `{{fg}}`, `{{ac}}`, `{{mt}}`, `{{hf}}`, `{{hw}}`, `{{bf}}`, `{{bw}}`, `{{cr}}` (corner radius), `{{pad}}`, `{{gap}}`, `{{shadow}}`, `{{g}}` (grid line color), `{{fg3}}`/`{{fg6}}`/`{{fg8}}`/`{{fg15}}` (fg at opacity), `{{ac3}}`/`{{ac5}}`/`{{ac25}}` (accent at opacity).
+
+**Every token must be used.** Apply `{{cr}}` to all cards, buttons, and containers. Apply `{{shadow}}` to elevated elements (cards, buttons, code blocks). Apply `{{pad}}` and `{{gap}}` to control spacing. If a token isn't used in the preview_html, that option will have no visible effect.
+
+**Density matters.** Each architecture preview must include 15+ distinct elements to give the user a real sense of the layout. Include: headline, subhead, body paragraph, label/overline, stat with number, secondary stat, quote/testimonial, attribution, card with title+body, second card (different treatment), code/command block, primary button, secondary button, list or tags, accent divider/rule, and a data element (table row, progress bar, or chart).
+
+Optionally include `components` (component styling rules) and `dos` (do's and don'ts) as strings — these appear in the generated design.md.
+
+**Layout constraint:** All preview HTML must use percentage widths or `max-width: 100%`. Use `flex-wrap: wrap` on all flex rows. Absolute-positioned decoratives must stay within a parent with `overflow: hidden`.
+
+**Security:** Architecture `preview_html` must not contain `<script>` tags, event handlers (`onclick`, `onerror`, etc.), or `javascript:` URLs. It is injected via `innerHTML`.
+
+**Image URLs:** When using background images in `preview_html`, use `url(path/to/image.jpg)` WITHOUT quotes around the path. Single quotes like `url('path.jpg')` break because `preview_html` is inside a `style='...'` attribute — the inner single quotes terminate the outer attribute.
+
+**Palette variety:** Always include a mix of light, dark, and tinted backgrounds across the 6 palettes — even for calm/wellness prompts.
+
+### Example architecture object
+
+```json
+{
+  "name": "Editorial Stack",
+  "description": "Vertical rhythm with large type, pull quotes, and data callouts",
+  "tag": "editorial / longform / narrative",
+  "mood": "Confident, unhurried, typographically driven",
+  "preview_html": "<div style='background:{{bg}};color:{{fg}};padding:{{pad}};min-height:100vh;font-family:\"{{bf}}\",sans-serif;font-weight:{{bw}};'><div style='max-width:100%;display:flex;flex-direction:column;gap:{{gap}};'><div style='font-size:10px;text-transform:uppercase;letter-spacing:0.12em;color:{{mt}};'>Overline Label</div><div style='font-family:\"{{hf}}\",serif;font-weight:{{hw}};font-size:48px;line-height:1.1;letter-spacing:-0.02em;'>The Headline Goes Here</div><div style='font-size:20px;color:{{mt}};max-width:70%;line-height:1.5;'>Subheading text that introduces the narrative arc of this composition with enough words to fill two lines.</div><div style='font-size:15px;line-height:1.7;color:{{fg}};max-width:65%;'>Body paragraph with real sentences. The quick brown fox jumps over the lazy dog. This gives a sense of text density and reading rhythm at the chosen type size.</div><div style='display:flex;gap:{{gap}};flex-wrap:wrap;'><div style='background:{{fg6}};border-radius:{{cr}};padding:{{pad}};flex:1;min-width:200px;box-shadow:{{shadow}};'><div style='font-size:36px;font-family:\"{{hf}}\",serif;font-weight:{{hw}};color:{{ac}};'>2.4M</div><div style='font-size:12px;color:{{mt}};margin-top:4px;'>Primary Stat</div></div><div style='background:{{fg6}};border-radius:{{cr}};padding:{{pad}};flex:1;min-width:200px;box-shadow:{{shadow}};'><div style='font-size:36px;font-family:\"{{hf}}\",serif;font-weight:{{hw}};color:{{fg}};'>87%</div><div style='font-size:12px;color:{{mt}};margin-top:4px;'>Secondary Stat</div></div></div><div style='border-left:3px solid {{ac}};padding:12px {{pad}};background:{{ac3}};border-radius:0 {{cr}} {{cr}} 0;'><div style='font-size:18px;font-style:italic;color:{{fg}};line-height:1.5;'>\"A pull quote that captures the key insight of the piece.\"</div><div style='font-size:12px;color:{{mt}};margin-top:8px;'>— Attribution Name</div></div><div style='background:{{fg3}};border-radius:{{cr}};padding:{{pad}};box-shadow:{{shadow}};'><div style='font-size:14px;font-weight:{{hw}};margin-bottom:8px;'>Card Title</div><div style='font-size:13px;color:{{mt}};line-height:1.5;'>Card body text with a different treatment than the main content area.</div></div><div style='background:{{ac5}};border:1px solid {{ac25}};border-radius:{{cr}};padding:{{pad}};box-shadow:{{shadow}};'><div style='font-size:14px;font-weight:{{hw}};color:{{ac}};margin-bottom:8px;'>Accent Card</div><div style='font-size:13px;color:{{fg}};line-height:1.5;'>Second card with a tinted accent treatment for variety.</div></div><div style='font-family:monospace;font-size:13px;background:{{fg8}};border-radius:{{cr}};padding:{{pad}};color:{{fg15}};box-shadow:{{shadow}};'>$ hyperframes render --output video.mp4</div><div style='display:flex;gap:12px;flex-wrap:wrap;'><button style='background:{{ac}};color:{{bg}};border:none;padding:10px 24px;border-radius:{{cr}};font-size:14px;font-weight:600;box-shadow:{{shadow}};cursor:pointer;'>Primary Action</button><button style='background:transparent;color:{{fg}};border:1px solid {{fg15}};padding:10px 24px;border-radius:{{cr}};font-size:14px;cursor:pointer;'>Secondary</button></div><div style='display:flex;gap:8px;flex-wrap:wrap;'><span style='background:{{fg6}};border-radius:100px;padding:4px 12px;font-size:11px;color:{{mt}};'>Tag One</span><span style='background:{{fg6}};border-radius:100px;padding:4px 12px;font-size:11px;color:{{mt}};'>Tag Two</span><span style='background:{{ac5}};border-radius:100px;padding:4px 12px;font-size:11px;color:{{ac}};'>Accent Tag</span></div><div style='height:1px;background:linear-gradient(to right,{{ac25}},{{fg6}},{{ac25}});'></div><div style='display:flex;justify-content:space-between;font-size:12px;color:{{mt}};border-bottom:1px solid {{g}};padding:8px 0;'><span>Data row label</span><span style='color:{{fg}};font-weight:600;'>1,234</span></div></div></div>"
+}
+```
+
+### Mood board data format
+
+Each mood board pre-selects one option from each category. The user picks a mood board in Phase 1, then fine-tunes in Phase 2 with those selections pre-filled.
+
+```json
+{
+  "name": "Terminal Precision",
+  "description": "Code-forward, data-dense, CLI energy. Dark canvas, monospace body, sharp corners.",
+  "theme": "dark",
+  "arch_index": 0,
+  "palette_index": 0,
+  "type_index": 0,
+  "corners_index": 0,
+  "density_index": 0,
+  "depth_index": 1,
+  "easing_index": 0,
+  "corners": "0px",
+  "padding": "12px",
+  "gap": "8px",
+  "shadow": "0 2px 16px rgba(0,230,255,0.15)"
+}
+```
+
+Indices reference into the ARCHITECTURES, PALETTES, and TYPEPAIRS arrays. The template renders a mini preview of each mood board using its architecture's `preview_html` with the mood board's palette/type applied.
+
+### Prompt context data format
+
+```json
+{
+  "title": "AI Coding Assistant",
+  "headline": "Your Code, Understood.",
+  "subline": "An AI coding assistant that reads your entire codebase.",
+  "section_desc": "Layout options for your product launch"
+}
+```
+
+`title` appears in the Phase 1 header. `headline` and `subline` replace `{{prompt_headline}}` and `{{prompt_sub}}` in architecture preview_html so previews show real content.
+
+### Content tokens in preview_html
+
+In addition to the standard design tokens (`{{bg}}`, `{{fg}}`, `{{ac}}`, etc.), architecture `preview_html` can use:
+
+- `{{prompt_headline}}` — the user's actual headline text
+- `{{prompt_sub}}` — the user's actual subline text
+
+This makes previews contextual — the user sees their own content styled, not generic placeholders.
+
+## Serving and user selection
+
+4. Serve the file: `cd <project-dir> && python3 -m http.server 8723 &` (use port 8723 or any unused port above 8000; if the curl check fails, try the next port). Verify: `curl -s -o /dev/null -w "%{http_code}" http://localhost:8723/.hyperframes/pick-design.html` — only share the link if it returns 200. Do NOT use `npx hyperframes preview` for the picker — it blocks. Only start the HTTP server from the main conversation thread. If you are running as a dispatched task or subagent, return the file path and let the caller serve it.
+5. Once the user picks, tell them: "Copy the design.md from the picker and paste it here." The user pastes the markdown back into the conversation. Save it verbatim to `design.md` in the project root — it's already in spec format (YAML frontmatter + prose sections). After the user pastes, kill the background server: `kill %1` or `kill $(lsof -ti:8723)`. Then proceed with construction.
+
+The picker outputs a [google-labs-code/design.md](https://github.com/google-labs-code/design.md) spec-compliant file: YAML frontmatter with `colors`, `typography`, `rounded`, and `spacing` tokens, followed by `## Overview`, `## Colors`, `## Typography`, `## Layout`, `## Elevation`, `## Components`, and `## Do's and Don'ts` prose sections.
diff --git a/skills/hyperframes/references/motion-principles.md b/skills/hyperframes/references/motion-principles.md
index f02a3bd51..011d59883 100644
--- a/skills/hyperframes/references/motion-principles.md
+++ b/skills/hyperframes/references/motion-principles.md
@@ -67,3 +67,76 @@ You build for the web. Video frames are not pages.
 - **Anchor to edges.** Pin content to left/top or right/bottom. Centered-and-floating is a web pattern.
 - **Split frames.** Data panel on the left, content on the right. Top bar with metadata, full-width below. Zone-based layouts, not centered stacks.
 - **Use structural elements.** Rules, dividers, border panels. They create paths for the eye and animate well (scaleX from 0).
+
+## Image Motion Treatment
+
+Never embed a raw flat image. Every image must have motion treatment:
+
+- **Perspective tilt**: use `gsap.set(el, { transformPerspective: 1200, rotationY: -8 })` + `box-shadow` — creates depth. Do NOT use CSS `transform: perspective(...)` as GSAP will overwrite it.
+- **Slow zoom (Ken Burns)**: GSAP `scale: 1` → `1.04` over beat duration — makes photos cinematic
+- **Device frame**: Wrap in a laptop/phone shape using CSS `border-radius` and `box-shadow`
+- **Floating UI**: Extract a key element and animate it at a different z-depth for parallax
+- **Scroll reveal**: Clip the image to a viewport window and animate `y` position
+
+## Load-Bearing GSAP Rules
+
+Rules below came out of two independent website-to-hyperframes builds (2026-04-20) where compositions lint-clean and still ship broken — elements that never appear, ambient motion that doesn't scrub, entrance tweens that silently kill their target. The linter cannot catch these; the rules must be followed by the author.
+
+- **No iframes for captured content.** Iframes do not seek deterministically with the timeline — the capture engine cannot scrub inside them, so they appear frozen (or blank) in the rendered output. If the source you're stylizing is a live web app, use the screenshots from `capture/` as stacked panels or layered images, not live embeds.
+
+- **Never stack two transform tweens on the same element.** A common failure: a `y` entrance plus a `scale` Ken Burns on the same `<img>`. The second tween's `immediateRender: true` writes the element's initial state at construction time, overwriting whatever the first tween set — leaving the element invisible or offscreen with no lint warning. A secondary mechanism: `tl.from()` resets to its declared "from" state when the playhead is seeked past the timeline's end, so an element that looked correct in linear playback vanishes in the capture engine's non-linear seek. Fix one of two ways:
+
+  ```html
+  <!-- BAD: two transforms on one element -->
+  <img class="hero" src="..." />
+  <script>
+    tl.from(".hero", { y: 50, opacity: 0, duration: 0.6 }, 0);
+    tl.to(".hero", { scale: 1.04, duration: beat }, 0); // kills the entrance
+  </script>
+
+  <!-- GOOD option A: combine into one tween -->
+  <script>
+    tl.fromTo(
+      ".hero",
+      { y: 50, opacity: 0, scale: 1.0 },
+      { y: 0, opacity: 1, scale: 1.04, duration: beat, ease: "none" },
+      0,
+    );
+  </script>
+
+  <!-- GOOD option B: split across parent + child -->
+  <div class="hero-wrap"><img class="hero" src="..." /></div>
+  <script>
+    tl.from(".hero-wrap", { y: 50, opacity: 0, duration: 0.6 }, 0); // entrance on parent
+    tl.to(".hero", { scale: 1.04, duration: beat }, 0); // Ken Burns on child
+  </script>
+  ```
+
+- **Prefer `tl.fromTo()` over `tl.from()` inside `.clip` scenes.** `gsap.from()` sets `immediateRender: true` by default, which writes the "from" state at timeline construction — before the `.clip` scene's `data-start` is active. Elements can flash visible, start from the wrong position, or skip their entrance entirely when the scene is seeked non-linearly (which the capture engine does). Explicit `fromTo` makes the state at every timeline position deterministic:
+
+  ```js
+  // BRITTLE: immediateRender interacts badly with scene boundaries
+  tl.from(el, { opacity: 0, y: 50, duration: 0.6 }, t);
+
+  // DETERMINISTIC: state is defined at both ends, no immediateRender surprise
+  tl.fromTo(el, { opacity: 0, y: 50 }, { opacity: 1, y: 0, duration: 0.6 }, t);
+  ```
+
+- **Ambient pulses must attach to the seekable `tl`, never bare `gsap.to()`.** Auras, shimmers, gentle float loops, logo breathing — all of these must be added to the scene's timeline, not fired standalone. Standalone tweens run on wallclock time and do not scrub with the capture engine, so the effect is absent in the rendered video even though it looks correct in the studio preview:
+
+  ```js
+  // BAD: lives outside the timeline, never renders in capture
+  gsap.to(".aura", { scale: 1.08, yoyo: true, repeat: 5, duration: 1.2 });
+
+  // GOOD: seekable, deterministic, renders
+  tl.to(".aura", { scale: 1.08, yoyo: true, repeat: 5, duration: 1.2 }, 0);
+  ```
+
+- **Hard-kill every scene boundary, not just captions.** The caption hard-kill rule above generalizes: any element whose visibility changes at a beat boundary needs a deterministic `tl.set()` kill after its fade, because later tweens on the same element (or `immediateRender` from a sibling tween) can resurrect it. Apply to every element with an exit animation:
+
+  ```js
+  tl.to(el, { opacity: 0, duration: 0.3 }, beatEnd);
+  tl.set(el, { opacity: 0, visibility: "hidden" }, beatEnd + 0.3); // deterministic kill
+  ```
+
+These are the exact rules with the exact code examples — don't summarize or shorten them. They exist because compositions that lint clean still ship broken without them.
diff --git a/skills/hyperframes/references/narration.md b/skills/hyperframes/references/narration.md
new file mode 100644
index 000000000..c28fff2ee
--- /dev/null
+++ b/skills/hyperframes/references/narration.md
@@ -0,0 +1,92 @@
+# Narration & Script
+
+How to write narration scripts for video compositions. Read when the composition includes voiceover or TTS.
+
+## Pacing
+
+- **2.5 words per second** is natural speaking pace
+- 15s = ~37 words. 30s = ~75 words. 60s = ~150 words
+- Leave room for pauses. Silence between sentences is a feature, not dead air
+- The script should feel SHORTER than the video — visual breathing room matters
+
+## Tone
+
+Write like a person, not a brochure:
+
+- Use contractions: "it's", "you'll", "that's", "we've"
+- Vary sentence length — short punchy phrases mixed with longer flowing ones
+- Read it out loud. If it sounds robotic, rewrite it
+- Avoid jargon unless the audience expects it
+
+## Number Pronunciation
+
+Write what you want the voice to say. TTS reads literally.
+
+| In the product | Write in script as                |
+| -------------- | --------------------------------- |
+| 135+           | more than one hundred thirty five |
+| $1.9T          | nearly two trillion dollars       |
+| 99.999%        | ninety nine point nine percent    |
+| 200M+          | over two hundred million          |
+| 10x            | ten times                         |
+| API            | A P I                             |
+| stripe.com     | stripe dot com                    |
+
+The visual can show the exact figure while the voice rounds it.
+
+## Structure
+
+For product videos:
+
+1. **Hook** — what's surprising or impressive about this product? A bold claim, a provocative question, a contrast, or a striking number. This is the opening line. **Vary the hook type** — don't default to a stat every time.
+2. **Story** — what does the product do? Who uses it? Keep it concrete.
+3. **Proof** — stats, customer names, social proof. Real numbers from the product.
+4. **CTA** — what should the viewer do? "Start building at stripe dot com."
+
+Not every video needs all four. A 15-second social ad might be Hook + Proof + CTA. A 60-second product tour uses all four with more Story.
+
+## The Opening Line
+
+The most important sentence in the video. It must create tension, curiosity, or surprise in the first 3 seconds.
+
+Patterns that work:
+
+- **A bold claim**: "The financial infrastructure that powers the internet economy."
+- **A question that provokes**: "What if your database could think?"
+- **A contrast**: "Your AI agent already knows how to make videos. It just needs the right format."
+- **A number that shocks**: "Nearly two trillion dollars." (Use sparingly — not every video should open with a stat.)
+
+If the opening is generic ("Welcome to Stripe" / "Introducing our product"), start over.
+
+## Example
+
+From a 62-second product launch video (team reference):
+
+```
+Your AI agent already knows how to make videos.
+It just needs the right format.
+
+This is Hyperframes. An open source framework. HTML in, video out.
+
+A div is a keyframe. Data attributes are your timeline.
+CSS is your look. G-Sap is your animation engine.
+
+Anything a browser can render can be a frame in your video.
+
+CSS animations. G-Sap. Lottie. Shaders. Three.js.
+
+Drop in music, sound effects, footage — it all composes together.
+
+No new framework for the agent to learn.
+Just HTML.
+
+The agent writes it. The renderer captures every frame as MP4.
+It's deterministic. Identical outputs, every time.
+
+Give your agent the CLI. Tell it what to make.
+Watch it build.
+
+Hyperframes. Go make something.
+```
+
+Note: ~140 words for 62 seconds — that's 2.3 words/sec, leaving room for pauses and visual breathing.
diff --git a/skills/hyperframes/references/prompt-expansion.md b/skills/hyperframes/references/prompt-expansion.md
new file mode 100644
index 000000000..ab504eee1
--- /dev/null
+++ b/skills/hyperframes/references/prompt-expansion.md
@@ -0,0 +1,68 @@
+# Prompt Expansion
+
+Run on every composition. Expansion is not about lengthening a short prompt — it's about grounding the user's intent against `design.md` and `house-style.md` and producing a consistent intermediate that every downstream agent reads the same way.
+
+Runs AFTER design direction is established (Step 1). The expansion consumes design.md (if present) and produces output that cites its exact values.
+
+## Prerequisites
+
+Read before generating:
+
+- `design.md` (if it exists) — extract brand colors, fonts, mood, and constraints. The expansion cites these exact values (hex codes, font names); it does not invent new ones.
+- [beat-direction.md](beat-direction.md) — per-beat planning format (concept, mood, choreography verbs, transitions, depth layers, rhythm). The expansion outputs each scene using this format.
+- [video-composition.md](video-composition.md) — video-medium rules for density, scale, and color presence. The expansion applies these automatically.
+- [../house-style.md](../house-style.md) — its rules for Background Layer (2-5 decoratives), Color, Motion, Typography apply to every scene. The expansion writes output that conforms to them.
+
+If `design.md` doesn't exist yet, run Step 1 (Design system) first. Expansion without a design context produces generic scene breakdowns that later agents ignore.
+
+## Why always run it
+
+**The expansion is never pass-through.** Every user prompt — no matter how detailed — is a _seed_. The expansion's job is to enrich it into a fully-realized per-scene production spec that the scene subagents can build from directly.
+
+Even a detailed 7-scene brief lacks things only the expansion adds:
+
+- **Atmosphere layers per scene** (required 2–5 from house-style: radial glows, ghost type, hairline rules, grain, thematic decoratives) — the user's prompt almost never lists these; expansion adds them.
+- **Secondary motion for every decorative** — breath, drift, pulse, orbit. A decorative without ambient motion feels dead.
+- **Micro-details that make a scene feel real** — registration marks, tick indicators, monospace coord labels, typographic accents, code snippets in the background, grid patterns. Things the user didn't think to request.
+- **Transition choreography at the object level** — not "crossfade" but "X expands outward and becomes Y". Specific duration, ease, and morph source/target.
+- **Pacing beats within each scene** — where tension builds, where a hold lets the viewer breathe, where the accent word lands.
+- **Exact hex values, typography parameters, ease choices** from design.md — no vagueness left for the scene subagent to guess.
+
+Expansion's job on a detailed prompt is not to summarize or pass through — it's to **take what the user wrote and make it richer**. The user's content stays; the atmosphere, ambient motion, and micro-details are added on top. That's what makes the difference between a scene that matches the brief and a scene that feels alive.
+
+The quality gap between a single-pass composition and a multi-scene-pipeline composition comes from this step. Expansion front-loads the richness so every scene subagent builds from a rich brief, not a terse one.
+
+**Do not skip. Do not pass through.** Single-scene compositions and trivial edits are the only exceptions.
+
+## What to generate
+
+Expand into a full production prompt with these sections:
+
+1. **Title + style block** — cite design.md's exact hex values, font names, and mood. Do NOT invent a palette — quote what the design provides.
+
+2. **Rhythm declaration** — name the scene rhythm before detailing any scene. Example: `hook-PUNCH-breathe-CTA` or `slow-build-BUILD-PEAK-breathe-CTA`. See [beat-direction.md](beat-direction.md) for rhythm templates by video type.
+
+3. **Global rules** — parallax layers, micro-motion requirements, transition style, primary + accent transitions. Match energy to mood (calm → slow eases, high → snappy eases).
+
+4. **Per-scene beats** — for each scene, use the beat-direction format:
+   - **Concept** — the big idea in 2-3 sentences. What visual WORLD? What metaphor? What should the viewer FEEL?
+   - **Mood direction** — cultural/design references, not hex codes. ("Bauhaus color studies", "cinematic title sequence", "editorial calm")
+   - **Depth layers** — BG (2-5 decoratives with ambient motion), MG (content), FG (accents, structural elements, micro-details). 8-10 total elements per scene per video-composition.md.
+   - **Animation choreography** — specific verbs per element. High: SLAMS, CRASHES. Medium: CASCADE, SLIDES. Low: floats, types on, counts up. Every element gets a verb. If you can't name the verb, the element is not yet designed.
+   - **Transition out** — shader or CSS, with specific type and parameters. Not "crossfade" but "blur crossfade, 0.4s, power2.inOut."
+
+5. **Recurring motifs** — visual threads across scenes from the brand palette.
+
+6. **Negative prompt** — what to avoid, informed by design.md's constraints if present.
+
+## Output
+
+Write the expanded prompt to `.hyperframes/expanded-prompt.md` in the project directory. Do NOT dump it into the chat — it will be hundreds of lines.
+
+Tell the user:
+
+> "I've expanded your prompt into a full production breakdown. Review it here: `.hyperframes/expanded-prompt.md`
+>
+> It has [N] scenes across [duration] seconds with specific visual elements, transitions, and pacing. Edit anything you want, then let me know when you're ready to proceed."
+
+Only move to construction after the user approves or says to continue.
diff --git a/skills/website-to-hyperframes/references/techniques.md b/skills/hyperframes/references/techniques.md
similarity index 100%
rename from skills/website-to-hyperframes/references/techniques.md
rename to skills/hyperframes/references/techniques.md
diff --git a/skills/hyperframes/references/video-composition.md b/skills/hyperframes/references/video-composition.md
new file mode 100644
index 000000000..e0758eba0
--- /dev/null
+++ b/skills/hyperframes/references/video-composition.md
@@ -0,0 +1,62 @@
+# Video Composition
+
+Video frames are not web pages. These rules apply to every composition regardless of brand, style, or design.md.
+
+## design.md Is Brand, Not Layout
+
+design.md defines what the brand looks like: colors, fonts, personality, constraints. It does NOT define how to compose a video frame. Use brand colors at video-appropriate intensity — not at web-UI opacity.
+
+**Strict from design.md:** hex values (including background color), font families, weight relationships, Do's and Don'ts. If the user chose a light canvas, use a light canvas. If they chose dark, use dark. Do not override their palette.
+
+**Adapt for video:** type sizes, spacing, decorative opacity, border weight, component treatments. A web UI card at `border: 1px solid #e2e3e6` with `box-shadow: 0 2px 4px rgba(0,0,0,0.06)` is invisible on video. The brand color is sacred; the application is yours.
+
+## Density
+
+A beat with 3 elements looks empty. A beat with 8-10 feels alive.
+
+Every scene needs:
+
+- **Background texture** — radial glow, oversized ghost type, color panel, grain, grid. Never solid flat color.
+- **Midground content** — the actual message. Cards, stats, code blocks, images.
+- **Foreground accents** — dividers, labels, data bars, registration marks, monospace metadata. The details that make it feel produced, not generated.
+
+Aim for 8-10 visual elements per scene. Two of those should be decorative elements the user didn't ask for — you add them because empty frames look broken.
+
+## Color Presence
+
+Muted is fine. Flat is not. Every scene should have at least one color that pulls the eye.
+
+- Brand accent should be VISIBLE — not a 5% opacity glow lost in compression. 15-25% for atmospheric, full saturation for focal elements.
+- **Light canvases work differently than dark.** On dark: accent glows pop naturally. On light: use bolder borders (2px+ solid), stronger structural elements (rules, dividers), and full-saturation accent hits. Light backgrounds need texture (subtle grain, patterns) to avoid the "blank slide" feel. Don't switch to dark — make light cinematic.
+- Tint neutrals toward the brand hue. Dead gray reads as undesigned.
+
+## Scale
+
+Web sizes are invisible on video. Everything scales up.
+
+| Element            | Web     | Video    |
+| ------------------ | ------- | -------- |
+| Headlines          | 32-48px | 64-120px |
+| Body text          | 14-16px | 28-42px  |
+| Labels             | 12px    | 18-24px  |
+| Decorative opacity | 3-8%    | 12-25%   |
+| Borders            | 1px     | 2-4px    |
+| Padding            | 16-32px | 60-140px |
+
+If you're writing a font-size under 24px in a video composition, justify it. If you're writing decorative opacity under 10%, it's invisible.
+
+## Motion Intensity
+
+Subtle reads as static at 30fps. Err toward more movement than feels safe.
+
+- Every decorative element should have ambient motion: breathe, drift, pulse, orbit. Static decoratives feel dead.
+- Vary motion per scene — don't repeat the same ambient pattern.
+- Scene entrances should use 3+ different eases and directions. If every element enters from `y: 30, opacity: 0`, the scene has no choreography.
+
+## Frame Composition
+
+- **Two focal points minimum.** The eye needs somewhere to travel.
+- **Fill the frame.** Hero text: 60-80% of frame width.
+- **Anchor to edges.** Pin content to left/top or right/bottom. Centered-and-floating is a web layout pattern.
+- **Split frames.** Data panel left, content right. Top bar with metadata, full-width below. Zone-based layouts over centered stacks.
+- **Structural elements.** Rules, dividers, border panels. They create visual paths and animate well (`scaleX: 0` → `1`).
diff --git a/skills/hyperframes/templates/design-picker.html b/skills/hyperframes/templates/design-picker.html
new file mode 100644
index 000000000..6cb6f0878
--- /dev/null
+++ b/skills/hyperframes/templates/design-picker.html
@@ -0,0 +1,1432 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Design your visual direction</title>
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <style>
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+      body {
+        font-family:
+          system-ui,
+          -apple-system,
+          sans-serif;
+        background: #0e0e0e;
+        color: #eee;
+        height: 100vh;
+        overflow: hidden;
+        display: flex;
+        flex-direction: column;
+        font-size: 13px;
+        line-height: 1.4;
+        -webkit-font-smoothing: antialiased;
+      }
+
+      /* ── Phase bar ── */
+      .phase-bar {
+        display: flex;
+        border-bottom: 1px solid #1a1a1a;
+        padding: 0 20px;
+        flex-shrink: 0;
+        background: #111;
+      }
+      .phase-tab {
+        padding: 12px 16px;
+        font-size: 12px;
+        font-weight: 600;
+        color: #555;
+        cursor: pointer;
+        border-bottom: 2px solid transparent;
+        transition: all 0.15s;
+        letter-spacing: 0.02em;
+      }
+      .phase-tab.active {
+        color: #fff;
+        border-bottom-color: #fff;
+      }
+      .phase-tab.disabled {
+        opacity: 0.25;
+        pointer-events: none;
+      }
+
+      /* ── Phases ── */
+      .phase {
+        display: none;
+        flex: 1;
+        overflow: hidden;
+      }
+      .phase.active {
+        display: flex;
+      }
+
+      /* ── Phase 1: Mood boards ── */
+      .mood-grid {
+        display: grid;
+        grid-template-columns: repeat(auto-fill, minmax(380px, 1fr));
+        gap: 16px;
+        padding: 20px;
+        overflow-y: auto;
+        flex: 1;
+        align-content: start;
+      }
+      .mood-card {
+        border: 1px solid #1e1e1e;
+        border-radius: 12px;
+        overflow: hidden;
+        cursor: pointer;
+        transition:
+          border-color 0.15s,
+          transform 0.15s,
+          box-shadow 0.15s;
+        background: #141414;
+        display: flex;
+        flex-direction: column;
+      }
+      .mood-card:hover {
+        border-color: #333;
+        transform: translateY(-1px);
+        box-shadow: 0 4px 24px rgba(0, 0, 0, 0.3);
+      }
+      .mood-card.selected {
+        border-color: #fff;
+      }
+      .mood-preview {
+        height: 500px;
+        overflow: hidden;
+        position: relative;
+        background: #0a0a0a;
+      }
+      .mood-preview > div {
+        transform-origin: top left;
+      }
+      .mood-info {
+        padding: 14px 16px;
+      }
+      .mood-name {
+        font-size: 14px;
+        font-weight: 600;
+        margin-bottom: 3px;
+      }
+      .mood-desc {
+        font-size: 11px;
+        color: #666;
+        line-height: 1.4;
+        display: -webkit-box;
+        -webkit-line-clamp: 2;
+        -webkit-box-orient: vertical;
+        overflow: hidden;
+      }
+      .mood-tokens {
+        display: flex;
+        gap: 4px;
+        margin-top: 8px;
+        flex-wrap: wrap;
+      }
+      .mood-token {
+        font-size: 9px;
+        color: #555;
+        background: #1a1a1a;
+        padding: 2px 7px;
+        border-radius: 3px;
+        letter-spacing: 0.02em;
+      }
+
+      .mood-header {
+        padding: 20px 20px 0;
+        flex-shrink: 0;
+      }
+      .mood-header h2 {
+        font-size: 16px;
+        font-weight: 600;
+        margin-bottom: 2px;
+      }
+      .mood-header p {
+        font-size: 12px;
+        color: #555;
+      }
+      .mood-next {
+        padding: 12px 20px;
+        flex-shrink: 0;
+        display: flex;
+        justify-content: flex-end;
+      }
+      .mood-next-btn {
+        background: #fff;
+        color: #000;
+        border: none;
+        padding: 10px 24px;
+        border-radius: 8px;
+        font-size: 13px;
+        font-weight: 600;
+        cursor: pointer;
+        opacity: 0;
+        transform: translateY(8px);
+        transition: all 0.2s;
+      }
+      .mood-next-btn.visible {
+        opacity: 1;
+        transform: translateY(0);
+      }
+      .mood-next-btn:hover {
+        background: #ddd;
+      }
+
+      /* ── Phase 2: Fine-tune ── */
+      .panel-left {
+        width: 400px;
+        min-width: 400px;
+        height: 100%;
+        overflow-y: auto;
+        border-right: 1px solid #1a1a1a;
+        padding: 0 0 100px;
+        background: #111;
+      }
+      .panel-right {
+        flex: 1;
+        height: 100%;
+        overflow-y: auto;
+        overflow-x: hidden;
+        background: #0e0e0e;
+      }
+      .panel-right * {
+        max-width: 100%;
+        box-sizing: border-box;
+      }
+
+      /* ── Section cards (Neuform-inspired) ── */
+      .section-card {
+        border-bottom: 1px solid #1a1a1a;
+      }
+      .section-header {
+        display: flex;
+        align-items: center;
+        gap: 8px;
+        padding: 14px 16px 6px;
+      }
+      .section-icon {
+        width: 22px;
+        height: 22px;
+        border-radius: 5px;
+        background: rgba(255, 255, 255, 0.04);
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        color: #555;
+        font-size: 11px;
+        flex-shrink: 0;
+      }
+      .section-title {
+        font-size: 11px;
+        font-weight: 600;
+        color: #fff;
+        letter-spacing: 0.01em;
+      }
+      .section-meta {
+        font-size: 10px;
+        color: #444;
+        margin-left: auto;
+      }
+      .section-body {
+        padding: 6px 16px 16px;
+      }
+
+      /* ── Option cards ── */
+      .opt {
+        border: 1px solid #1e1e1e;
+        border-radius: 10px;
+        margin-bottom: 6px;
+        cursor: pointer;
+        transition: border-color 0.12s;
+        overflow: hidden;
+        background: #141414;
+        position: relative;
+      }
+      .opt:hover {
+        border-color: #333;
+      }
+      .opt.selected {
+        border-color: #fff;
+      }
+      .opt-inner {
+        padding: 12px 14px;
+      }
+      .opt-name {
+        font-size: 12px;
+        font-weight: 600;
+        margin-bottom: 2px;
+      }
+      .opt-desc {
+        font-size: 10px;
+        color: #666;
+        line-height: 1.4;
+      }
+      .opt-tag {
+        font-size: 9px;
+        color: #444;
+        margin-top: 4px;
+        text-transform: uppercase;
+        letter-spacing: 0.04em;
+      }
+      .opt-rec {
+        position: absolute;
+        top: 8px;
+        right: 10px;
+        font-size: 8px;
+        font-weight: 700;
+        color: #4ade80;
+        background: rgba(74, 222, 128, 0.08);
+        padding: 2px 6px;
+        border-radius: 3px;
+        text-transform: uppercase;
+        letter-spacing: 0.04em;
+      }
+
+      /* ── Palette option ── */
+      .pal-strip {
+        display: flex;
+        height: 28px;
+        border-radius: 6px;
+        overflow: hidden;
+        margin-bottom: 8px;
+      }
+      .pal-strip > div {
+        flex: 1;
+      }
+      .pal-ramp {
+        display: flex;
+        gap: 2px;
+        margin-top: 4px;
+      }
+      .pal-ramp-swatch {
+        width: 100%;
+        height: 6px;
+        border-radius: 2px;
+      }
+
+      /* ── Type option (specimen) ── */
+      .type-specimen {
+        padding: 14px;
+        border-bottom: 1px solid #1a1a1a;
+      }
+      .type-headline {
+        line-height: 1.1;
+        letter-spacing: -0.02em;
+        margin-bottom: 6px;
+      }
+      .type-body {
+        line-height: 1.5;
+        color: #666;
+        font-size: 11px;
+      }
+      .type-meta {
+        padding: 10px 14px;
+        display: flex;
+        justify-content: space-between;
+        align-items: center;
+      }
+      .type-families {
+        font-size: 9px;
+        color: #444;
+        letter-spacing: 0.02em;
+      }
+      .type-letters {
+        font-size: 9px;
+        color: #333;
+        letter-spacing: 0.08em;
+        overflow: hidden;
+        white-space: nowrap;
+        text-overflow: ellipsis;
+        max-width: 200px;
+      }
+
+      /* ── Chip options ── */
+      .chips {
+        display: flex;
+        gap: 6px;
+        flex-wrap: wrap;
+      }
+      .chip {
+        border: 1px solid #1e1e1e;
+        border-radius: 8px;
+        padding: 8px 12px;
+        cursor: pointer;
+        transition: border-color 0.12s;
+        display: flex;
+        align-items: center;
+        gap: 8px;
+        background: #141414;
+      }
+      .chip:hover {
+        border-color: #333;
+      }
+      .chip.selected {
+        border-color: #fff;
+      }
+      .chip-label {
+        font-size: 11px;
+        font-weight: 500;
+      }
+      .chip-sub {
+        font-size: 9px;
+        color: #555;
+      }
+      .chip-preview {
+        flex-shrink: 0;
+      }
+
+      .theme-chip {
+        flex: 1;
+        min-width: 90px;
+        flex-direction: column;
+        align-items: center;
+        padding: 10px 12px;
+        text-align: center;
+      }
+      .theme-swatch {
+        width: 100%;
+        height: 28px;
+        border-radius: 4px;
+        margin-bottom: 4px;
+        border: 1px solid rgba(255, 255, 255, 0.06);
+      }
+      .corner-box {
+        width: 22px;
+        height: 22px;
+        border: 2px solid #666;
+      }
+      .density-bars {
+        display: flex;
+        flex-direction: column;
+        width: 24px;
+      }
+      .density-bar {
+        background: #666;
+        height: 3px;
+        border-radius: 1px;
+      }
+      .depth-square {
+        width: 22px;
+        height: 22px;
+        background: #2a2a2a;
+        border-radius: 3px;
+      }
+
+      /* ── Easing option ── */
+      .ease-opt {
+        border: 1px solid #1e1e1e;
+        border-radius: 10px;
+        margin-bottom: 6px;
+        cursor: pointer;
+        transition: border-color 0.12s;
+        overflow: hidden;
+        background: #141414;
+        padding: 10px 14px;
+      }
+      .ease-opt:hover {
+        border-color: #333;
+      }
+      .ease-opt.selected {
+        border-color: #fff;
+      }
+      .ease-track {
+        position: relative;
+        height: 8px;
+        background: #1a1a1a;
+        border-radius: 4px;
+        margin-bottom: 8px;
+        overflow: visible;
+      }
+      .ease-dot {
+        position: absolute;
+        top: 50%;
+        transform: translateY(-50%);
+        left: 0;
+        width: 12px;
+        height: 12px;
+        border-radius: 50%;
+        background: #fff;
+      }
+      .ease-label {
+        display: flex;
+        justify-content: space-between;
+        align-items: center;
+      }
+      .ease-name {
+        font-size: 11px;
+        font-weight: 600;
+      }
+      .ease-value {
+        font-size: 9px;
+        color: #444;
+        font-family: "SF Mono", Consolas, monospace;
+        letter-spacing: 0.02em;
+      }
+
+      .preview-empty {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        height: 100%;
+        color: #2a2a2a;
+        font-size: 13px;
+      }
+
+      /* ── FAB + Overlay ── */
+      .fab {
+        position: fixed;
+        bottom: 20px;
+        right: 32px;
+        transform: translateY(60px);
+        opacity: 0;
+        background: #fff;
+        color: #000;
+        border: none;
+        padding: 12px 24px;
+        border-radius: 10px;
+        font-size: 13px;
+        font-weight: 600;
+        cursor: pointer;
+        box-shadow: 0 4px 24px rgba(0, 0, 0, 0.5);
+        transition:
+          transform 0.25s ease,
+          opacity 0.25s ease;
+        z-index: 100;
+      }
+      .fab.visible {
+        transform: translateY(0);
+        opacity: 1;
+      }
+      .fab:hover {
+        background: #ddd;
+      }
+
+      .md-overlay {
+        position: fixed;
+        inset: 0;
+        background: rgba(0, 0, 0, 0.85);
+        backdrop-filter: blur(8px);
+        z-index: 200;
+        display: none;
+        align-items: center;
+        justify-content: center;
+      }
+      .md-overlay.visible {
+        display: flex;
+      }
+      .md-card {
+        background: #161616;
+        border: 1px solid #2a2a2a;
+        border-radius: 14px;
+        max-width: 600px;
+        width: 90%;
+        max-height: 80vh;
+        display: flex;
+        flex-direction: column;
+      }
+      .md-header {
+        padding: 16px 20px;
+        border-bottom: 1px solid #1e1e1e;
+        display: flex;
+        justify-content: space-between;
+        align-items: center;
+      }
+      .md-title {
+        font-size: 14px;
+        font-weight: 600;
+      }
+      .md-actions {
+        display: flex;
+        gap: 6px;
+      }
+      .copy-btn {
+        background: #fff;
+        color: #000;
+        border: none;
+        padding: 7px 16px;
+        border-radius: 6px;
+        font-size: 12px;
+        font-weight: 600;
+        cursor: pointer;
+      }
+      .copy-btn:hover {
+        background: #ddd;
+      }
+      .close-btn {
+        background: transparent;
+        color: #666;
+        border: 1px solid #2a2a2a;
+        padding: 7px 14px;
+        border-radius: 6px;
+        font-size: 12px;
+        cursor: pointer;
+      }
+      .close-btn:hover {
+        color: #fff;
+        border-color: #444;
+      }
+      .md-body {
+        padding: 20px;
+        overflow-y: auto;
+        flex: 1;
+      }
+      .md-editor {
+        font-family: "SF Mono", Consolas, monospace;
+        font-size: 12px;
+        line-height: 1.6;
+        color: #aaa;
+        background: transparent;
+        border: none;
+        width: 100%;
+        min-height: 360px;
+        resize: vertical;
+        outline: none;
+        white-space: pre-wrap;
+      }
+
+      /* ── Phase 1 palette bar ── */
+      .pal-bar {
+        display: flex;
+        gap: 8px;
+        padding: 12px 20px 0;
+        flex-shrink: 0;
+        flex-wrap: wrap;
+        align-items: center;
+      }
+      .pal-bar-label {
+        font-size: 10px;
+        color: #444;
+        letter-spacing: 0.03em;
+        text-transform: uppercase;
+        margin-right: 4px;
+      }
+      .pal-bar-chip {
+        display: flex;
+        align-items: center;
+        gap: 6px;
+        padding: 5px 10px;
+        border: 1px solid #1e1e1e;
+        border-radius: 6px;
+        cursor: pointer;
+        transition: border-color 0.12s;
+        background: #141414;
+      }
+      .pal-bar-chip:hover {
+        border-color: #333;
+      }
+      .pal-bar-chip.active {
+        border-color: #fff;
+      }
+      .pal-bar-chip-swatches {
+        display: flex;
+        gap: 2px;
+      }
+      .pal-bar-chip-swatch {
+        width: 14px;
+        height: 14px;
+        border-radius: 3px;
+      }
+      .pal-bar-chip-name {
+        font-size: 10px;
+        font-weight: 500;
+        color: #888;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="phase-bar">
+      <div class="phase-tab active" id="tab-mood" onclick="showPhase('mood')">1. Direction</div>
+      <div class="phase-tab disabled" id="tab-tune" onclick="showPhase('tune')">2. Fine-tune</div>
+    </div>
+
+    <!-- Phase 1: Mood boards -->
+    <div class="phase active" id="phase-mood" style="flex-direction: column">
+      <div class="mood-header">
+        <h2 id="mood-title">Pick a direction</h2>
+        <p id="mood-subtitle">
+          Each option is a complete visual identity. Pick one, then fine-tune.
+        </p>
+      </div>
+      <div class="pal-bar" id="pal-bar"><span class="pal-bar-label">Palette</span></div>
+      <div class="mood-grid" id="mood-grid"></div>
+      <div class="mood-next">
+        <button class="mood-next-btn" id="mood-next-btn" onclick="goToTune()">
+          Customize this direction →
+        </button>
+      </div>
+    </div>
+
+    <!-- Phase 2: Fine-tune -->
+    <div class="phase" id="phase-tune" style="flex-direction: row">
+      <div class="panel-left">
+        <!-- Theme -->
+        <div class="section-card">
+          <div class="section-header">
+            <div class="section-icon">◐</div>
+            <div class="section-title">Theme</div>
+          </div>
+          <div class="section-body"><div class="chips" id="theme-options"></div></div>
+        </div>
+        <!-- Structure -->
+        <div class="section-card">
+          <div class="section-header">
+            <div class="section-icon">▦</div>
+            <div class="section-title">Structure</div>
+            <div class="section-meta" id="arch-meta"></div>
+          </div>
+          <div class="section-body" id="arch-options"></div>
+        </div>
+        <!-- Palette -->
+        <div class="section-card">
+          <div class="section-header">
+            <div class="section-icon">◉</div>
+            <div class="section-title">Color</div>
+          </div>
+          <div class="section-body" id="pal-options"></div>
+        </div>
+        <!-- Typography -->
+        <div class="section-card">
+          <div class="section-header">
+            <div class="section-icon">Aa</div>
+            <div class="section-title">Typography</div>
+          </div>
+          <div class="section-body" id="type-options"></div>
+        </div>
+        <!-- Corners -->
+        <div class="section-card">
+          <div class="section-header">
+            <div class="section-icon">⬔</div>
+            <div class="section-title">Corners</div>
+          </div>
+          <div class="section-body"><div class="chips" id="corner-options"></div></div>
+        </div>
+        <!-- Density -->
+        <div class="section-card">
+          <div class="section-header">
+            <div class="section-icon">≡</div>
+            <div class="section-title">Density</div>
+          </div>
+          <div class="section-body"><div class="chips" id="density-options"></div></div>
+        </div>
+        <!-- Depth -->
+        <div class="section-card">
+          <div class="section-header">
+            <div class="section-icon">◧</div>
+            <div class="section-title">Depth</div>
+          </div>
+          <div class="section-body"><div class="chips" id="depth-options"></div></div>
+        </div>
+        <!-- Motion / Easing -->
+        <div class="section-card">
+          <div class="section-header">
+            <div class="section-icon">⟿</div>
+            <div class="section-title">Motion</div>
+            <div class="section-meta">entry easing</div>
+          </div>
+          <div class="section-body" id="ease-options"></div>
+        </div>
+      </div>
+      <div class="panel-right" id="preview">
+        <div class="preview-empty">Pick a structure to preview</div>
+      </div>
+    </div>
+
+    <button class="fab" id="fab" onclick="showOutput()">Create design.md</button>
+
+    <div class="md-overlay" id="md-overlay">
+      <div class="md-card">
+        <div class="md-header">
+          <div class="md-title">
+            design.md
+            <span style="font-size: 11px; font-weight: 400; color: #555">— edit, then copy</span>
+          </div>
+          <div class="md-actions">
+            <button class="copy-btn" id="copy-btn">Copy</button>
+            <button
+              class="close-btn"
+              onclick="document.getElementById('md-overlay').classList.remove('visible')"
+            >
+              Close
+            </button>
+          </div>
+        </div>
+        <div class="md-body">
+          <textarea class="md-editor" id="md-output" spellcheck="false"></textarea>
+        </div>
+      </div>
+    </div>
+
+    <script>
+      var ARCHITECTURES = __ARCHITECTURES_JSON__;
+      var PALETTES = __PALETTES_JSON__;
+      var TYPEPAIRS = __TYPEPAIRS_JSON__;
+      var MOODBOARDS = __MOODBOARDS_JSON__;
+      var PROMPT = __PROMPT_JSON__;
+      var picks = {
+        theme: null,
+        arch: null,
+        palette: null,
+        type: null,
+        corners: null,
+        density: null,
+        depth: null,
+        easing: null,
+      };
+
+      var EASINGS = [
+        { name: "Confident", value: "power3.out", desc: "Fast start, smooth deceleration" },
+        { name: "Snappy", value: "expo.out", desc: "Very fast start, crisp stop" },
+        { name: "Gentle", value: "sine.inOut", desc: "Soft acceleration and deceleration" },
+        { name: "Bouncy", value: "back.out(1.4)", desc: "Overshoots then settles" },
+        { name: "Elastic", value: "elastic.out(1, 0.5)", desc: "Springs past target and wobbles" },
+        { name: "Sharp", value: "power4.out", desc: "Aggressive start, hard stop" },
+      ];
+
+      var THEMES = [
+        { name: "Dark", id: "dark", bg: "#0e0e0e", fg: "#eee", desc: "Light on dark" },
+        { name: "Light", id: "light", bg: "#f5f3ef", fg: "#1a1a1a", desc: "Dark on light" },
+        { name: "Palette", id: "palette", bg: null, fg: null, desc: "Use palette colors" },
+      ];
+      var CORNERS = [
+        { name: "Sharp", value: "0px" },
+        { name: "Slight", value: "4px" },
+        { name: "Rounded", value: "12px" },
+      ];
+      var DENSITIES = [
+        { name: "Tight", padding: "8-12px", gap: "8-12px", desc: "Compact" },
+        { name: "Normal", padding: "16-24px", gap: "16-20px", desc: "Balanced" },
+        { name: "Generous", padding: "32-48px", gap: "28-40px", desc: "Spacious" },
+      ];
+      var DEPTHS = [
+        { name: "Flat", desc: "No shadows" },
+        { name: "Subtle", desc: "Faint shadows" },
+        { name: "Layered", desc: "Glows + depth" },
+      ];
+
+      // Load fonts
+      var fams = [];
+      TYPEPAIRS.forEach(function (tp) {
+        fams.push(tp.headline.family.replace(/ /g, "+") + ":wght@" + tp.headline.weight);
+        fams.push(tp.body.family.replace(/ /g, "+") + ":wght@" + tp.body.weight);
+      });
+      var lnk = document.createElement("link");
+      lnk.rel = "stylesheet";
+      lnk.href =
+        "https://fonts.googleapis.com/css2?family=" + fams.join("&family=") + "&display=swap";
+      document.head.appendChild(lnk);
+
+      function al(hex, o) {
+        if (!hex || typeof hex !== "string" || hex[0] !== "#") return "rgba(128,128,128," + o + ")";
+        if (hex.length === 4) hex = "#" + hex[1] + hex[1] + hex[2] + hex[2] + hex[3] + hex[3];
+        var r = parseInt(hex.slice(1, 3), 16),
+          g = parseInt(hex.slice(3, 5), 16),
+          b = parseInt(hex.slice(5, 7), 16);
+        if (isNaN(r)) r = 128;
+        if (isNaN(g)) g = 128;
+        if (isNaN(b)) b = 128;
+        return "rgba(" + r + "," + g + "," + b + "," + o + ")";
+      }
+
+      // Prompt-aware UI
+      if (PROMPT && PROMPT.title)
+        document.getElementById("mood-title").textContent = "Pick a direction for: " + PROMPT.title;
+
+      // ── Phase 1: Mood boards + Palette bar ──
+      var moodGrid = document.getElementById("mood-grid");
+      var selectedMood = null;
+      var overridePalette = null;
+
+      // Build palette bar
+      var palBar = document.getElementById("pal-bar");
+      PALETTES.forEach(function (p, i) {
+        var chip = document.createElement("div");
+        chip.className = "pal-bar-chip" + (i === 0 ? "" : "");
+        chip.innerHTML =
+          '<div class="pal-bar-chip-swatches"><div class="pal-bar-chip-swatch" style="background:' +
+          p.background +
+          ';border:1px solid rgba(255,255,255,0.08);"></div><div class="pal-bar-chip-swatch" style="background:' +
+          p.accent +
+          ';"></div><div class="pal-bar-chip-swatch" style="background:' +
+          p.foreground +
+          ';border:1px solid rgba(255,255,255,0.08);"></div></div><span class="pal-bar-chip-name">' +
+          p.name +
+          "</span>";
+        chip.onclick = function () {
+          palBar.querySelectorAll(".pal-bar-chip").forEach(function (c) {
+            c.classList.remove("active");
+          });
+          if (overridePalette === i) {
+            overridePalette = null;
+          } else {
+            chip.classList.add("active");
+            overridePalette = i;
+          }
+          renderMoodBoards();
+        };
+        palBar.appendChild(chip);
+      });
+
+      function renderMoodBoards() {
+        var prevSelected = selectedMood;
+        moodGrid.innerHTML = "";
+        MOODBOARDS.forEach(function (mb, i) {
+          var card = document.createElement("div");
+          card.className = "mood-card" + (i === prevSelected ? " selected" : "");
+          var tp = TYPEPAIRS[mb.type_index || 0],
+            arch = ARCHITECTURES[mb.arch_index || 0];
+          var pal =
+            overridePalette !== null ? PALETTES[overridePalette] : PALETTES[mb.palette_index || 0];
+          var thId = mb.theme || "dark",
+            th =
+              THEMES.find(function (t) {
+                return t.id === thId;
+              }) || THEMES[0];
+          var bg = thId === "palette" ? pal.background : th.bg,
+            fg = thId === "palette" ? pal.foreground : th.fg;
+          var tokens = {
+            "{{bg}}": bg,
+            "{{fg}}": fg,
+            "{{ac}}": pal.accent,
+            "{{mt}}": pal.muted || pal.mid || al(fg, 0.4),
+            "{{hf}}": tp.headline.family,
+            "{{hw}}": tp.headline.weight,
+            "{{bf}}": tp.body.family,
+            "{{bw}}": tp.body.weight,
+            "{{cr}}": mb.corners || "4px",
+            "{{pad}}": mb.padding || "20px",
+            "{{gap}}": mb.gap || "16px",
+            "{{shadow}}": mb.shadow || "none",
+            "{{sf}}": al(fg, 0.06),
+            "{{g}}": al(fg, 0.06),
+            "{{fg3}}": al(fg, 0.03),
+            "{{fg6}}": al(fg, 0.06),
+            "{{fg8}}": al(fg, 0.08),
+            "{{fg15}}": al(fg, 0.15),
+            "{{ac3}}": al(pal.accent, 0.03),
+            "{{ac5}}": al(pal.accent, 0.05),
+            "{{ac25}}": al(pal.accent, 0.25),
+            "{{prompt_headline}}": (PROMPT && PROMPT.headline) || "Your Headline",
+            "{{prompt_sub}}": (PROMPT && PROMPT.subline) || "A subline for your product.",
+          };
+          var preview = arch.preview_html || "";
+          Object.keys(tokens).forEach(function (k) {
+            preview = preview.split(k).join(tokens[k]);
+          });
+          var tagHtml = [tp.headline.family, pal.name, CORNERS[mb.corners_index || 1].name]
+            .map(function (t) {
+              return '<span class="mood-token">' + t + "</span>";
+            })
+            .join("");
+          card.innerHTML =
+            '<div class="mood-preview"><div style="transform:scale(0.38);transform-origin:top left;width:263.16%;min-height:263.16%;">' +
+            preview +
+            '</div></div><div class="mood-info"><div class="mood-name">' +
+            mb.name +
+            '</div><div class="mood-desc">' +
+            mb.description +
+            '</div><div class="mood-tokens">' +
+            tagHtml +
+            "</div></div>";
+          card.onclick = function () {
+            moodGrid.querySelectorAll(".mood-card").forEach(function (c) {
+              c.classList.remove("selected");
+            });
+            card.classList.add("selected");
+            selectedMood = i;
+            document.getElementById("mood-next-btn").classList.add("visible");
+          };
+          moodGrid.appendChild(card);
+        });
+      }
+      renderMoodBoards();
+
+      var currentPhase = "mood";
+      function showPhase(name) {
+        currentPhase = name;
+        document.querySelectorAll(".phase").forEach(function (p) {
+          p.classList.remove("active");
+        });
+        document.querySelectorAll(".phase-tab").forEach(function (t) {
+          t.classList.remove("active");
+        });
+        document.getElementById("phase-" + name).classList.add("active");
+        document.getElementById("tab-" + name).classList.add("active");
+        if (name === "mood") document.getElementById("fab").classList.remove("visible");
+        else checkReady();
+      }
+
+      function goToTune() {
+        if (selectedMood === null) return;
+        var mb = MOODBOARDS[selectedMood];
+        var thIdx = THEMES.findIndex(function (t) {
+          return t.id === (mb.theme || "dark");
+        });
+        if (thIdx >= 0) chipSel("theme", thIdx, document.getElementById("theme-options"));
+        if (mb.arch_index != null)
+          sel("arch", mb.arch_index, document.getElementById("arch-options"));
+        var palIdx = overridePalette !== null ? overridePalette : mb.palette_index;
+        if (palIdx != null) sel("palette", palIdx, document.getElementById("pal-options"));
+        if (mb.type_index != null)
+          sel("type", mb.type_index, document.getElementById("type-options"));
+        if (mb.corners_index != null)
+          chipSel("corners", mb.corners_index, document.getElementById("corner-options"));
+        if (mb.density_index != null)
+          chipSel("density", mb.density_index, document.getElementById("density-options"));
+        if (mb.depth_index != null)
+          chipSel("depth", mb.depth_index, document.getElementById("depth-options"));
+        var eIdx = mb.easing_index != null ? mb.easing_index : 0;
+        var eOpts = document.getElementById("ease-options");
+        eOpts.querySelectorAll(".ease-opt").forEach(function (c) {
+          c.classList.remove("selected");
+        });
+        eOpts.children[eIdx].classList.add("selected");
+        picks.easing = eIdx;
+        document.getElementById("tab-tune").classList.remove("disabled");
+        showPhase("tune");
+      }
+
+      // ── Phase 2: Build options ──
+
+      // Architecture cards
+      var archOpts = document.getElementById("arch-options");
+      ARCHITECTURES.forEach(function (a, i) {
+        var el = document.createElement("div");
+        el.className = "opt";
+        el.innerHTML =
+          '<div class="opt-inner"><div class="opt-name">' +
+          a.name +
+          '</div><div class="opt-desc">' +
+          a.description +
+          '</div><div class="opt-tag">' +
+          a.tag +
+          "</div></div>";
+        el.onclick = function () {
+          sel("arch", i, archOpts);
+        };
+        archOpts.appendChild(el);
+      });
+
+      // Palette cards with ramp
+      var palOpts = document.getElementById("pal-options");
+      PALETTES.forEach(function (p, i) {
+        var el = document.createElement("div");
+        el.className = "opt";
+        el.innerHTML =
+          '<div class="opt-inner"><div class="pal-strip"><div style="background:' +
+          p.background +
+          ';"></div><div style="background:' +
+          (p.muted || p.mid || "#888") +
+          ';"></div><div style="background:' +
+          p.accent +
+          ';"></div><div style="background:' +
+          p.foreground +
+          ';"></div></div><div class="opt-name">' +
+          p.name +
+          '</div><div class="opt-desc">' +
+          p.description +
+          "</div></div>";
+        el.onclick = function () {
+          sel("palette", i, palOpts);
+        };
+        palOpts.appendChild(el);
+      });
+
+      // Typography cards with specimen
+      var typeOpts = document.getElementById("type-options");
+      TYPEPAIRS.forEach(function (tp, i) {
+        var letters = "AaBbCcDdEeFfGgHh";
+        var el = document.createElement("div");
+        el.className = "opt";
+        el.innerHTML =
+          '<div class="type-specimen"><div class="type-headline" style="font-family:\'' +
+          tp.headline.family +
+          "',sans-serif;font-weight:" +
+          tp.headline.weight +
+          ';font-size:24px;">' +
+          tp.preview +
+          '</div><div class="type-body" style="font-family:\'' +
+          tp.body.family +
+          "',monospace;font-weight:" +
+          tp.body.weight +
+          ';">' +
+          tp.body_preview +
+          '</div></div><div class="type-meta"><div class="type-families">' +
+          tp.headline.family +
+          " " +
+          tp.headline.weight +
+          " · " +
+          tp.body.family +
+          " " +
+          tp.body.weight +
+          '</div><div class="type-letters" style="font-family:\'' +
+          tp.headline.family +
+          "',sans-serif;font-weight:" +
+          tp.headline.weight +
+          ';">' +
+          letters +
+          "</div></div>";
+        el.onclick = function () {
+          sel("type", i, typeOpts);
+        };
+        typeOpts.appendChild(el);
+      });
+
+      // Theme chips
+      var themeOpts = document.getElementById("theme-options");
+      THEMES.forEach(function (th, i) {
+        var el = document.createElement("div");
+        el.className = "chip theme-chip";
+        el.innerHTML =
+          '<div class="theme-swatch" style="background:' +
+          th.bg +
+          ';"></div><div class="chip-label">' +
+          th.name +
+          '</div><div class="chip-sub">' +
+          th.desc +
+          "</div>";
+        el.onclick = function () {
+          chipSel("theme", i, themeOpts);
+        };
+        themeOpts.appendChild(el);
+      });
+
+      // Corner chips
+      var cornerOpts = document.getElementById("corner-options");
+      CORNERS.forEach(function (c, i) {
+        var el = document.createElement("div");
+        el.className = "chip";
+        el.innerHTML =
+          '<div class="chip-preview"><div class="corner-box" style="border-radius:' +
+          c.value +
+          ';"></div></div><div><div class="chip-label">' +
+          c.name +
+          '</div><div class="chip-sub">' +
+          c.value +
+          "</div></div>";
+        el.onclick = function () {
+          chipSel("corners", i, cornerOpts);
+        };
+        cornerOpts.appendChild(el);
+      });
+
+      // Density chips
+      var densityOpts = document.getElementById("density-options");
+      DENSITIES.forEach(function (d, i) {
+        var gaps = [2, 4, 7][i];
+        var el = document.createElement("div");
+        el.className = "chip";
+        el.innerHTML =
+          '<div class="chip-preview"><div class="density-bars" style="gap:' +
+          gaps +
+          'px;"><div class="density-bar"></div><div class="density-bar"></div><div class="density-bar"></div></div></div><div><div class="chip-label">' +
+          d.name +
+          '</div><div class="chip-sub">' +
+          d.desc +
+          "</div></div>";
+        el.onclick = function () {
+          chipSel("density", i, densityOpts);
+        };
+        densityOpts.appendChild(el);
+      });
+
+      // Depth chips
+      var depthOpts = document.getElementById("depth-options");
+      DEPTHS.forEach(function (d, i) {
+        var shadow = [
+          "none",
+          "0 2px 8px rgba(255,255,255,0.04)",
+          "0 0 16px rgba(255,255,255,0.06)",
+        ][i];
+        var el = document.createElement("div");
+        el.className = "chip";
+        el.innerHTML =
+          '<div class="chip-preview"><div class="depth-square" style="box-shadow:' +
+          shadow +
+          ';"></div></div><div><div class="chip-label">' +
+          d.name +
+          '</div><div class="chip-sub">' +
+          d.desc +
+          "</div></div>";
+        el.onclick = function () {
+          chipSel("depth", i, depthOpts);
+        };
+        depthOpts.appendChild(el);
+      });
+
+      // Easing options with GSAP animation
+      var easeOpts = document.getElementById("ease-options");
+      EASINGS.forEach(function (e, i) {
+        var el = document.createElement("div");
+        el.className = "ease-opt";
+        var dotId = "ease-dot-" + i;
+        el.innerHTML =
+          '<div class="ease-track"><div class="ease-dot" id="' +
+          dotId +
+          '"></div></div>' +
+          '<div class="ease-label"><div class="ease-name">' +
+          e.name +
+          '</div><div class="ease-value">' +
+          e.value +
+          "</div></div>";
+        el.onclick = function () {
+          easeOpts.querySelectorAll(".ease-opt").forEach(function (c) {
+            c.classList.remove("selected");
+          });
+          el.classList.add("selected");
+          picks.easing = i;
+          checkReady();
+        };
+        easeOpts.appendChild(el);
+        // Animate the dot with GSAP
+        gsap.to("#" + dotId, {
+          left: "calc(100% - 12px)",
+          duration: 1.2,
+          ease: e.value,
+          repeat: -1,
+          repeatDelay: 0.8,
+          yoyo: true,
+        });
+      });
+
+      function chipSel(key, idx, container) {
+        container.querySelectorAll(".chip").forEach(function (c) {
+          c.classList.remove("selected");
+        });
+        container.children[idx].classList.add("selected");
+        picks[key] = idx;
+        checkReady();
+        renderPreview();
+      }
+      function sel(key, idx, container) {
+        container.querySelectorAll(".opt").forEach(function (c) {
+          c.classList.remove("selected");
+        });
+        container.children[idx].classList.add("selected");
+        picks[key] = idx;
+        checkReady();
+        renderPreview();
+      }
+
+      function checkReady() {
+        var ready =
+          picks.theme !== null &&
+          picks.arch !== null &&
+          picks.palette !== null &&
+          picks.type !== null &&
+          picks.corners !== null &&
+          picks.density !== null &&
+          picks.depth !== null &&
+          picks.easing !== null;
+        document
+          .getElementById("fab")
+          .classList.toggle("visible", ready && currentPhase === "tune");
+        document.getElementById("md-overlay").classList.remove("visible");
+      }
+
+      function renderPreview() {
+        var pv = document.getElementById("preview");
+        if (picks.arch === null) {
+          pv.innerHTML = '<div class="preview-empty">Pick a structure to preview</div>';
+          return;
+        }
+        var a = ARCHITECTURES[picks.arch];
+        var th = picks.theme !== null ? THEMES[picks.theme] : THEMES[0];
+        var p =
+          picks.palette !== null ? PALETTES[picks.palette] : { accent: "#888", muted: "#555" };
+        var t =
+          picks.type !== null
+            ? TYPEPAIRS[picks.type]
+            : {
+                headline: { family: "system-ui", weight: 600 },
+                body: { family: "system-ui", weight: 400 },
+              };
+        var cr = picks.corners !== null ? CORNERS[picks.corners].value : "0px";
+        var dn = picks.density !== null ? picks.density : 1;
+        var dp = picks.depth !== null ? picks.depth : 0;
+        var bg, fg;
+        if (th.id === "palette" && p.background) {
+          bg = p.background;
+          fg = p.foreground;
+        } else {
+          bg = th.bg;
+          fg = th.fg;
+        }
+        var ac = p.accent,
+          mt = p.muted || al(fg, 0.4);
+        var pad = [12, 20, 36][dn] + "px",
+          gap = [8, 16, 28][dn] + "px";
+        var isDark = bg && bg[0] === "#" ? parseInt(bg.slice(1, 3), 16) < 80 : true;
+        var shCol = isDark ? ac : fg;
+        var shadow = [
+          "none",
+          "0 2px 16px " + al(shCol, isDark ? 0.15 : 0.1),
+          "0 4px 32px " + al(shCol, isDark ? 0.3 : 0.18),
+        ][dp];
+        var tokens = {
+          "{{bg}}": bg,
+          "{{fg}}": fg,
+          "{{ac}}": ac,
+          "{{mt}}": mt,
+          "{{sf}}": al(fg, 0.06),
+          "{{hf}}": t.headline.family,
+          "{{hw}}": t.headline.weight,
+          "{{bf}}": t.body.family,
+          "{{bw}}": t.body.weight,
+          "{{cr}}": cr,
+          "{{pad}}": pad,
+          "{{gap}}": gap,
+          "{{shadow}}": shadow,
+          "{{g}}": al(fg, 0.06),
+          "{{fg3}}": al(fg, 0.03),
+          "{{fg6}}": al(fg, 0.06),
+          "{{fg8}}": al(fg, 0.08),
+          "{{fg15}}": al(fg, 0.15),
+          "{{ac3}}": al(ac, 0.03),
+          "{{ac5}}": al(ac, 0.05),
+          "{{ac25}}": al(ac, 0.25),
+          "{{prompt_headline}}": (PROMPT && PROMPT.headline) || "Your Headline",
+          "{{prompt_sub}}": (PROMPT && PROMPT.subline) || "Subline.",
+        };
+        var h =
+          a.preview_html ||
+          '<div style="background:' +
+            bg +
+            ";padding:40px;min-height:100%;display:flex;align-items:center;justify-content:center;color:" +
+            mt +
+            ';font-size:14px;">No preview</div>';
+        Object.keys(tokens).forEach(function (k) {
+          h = h.split(k).join(tokens[k]);
+        });
+        pv.innerHTML = h;
+      }
+
+      // ── Output ──
+      function showOutput() {
+        if (
+          picks.theme === null ||
+          picks.arch === null ||
+          picks.palette === null ||
+          picks.type === null ||
+          picks.corners === null ||
+          picks.density === null ||
+          picks.depth === null
+        )
+          return;
+        var a = ARCHITECTURES[picks.arch],
+          p = PALETTES[picks.palette],
+          t = TYPEPAIRS[picks.type];
+        var th = THEMES[picks.theme],
+          cr = CORNERS[picks.corners],
+          dn = DENSITIES[picks.density],
+          dp = DEPTHS[picks.depth];
+        var bg = th.id === "palette" && p.background ? p.background : th.bg;
+        var fg = th.id === "palette" && p.foreground ? p.foreground : th.fg;
+        var ac = p.accent,
+          mt = p.muted || p.mid || "#888";
+        var padVal = { Tight: "8px", Normal: "16px", Generous: "32px" }[dn.name] || "16px";
+        var gapVal = { Tight: "8px", Normal: "16px", Generous: "28px" }[dn.name] || "16px";
+
+        var md = "---\n";
+        md += "name: " + ((PROMPT && PROMPT.title) || "Untitled") + "\n";
+        md +=
+          'colors:\n  primary: "' +
+          bg +
+          '"\n  on-primary: "' +
+          fg +
+          '"\n  accent: "' +
+          ac +
+          '"\n  muted: "' +
+          mt +
+          '"\n';
+        md +=
+          "typography:\n  headline:\n    fontFamily: " +
+          t.headline.family +
+          "\n    fontSize: 3.5rem\n    fontWeight: " +
+          t.headline.weight +
+          "\n    letterSpacing: -0.03em\n";
+        md +=
+          "  body:\n    fontFamily: " +
+          t.body.family +
+          "\n    fontSize: 1rem\n    fontWeight: " +
+          t.body.weight +
+          "\n    lineHeight: 1.5\n";
+        md += "rounded:\n  md: " + cr.value + "\n";
+        md += "spacing:\n  md: " + padVal + "\n  lg: " + gapVal + "\n";
+        md += "---\n\n";
+        md += "## Overview\n\n" + a.mood + ". " + a.description + ". " + p.description + ".\n\n";
+        md +=
+          "## Colors\n\n- **Primary** (`" +
+          bg +
+          "`) — Canvas background\n- **On-Primary** (`" +
+          fg +
+          "`) — Text and content\n- **Accent** (`" +
+          ac +
+          "`) — CTAs, highlights\n- **Muted** (`" +
+          mt +
+          "`) — Secondary text\n\n";
+        md +=
+          "## Typography\n\n- **Headline** — " +
+          t.headline.family +
+          " at weight " +
+          t.headline.weight +
+          "\n- **Body** — " +
+          t.body.family +
+          " at weight " +
+          t.body.weight +
+          "\n\n";
+        md +=
+          "## Layout\n\n- Structure: " +
+          a.name +
+          " — " +
+          a.tag +
+          "\n- Density: " +
+          dn.name +
+          " (" +
+          dn.desc +
+          ")\n- Corners: " +
+          cr.name +
+          " (" +
+          cr.value +
+          ")\n\n";
+        md += "## Elevation\n\n" + dp.name + " — " + dp.desc + ".\n\n";
+        var easeObj = picks.easing !== null ? EASINGS[picks.easing] : null;
+        if (easeObj) {
+          md +=
+            "## Motion\n\n- **Entry easing:** `" +
+            easeObj.value +
+            "` — " +
+            easeObj.desc +
+            "\n- **Energy:** " +
+            easeObj.name +
+            "\n\n";
+        }
+        if (a.components) md += "## Components\n\n" + a.components + "\n\n";
+        md += "## Do's and Don'ts\n\n";
+        if (a.dos) {
+          md += a.dos + "\n";
+        } else {
+          md +=
+            "### Do's\n- Use accent color sparingly for maximum impact\n- Maintain consistent " +
+            cr.name.toLowerCase() +
+            " corners\n\n### Don'ts\n- Do not mix multiple accent colors\n- Do not use weights outside the headline/body pair\n";
+        }
+
+        document.getElementById("md-output").value = md;
+        document.getElementById("md-overlay").classList.add("visible");
+      }
+
+      document.getElementById("copy-btn").addEventListener("click", function () {
+        navigator.clipboard.writeText(document.getElementById("md-output").value).then(function () {
+          document.getElementById("copy-btn").textContent = "Copied!";
+          setTimeout(function () {
+            document.getElementById("copy-btn").textContent = "Copy";
+          }, 2000);
+        });
+      });
+    </script>
+  </body>
+</html>
diff --git a/skills/hyperframes/visual-styles.md b/skills/hyperframes/visual-styles.md
index d1e8025c8..55f618815 100644
--- a/skills/hyperframes/visual-styles.md
+++ b/skills/hyperframes/visual-styles.md
@@ -1,14 +1,14 @@
 # Visual Style Library
 
-Named visual identities for HyperFrames videos. Each style is grounded in a real graphic design tradition. Use them to give your video a specific visual personality, not just generic "clean" or "bold."
+Named visual identities for HyperFrames videos. Each style is grounded in a real graphic design tradition and expressed as a DESIGN.md-compatible token block. Use them as starters — copy the YAML into your project's `design.md` front matter, then customize.
 
 **How to pick:** Match mood first, content second. Ask: _"What should the viewer FEEL?"_
 
-**How to use:** Reference the style in your scene plan. Translate the style's principles into concrete composition decisions — palette choice, font selection, entrance patterns, transition type, ambient motion feel.
+**How to use:** Copy the style's YAML token block into `design.md` front matter. Add `## Overview`, `## Colors`, `## Typography`, `## Elevation`, `## Components`, `## Do's and Don'ts` prose sections to complete the file.
 
 ## Quick Reference
 
-| Style           | Mood                  | Best for                           | Primary shader                    |
+| Style           | Mood                  | Best for                           | Transition shader                 |
 | --------------- | --------------------- | ---------------------------------- | --------------------------------- |
 | Swiss Pulse     | Clinical, precise     | SaaS, data, dev tools, metrics     | Cinematic Zoom or SDF Iris        |
 | Velvet Standard | Premium, timeless     | Luxury, enterprise, keynotes       | Cross-Warp Morph                  |
@@ -25,161 +25,395 @@ Named visual identities for HyperFrames videos. Each style is grounded in a real
 
 **Mood:** Clinical, precise | **Best for:** SaaS dashboards, developer tools, APIs, metrics
 
-- Black (`#1a1a1a`), white, ONE accent — electric blue (`#0066FF`) or amber (`#FFB300`)
-- Helvetica or Inter Bold for headlines, Regular for labels. Numbers large (80–120px)
-- Grid-locked compositions. Every element snaps to an invisible 12-column grid
-- Animated counters count up from 0. Hard cuts, no decorative transitions
-- Transitions: Cinematic Zoom or SDF Iris (precise, geometric)
-
-**GSAP signature:** `expo.out`, `power4.out`. Entries are fast and snap into place. Nothing floats.
-
-```
-Swiss Pulse: Black/white + one electric accent. Grid-locked compositions.
-Numbers dominate the frame at 80-120px. Counter animations from 0.
-Hard cuts or geometric transitions. Nothing decorative.
+```yaml
+name: Swiss Pulse
+colors:
+  primary: "#1a1a1a"
+  on-primary: "#ffffff"
+  accent: "#0066FF"
+typography:
+  headline:
+    fontFamily: Helvetica Neue
+    fontSize: 5rem
+    fontWeight: 700
+  label:
+    fontFamily: Inter
+    fontSize: 0.875rem
+    fontWeight: 400
+  stat:
+    fontFamily: Helvetica Neue
+    fontSize: 7rem
+    fontWeight: 700
+rounded:
+  none: 0px
+  sm: 2px
+spacing:
+  sm: 8px
+  md: 16px
+  lg: 32px
+motion:
+  energy: high
+  easing:
+    entry: "expo.out"
+    exit: "power4.in"
+    ambient: "none"
+  duration:
+    entrance: 0.4
+    hold: 1.5
+    transition: 0.6
+  atmosphere:
+    - grid-lines
+    - registration-marks
+  transition: cinematic-zoom
 ```
 
+Grid-locked compositions. Every element snaps to an invisible 12-column grid. Numbers dominate the frame at 80–120px. Animated counters count up from 0. Hard cuts, no decorative transitions. Nothing floats.
+
 ---
 
 ## 2. Velvet Standard — Massimo Vignelli
 
 **Mood:** Premium, timeless | **Best for:** Luxury products, enterprise software, keynotes, investor decks
 
-- Black, white, ONE rich accent — deep navy (`#1a237e`) or gold (`#c9a84c`)
-- Thin sans-serif, ALL CAPS, wide letter-spacing (`0.15em+`)
-- Generous negative space. Symmetrical, centered, architectural precision
-- Slow, deliberate. Sequential reveals with long holds. No frantic motion
-- Transitions: Cross-Warp Morph (elegant, organic flow between scenes)
-
-**GSAP signature:** `sine.inOut`, `power1`. Nothing snaps — everything glides with intention.
-
-```
-Velvet Standard: Black, white, one rich accent. Thin ALL CAPS type with wide tracking.
-Generous negative space. Sequential reveals, long holds.
-Cross-Warp Morph transitions. Slow and deliberate — luxury takes its time.
+```yaml
+name: Velvet Standard
+colors:
+  primary: "#0a0a0a"
+  on-primary: "#ffffff"
+  accent: "#1a237e"
+typography:
+  headline:
+    fontFamily: Inter
+    fontSize: 3rem
+    fontWeight: 300
+    letterSpacing: 0.15em
+    textTransform: uppercase
+  body:
+    fontFamily: Inter
+    fontSize: 1rem
+    fontWeight: 300
+    lineHeight: 1.6
+rounded:
+  sm: 0px
+  md: 2px
+spacing:
+  sm: 16px
+  md: 32px
+  lg: 64px
+motion:
+  energy: calm
+  easing:
+    entry: "sine.inOut"
+    exit: "power1.in"
+    ambient: "sine.inOut"
+  duration:
+    entrance: 1.2
+    hold: 3.0
+    transition: 1.5
+  atmosphere:
+    - subtle-grain
+    - hairline-rules
+  transition: cross-warp-morph
 ```
 
+Generous negative space. Symmetrical, centered, architectural precision. Thin sans-serif, ALL CAPS, wide letter-spacing. Sequential reveals with long holds. Nothing snaps — everything glides with intention. Luxury takes its time.
+
 ---
 
 ## 3. Deconstructed — Neville Brody
 
 **Mood:** Industrial, raw | **Best for:** Tech news, developer launches, security products, punk-energy reveals
 
-- Dark grey (`#1a1a1a`), rust orange (`#D4501E`), raw white (`#f0f0f0`)
-- Type at angles, overlapping edges, escaping frames. Bold industrial weight
-- Gritty textures: scan-line effects, glitch artifacts baked into the design
-- Text SLAMS and SHATTERS. Letters scramble then snap to final position
-- Transitions: Glitch shader or Whip Pan (breaks the rules, feels aggressive)
-
-**GSAP signature:** `back.out(2.5)`, `steps(8)`, `elastic.out(1.2, 0.4)`. Intentional irregularity.
-
-```
-Deconstructed: Dark grey #1a1a1a + rust orange #D4501E. Type at angles, escaping frames.
-Scan-line glitch overlays. Text SLAMS and scrambles into place.
-Glitch shader transitions. Industrial and raw — nothing should feel polished.
+```yaml
+name: Deconstructed
+colors:
+  primary: "#1a1a1a"
+  on-primary: "#f0f0f0"
+  accent: "#D4501E"
+typography:
+  headline:
+    fontFamily: Space Grotesk
+    fontSize: 4rem
+    fontWeight: 700
+  label:
+    fontFamily: Space Mono
+    fontSize: 0.75rem
+    fontWeight: 700
+    textTransform: uppercase
+rounded:
+  none: 0px
+spacing:
+  sm: 4px
+  md: 12px
+  lg: 24px
+motion:
+  energy: high
+  easing:
+    entry: "back.out(2.5)"
+    exit: "steps(8)"
+    ambient: "elastic.out(1.2, 0.4)"
+  duration:
+    entrance: 0.3
+    hold: 1.0
+    transition: 0.5
+  atmosphere:
+    - scan-lines
+    - glitch-artifacts
+    - grain-overlay
+  transition: glitch
 ```
 
+Type at angles, overlapping edges, escaping frames. Bold industrial weight. Gritty textures: scan-line effects, glitch artifacts baked into design. Text SLAMS and SHATTERS. Letters scramble then snap to final position. Intentional irregularity — nothing should feel polished.
+
 ---
 
 ## 4. Maximalist Type — Paula Scher
 
 **Mood:** Loud, kinetic | **Best for:** Big product launches, milestone announcements, high-energy hype videos
 
-- Bold saturated: red (`#E63946`), yellow (`#FFD60A`), black, white — maximum contrast
-- Text IS the visual. Overlapping type layers at different scales and angles, filling 50–80% of frame
-- Everything is kinetic: slamming, sliding, scaling. 2–3 second rapid-fire scenes
-- Text layered OVER footage — never empty backgrounds
-- Transitions: Ridged Burn (explosive, dramatic, impossible to ignore)
-
-**GSAP signature:** `expo.out`, `back.out(1.8)`. Fast arrivals, hard stops.
-
-```
-Maximalist Type: Red, yellow, black, white — max contrast. Text IS the visual.
-Overlapping at different scales, 50-80% of frame. Everything in motion.
-Ridged Burn transitions. No static moments — kinetic energy throughout.
+```yaml
+name: Maximalist Type
+colors:
+  primary: "#0a0a0a"
+  on-primary: "#ffffff"
+  accent-red: "#E63946"
+  accent-yellow: "#FFD60A"
+typography:
+  headline:
+    fontFamily: Anton
+    fontSize: 8rem
+    fontWeight: 400
+    textTransform: uppercase
+  subhead:
+    fontFamily: Space Grotesk
+    fontSize: 3rem
+    fontWeight: 700
+rounded:
+  none: 0px
+spacing:
+  sm: 0px
+  md: 8px
+motion:
+  energy: high
+  easing:
+    entry: "expo.out"
+    exit: "back.out(1.8)"
+    ambient: "power3.out"
+  duration:
+    entrance: 0.3
+    hold: 0.8
+    transition: 0.4
+  atmosphere:
+    - type-layers
+    - color-blocks
+  transition: ridged-burn
 ```
 
+Text IS the visual. Overlapping type layers at different scales and angles, filling 50–80% of frame. Bold saturated colors — maximum contrast. Everything kinetic: slamming, sliding, scaling. 2–3 second rapid-fire scenes. No static moments. Fast arrivals, hard stops.
+
 ---
 
 ## 5. Data Drift — Refik Anadol
 
 **Mood:** Futuristic, immersive | **Best for:** AI products, ML platforms, data companies, speculative tech
 
-- Iridescent: deep black (`#0a0a0a`), electric purple (`#7c3aed`), cyan (`#06b6d4`)
-- Thin futuristic sans-serif — floating, weightless, minimal
-- Fluid morphing compositions. Extreme scale shifts (micro → macro)
-- Particles coalesce into numbers. Light traces data paths through the frame
-- Transitions: Gravitational Lens or Domain Warp (otherworldly distortion)
-
-**GSAP signature:** `sine.inOut`, `power2.out`. Smooth, continuous, organic. Nothing hard.
-
-```
-Data Drift: Deep black #0a0a0a with electric purple #7c3aed and cyan #06b6d4.
-Thin futuristic type, minimal text. Particles coalesce into numbers.
-Gravitational Lens or Domain Warp transitions. Fluid, immersive, otherworldly.
+```yaml
+name: Data Drift
+colors:
+  primary: "#0a0a0a"
+  on-primary: "#e0e0e0"
+  accent-purple: "#7c3aed"
+  accent-cyan: "#06b6d4"
+typography:
+  headline:
+    fontFamily: Inter
+    fontSize: 2.5rem
+    fontWeight: 200
+    letterSpacing: 0.05em
+  body:
+    fontFamily: Inter
+    fontSize: 0.875rem
+    fontWeight: 300
+rounded:
+  sm: 4px
+  md: 12px
+  full: 9999px
+spacing:
+  sm: 16px
+  md: 32px
+  lg: 64px
+motion:
+  energy: moderate
+  easing:
+    entry: "sine.inOut"
+    exit: "power2.out"
+    ambient: "sine.inOut"
+  duration:
+    entrance: 1.0
+    hold: 2.5
+    transition: 1.5
+  atmosphere:
+    - particle-field
+    - light-traces
+    - radial-glow
+  transition: gravitational-lens
 ```
 
+Thin futuristic sans-serif — floating, weightless, minimal. Fluid morphing compositions. Extreme scale shifts (micro → macro). Particles coalesce into numbers. Light traces data paths through the frame. Smooth, continuous, organic. Nothing hard.
+
 ---
 
 ## 6. Soft Signal — Stefan Sagmeister
 
 **Mood:** Intimate, warm | **Best for:** Wellness brands, personal stories, lifestyle products, human-centered apps
 
-- Warm amber (`#F5A623`), cream (`#FFF8EC`), dusty rose (`#C4A3A3`), sage green (`#8FAF8C`)
-- Handwritten-style or humanist serif fonts. Personal, lowercase, delicate
-- Close-up framing feel: single element fills the frame. Nothing feels corporate
-- Slow drifts and floats, never snaps. Soft organic motion throughout
-- Transitions: Thermal Distortion (warm, flowing, like heat shimmer)
-
-**GSAP signature:** `sine.inOut`, `power1.inOut`. Everything breathes.
-
-```
-Soft Signal: Warm amber, cream, dusty rose, sage green. Humanist or handwritten type.
-Single elements fill the frame — intimate, never corporate.
-Slow drifts and floats throughout. Thermal Distortion transitions.
-Nothing should feel hurried or polished.
+```yaml
+name: Soft Signal
+colors:
+  primary: "#FFF8EC"
+  on-primary: "#2a2a2a"
+  accent-amber: "#F5A623"
+  accent-rose: "#C4A3A3"
+  accent-sage: "#8FAF8C"
+typography:
+  headline:
+    fontFamily: Playfair Display
+    fontSize: 3rem
+    fontWeight: 400
+    fontStyle: italic
+  body:
+    fontFamily: Inter
+    fontSize: 1rem
+    fontWeight: 300
+    lineHeight: 1.7
+rounded:
+  sm: 8px
+  md: 16px
+  lg: 24px
+  full: 9999px
+spacing:
+  sm: 12px
+  md: 24px
+  lg: 48px
+motion:
+  energy: calm
+  easing:
+    entry: "sine.inOut"
+    exit: "power1.inOut"
+    ambient: "sine.inOut"
+  duration:
+    entrance: 1.0
+    hold: 3.0
+    transition: 1.5
+  atmosphere:
+    - soft-gradient
+    - warm-grain
+  transition: thermal-distortion
 ```
 
+Handwritten-style or humanist serif fonts. Personal, lowercase, delicate. Close-up framing: single element fills the frame. Slow drifts and floats, never snaps. Soft organic motion. Nothing should feel hurried or polished. Intimate, never corporate.
+
 ---
 
 ## 7. Folk Frequency — Eduardo Terrazas
 
 **Mood:** Cultural, vivid | **Best for:** Consumer apps, food platforms, community products, festive launches
 
-- Vivid folk: hot pink (`#FF1493`), cobalt blue (`#0047AB`), sun yellow (`#FFE000`), emerald (`#009B77`)
-- Bold warm rounded type. Pattern and repetition — folk art rhythm and density
-- Layered compositions with rich visual texture. Every frame feels handcrafted
-- Colorful motion: elements bounce, pop, and spin into place with joy
-- Transitions: Swirl Vortex or Ripple Waves (hypnotic, celebratory)
-
-**GSAP signature:** `back.out(1.6)`, `elastic.out(1, 0.5)`. Overshoots feel intentional.
-
-```
-Folk Frequency: Hot pink #FF1493, cobalt blue, sun yellow, emerald. Bold rounded type.
-Pattern and repetition throughout. Layered, dense, handcrafted feeling.
-Swirl Vortex or Ripple Waves transitions. Joyful, celebratory energy.
+```yaml
+name: Folk Frequency
+colors:
+  primary: "#ffffff"
+  on-primary: "#1a1a1a"
+  accent-pink: "#FF1493"
+  accent-blue: "#0047AB"
+  accent-yellow: "#FFE000"
+  accent-green: "#009B77"
+typography:
+  headline:
+    fontFamily: Fredoka One
+    fontSize: 4rem
+    fontWeight: 400
+  body:
+    fontFamily: Nunito
+    fontSize: 1rem
+    fontWeight: 600
+rounded:
+  sm: 8px
+  md: 16px
+  lg: 32px
+  full: 9999px
+spacing:
+  sm: 8px
+  md: 16px
+  lg: 32px
+motion:
+  energy: high
+  easing:
+    entry: "back.out(1.6)"
+    exit: "elastic.out(1, 0.5)"
+    ambient: "sine.inOut"
+  duration:
+    entrance: 0.5
+    hold: 1.5
+    transition: 0.8
+  atmosphere:
+    - pattern-tiles
+    - confetti-burst
+    - color-blocks
+  transition: swirl-vortex
 ```
 
+Bold warm rounded type. Pattern and repetition — folk art rhythm and density. Layered compositions with rich visual texture. Every frame feels handcrafted. Colorful motion: elements bounce, pop, spin into place with joy. Overshoots feel intentional. Celebratory energy.
+
 ---
 
 ## 8. Shadow Cut — Hans Hillmann
 
 **Mood:** Dark, cinematic | **Best for:** Security products, dramatic reveals, investigative content, intense launches
 
-- Near-monochrome: deep blacks (`#0a0a0a`), cold greys (`#3a3a3a`), stark white + blood red (`#C1121F`) or toxic green (`#39FF14`)
-- Sharp angular text like film noir title cards. Heavy contrast, no softness
-- Heavy shadow — elements emerge from darkness. Reveal is the narrative
-- Slow creeping push-ins, dramatic scale reveals, silence before the hit
-- Transitions: Domain Warp (dissolves reality itself before revealing the next scene)
-
-**GSAP signature:** `power4.in` for exits, `power3.out` for dramatic reveals. The pause before the hit matters.
-
-```
-Shadow Cut: Deep blacks #0a0a0a, cold greys, stark white + one accent (blood red or toxic green).
-Sharp angular type, film noir aesthetic. Elements emerge from darkness.
-Slow creeping push-ins. Domain Warp transitions. The reveal IS the story.
+```yaml
+name: Shadow Cut
+colors:
+  primary: "#0a0a0a"
+  on-primary: "#f0f0f0"
+  surface: "#3a3a3a"
+  accent: "#C1121F"
+typography:
+  headline:
+    fontFamily: Oswald
+    fontSize: 4rem
+    fontWeight: 700
+    textTransform: uppercase
+  body:
+    fontFamily: Inter
+    fontSize: 0.875rem
+    fontWeight: 400
+rounded:
+  none: 0px
+  sm: 2px
+spacing:
+  sm: 8px
+  md: 16px
+  lg: 48px
+motion:
+  energy: moderate
+  easing:
+    entry: "power3.out"
+    exit: "power4.in"
+    ambient: "sine.inOut"
+  duration:
+    entrance: 0.8
+    hold: 2.5
+    transition: 1.2
+  atmosphere:
+    - deep-shadow
+    - vignette
+    - grain-overlay
+  transition: domain-warp
 ```
 
+Near-monochrome: deep blacks, cold greys, stark white + one blood accent. Sharp angular text like film noir title cards. Heavy contrast, no softness. Elements emerge from darkness — reveal is the narrative. Slow creeping push-ins, dramatic scale reveals. The pause before the hit matters. Domain Warp dissolves reality before the next scene.
+
 ---
 
 ## Mood → Style Guide
@@ -199,13 +433,11 @@ Slow creeping push-ins. Domain Warp transitions. The reveal IS the story.
 
 ## Creating Custom Styles
 
-These 8 styles are examples — not constraints. Create your own by:
+These 8 styles are starters — not constraints. Create your own:
 
 1. **Name it** after a designer, art movement, or cultural reference
-2. **Palette**: 2-3 colors max. Declare explicit hex values
-3. **Typography**: One family, two weights. State the role of each
-4. **Motion rules**: How fast? Snappy or fluid? Overshoot or precision?
-5. **Transition**: Which shader matches the energy?
-6. **What NOT to do**: 2-3 explicit anti-patterns for this style
+2. **Write YAML tokens** — `colors` (2–5 tokens), `typography` (2–3 scales), `rounded`, `spacing`, `motion` (energy + easing + duration + atmosphere + transition)
+3. **Add prose** — one paragraph describing the feel, what to do, what to avoid
+4. **Token references** — use `{colors.accent}`, `{typography.headline}` in component definitions
 
-The pattern: **named style → palette → typography → motion rules → transition → avoids.**
+The pattern: **YAML tokens (what) → prose rationale (why) → components (how they combine).**
diff --git a/skills/website-to-hyperframes/SKILL.md b/skills/website-to-hyperframes/SKILL.md
index 2233ffdae..0eb1f50b1 100644
--- a/skills/website-to-hyperframes/SKILL.md
+++ b/skills/website-to-hyperframes/SKILL.md
@@ -112,13 +112,13 @@ handoff link; it is source-code context only.
 
 ### Reference Files
 
-| File                                                    | When to read                                                                                                                                                   |
-| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [step-1-capture.md](references/step-1-capture.md)       | Step 1 — reading captured data                                                                                                                                 |
-| [step-2-design.md](references/step-2-design.md)         | Step 2 — writing DESIGN.md                                                                                                                                     |
-| [step-3-script.md](references/step-3-script.md)         | Step 3 — writing the narration script                                                                                                                          |
-| [step-4-storyboard.md](references/step-4-storyboard.md) | Step 4 — per-beat creative direction                                                                                                                           |
-| [step-5-vo.md](references/step-5-vo.md)                 | Step 5 — TTS, transcription, timing                                                                                                                            |
-| [step-6-build.md](references/step-6-build.md)           | Step 6 — building compositions with self-review                                                                                                                |
-| [step-7-validate.md](references/step-7-validate.md)     | Step 7 — lint, validate, snapshot, preview                                                                                                                     |
-| [techniques.md](references/techniques.md)               | Steps 4 & 6 — 10 visual techniques with code patterns (SVG drawing, Canvas 2D, 3D, typography, Lottie, video, typing, variable fonts, MotionPath, transitions) |
+| File                                                     | When to read                                                                                                                                                                   |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [step-1-capture.md](references/step-1-capture.md)        | Step 1 — reading captured data                                                                                                                                                 |
+| [step-2-design.md](references/step-2-design.md)          | Step 2 — writing DESIGN.md                                                                                                                                                     |
+| [step-3-script.md](references/step-3-script.md)          | Step 3 — writing the narration script                                                                                                                                          |
+| [step-4-storyboard.md](references/step-4-storyboard.md)  | Step 4 — per-beat creative direction                                                                                                                                           |
+| [step-5-vo.md](references/step-5-vo.md)                  | Step 5 — TTS, transcription, timing                                                                                                                                            |
+| [step-6-build.md](references/step-6-build.md)            | Step 6 — building compositions with self-review                                                                                                                                |
+| [step-7-validate.md](references/step-7-validate.md)      | Step 7 — lint, validate, snapshot, preview                                                                                                                                     |
+| [techniques.md](../hyperframes/references/techniques.md) | Steps 4 & 6 — 11 visual techniques with code patterns (SVG drawing, Canvas 2D, 3D, typography, Lottie, video, typing, variable fonts, MotionPath, transitions, audio-reactive) |
diff --git a/skills/website-to-hyperframes/references/step-3-script.md b/skills/website-to-hyperframes/references/step-3-script.md
index 28a0743cb..ea16e2294 100644
--- a/skills/website-to-hyperframes/references/step-3-script.md
+++ b/skills/website-to-hyperframes/references/step-3-script.md
@@ -6,91 +6,4 @@ The script is the backbone. Everything downstream — scene durations, animation
 
 Save as `SCRIPT.md` in the project directory.
 
-## Pacing
-
-- **2.5 words per second** is natural speaking pace
-- 15s = ~37 words. 30s = ~75 words. 60s = ~150 words
-- Leave room for pauses. Silence between sentences is a feature, not dead air
-- The script should feel SHORTER than the video — visual breathing room matters
-
-## Tone
-
-Write like a person, not a brochure:
-
-- Use contractions: "it's", "you'll", "that's", "we've"
-- Vary sentence length — short punchy phrases mixed with longer flowing ones
-- Read it out loud. If it sounds robotic, rewrite it
-- Avoid jargon unless the audience expects it
-
-## Number Pronunciation
-
-Write what you want the voice to say. TTS reads literally.
-
-| On the website | Write in script as                |
-| -------------- | --------------------------------- |
-| 135+           | more than one hundred thirty five |
-| $1.9T          | nearly two trillion dollars       |
-| 99.999%        | ninety nine point nine percent    |
-| 200M+          | over two hundred million          |
-| 10x            | ten times                         |
-| API            | A P I                             |
-| stripe.com     | stripe dot com                    |
-
-The visual can show the exact figure while the voice rounds it.
-
-## Structure
-
-For product videos from a website capture:
-
-1. **Hook** — what's surprising or impressive about this product? A bold claim, a provocative question, a contrast, or a striking number. This is the opening line. **Vary the hook type** — don't default to a stat every time.
-2. **Story** — what does the product do? Who uses it? Keep it concrete.
-3. **Proof** — stats, customer names, social proof. Real numbers from the website.
-4. **CTA** — what should the viewer do? "Start building at stripe dot com."
-
-Not every video needs all four. A 15-second social ad might be Hook + Proof + CTA. A 60-second product tour uses all four with more Story.
-
-## The Opening Line
-
-The most important sentence in the video. It must create tension, curiosity, or surprise in the first 3 seconds.
-
-Patterns that work:
-
-- **A bold claim**: "The financial infrastructure that powers the internet economy."
-- **A question that provokes**: "What if your database could think?"
-- **A contrast**: "Your AI agent already knows how to make videos. It just needs the right format."
-- **A number that shocks**: "Nearly two trillion dollars." (Use sparingly — not every video should open with a stat.)
-
-If the opening is generic ("Welcome to Stripe" / "Introducing our product"), start over.
-
-## Example
-
-From a 62-second product launch video (team reference):
-
-```
-Your AI agent already knows how to make videos.
-It just needs the right format.
-
-This is Hyperframes. An open source framework. HTML in, video out.
-
-A div is a keyframe. Data attributes are your timeline.
-CSS is your look. G-Sap is your animation engine.
-
-Anything a browser can render can be a frame in your video.
-
-CSS animations. G-Sap. Lottie. Shaders. Three.js.
-
-Drop in music, sound effects, footage — it all composes together.
-
-No new framework for the agent to learn.
-Just HTML.
-
-The agent writes it. The renderer captures every frame as MP4.
-It's deterministic. Identical outputs, every time.
-
-Give your agent the CLI. Tell it what to make.
-Watch it build.
-
-Hyperframes. Go make something.
-```
-
-Note: ~140 words for 62 seconds — that's 2.3 words/sec, leaving room for pauses and visual breathing.
+Read [../../hyperframes/references/narration.md](../../hyperframes/references/narration.md) for the full narration guide.
diff --git a/skills/website-to-hyperframes/references/step-4-storyboard.md b/skills/website-to-hyperframes/references/step-4-storyboard.md
index c802a4425..6db26bea4 100644
--- a/skills/website-to-hyperframes/references/step-4-storyboard.md
+++ b/skills/website-to-hyperframes/references/step-4-storyboard.md
@@ -4,7 +4,7 @@
 
 - **DESIGN.md** — your color palette, font rules, components, Do's/Don'ts. Every creative decision must be grounded in this brand identity. If it says "white backgrounds with purple accent" — plan light scenes, not dark moody ones.
 - **`capture/extracted/asset-descriptions.md`** — read EVERY line. This is your menu of available visuals. Each line describes what the image actually shows (e.g., "translucent ribbons in orange, pink, and purple on white background" or "a high-speed train under a dark starry sky"). Use these descriptions to decide which assets belong in which beat. Assets you don't understand from the description — view them directly before assigning.
-- **[techniques.md](techniques.md)** — 11 visual techniques (SVG path drawing, Canvas 2D art, CSS 3D, per-word typography, Lottie, video compositing, typing effect, variable fonts, MotionPath, velocity transitions, audio-reactive). Pick 2-3 per beat and specify them in the storyboard.
+- **[techniques.md](../../hyperframes/references/techniques.md)** — 11 visual techniques (SVG path drawing, Canvas 2D art, CSS 3D, per-word typography, Lottie, video compositing, typing effect, variable fonts, MotionPath, velocity transitions, audio-reactive). Pick 2-3 per beat and specify them in the storyboard.
 
 The storyboard is the creative north star. It tells the engineer exactly what to build for each beat — mood, camera, animations, transitions, assets, sound. Write it as if you're briefing a motion designer who's never seen the website.
 
@@ -24,12 +24,9 @@ Apple keynote register — economy of words, silence between sentences is a feat
 **Style basis:** DESIGN.md (brand colors, fonts, components from the captured site)
 ```
 
-**Global guardrails** (adapt to the brand):
+**Global guardrails** — read [video-composition.md](../../hyperframes/references/video-composition.md) first. It defines the medium rules: density, color presence, scale, frame composition, and how design.md is brand truth not layout spec. Then apply these capture-specific additions:
 
-- Push color presence. Muted is fine, flat is not. Every beat should have at least one color that pulls your eye.
-- Motion should be visible and intentional. Err toward more movement than feels safe — subtle reads as static at 30fps.
 - Use as many captured assets as the creative vision allows. Scatter framework icons around a dashboard. Layer enterprise photos behind stats. Use product screenshots as floating cards. The assets exist — use them generously.
-- Aim for 8-10 visual elements per beat, not 2-3. A great beat has: background texture, midground content, foreground accents, floating decorative elements, animated icons, SVG path drawings, particle effects, typographic details. It should feel DENSE and alive.
 - Use at least 2-3 different techniques from techniques.md per beat — not across the whole video, per beat. Don't default to basic fade/scale/opacity — mix in SVG path drawing, CSS 3D transforms, typing effects, counter animations, canvas procedural art. Each beat should feel like its own visual world.
 
 **Underscore/music direction** (if applicable):
@@ -63,18 +60,9 @@ Before writing any beats, audit every captured asset. Print this table:
 
 ## Per-Beat Direction
 
-Each beat is a WORLD, not a layout. Before writing CSS specs and GSAP instructions, describe what the viewer EXPERIENCES. The difference between a great storyboard and a mediocre one:
+Read [beat-direction.md](../../hyperframes/references/beat-direction.md) for the general beat template: concept, mood, animation choreography (energy verbs), transitions (shader vs CSS vs hard cut decision matrix), depth layers, SFX cues, rhythm planning, and velocity-matched transitions.
 
-**Mediocre:** "Dark navy background. '$1.9T' in white, 280px. Logo top-left. Wave image bottom-right."
-**Great:** "Camera is already mid-flight over a vast dark canvas. The gradient wave sweeps across the frame like aurora borealis — alive, shifting. '$1.9T' SLAMS into existence with such force the wave ripples in response. This isn't a slide — it's a moment."
-
-The first describes pixels. The second describes an experience. Write the second, then figure out the pixels.
-
-Each beat should have:
-
-### Concept
-
-The big idea for this beat in 2-3 sentences. What visual WORLD are we in? What metaphor drives it? What should the viewer FEEL? This is the most important part — everything else flows from it.
+In the capture pipeline, each beat also includes:
 
 ### VO cue
 
@@ -84,14 +72,6 @@ Which narration line plays over this beat.
 
 What the viewer sees — described cinematically, not as CSS specs. Use camera language (pan, zoom, drift, settle). Describe at least 5 visual elements, not just text + background. Think in layers — what's moving in the foreground, midground, background simultaneously?
 
-### Mood direction
-
-Cultural and design references, not hex codes:
-
-- "Geometric, rhythmic, precise. Think Josef Albers or Bauhaus color studies."
-- "Warm workspace. Nice notebook energy, not technical blueprint."
-- "Cinematic title sequence. The kind of opening where you lean forward."
-
 ### Assets
 
 Which captured files to use, referenced by filename:
@@ -100,64 +80,6 @@ Which captured files to use, referenced by filename:
 - "Logo: `capture/assets/svgs/stripe-logo.svg` — centered, fades in at 0.5s"
 - "Enterprise photo: `capture/assets/enterprise-accordion-hertz.png` — Ken Burns pan, 70% opacity overlay"
 
-### Animation choreography
-
-Specific motion verbs per element — not "it animates in" but HOW:
-
-| Energy        | Verbs                                         | Example                               |
-| ------------- | --------------------------------------------- | ------------------------------------- |
-| High impact   | SLAMS, CRASHES, PUNCHES, STAMPS, SHATTERS     | "$1.9T" SLAMS in from left at -5°     |
-| Medium energy | CASCADE, SLIDES, DROPS, FILLS, DRAWS          | Three cards CASCADE in staggered 0.3s |
-| Low energy    | types on, FLOATS, morphs, COUNTS UP, fades in | Counter COUNTS UP from 0 to 135K      |
-
-Every element gets a verb. If you can't name the verb, the element is not yet designed.
-
-### Transition
-
-How this beat hands off to the next. Specify the type and parameters.
-
-**When to pick which:**
-
-| Choose shader transition for                                                    | Choose CSS transition for                                                           | Choose hard cut for                                            |
-| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------- |
-| Reveals, big reaction shots, product/logo unveils, energy shifts, "wow" moments | Continuous camera-motion beats where the scene feels like one move broken into cuts | Rapid-fire lists, percussive edits on the beat, comedic timing |
-| Any moment the music/VO punctuates with a downbeat or SFX hit                   | Beats that ease from one composition into the next with shared motion vocabulary    | Sequences of 3+ quick tempo-matched switches                   |
-| Brand moments where the transition itself _is_ the visual                       | Minimal/editorial pacing                                                            | Anytime a 0.3-0.8s transition would feel too slow              |
-
-Rule of thumb: if the beat is the _centerpiece_ of the video, shader-transition into it. If the beat is connective tissue, CSS-transition. A brand reel of 5-7 beats usually wants 1-2 shader transitions (the hero reveal + the CTA) and the rest CSS or hard cuts — too many shader transitions flatten their impact.
-
-**CSS transitions** (choose from `skills/hyperframes/references/transitions/catalog.md`):
-
-- Velocity-matched upward: exit `y:-150, blur:30px, 0.33s power2.in` → entry `y:150→0, blur:30px→0, 1.0s power2.out`
-- Whip pan: exit `x:-400, blur:24px, 0.3s power3.in` → entry `x:400→0, blur:24px→0, 0.3s power3.out`
-- Blur through: exit `blur:20px, 0.3s` → entry `blur:20px→0, 0.25s power3.out`
-- Zoom through: exit `scale:1→1.2, blur:20px, 0.2s power3.in` → entry `scale:0.75→1, blur:20px→0, 0.5s expo.out`
-- Hard cut / smash cut (for rapid-fire sequences)
-
-**Shader transitions** (choose from `packages/shader-transitions/README.md`):
-
-- Cross-Warp Morph (organic, versatile) — 0.5-0.8s, power2.inOut
-- Cinematic Zoom (professional momentum) — 0.4-0.6s, power2.inOut
-- Gravitational Lens (otherworldly) — 0.6-1.0s, power2.inOut
-- Glitch (aggressive, high energy) — 0.3-0.5s
-- See `packages/shader-transitions/README.md` for the full API, available shaders, and setup
-
-**How velocity-matched CSS transitions work:**
-Exit the outgoing beat with an accelerating ease (power2.in or power3.in) plus a blur ramp. Enter the incoming beat with a decelerating ease (power2.out or power3.out) plus blur clear. The fastest point of both easing curves meets at the cut — the viewer perceives continuous camera motion, not two discrete animations. Match exit velocity to entry velocity within ~5% tolerance.
-
-### Depth layers
-
-What's in foreground, midground, and background. Every beat should have at least 2 layers:
-
-- "BG: dark navy fill + subtle radial glow. MG: stat cards with drop shadow. FG: brand logo bottom-right."
-
-### SFX cues
-
-What sounds at what moment:
-
-- "On the capture pulse — a soft, warm analog shutter click."
-- "Left side carries a faint low drone. On fold: drone cuts. Silence. Then a single clean chime."
-
 ---
 
 ## Production Architecture
diff --git a/skills/website-to-hyperframes/references/step-6-build.md b/skills/website-to-hyperframes/references/step-6-build.md
index 0021ccaf2..3a028e1a6 100644
--- a/skills/website-to-hyperframes/references/step-6-build.md
+++ b/skills/website-to-hyperframes/references/step-6-build.md
@@ -5,7 +5,7 @@
 - **DESIGN.md** — your color palette, fonts, components, and Do's/Don'ts. Every composition must use EXACT hex colors and font families from this file. If it says "white backgrounds" — use white, not dark.
 - **STORYBOARD.md** — the beat-by-beat plan you're executing. Each beat specifies assets, animations, transitions, and which techniques to use.
 - **`capture/extracted/asset-descriptions.md`** — when the storyboard assigns an asset to a beat, re-read the description to understand what it shows and how to position/style it correctly.
-- **[techniques.md](techniques.md)** — code patterns for the 10 visual techniques. When the storyboard says "SVG path drawing" or "per-word kinetic typography" — read the code pattern from this file and adapt it.
+- **[techniques.md](../../hyperframes/references/techniques.md)** — code patterns for the 10 visual techniques. When the storyboard says "SVG path drawing" or "per-word kinetic typography" — read the code pattern from this file and adapt it.
 - **transcript.json** — word-level timestamps that drive scene durations.
 
 **Split the work: spawn a sub-agent for each beat.** By this step your context is full of captured data, DESIGN.md, SCRIPT, STORYBOARD, and transcript. Building compositions on top of all that means the detailed rules below compete with thousands of tokens of prior work. Each sub-agent gets a fresh context focused on one beat — dramatically better output.