feat(skills): design.md integration, shared video references, Claude Design gaps

[vanceingalls]

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

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

🤖 Generated with Claude Code

[vanceingalls]

• feat(skills): pre-plan persistent-subject choreography (Addition C) #551
• feat(skills): add content-culture calibration + use-real-subject #550
• feat(skills): design.md integration, shared video references, Claude Design gaps #549 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[jrusso1020]

Staff review

TL;DR: Intent is right (design-first → expand → build is the correct pipeline order), and references/prompt-expansion.md is well-built. But this PR ships a second design gate next to the existing <HARD-GATE> "Visual Identity Gate" already in SKILL.md (lines 56–73 on main) — different filename casing, different resolution order, no reconciliation. Plus a broken file reference, an undeclared external skill dependency, and significant prose duplication.

---

Blocking

1. Two competing design gates in one file. After this PR, SKILL.md contains both the new "Step 0a" (design.md lowercase, 4-path resolution) and the existing <HARD-GATE> "Visual Identity Gate" (DESIGN.md uppercase, different 4-path resolution). They conflict on:

• Filename casing — design.md vs DESIGN.md. On Linux (where the renderer runs) these are different files; on macOS they collide unpredictably. Existing projects with DESIGN.md won't satisfy Step 0a's path 1.
• Bootstrap source — new gate uses external /visual-style skill + references/design-picker.md + house-style.md; old gate uses in-repo visual-styles.md presets + 3-question fallback.
• Hardness — old one is wrapped in <HARD-GATE>, new one is just a step.

Pick one. If new replaces old, delete the <HARD-GATE> block in this PR. Align casing — DESIGN.md (uppercase) is already established.

2. Broken reference. SKILL.md:22 (new) links to references/design-picker.md for path 3. That file is not in the diff and not in the tree. Path 3 is unreachable.

3. Undeclared external dependency. Step 0a path 2 invokes /visual-style, which lives at /home/ubuntu/.agents/skills/visual-style/ — a separately-installed skill. OSS users installing via npx skills add heygen-com/hyperframes won't have it. No graceful fallback.

4. Filename + schema mismatch with the dependency. /visual-style natively produces visual-style.md (structured YAML: style_prompt_full, colors[], typography, etc.). The PR says save it as design.md — but never defines a design.md schema. Downstream subagents are told to "use only the values it defines" without knowing what fields are guaranteed. references/prompt-expansion.md:35 even references "ease choices from design.md" — visual-style.md doesn't carry easings. Either define the schema or the contract is fictional.

---

Significant

5. Duplicated prose. "Design direction shapes/affects expansion output (atmosphere layers, motion energy, typography)..." appears twice almost verbatim (SKILL.md:14 and :25). Drop one.

6. SKILL.md is the hot path. This file loads on every hyperframes invocation. The PR adds ~30 lines. Per skill-creator principles: keep SKILL.md to essentials, push detail into references/. The "Using design.md during construction" subsection (passing-design-downstream bullets) belongs in a reference file.

7. SKILL.md and prompt-expansion.md contradict each other on pass-through.

• SKILL.md:43 (new): "If the user's prompt is already scene-by-scene, the expansion is mostly pass-through..."
• references/prompt-expansion.md:24: "Do not skip. Do not pass through."

The reference is more correct (the rest of prompt-expansion.md argues forcefully against pass-through). Fix the SKILL.md sentence.

8. PR template is empty + no test plan. No "What/Why/How/Test plan." For a workflow change that gates every composition, please document at minimum:

• Run on a project with existing DESIGN.md (uppercase) — confirms migration path.
• Run on a fresh project with no design context — confirms /visual-style invocation path.
• "Small edit" run — confirms escape hatch fires.
• "Skip design" run — confirms last-resort path writes a usable file.

---

Smaller things

• Step numbering: 0a/0b/1 is the visible scar of accreted edits. Renumber.
• house-style.md decorative-count addition is a useful clarification but reads as a band-aid mid-section. Promote to a real subheader.
• prompt-expansion.md writes to .hyperframes/expanded-prompt.md — confirm nothing in the CLI/registry treats .hyperframes/ as generated artifact directory that lint/build could clobber.
• Behavioral cost on iteration: even with the "tiny edit" exception, the gate triggers on every fresh invocation. Consider an explicit shortcut: existing design + single-element change → skip expansion entirely.

---

What this PR gets right

• Diagnosis is correct: ordering design → expansion → scenes is the right architecture; expanding before grounding produces generic breakdowns.
• references/prompt-expansion.md is well-structured: clear prerequisites, "why always run", per-section output spec, output destination, user handoff message. Good progressive disclosure.
• Decorative-vs-motion clarification in house-style.md resolves a real ambiguity ("4 decoratives sharing one breathing motion is correct; 1 decorative is under-dressed" — concrete and memorable).

---

Recommended path

Block on (1)–(4). Reissue with: one gate not two, schema for design.md, explicit /visual-style dependency note + OSS fallback, the missing design-picker.md (or remove path 3), de-duplicated prose, real PR description and test plan. The reference file and house-style.md clarification can ship as-is.

[vanceingalls]

Review response

All blocking and significant items addressed:

Blocking (1-4)

1. Two competing gates → Merged. HARD-GATE is now a 2-line verification referencing Step 1. No duplicate resolution order.

2. Broken design-picker.md → File exists. Ships with two-phase mood board UI and spec-compliant output.

3. /visual-style external dependency → Removed. Uses in-repo visual-styles.md presets or the design picker. No external skill.

4. Schema mismatch → Format-agnostic. "Any format works (YAML, prose, tables — just extract the values)." No schema contract to violate.

Significant (5-8)

5. Duplicated prose → Removed.

6. SKILL.md size → Reduced by merging gates. Construction subsection removed.

7. Pass-through contradiction → Fixed. SKILL.md no longer mentions pass-through.

8. PR template → Updated with full description + test plan.

Smaller

• Step numbering → 1/2/3 (was 0a/0b/1)
• .hyperframes/ not clobbered by CLI
• Small edit shortcut: "skip straight to the rules"

Additional work since review

• video-composition.md — shared video-medium rules (density, scale, color presence, light canvas guidance)
• beat-direction.md — per-beat planning, choreography verbs, rhythm templates
• techniques.md, narration.md — extracted from website-to-hyperframes to shared
• motion-principles.md — gained image treatment + load-bearing GSAP rules
• 6 Claude Design transfer brief gaps applied (discovery, anti-scope-creep, read-source, rhythm, variations, two-phase verify)
• Design picker: mood-board-first two-phase UI, contextual generation, prompt-aware previews, media asset support

[miguel-heygen]

Requesting changes on the live head 541173f8 because the design file contract is still split between lowercase design.md and the existing uppercase DESIGN.md website-to-HyperFrames pipeline. That is not just naming churn: Step 6 loads the shared hyperframes skill, so captured projects can now miss the brand file and fall into no-design defaults on case-sensitive filesystems.

Validation notes: I checked the current patch and existing website-to-hyperframes docs, ran bunx oxfmt --check on the touched files, ran bunx tsx scripts/lint-skills.ts, and exercised the new design picker in agent-browser with sample JSON. The picker did generate a design.md, but I left a UX/schema comment from that browser pass too. bun run lint:skills did not run directly in this checkout because tsx is not installed locally; the bunx tsx equivalent passed.

[miguel-heygen]

This still leaves the original casing blocker unresolved. The website-to-hyperframes pipeline in this PR still creates and gates on DESIGN.md (skills/website-to-hyperframes/SKILL.md Step 2, plus the Step 6 build docs), but the shared HyperFrames skill now only checks lowercase design.md. Step 6 explicitly loads this skill, so a captured project with only DESIGN.md will take the no-design path here and can prompt/fallback to house style instead of using the captured brand. On Linux those are different files. Please either recognize DESIGN.md here, preferably before design.md for existing projects, or migrate every producer and consumer to one canonical casing in the same PR.

[miguel-heygen]

The template now treats Motion/easing as a required category (checkReady requires picks.easing !== null), but this moodboard contract and example do not include easing_index. I exercised the picker with data shaped like this example: selecting a moodboard prefilled every documented category, but the Create design.md button stayed hidden until I manually scrolled to Motion and picked an easing. Either add easing_index to the required moodboard schema/example or default an easing in goToTune; otherwise the advertised complete-direction path looks stuck.

[miguel-heygen]

This new rule conflicts with the hot-path docs that still tell authors to use gsap.from() for entrances (skills/hyperframes/SKILL.md under Layout Before Animation and website-to-hyperframes Step 6). Since this section says from() can silently fail under seek, please update those higher-priority examples/instructions in the same PR; otherwise agents will keep following the hot path and only discover this exception later.

[jrusso1020]

Staff re-review (round 2)

TL;DR: Major progress. The four blocking items from round 1 are all resolved or substantially addressed. Remaining issues are doc-cleanup-grade — none are blocking. Recommend approve after the stale Step 0a references are updated.

---

Round 1 blockers — status

1. Two competing design gates → ✅ Resolved. The <HARD-GATE> block has collapsed to a one-line "verify you have a visual identity from Step 1" pointer. design.md casing is now consistent throughout (lowercase). The "Step 0a/0b/1" numbering is gone — clean Step 1/2/3 ordering.

2. Broken references/design-picker.md link → ✅ Resolved. File is in the diff (+116 lines) and well-structured. The two-phase mood-boards-first picker is a solid UX choice, and the preview_html token contract ({{bg}}, {{fg}}, {{ac}}, {{cr}}, {{shadow}}, {{prompt_headline}}, etc.) is concrete enough to author against. Security guidance (no <script>, no event handlers) and the single-quote-in-style gotcha are real and worth keeping.

3. Undeclared external /visual-style dependency → ✅ Resolved. The picker now lives in-skill (templates/design-picker.html is shipped, references/design-picker.md documents the workflow). No external skill required. OSS users get the picker for free.

4. design.md schema mismatch → ✅ Substantially resolved. The picker outputs google-labs-code/design.md spec format (YAML frontmatter with colors, typography, rounded, spacing, plus ## Overview, ## Colors, ## Typography, ## Layout, ## Elevation, ## Components, ## Do's and Don'ts prose). Easings now flow through via the ## Motion block (verified in templates/design-picker.html:1302). One soft-contract concern below.

5. Duplicated prose → ✅ Resolved (zero hits for the duplicated phrases now).

6. SKILL.md hot-path bloat → 🟡 Partly. Net delta is +50 lines (364 → 414) vs the originally-flagged ~30. The "Using design.md during construction" subsection moved out — good. The new shared references (video-composition.md, beat-direction.md, motion-principles.md, narration.md, techniques.md) are pulled into the References block at the bottom marked "Always read" or "Read when…". Loading rule is clear; size is acceptable.

7. Pass-through contradiction → ✅ Resolved. Step 2 in SKILL.md and prompt-expansion.md now agree — always run, exception is single-scene + trivial edits.

8. PR template + test plan → ✅ Body is filled in, test plan is concrete (5 checked items including a before/after eval).

---

New / lingering issues (non-blocking)

A. Stale Step 0a references in references/prompt-expansion.md. Steps were renumbered to 1/2/3 in SKILL.md, but the reference still says:

• L5: "Runs AFTER design direction is established (Step 0a)."
• L16: "If design.md doesn't exist yet, run Step 0a (Design system) first."

Should be "Step 1" / "Step 1 (Design system)". Same stale Step 0a appears in the PR description's ### design.md Integration bullet — worth a one-line edit to keep the description honest.

B. "Ease choices from design.md" is now technically true but soft-contract. prompt-expansion.md:29 tells expansion to cite "exact hex values, typography parameters, ease choices from design.md." The picker does emit a ## Motion prose block (Entry easing: power3.out), so easings are present — but as prose, not a structured field. Scene subagents must regex out of free-form markdown. Workable; flag for future structuring.

C. revert(skills): restore step-2-design.md to original — small thing, but the commit log shows step-2-design.md was added then reverted. If that file was never landed it's fine; if it's referenced anywhere in the new docs, double-check the link still resolves.

D. chore(skills): delete techniques.md redirect stub, update SKILL.md reference — verify the references/techniques.md referenced in SKILL.md:404 points at the in-skill copy and not the website-to-hyperframes shadow that the redirect stub used to forward to. (Spot-checked SKILL.md — the path looks right, just confirming the cleanup is complete.)

E. design picker easing UI is GSDevTools-grade but undocumented in SKILL.md. The new feat(skills): add GSAP easing picker with live animated demos commit adds real value but isn't mentioned in the design-picker.md prerequisites or the SKILL.md References block. Worth a one-liner so authors know easings are first-class in the picker.

---

What this PR continues to get right

• Diagnosis is correct: design → expansion → scenes is the right pipeline order.
• references/prompt-expansion.md has held up well — clear prerequisites, "why always run", per-section output spec, output destination, user handoff message.
• The decorative-vs-motion clarification in house-style.md ("4 decoratives sharing one breathing motion is correct; 1 decorative is under-dressed") is concrete and memorable.
• Mood-boards-first picker workflow with deeply-contextual generation requirements ("genuinely different ways to position this product, not different fonts on the same layout") is exactly the right shape for an LLM-driven design tool.
• ## Motion block in the picker output bridges design + animation cleanly.

---

Recommended path

Approve after the stale Step 0a references in references/prompt-expansion.md (L5, L16) and the PR description are updated to "Step 1". The other items (B–E) are doc cleanup, not gating.

[jrusso1020]

Approving — round-1 blockers all resolved. The remaining items (stale Step 0a references in references/prompt-expansion.md L5/L16 and the PR description) are doc cleanup, fine to land in a follow-up or as a quick fix before merge.