hyperframes/skills/product-launch-video/references/story-design.md

Story design — product launch video

Use this reference in Step 3 to write STORYBOARD.md and SCRIPT.md for a product launch, promo, feature reveal, or marketing video.

This file defines the story: what the video says, in what order, and why each frame exists. It does not define layout, visual effects, animation, or final markdown schemas. For exact file syntax, follow ../hyperframes-core/references/storyboard-format.md and ../hyperframes-core/references/script-format.md.

Read first

Read these inputs before writing:

1. hyperframes.json — locked brief: angle, length, aspect ratio, language.
2. frame.md — tone, mood, design system, and brand register.
3. capture/extracted/visible-text.txt — product facts, page copy, positioning, proof, CTA.
4. capture/extracted/asset-descriptions.md — the only source for captured asset inventory.
5. user_script.txt and VO_MODE, when present.

Do not inspect capture/assets/, contact sheets, screenshots, or raw captured files during Step 3. Treat asset-descriptions.md as the canonical asset list. Do not invent asset filenames.

Output

Create two files:

• STORYBOARD.md — the narrative plan, one frame per beat.
• SCRIPT.md — the locked narration, only for spoken frames.

Every storyboard frame must include the required fields from the storyboard format reference, plus the narrative metadata below.

Core rule

A website is an information layout. A video is an emotional sequence.

Do not follow page order. Reorder, merge, omit, and reshape captured content into a clear launch story.

Step 3 method

1. Extract the product truth

From the brief and captured text, identify:

• Audience — who the video is speaking to.
• Pain or desire — what the viewer already wants fixed or achieved.
• Promise — the one-line thesis of the video.
• Product role — what the product does in the story.
• Proof — features, UI moments, metrics, logos, examples, or demos.
• CTA — what the viewer should do next.

Write the storyboard around the promise, not around a list of features.

2. Match the register to frame.md

Use frame.md as a soft guide:

frame.md signal	Story effect
restrained, editorial, B2B	plain, confident, low-hype script
bold, kinetic, launch-like	short hooks, punchier beats
warm, human, playful	friendly direct address, lighter phrasing
premium, cinematic, spectacle	aspirational framing, fewer words

The product truth decides the arc. The visual system tunes the voice.

3. Choose one outer arc

Pick one primary arc. Use a compound only when useful, e.g. PAS with feature-benefit progression.

Arc	Use when	Beat order	Reveal timing
PAS	The pain is known and urgent. Best for broken B2B workflows.	hook → pain → agitation → solution tease → product intro → proof/demo → CTA	late
Future Pacing	The product sells a new future, category, or paradigm.	imagine → name product → remove pain → show mechanism → show outcome → CTA	early
Demo Loop	The UI is self-explanatory and the product is best shown working.	question → product intro → demo cycle 1 → demo cycle 2 → trust/benefit → CTA	early
BAB	The product bridges an old workflow to a better one.	before → after tease → bridge/product → step 1 → step 2 → step 3/wow → CTA	early-mid
Feature-Benefit Cascade	The product is feature-rich or desire/status-driven.	product/category hook → feature → benefit → feature → benefit → climax → CTA	frame 1

Use feature-benefit rhythm inside any arc when the video has many capabilities. Do not stack several features without translating them into viewer value.

4. Build the frame sequence

Each frame needs one clear job. Avoid frames that only say “more benefits” or “another feature.”

Use these frame types:

hook | pain_point | product_intro | feature_showcase | benefit_highlight | social_proof | branding | cta

For every frame, define:

• type — one of the allowed frame types.
• persuasion — the specific persuasion move.
• beat — the viewer emotion.
• scene — a one-line visual idea, not detailed composition.
• voiceover — spoken guide text, or empty for silent frames.
• asset_candidates — real captured assets that could support the frame.

The prose under each frame should state:

• narrativeRole — why this frame exists in the story.
• keyMessage — the one idea the viewer should remember.

Hook strategy

Pick one opening strategy for the first 3-5 seconds:

Strategy	Use when
Shocking statistic	A credible number proves the pain.
Pain validation	The audience already knows the problem.
Rhetorical question	You need curiosity and speed.
Direct address	The audience is clear and specific.
Imagine / future pacing	The product introduces a new future.
Category announcement	The product is the category or launch headline.
Visual spectacle	The aesthetic is part of the pitch.
Trend positioning	The product rides a timely market shift.

The hook must create tension, curiosity, or desire. Do not open with generic company description.

Persuasion labels

Use concrete labels. Do not write generic labels like “show benefit.”

Good labels include:

• Pain agitation
• Cognitive overload
• Negative contrast
• Friction reduction
• Simplification
• Show-don’t-tell proof
• Demonstration of capability
• Feature-to-benefit translation
• Statistical proof
• Authority by association
• Social proof
• Risk reversal
• Future pacing
• Value stacking
• Empowerment and control
• Rule of three
• Scarcity / urgency
• Status seeking

When no label fits, create one and explain the mechanism in the frame prose.

Emotional beats

Use specific emotions:

• Negative: anxiety, frustration, overwhelm, tension, urgency, skepticism, FOMO
• Pivot: relief, curiosity, clarity, intrigue, aspiration
• Build: trust, confidence, control, ease, power, awe, excitement, belonging, reassurance
• Close: triumph, motivation, urgency-to-act, peace of mind, inevitability

Compound beats are allowed, e.g. relief + control.

Asset candidates

asset_candidates is the handoff from Step 3 to visual design and frame building.

Rules:

1. Read only capture/extracted/asset-descriptions.md to know what assets exist.
2. Use only filenames listed there.
3. Write candidates as assets/<basename>, where <basename> is the captured file basename.
4. Put all candidates on one line.
5. Separate candidates with semicolons.
6. Add a short description after —.
7. Prefer [video] assets when motion proves the product better than a still.
8. Use content assets: UI, screenshots, product photos, charts, diagrams, demos.
9. Skip tiny icons, favicons, badges, decorative chrome, and repeated logo variants unless the frame needs them.
10. Pure typography frames may use an empty asset list.

Example:

- asset_candidates: assets/dashboard-hero.png — main analytics UI, dark dashboard, wide screenshot; assets/demo-loop.mp4 — product interaction clip, query to result flow

Do not use nested lists for assets. The parser expects a single metadata line.

UI demos

A UI demo should usually be a sequence, not one isolated frame.

Use 3 or more consecutive feature_showcase / benefit_highlight frames on the same product surface when the product value depends on workflow or interaction.

Good demo rhythm:

1. Input or user action.
2. Product response.
3. Result, insight, automation, or saved effort.
4. Benefit or trust proof.

Use consistent transitions across the sequence so it feels like one flow.

Script rules

If there is no pasted script

Write tight per-frame narration:

• 1-2 sentences per spoken frame.
• Usually 6-20 words per frame.
• Concrete and human.
• Say what the product does for a person.
• Prefer active verbs.

Avoid:

• “Seamless experience.”
• “Unlock the power of...”
• “Streamline your workflow.”
• Long noun-phrase lists.
• A whole frame with only “Or...” or another filler bridge.

Silent frames are allowed when the visual proves the point. Leave them out of SCRIPT.md.

If VO_MODE = restructure

Treat user_script.txt as source material. Rewrite, reorder, merge, or omit to fit the chosen arc and target length.

If VO_MODE = verbatim

Do not rewrite the user’s words. Segment the script into frame-sized chunks at sentence or paragraph boundaries. You may split a long sentence at a natural clause boundary, but do not change words. The final duration follows the provided script.

Transitions

Use only registry transition names:

cut | crossfade | blur-crossfade | push-slide LEFT | push-slide RIGHT | push-slide UP | push-slide DOWN | zoom-through | squeeze

Pick 2-3 transition types for the whole video and repeat them. Frame 1 can use cut as a placeholder.

Frame template

Use the exact fields required by the core storyboard format. This is the narrative shape each frame should satisfy:

## Frame N — Short name

- scene: one clear visual idea
- voiceover: "spoken guide text, or empty"
- duration: rough estimate in seconds
- transition_in: cut
- status: outline
- src: compositions/frames/NN-short-name.html
- type: hook
- persuasion: Pain validation
- beat: urgency
- asset_candidates: assets/example.png — short asset description

narrativeRole: What this frame does in the viewer journey.
keyMessage: The one idea the viewer should remember.

Final checklist

Before asking for user approval, verify:

• The arc is named and consistent.
• The sequence is narrative-driven, not page-order-driven.
• The opening uses a clear hook strategy.
• Each frame has one job.
• Every frame has type, persuasion, and beat.
• Every visual frame has suitable asset_candidates, unless intentionally typography-only.
• Asset filenames come only from capture/extracted/asset-descriptions.md.
• UI/product demos use a multi-frame sequence when needed.
• Transitions use only registry names and repeat 2-3 types.
• SCRIPT.md contains only locked spoken narration.
• Silent frames are intentional and omitted from SCRIPT.md.