mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-03 04:38:33 +00:00

Files

T

WaterrrForever 17b852784b feat(skills): mode-first briefs, value-first storyboards, and destination defaults across creation workflows (#2058 )

* feat(skills): add brief contract — interaction modes + shared intake fields across workflows

New hyperframes-core/references/brief-contract.md, the shared intake
contract every creation workflow now runs its brief against:

- §1 interaction mode: collaborative (default) vs autonomous, ongoing
  vs one-time signals, mode set once and carried forward, and a gate
  taxonomy (preference / checkpoint / quality / routing) — autonomous
  skips waiting, never verification
- §2 field registry: destination→aspect derivation (feed → 1:1,
  Shorts/TikTok → 9:16, else 16:9), message, angle, length, audience,
  language, narration — each workflow binds fields as ask or state
- §3 question rules: one round with one question per asked field
  (native question UI mandatory when available, recommended option
  first with a receipt), never drop a question as inferable, and a
  mode legend advertised in the intro text instead of asked

Wired into the surfaces:

- hyperframes router: detect mode at entry, derive aspect from
  destination instead of stating 16:9
- product-launch-video / pr-to-video / faceless-explainer: ask/state
  binding tables at Step 0; Step 3/6 checkpoint-gate branches
  (autonomous posts a heads-up with a preview hint before render)
- website-to-video: local mode definition now defers to the contract
- music-to-video, general-video, embedded-captions, talking-head-recut,
  slideshow, motion-graphics: mode semantics wired per gate type
- storyboard-format: new optional 'mode' frontmatter key
- pr-to-video: length tier is a ceiling, not a floor — a one-headline
  PR recommends inside the 30–90s sweet spot regardless of diff size

* feat(skills): story spine + mode-first brief across creation workflows

Story — the reverse-iceberg feedback:

- New hyperframes-creative/references/story-spine.md, three rules for
  the narrated workflows: the hook speaks the viewer's outcome
  language, the value claim lands by beat 2 (implementation is the
  footnote of the story, not the spine), and the storyboard is
  presented as a proposal — 'This video tells [audience] that
  [message]' plus a per-frame why: drawn from narrativeRole
- pr-to-video: feature-reveal reordered promise-first (impact leads,
  diff/mechanism follow as evidence); hooks ban file/function names;
  fix-explainer, refactor-walkthrough, changelog unchanged
- product-launch-video / faceless-explainer hook rules aligned to the
  spine; website-to-video's beat summary gains the echo line + why:;
  general-video points at the spine from its plan step

Brief — hardened after live-test drift:

- Mode is now the first question (Collaborative recommended vs
  Autonomous), its own round, skipped when the request carries a
  signal; autonomous asks nothing further until one final
  preview-or-render question before render
- Step 0 rewritten as a literal two-round question script in each
  shot-sequence workflow (website-to-video's editorial register,
  channel-agnostic); brief-contract.md §3 reduced to invariants so the
  procedure lives in exactly one place

* feat(skills): split type minimums by viewing context

typography.md: full-screen viewing keeps body 20px / headline 60px;
in-feed destinations (X / LinkedIn / Instagram — brief-contract's
destination field) scale to body >=32px, headline >=90px, data labels
>=24px. First-pass values, to be calibrated against real renders.

* feat(skills): storyboard proposal as a table + credits close by default

- story-spine § 3: the proposal presents frames as a markdown table
  (frame · beat · on screen · why) instead of dense paragraphs; the
  three shot-sequence workflows and website-to-video's beat summary
  reference the same shape
- pr-to-video: the credits close is now the default ending — every PR
  video ends on a contributors frame (committers by commit count, 1-6
  avatars), with no taste judgment; the only skip is when no avatar
  was fetched, and the user can cut the frame in the proposal

* fix(skills): address review nits on the brief/story contracts

- embedded-captions: the identity procedure now states both sides of the
  preference gate inline (user picks; autonomous picks with a stated why)
- website-to-video step-2-brief: note that its mode section is the
  workflow's application of brief-contract.md, not a second definition
- brief-contract: resuming a project reads mode from STORYBOARD.md
  frontmatter — a recorded mode counts as set, closing the write-only gap

* docs(skills): add a non-code receipts example to the brief contract

Review nit (jrusso1020, #2058): the receipts example in § 3 was
PR-video-shaped only. A destination-shaped example joins it so the rule
reads as workflow-neutral.

2026-07-09 01:58:51 +08:00

5.8 KiB

Raw Blame History

name, description

name	description
hyperframes-creative	Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

HyperFrames Creative

Brand, pacing, style, narration, and composition direction. Use after the technical contract from hyperframes-core is in place.

For motion patterns, scene blueprints, transitions, and CSS marker effects, use hyperframes-animation — this skill is intentionally non-animation.

Read these two FIRST for any non-trivial composition — they override web instincts:

references/house-style.md — "interpret the prompt, generate real content," the lazy-default list, and the background/foreground layer recipe. This is what turns a literal restyle into a concept.

references/video-composition.md — video-medium density, scale, foreground metadata (the "produced, not generated" detailing: data bars, registration marks, monospace readouts, 8-10 elements/scene).

Skipping these is the single biggest cause of generic, web-page-looking output. They are not optional rows in the routing table below — for anything beyond a one-line edit, open both before you choose colors or write HTML.

Workflow

If a project has a design spec, read it first and treat its frontmatter tokens as brand truth (colors, fonts, spacing, tone, constraints). Which file to read (precedence frame.md → design.md → DESIGN.md) and how to parse it (frontmatter = normative, prose = context) are defined once in references/design-spec.md — resolve and load per that doc.
If no design spec exists and the user asks for visual direction, choose a route:
- Ready-made frame-preset (optional) → frame-presets/ (adopt a FRAME.md as frame.md; see references/design-spec.md)
- Named style or mood → references/visual-styles.md
- Fast defaults → references/house-style.md
- Interactive selection → references/design-picker.md
For multi-scene work, plan beats and rhythm before writing HTML → references/beat-direction.md. For scene transitions, jump to hyperframes-animation/transitions/.
For motion-heavy work, read references/motion-principles.md (high-level guardrails), then go to hyperframes-animation for atomic rules.

Routing

Topic	Read
Adopt a ready-made frame-preset as `frame.md` (optional)	`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-specific color tokens	`palettes/*.md`
Composition patterns — PiP, text-behind-subject, title card, slide show	`references/composition-patterns.md`
Stats / infographic presentation	`references/data-in-motion.md`
Structured expansion for open-ended prompts	`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-authoring spec verification (colors, type, corners, spacing, depth)	`references/design-adherence.md`
High-level motion guardrails and GSAP-quality rules	`references/motion-principles.md`
Font selection, pairings, rendered-video type guardrails	`references/typography.md`
Story doctrine — hook language, value-before-evidence, storyboard-as-proposal	`references/story-spine.md`
Script pacing, tone, openings, number pronunciation	`references/narration.md`
Precomputed audio bands mapped to motion	`references/audio-reactive.md`

Scripts

scripts/contrast-report.mjs — inspect contrast warnings from rendered frames.
scripts/extract-audio-data.py — pre-extract audio bands for audio-reactive compositions.
scripts/package-loader.mjs — support script for bundled creative tooling.

contrast-report.mjs resolves helper packages from the current project first, then can bootstrap the bundled HyperFrames package version. Set HYPERFRAMES_SKILL_PKG_VERSION=<version> only when running the skill outside the bundled CLI/skill install and you need to pin that bootstrap version explicitly.

Run from the repo root with explicit paths, for example:

python skills/hyperframes-creative/scripts/extract-audio-data.py <audio-file>

Animation analysis (animation-map.mjs) lives in hyperframes-animation/scripts/.

Boundaries

Do not override hyperframes-core technical rules.
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.
Keep recipe references task-specific; do not read every reference for simple edits.

5.8 KiB Raw Blame History