diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md index 390504fbc..85e6bbcf3 100644 --- a/skills/hyperframes/SKILL.md +++ b/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 diff --git a/skills/hyperframes/house-style.md b/skills/hyperframes/house-style.md index 6d5161552..fa7235067 100644 --- a/skills/hyperframes/house-style.md +++ b/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. diff --git a/skills/hyperframes/references/prompt-expansion.md b/skills/hyperframes/references/prompt-expansion.md index ece0bc2b3..c33b27f77 100644 --- a/skills/hyperframes/references/prompt-expansion.md +++ b/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.