mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-05 00:56:23 +00:00

Files

T

Vance Ingalls 22f0e6a5cd feat(skills): design.md integration, shared video references, Claude Design gaps (#549 )

## What

Major skill infrastructure update: design.md support, shared video-composition references, and creative direction patterns extracted from website-to-hyperframes into the base hyperframes skill.

## Changes

### design.md Integration (lightweight)
- Step 0a reads any format design.md (YAML, prose, tables) — no format mandate
- Brand colors/fonts are strict; video layout adapts per video-composition.md
- Font warning gate: warns user if design.md names fonts without local .woff2 files
- Design picker generates spec-compliant design.md with YAML frontmatter + prose
- Picker generates contextual options from user's prompt (3-4 architectures, 5-6 palettes, 3 type pairings)

### Shared Video References (extracted from website-to-hyperframes)
- `video-composition.md` — density, scale, color presence, frame composition rules. Light canvas guidance (don't override user palette). **Always read.**
- `beat-direction.md` — per-beat planning (concept → mood → choreography verbs → transition), rhythm templates by video type
- `techniques.md` — 11 visual techniques with code patterns (SVG drawing, Canvas 2D, kinetic type, Lottie, etc.)
- `narration.md` — pacing, tone, script structure, number pronunciation, hooks
- `motion-principles.md` — gained image motion treatment + load-bearing GSAP rules

### Claude Design Transfer Brief (6 gaps applied)
1. Discovery step for exploratory requests (audience, platform, priority, variations)
2. Anti-scope-creep: "build what was asked, every element earns its place"
3. Read-source discipline: "read actual files, don't guess"
4. Rhythm planning: declare scene rhythm before implementing
5. Variations as first-class output for exploratory requests
6. Two-phase verification: fast checks block, slow checks parallel

### Prompt Expansion Updated
- Uses beat-direction format (concept → mood → verbs → depth layers)
- Rhythm declaration before scene breakdown
- References video-composition.md and beat-direction.md

### Key Design Decision
**design.md = brand truth, not video layout spec.** Background color is strict from design.md (don't switch light to dark). Video-composition rules teach how to make any palette work cinematically.

## Files Changed (16)

**New shared references:**
- `skills/hyperframes/references/video-composition.md`
- `skills/hyperframes/references/beat-direction.md`
- `skills/hyperframes/references/techniques.md`
- `skills/hyperframes/references/narration.md`

**Updated:**
- `skills/hyperframes/SKILL.md` — discovery, anti-scope-creep, rhythm, variations, two-phase verify, new references
- `skills/hyperframes/references/prompt-expansion.md` — beat-direction format
- `skills/hyperframes/references/motion-principles.md` — image treatment + GSAP rules
- `skills/hyperframes/references/design-picker.md` — contextual generation
- `skills/hyperframes/visual-styles.md` — YAML token blocks per preset
- `skills/hyperframes/house-style.md` — design.md precedence
- `skills/hyperframes/templates/design-picker.html` — spec-compliant output
- `skills/website-to-hyperframes/references/*` — now reference shared files

## Test plan

- [x] Design picker generates and serves correctly
- [x] Picker output is spec-compliant design.md
- [x] Composition built from picker design.md renders in Studio
- [x] Before/after eval: 4 topics × 2 versions showing skill guidance impact
- [x] Light canvas compositions respect user palette (don't switch to dark)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

2026-04-29 17:48:54 -07:00

4.9 KiB

Raw Permalink Blame History

House Style

Creative direction for compositions when no design.md is provided. These are starting points — override anything that doesn't serve the content. When a design.md exists, its brand values take precedence; house-style fills gaps.

Before Writing HTML

Interpret the prompt. Generate real content. A recipe lists real ingredients. A HUD has real readouts.
Pick a palette. Light or dark? Declare bg, fg, accent before writing code.
Pick typefaces. Run the font discovery script in references/typography.md — or pick a font you already know that fits the theme. The script broadens your options; it's not the only source.

Lazy Defaults to Question

These patterns are AI design tells — the first thing every LLM reaches for. If you're about to use one, pause and ask: is this a deliberate choice for THIS content, or am I defaulting?

Gradient text (background-clip: text + gradient)
Left-edge accent stripes on cards/callouts
Cyan-on-dark / purple-to-blue gradients / neon accents
Pure #000 or #fff (tint toward your accent hue instead)
Identical card grids (same-size cards repeated)
Everything centered with equal weight (lead the eye somewhere)
Banned fonts (see references/typography.md for full list)

If the content genuinely calls for one of these — centered layout for a solemn closing, cards for a real product UI mockup, a banned font because it's the perfect thematic match — use it. The goal is intentionality, not avoidance.

Color

Match light/dark to content: food, wellness, kids → light. Tech, cinema, finance → dark.
One accent hue. Same background across all scenes.
Tint neutrals toward your accent (even subtle warmth/coolness beats dead gray).
Contrast: enforced by hyperframes validate (WCAG AA). Text must be readable with decoratives removed.
Declare palette up front. Don't invent colors per-element.

Background Layer

Every scene needs visual depth — persistent decorative elements that stay visible while content animates in. Without these, scenes feel empty during entrance staggering.

Ideas (mix and match, 2-5 per scene):

Radial glows (accent-tinted, low opacity, breathing scale)
Ghost text (theme words at 3-8% opacity, very large, slow drift)
Accent lines (hairline rules, subtle pulse)
Grain/noise overlay, geometric shapes, grid patterns
Thematic decoratives (orbit rings for space, vinyl grooves for music, grid lines for data)

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 for full rules. Quick: 0.3–0.6s, vary eases, combine transforms on entrances, overlap entries.

Typography

See references/typography.md for full rules. Quick: 700-900 headlines / 300-400 body, serif + sans (not two sans), 60px+ headlines / 20px+ body.

Palettes

Declare one background, one foreground, one accent before writing HTML.

Category	Use for	File
Bold / Energetic	Product launches, social media, announcements	palettes/bold-energetic.md
Warm / Editorial	Storytelling, documentaries, case studies	palettes/warm-editorial.md
Dark / Premium	Tech, finance, luxury, cinematic	palettes/dark-premium.md
Clean / Corporate	Explainers, tutorials, presentations	palettes/clean-corporate.md
Nature / Earth	Sustainability, outdoor, organic	palettes/nature-earth.md
Neon / Electric	Gaming, tech, nightlife	palettes/neon-electric.md
Pastel / Soft	Fashion, beauty, lifestyle, wellness	palettes/pastel-soft.md
Jewel / Rich	Luxury, events, sophisticated	palettes/jewel-rich.md
Monochrome	Dramatic, typography-focused	palettes/monochrome.md

Or derive from OKLCH — pick a hue, build bg/fg/accent at different lightnesses, tint everything toward that hue.

4.9 KiB Raw Permalink Blame History Unescape Escape