HyperFrames Creative Direction

You decide what a HyperFrames video looks and sounds like before anyone writes a line of composition HTML: the brand system, the palette and type, the story order, the beats and their rhythm, the narration, and how the build is checked against all of it. The standard is a produced film, not a web page that moves: brand values quoted exactly, frames composed for video scale, every beat traceable to the message, and nothing added that the owner did not ask for.

Motion itself (atomic animation rules, scene blueprints, transitions, easing recipes) belongs to hyperframes-animation. The composition contract (data-* timing, clips, sub-compositions, determinism) belongs to hyperframes-core. Load either with skill_view when you reach that part of the job.

When to use

• "Make a launch video / promo / explainer for our product", before the first scene is built.
• "Use our brand colors and fonts", "make it look like our site", "set up a design system for the video".
• "Give me a few looks to choose from" or "what style should this be?"
• "Write the voiceover script", "how long should the narration be?"
• "Plan the scenes", "storyboard this first", "the pacing feels off".
• "Make the visuals react to the music."
• "It looks generic / like a slide deck / like a web page": a creative review of an existing composition.

What you need

• Run the check in references/setup.md first, every time: installs outside /home/user are lost when the computer is rebuilt.
• The brief: the message (one sentence, a claim), the audience, the destination (YouTube or a site embed is 16:9; an X, LinkedIn or Instagram feed is 1:1; Shorts, Reels or TikTok is 9:16), the length, and whether there is voiceover, music and captions. Ask with clarify for anything missing that changes the design; do not guess the destination.
• Brand inputs: a design spec already in the project; otherwise the owner's site (read it with web_extract, or your browser if it needs the owner's sign-in), a brand guide, or a logo file the owner sends. If none exist, say so and propose a direction instead of inventing a "brand".
• The source material when the video is about something concrete (product page, PR, article, data): it supplies the props, numbers and words.
• The job folder ~/Desktop/<your name> - Work space/<job>/. This skill's files are not on your computer: fetch any file with skill_view (name hyperframes-creative, file_path references/... or scripts/...) and write_file it into the job folder.

Method

1. Read the two overriding references first for anything beyond a one-line edit: references/house-style.md ("interpret the prompt, generate real content", the lazy defaults to question, the background layer) and references/video-composition.md (video scale, density, color presence, frame composition). They override web instincts. Skipping them is the biggest single cause of generic, web-page-looking output.
2. Resolve the design spec once. Read the first that exists in the project root: frame.md, then design.md, then DESIGN.md (references/design-spec.md). Frontmatter is normative: quote hex values, font families and weights verbatim, never rounded or "improved". Prose is context for judgment. The spec is brand, not layout: strict on colors, fonts, weight relationships and Do's/Don'ts, free on composition.
3. No spec and the job needs visual direction: pick one route and write the result to the project root as frame.md or design.md.
   • The owner names a mood or reference ("cinematic", "Swiss", "playful") → a named style in references/visual-styles.md, its YAML block as frontmatter plus the prose sections.
   • The brief wants a finished system fast, or a code / launch / editorial piece → a frame preset (references/frame-presets/). Render two or three showcases to PNG, look at them with vision_analyze, adopt one as frame.md and overlay the brand's exact values.
   • The owner wants a say in the look → the design picker (references/design-picker.md): render the boards, show the best 3 or 4 on a show_card (type media), ask with clarify, write the chosen design.md.
   • The owner said "you decide" and there is no brand → house style: declare one background, one foreground and one accent from a palette in references/palettes/, plus a serif + sans (or sans + mono) pairing from references/typography.md. A minimal technical composition (a test clip, a one-line title) needs no design system; don't force one.
4. Fix the story order for narrated, story-driven pieces (references/story-spine.md): the hook speaks outcome language, the value claim lands by beat 2, every later beat is evidence, every visual traces to the source.
5. Plan beats and rhythm before any HTML (references/beat-direction.md). Each beat gets a concept, mood references, a verb for every element, depth layers, a transition out and any sound cue. Count beats from the length: 1.5 to 3.5 s per beat, so a 30 s film carries roughly 8 to 15 beats, fewer when beats must be read. Name the rhythm in one line (hook-PUNCH-breathe-CTA) and put the peak where the narration's heaviest emphasis lands. Shader transitions go to the centerpiece moments, 1 or 2 in a 5 to 7 beat reel.
6. Write the narration when there is a voiceover (references/narration.md): 2.5 words per second, so 75 words for 30 s and fewer if visuals need room; write numbers as they should be spoken; vary the hook type. Get the owner's approval on the words, generate with text_to_speech, then measure the real duration and fit the beats to it.
7. Expand the brief for every multi-scene piece (references/prompt-expansion.md): rhythm, global rules, per-scene beats with atmosphere layers, ambient motion, micro-details and exact tokens, written to .hyperframes/expanded-prompt.md. Show the rhythm and one line per scene on a show_card and build only after the owner says go. When the brief asks for a storyboard, follow references/storyboard-recipe.md and review the rendered sheet with the owner.
8. Hand over to the build with the spec loaded: hyperframes-core for structure, hyperframes-animation for motion. While building, use the routing table below for the topic at hand; read only what the task needs.
9. Verify against the spec after the build: references/design-adherence.md, the contrast report, and snapshots checked with vision_analyze (see Checks).

Routing

Topic	Read
Adopt a ready-made frame preset as frame.md (optional)	references/frame-presets/ · references/design-spec.md
Default palettes, motion, typography, lazy defaults to question	references/house-style.md
Named style presets, mood-to-style routing	references/visual-styles.md
Palette color rows	references/palettes/*.md
Interactive choice of direction, rendered for the owner	references/design-picker.md · references/templates/design-picker.html
Composition patterns: picture-in-picture, text behind subject, title card, slide show	references/composition-patterns.md
Stats and infographic presentation	references/data-in-motion.md
Structured expansion of a brief	references/prompt-expansion.md
Video-medium density, scale, color, frame composition	references/video-composition.md
Per-beat direction, rhythm planning, transition timing	references/beat-direction.md
Post-build spec verification (colors, type, corners, spacing, depth)	references/design-adherence.md
High-level motion guardrails and load-bearing GSAP rules	references/motion-principles.md
Font selection, pairings, rendered-video type rules, embedding fonts	references/typography.md
Story doctrine: hook language, value before evidence, storyboard as proposal, source-traceable visuals	references/story-spine.md
Storyboard method and the review sheet; the STORYBOARD.md file format	references/storyboard-recipe.md · references/storyboard-format.md
Script pacing, tone, openings, number pronunciation	references/narration.md
Precomputed audio bands mapped to motion	references/audio-reactive.md
Preset caption skins filled from word timings	references/caption-skins.md
Computer setup, headless previews, running the scripts	references/setup.md

Scripts

Copy a script into the job folder first: skill_view with name hyperframes-creative and file_path scripts/<file>, then write_file the content to <job>/tools/<file> (for contrast-report.mjs, copy package-loader.mjs too, since it imports it). Then run it with terminal from the job folder.

• scripts/contrast-report.mjs: seeks the composition to N sample times, measures WCAG contrast of every text element against the real pixels behind it, writes contrast-report.json and an overlay sprite (magenta fails AA). Exits 1 on any AA failure. Run with HYPERFRAMES_SKILL_PKG_VERSION="$(npx --yes hyperframes --version)" HYPERFRAMES_SKILL_BOOTSTRAP_DEPS=1 node tools/contrast-report.mjs . --samples 10; it installs its helper packages into a temporary folder with install scripts disabled.
• scripts/extract-audio-data.py: per-frame RMS and frequency bands from any audio or video file, for audio-reactive work (needs FFmpeg and NumPy; see references/audio-reactive.md).
• scripts/package-loader.mjs: support module for contrast-report.mjs (pinned, script-free temporary installs).
• scripts/fill-caption-skin.py: fills a preset's caption skin with word groups, duration and brand tokens (see references/caption-skins.md).

Animation analysis (the animation map) lives in hyperframes-animation.

Output

Hand back files in the project, plus a short message to the owner:

• frame.md or design.md in the project root: frontmatter tokens (colors, typography, spacing, components) and prose (Overview, frame or layout rules, Do's and Don'ts), with one line saying where each brand value came from.
• .hyperframes/expanded-prompt.md for multi-scene work, and STORYBOARD.md + storyboard.html (+ storyboard.png) when a storyboard was asked for.
• The narration script with its word count and expected length, when there is a voiceover.
• The proposal, as a message and a show_card:

This video tells [audience] that [message].
Look: [preset / style / picker choice], [bg hex] / [fg hex] / [accent hex], [display font] + [body font]
Rhythm: [e.g. hook-PUNCH-breathe-proof-CTA], [N] beats, [length] s, [aspect]
01 · [beat name] · [s] · [what is on screen] · [why]
...
Sound: [voiceover yes/no] · [music yes/no, source and licence] · [captions yes/no]
Approve, or tell me what to change.

• After the build: the adherence checklist (violations found and fixed), the contrast summary (AA failures: 0), and the snapshot PNGs you checked, shown on a show_card (type media) with the file paths.

Checks before you finish

• The spec was resolved once and every hex, family and weight in the build appears in it (run the listing in references/design-adherence.md); no invented or rounded values.
• npx hyperframes lint and check pass; the contrast report shows no AA failure, or each one is a deliberate decorative element with no readable text.
• Snapshots at 3 to 5 moments, each checked with vision_analyze: at least two focal points, content anchored to edges rather than floating in the middle, headlines 60px+ and body 20px+ at 1920 wide (body 32px+ for feed destinations), the accent visible, the named fonts actually rendered (a serif that comes back as a plain sans means the font did not load).
• Every number on screen and in the narration comes from the brief, the owner or the source; placeholders remain where none was supplied, and you told the owner which.
• Narration word count fits the measured voice length; nothing important is spoken over a transition.
• No scene, narration, music, captions or transition was added that the brief did not ask for, unless the owner approved your proposal.
• Any font, music, sound or shader code you brought in has its licence checked and noted in the project's credits.

Pitfalls

• The generic web-page look: centered stacks, 14 to 16px text, 1px borders, 5% glows, identical card grids, gradient text, purple-to-blue gradients. Re-read the scale table in video-composition.md and the lazy defaults in house-style.md.
• Reaching for the same fonts: Inter, Playfair, Space Grotesk and friends by reflex, or two sans-serifs together. Run the font discovery script and pair across categories.
• Treating the spec as a layout: copying web card styling at web opacity. The brand values are sacred; the frame composition is yours.
• Unasked extras: extra scenes, a music bed, captions, narration or a fancy transition the brief did not request. Propose it; do not build it.
• A feature tour instead of a story: file names, feature lists or "23 files changed" in the hook; the value claim arriving at beat 5.
• Invented proof: made-up stats, customer names or UI. Use the source, or a labelled placeholder.
• Previews that lie: a headless screenshot without --virtual-time-budget shows fallback fonts; a showcase or picker judged from its code rather than its PNG.
• Sending the owner a link to a page served on your computer, or asking them to open a file there. They cannot reach it. Render a PNG, check it, and show it on a card.
• Equalizer bars and pulsing orbs for audio-reactive work: audio drives timing and intensity; the content decides the visual.
• Reading every reference for a small edit. Route by topic; a color fix needs design-spec.md, not the whole folder.

Boundaries

• Do not override hyperframes-core technical rules; when creative direction and the contract disagree, the contract wins and you adjust the design.
• Do not require a design system for a minimal technical composition.
• Do not add extra scenes, narration, music, captions, or transitions unless the request calls for them or you first propose the expansion and the owner agrees.
• Keep reference reads task-specific.
• Sourcing media (music, sound effects, images, icons, logos, voice transcription) is media-use; mixing placed audio is hyperframes-audio; turning a website into a launch video end to end is website-launch-video.