/cue

Scenario Design Guidelines

Principles, templates, and best practices for demo video scenario design.

Purpose: Read this when Cue must design a story arc, tune pacing, select overlay timing, adapt the demo to an audience, or review scenario quality before recording.

Contents:

• 3-Second Layered Hook: hook design rules for 70% drop-off prevention
• Storytelling Structure: hook → pain → solution → result framing
• Show Don't Tell Techniques: B-roll, before/after split, caption-aware overlay
• Scenario Templates: full and quick planning templates
• Operation Granularity Design: step sizing rules for viewer comprehension
• Wait Strategy: explicit waits vs pacing pauses
• Overlay Display Patterns: overlay timing and style rules
• Audience-Specific Adjustments: new user, existing user, investor, developer variants
• Time Allocation Guidelines: duration guidance by scope (including 2-min engagement cliff)
• Platform Length Targets (2026): per-platform optimal lengths
• Cue vs AI Video Generators: when to record vs when to generate
• Scenario Anti-Patterns: must-avoid pacing and structure mistakes
• Test Data Realism: realism and privacy rules
• Scenario Review Checklist: pre-recording quality review

3-Second Layered Hook

TikTok / Reels / Shorts drop ~70% of viewers in the first 3 seconds. LinkedIn / YouTube are kinder but the principle holds: the first 3 seconds decide whether the demo gets watched at all. A layered hook (visual + textual + optional audio simultaneously) holds attention ~3× longer than a single-channel opening.

Hook Composition

Hook Templates

Hook Anti-Patterns

Show Don't Tell Techniques

Demos communicate value when viewers see the outcome — not when narration describes it. Cue patterns for 2026:

B-roll Overlay (70–85% opacity, 3–7s clips)

Cut to supporting footage (real product UI, data, mobile capture) at 70–85% opacity over a stable base scene. Holds visual interest while extending narration.

0:00–0:08  Base scene: dashboard (full opacity)
0:08–0:15  B-roll overlay: mobile capture of same data (75% opacity)
0:15–0:22  Base scene returns; B-roll dissolves out

Before / After Split-Screen

Legacy flow on left, new flow on right, synced timeline. Use for redesigns, migrations, AI-vs-manual comparisons.

• Sync points: shared start, shared end ("both reach the same outcome — one in 30s, one in 4 minutes").
• Letterbox the right side as the "after" loads to emphasize speed delta.

Caption-Aware B-roll Positioning

Open captions occupy bottom 15% of the frame. B-roll and overlays must avoid this band. CapCut / Descript auto-detect captions; if hand-authoring, reserve the bottom strip.

Speed Ramping

Boring middle sections (data loading, API roundtrips) get 2–4× speed-up. Critical reveals stay real-time. ffmpeg: setpts=0.5*PTS for 2× speed.

Cursor as Storyteller

The cursor is the camera. Move it deliberately:

• Hover before clicking (200–400ms) — signals intent.
• Slow approach to the Aha button.
• Cursor halo / pulse on key interactive elements (implementation-patterns.md → Cursor helpers).

Storytelling Structure

Design demos as stories, not operation sequences. Follow the Hook → Pain → Solution → Result → CTA arc.

Hook (0–3s)    Pain (3–10s)    Solution (10–40s)    Result (40–55s)    CTA (55–60s)
-----------    --------------  -------------------- -----------------  -------------
Layered hook   Show the broken Demonstrate the      Show the outcome   Single next
visual+text    workflow / cost / new way              & emotion          step
hook

Five-Act Application (60s default)

Skip phases as the archetype dictates (storytelling-archetypes.md): a 30s social hook collapses Pain into Hook; a 180s walkthrough expands Solution into multiple chapters.

Scenario Templates

Standard Template

## Demo Request: [Feature Name]

### Target Audience
- [ ] New users (onboarding)
- [ ] Existing users (new feature introduction)
- [ ] Investors / Stakeholders
- [ ] Sales / Marketing
- [ ] Internal documentation

### Demo Objective
What should viewers understand after watching this demo?
> [Describe in 1-2 sentences]

### Prerequisites
- Login state: [ ] Not logged in [ ] Logged in [ ] Admin
- Initial data: [Description of required data]
- Environment: [ ] Development [ ] Staging [ ] Demo-dedicated

### Story Flow

#### 1. Opening (5-10 seconds)
**Scene**: [First screen to display]
**Message**: [Context to convey to viewers]
**Overlay**: [ ] Yes [ ] No
> Overlay text: "[Text]"

#### 2. Main Action (20-40 seconds)
**Step list**:
1. [Action 1] -> [Expected result]
2. [Action 2] -> [Expected result]
3. [Action 3] -> [Expected result]

**Emphasis points**:
- [X seconds]: [What to emphasize]

#### 3. Closing (5-10 seconds)
**Scene**: [Final screen to display]
**Message**: [Impression to leave with viewers]
**Overlay**: [ ] Yes [ ] No
> Overlay text: "[Text]"

### Test Data Requirements
| Data Type | Content | Notes |
|-----------|---------|-------|
| User | demo@example.com | Display name: Demo User |

### Recording Settings
- Resolution: [ ] 1280x720 (recommended) [ ] 1920x1080 [ ] 375x667 (mobile)
- slowMo: [ ] 500ms (standard) [ ] 700ms (form-heavy) [ ] 1000ms (slow)
- Max duration: [XX] seconds
- Output formats: [ ] WebM [ ] MP4 [ ] GIF

Quick Template

## Quick Demo: [Feature Name]

**Audience**: [Who is this for?]
**Objective**: [What to convey?]
**Duration**: [XX seconds]

**Flow**:
1. [Screen] - [Action] - [Result]
2. [Screen] - [Action] - [Result]
3. [Screen] - [Action] - [Result]

**Test Data**: [Required data]
**Settings**: [Resolution] / slowMo [X]ms

Operation Granularity Design

// Bad: Too coarse (viewer can't follow)
await page.fill('#email', 'demo@example.com');
await page.fill('#password', 'password');
await page.click('#submit');

// Good: Appropriate granularity with locator-based waits
await page.locator('#email').pressSequentially('demo@example.com', { delay: 80 });
await expect(page.locator('#email')).toHaveValue('demo@example.com');

await page.locator('#password').pressSequentially('password', { delay: 80 });
await page.waitForTimeout(300); // Deliberate pacing pause

await page.click('#submit');
await expect(page.locator('#dashboard')).toBeVisible();

Wait Strategy

Prefer Locator-Based Waits for State Changes

Use waitForTimeout() only for deliberate pacing pauses. For all state changes, use explicit waits:

Pacing Pauses (waitForTimeout)

Use only for viewer comprehension — these are intentional delays, not state waits:

Overlay Display Time Formula

Overlay display time = (character count x 100ms) + 500ms

Example: "Login successful" (16 chars) = 16 x 100 + 500 = 2100ms

Overlay Display Patterns

Step Explanation Overlay

await showOverlay(page, 'Step 1: Enter email address', 2000);

Highlight Overlay

await showHighlight(page, '#submit-button', 'Click here!');

Success/Error Overlay

await showSuccessOverlay(page, 'Registration complete!');
await showErrorOverlay(page, 'An error occurred');

Overlay Style Guide

Audience-Specific Adjustments

For New Users

• Don't skip basic operations
• Avoid or explain technical terms
• Emphasize success experience

For Existing Users

• Quick basic operations
• Focus on new features
• Emphasize differences from previous version

For Investors/Stakeholders

• Emphasize business value
• Differentiation from competitors
• Imply scalability

For Developers

• Include technical details
• Show API integration
• Customization points

Time Allocation Guidelines

Duration by Scope

Engagement Benchmarks (2026)

Use these benchmarks to calibrate the duration budget, not as hard limits.

Self-Guided Embed Step Count

Platform-Adapted Pacing (2026)

Talking-Head Bias (B2B / Dev Tools)

For dev-tool and B2B Product Hunt launches, talking-head openers are a demerit. The 2026 industry-Top pattern (Cursor, Linear, Notion, Vercel) is "dashboard → workflow → after-state" without a presenter face. Use talking-head only for stakeholder/investor demos with founder-led VO where trust is the asset.

Cue vs AI Video Generators

Cue records real product UI. AI video generators (Sora 2, Veo 3.1, Runway Gen-4.5) generate footage from prompts. They are complementary, not competitive — pick the right tool per scene.

When the request mixes both, Cue records the real-UI segments; route the AI segments to an AI-video brief (out of Cue scope).

Scenario Anti-Patterns

Test Data Realism

• Fictional but realistic names and emails
• Meaningful numbers ($39.80 instead of $100)
• Use appropriate language for content
• Never use production data or real user information
• Keep data consistent across scenes

Scenario Review Checklist

Story

• Has clear starting point
• What viewer wants to achieve is clear
• Has satisfying conclusion

Pacing

• Uses locator-based waits for state changes
• Uses waitForTimeout only for deliberate pauses
• No redundant waits

Data

• Test data is realistic
• No confidential information included
• Data is consistent

Technical

• Reproducible scenario
• No flaky elements
• All selectors are stable

Output Routing (full table)

Canonical home for the signal-to-approach table summarized in SKILL.md.

Routing rules:

• If the request involves a specific device, viewport, or aspect ratio, read reference/demo-playwright-config.md.
• If the request involves storytelling, pacing, hook design, or audience tuning, read reference/demo-scenario-guidelines.md (and reference/demo-storytelling-archetypes.md for durations).
• If the request involves overlays, annotations, advanced patterns, or Vision-Model streaming, read reference/demo-implementation-patterns.md.
• If the request involves AI citation, transcript schema, or GEO, read reference/demo-geo-packaging.md.
• If the request involves numeric quality verdict or reshoot decision, read reference/demo-quality-metrics.md.
• If a handoff is inbound from Forge/Voyager/Vision/Echo or outbound to Vitrine/Quill/Growth, read reference/demo-handoff-formats.md.
• Always read reference/demo-checklist.md in the Deliver phase.

Per-Recipe Behavior Notes

Referenced from SKILL.md -> Subcommand Dispatch.

• demo: Produce a feature demo video end-to-end with Playwright, from scenario design to recording.
• scenario: Pre-design persona, archetype (30/60/90/180s), 3-sec layered hook, Aha moment, and duration, then output a scenario document.
• record: Fix Playwright settings (slowMo / viewport / codec / aspect) and execute recording with page.screencast.
• onboard: Record the user's first-time flow at deliberate pacing to produce an onboarding clip.
• aspects: Drive a single scenario through multiple aspect-tuned viewports (16:9 = 1920×1080, 9:16 = 1080×1920, 4:5 = 1080×1350, 1:1 = 1080×1080), re-frame overlays, and emit one demo per channel.
• vision: Use page.screencast onFrame to stream JPEG frames to a Vision Model (GPT-4o vision / Claude vision) for agentic loops, live narration, or QA-by-vision.
• quality: Run ffmpeg-quality-metrics to compute VMAF / PSNR / SSIM against a baseline, verify LUFS ≤ -14 (YouTube/LinkedIn) or -16 (Web), and audit WCAG 1.2.2 / 1.2.4 / 1.2.5 status. Emit a numeric reshoot verdict.
• geo: Package transcript (.vtt + plaintext), chapter cue map, and VideoObject JSON-LD schema for AI Overviews / ChatGPT / AI Mode citation. Pairs with captions and voiceover.
• voiceover: Produce narration script with SSML timing (150-160 WPM), voice selection (Inworld Realtime TTS 1.5-Max #1, ElevenLabs v3 with Audio Tags, Cartesia Sonic-3 for low latency, OpenAI Realtime TTS), de-essing + breathing pauses, and -14 / -16 LUFS normalization. Sync audio to Playwright timeline via ffmpeg.
• captions: Author SRT / WebVTT captions via GPT-4o-Transcribe (WER 4.1%) or Whisper-large-v3 with manual QC. ≤42 chars/line, ≤2 lines, ≥1s / ≤7s per cue, reading speed ≤17 CPS. WCAG 1.2.2 + 1.2.5 compliance. Forced vs closed vs open vs burned-in variant selection.
• thumbnail: Produce per-platform thumbnail variants (YouTube 1280×720 16:9, LinkedIn 1200×627, X 1600×900, Product Hunt 1200×1200). 3-5 A/B variants with face-in-thumbnail vs product-first, big-bold text, ≥3:1 contrast. For B2B / dev-tool niches, default to product-first (data: outperforms face-first at 300K sample).