feat(skills): require design.md first via visual-style skill

skills/hyperframes/SKILL.md

@@ -9,23 +9,38 @@ HTML is the source of truth for video. A composition is an HTML file with `data-
 
 ## Approach
 
-### Step 0a: Prompt expansion
+### Step 0a: Design system (always required, first)
 
-If the user's prompt lacks scene-by-scene structure, expand it into a full production prompt first. Read [references/prompt-expansion.md](references/prompt-expansion.md) for the full process and output format. Present the expanded prompt to the user for approval before proceeding.
+Run this BEFORE prompt expansion. Design direction shapes expansion output (atmosphere layers, motion energy, typography), so expanding first produces generic breakdowns that later ignore the palette.
 
-### Step 0b: Design system
+Every composition MUST have a `design.md` in the project root before construction. It is the source of truth for colors, typography, motion, spacing, and mood — every later step (expansion output, scene subagents, assembler) reads it.
 
-Check for a `design.md` in the project root. If one exists, read it — it defines colors, typography, motion, and mood for all compositions in this project.
+**Resolution order:**
 
-If none exists, **ask the user:**
+1. **Exists** — if `design.md` is already in the project root, read it and proceed to Step 1.
+2. **Build one via the `visual-style` skill** — invoke the `/visual-style` skill (Skill tool, `skill: "visual-style"`) in "Create" mode. Ask the user the batched vibe questions the skill prescribes (mood, palette, typography, energy), then have it emit a full design spec. Save the result to `design.md` in the project root.
+3. **Interactive picker (fallback)** — if the user prefers pre-built options instead of a guided build, read [references/design-picker.md](references/design-picker.md) and serve the picker.
+4. **House-style defaults (last resort)** — only if the user explicitly says "skip design" or this is a tiny edit to an existing composition without a design.md. In that case, follow [house-style.md](./house-style.md) and write its palette + typography into `design.md` so downstream steps have a file to read.
 
-> "Want to pick a visual style before we build? (yes = design picker, no = use defaults)"
-
-If yes → read [references/design-picker.md](references/design-picker.md) for the full picker workflow. If no → follow [house-style.md](./house-style.md) defaults.
+Do NOT begin prompt expansion or scene authoring without a `design.md`. Design direction affects expansion output (atmosphere layers, motion energy, typography choices) — expansion before design produces generic scene breakdowns that later ignore the palette.
 
 ### Using design.md during construction
 
-If a `design.md` exists (from Step 0b or provided by the user), it is the source of truth for all visual decisions. Use only the values it defines — colors, fonts, spacing, corners, depth, component treatments, and any other fields the user has added. Do not invent new colors, substitute fonts, or override its rules. If the composition needs a value the design.md doesn't cover, follow [house-style.md](./house-style.md) for that specific decision.
+`design.md` is the source of truth for all visual decisions. Use only the values it defines — colors, fonts, spacing, corners, depth, component treatments, and any other fields the user has added. Do not invent new colors, substitute fonts, or override its rules. If the composition needs a value the design.md doesn't cover, follow [house-style.md](./house-style.md) for that specific decision.
+
+**Passing design.md downstream:**
+
+- **Prompt expansion** — include the palette, typography, and mood/energy from design.md in the expanded prompt's style block. Every scene breakdown should reference the palette and note which decorative motifs belong.
+- **Scene subagents** — each subagent receives the full `design.md` (or a tight summary of its values). Fragment authors apply only these values; house-style decoratives are added WITHIN the design.md's palette constraints.
+- **Assembler** — reads design.md to populate any global CSS variables in the scaffold.
+
+### Step 0b: 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 — scene subagents, assembler, lint — reads the same way.
+
+Read [references/prompt-expansion.md](references/prompt-expansion.md) for the full process and output format. The expanded prompt quotes design.md's palette hex values, typography pair, and motion energy verbatim — it does not re-state generic defaults. Present the expanded prompt to the user for approval before proceeding.
+
+If the user's prompt is already scene-by-scene, the expansion is mostly pass-through, but it still binds the prompt to design.md and house-style — which is the contract the downstream steps depend on.
 
 ### Step 1: Plan
 

skills/hyperframes/house-style.md

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

skills/hyperframes/references/prompt-expansion.md

@@ -1,31 +1,54 @@
 # Prompt Expansion
 
-Expand a sparse user prompt into a full production prompt before proceeding with design and construction.
+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.
 
-## When to expand
+Runs AFTER `design.md` is established (Step 0a). The expansion consumes design.md and produces output that cites its palette, typography, and motion energy verbatim.
 
-A prompt needs expansion if it lacks: scene-by-scene structure, specific visual elements per scene, transition descriptions, or timing.
+## Prerequisites
 
-**Sparse:** "make me a trailer about a killer alien on a spaceship" or "coconut water promo, tropical, 45 seconds"
+Read before generating:
 
-**Already expanded:** Has numbered scenes with timing, specific elements, transition rules, and animation direction — skip this step.
+- `design.md` — palette, typography, energy, mood. The expansion quotes these values; it does not invent any.
+- [../house-style.md](../house-style.md) — its rules for Background Layer (2-5 decoratives), Color, Motion, Typography apply to every scene. The expansion does NOT re-state those rules; it writes output that conforms to them.
+
+If `design.md` doesn't exist yet, run Step 0a (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** — genre, visual style, format, color direction, typography direction, mood, audio feel
-2. **Global animation rules** — parallax layers, micro-motion requirements, kinetic typography, pacing rules, transition style
-3. **Scene-by-scene breakdown** — for each scene:
+1. **Title + style block** — cite design.md's palette (bg/fg/accent hex values), typography pairing, energy level, and mood. Do NOT invent a palette — quote the design.md values.
+2. **Global animation rules** — parallax layers, micro-motion requirements, kinetic typography, pacing rules, transition style. Align energy with design.md (calm → slow eases, high energy → snappy eases).
+3. **Scene-by-scene breakdown** — for each scene, enumerate:
    - Time range and title
-   - Specific visual elements (not generic — "alien claw slides across wall" not "scary things happen")
-   - Text/typography that appears with animation style
-   - Background, midground, foreground layer descriptions
-   - Transition to next scene as a specific morph (what object becomes what)
-4. **Recurring motifs** — visual threads that appear across multiple scenes
-5. **Transition rules** — every scene-to-scene connection described as object morphing
-6. **Pacing curve** — where energy builds, peaks, and releases
-7. **Negative prompt** — what to avoid
+   - **Background layer** — list the 2–5 decoratives (from house-style's list) with exact positioning, opacity values from design.md, and the ambient motion each uses (breath, drift, pulse, orbit). This is almost always richer than what the user's prompt specified — the user rarely lists atmosphere, you add it.
+   - **Midground** — content elements (not generic: "alien claw slides across wall" not "scary things happen"). Keep everything the user specified; add what's missing.
+   - **Foreground** — text, typography, animation style per text element. Type sizes and weights quoted from design.md.
+   - **Micro-details** — registration marks, tick indicators, monospace coord/meta labels, typographic accents, background data streams, grid patterns. These are what make a scene feel real. The user's prompt never lists them; expansion adds at least 2–3 per scene.
+   - **Transition out** — specific morph (what object becomes what, duration, ease), not just "cut" or "crossfade"
+4. **Recurring motifs** — visual threads that appear across multiple scenes, always drawn from design.md's palette and typography.
+5. **Transition rules** — every scene-to-scene connection described as object morphing. Transition duration/ease should match design.md's energy level.
+6. **Pacing curve** — where energy builds, peaks, and releases.
+7. **Negative prompt** — what to avoid for this specific composition.
 
 ## Output
 
@@ -35,6 +58,6 @@ 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 to the design picker."
+> 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 the design system step after the user approves or says to continue.
+Only move to construction after the user approves or says to continue.