From c26d8bf6d213b80baced465014dda39bf27aa4b8 Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Thu, 23 Apr 2026 12:27:14 -0700 Subject: [PATCH 01/37] feat(skills): adopt design.md as source of truth, replace visual-style.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace all visual-style.md references with design.md across SKILL.md and house-style.md. Add Step 0 design system gate: when design.md exists in a project, read it and use its values for all visual decisions. Add design adherence eval to Quality Checks — verifies colors, typography, corners, spacing, depth, and don'ts compliance after composition authoring. Co-Authored-By: Claude Opus 4.6 (1M context) --- skills/hyperframes/SKILL.md | 51 ++++++++++++++++--------------- skills/hyperframes/house-style.md | 2 +- 2 files changed, 28 insertions(+), 25 deletions(-) diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md index 5584493f3..d695b0b50 100644 --- a/skills/hyperframes/SKILL.md +++ b/skills/hyperframes/SKILL.md @@ -9,6 +9,16 @@ HTML is the source of truth for video. A composition is an HTML file with `data- ## Approach +### Step 0: Design system + +Check for a `design.md` in the project root. If one exists, read it — it defines colors, typography, motion, and mood for all compositions in this project. If none exists, follow [house-style.md](./house-style.md) defaults. + +### Using design.md during construction + +If a `design.md` exists, it is the source of truth for all visual decisions. Use only the values it defines — colors, fonts, spacing, corners, depth, component treatments, and any other fields the user has added. Do not invent new colors, substitute fonts, or override its rules. If the composition needs a value the design.md doesn't cover, follow [house-style.md](./house-style.md) for that specific decision. + +### Step 1: Plan + Before writing HTML, think at a high level: 1. **What** — what should the viewer experience? Identify the narrative arc, key moments, and emotional beats. @@ -19,27 +29,6 @@ Before writing HTML, think at a high level: For small edits (fix a color, adjust timing, add one element), skip straight to the rules. -### Visual Identity Gate - - -Before writing ANY composition HTML, you MUST have a visual identity defined. Do NOT write compositions with default or generic colors. - -Check in this order: - -1. **DESIGN.md exists in the project?** → Read it. Use its exact colors, fonts, motion rules, and "What NOT to Do" constraints. -2. **visual-style.md exists?** → Read it. Apply its `style_prompt_full` and structured fields. (Note: `visual-style.md` is a project-specific file. `visual-styles.md` is the style library with 8 named presets — different files.) -3. **User named a style** (e.g., "Swiss Pulse", "dark and techy", "luxury brand")? → Read [visual-styles.md](./visual-styles.md) for the 8 named presets. Generate a minimal DESIGN.md with: `## Style Prompt` (one paragraph), `## Colors` (3-5 hex values with roles), `## Typography` (1-2 font families), `## What NOT to Do` (3-5 anti-patterns). -4. **None of the above?** → Ask 3 questions before writing any HTML: - - What's the mood? (explosive / cinematic / fluid / technical / chaotic / warm) - - Light or dark canvas? - - Any specific brand colors, fonts, or visual references? - Then generate a minimal DESIGN.md from the answers. - -Every composition must trace its palette and typography back to a DESIGN.md, visual-style.md, or explicit user direction. If you're reaching for `#333`, `#3b82f6`, or `Roboto` — you skipped this step. - - -For motion defaults, sizing, entrance patterns, and easing — follow [house-style.md](./house-style.md). The house style handles HOW things move. The DESIGN.md handles WHAT things look like. - ## Layout Before Animation Position every element where it should be at its **most visible moment** — the frame where it's fully entered, correctly placed, and not yet exiting. Write this as static HTML+CSS first. No GSAP yet. @@ -259,7 +248,7 @@ tl.from("#s2-heading", { x: -40, opacity: 0, duration: 0.6, ease: "expo.out" }, - 60px+ headlines, 20px+ body, 16px+ data labels for rendered video - `font-variant-numeric: tabular-nums` on number columns -When no `visual-style.md` or animation direction is provided, follow [house-style.md](./house-style.md) for aesthetic defaults. +If no `design.md` was established in Step 0, follow [house-style.md](./house-style.md) for aesthetic defaults. ## Typography and Assets @@ -277,6 +266,7 @@ When no `visual-style.md` or animation direction is provided, follow [house-styl ## Output Checklist - [ ] `npx hyperframes lint` and `npx hyperframes validate` both pass +- [ ] Design adherence verified if design.md exists (see Quality Checks below) - [ ] Contrast warnings addressed (see Quality Checks below) - [ ] Animation choreography verified (see Quality Checks below) @@ -300,6 +290,19 @@ If warnings appear: Use `--no-contrast` to skip if iterating rapidly and you'll check later. +### Design Adherence + +If a `design.md` exists, verify the composition follows it after authoring. Read the HTML and check: + +1. **Colors** — every hex value in the composition appears in design.md's palette (accent, muted, surface, bg, fg). Flag any invented colors. +2. **Typography** — font families and weights match design.md's headline/body spec. No substitutions. +3. **Corners** — border-radius values match the declared corner style. +4. **Spacing** — padding and gap values fall within the declared density range. +5. **Depth** — shadow usage matches the declared depth level (flat = none, subtle = light, layered = glows). +6. **"What NOT to Do"** — if design.md has a don'ts section, verify none are present. + +Report violations as a checklist. Fix each one before serving. + ### Animation Map After authoring animations, run the animation map to verify choreography: @@ -333,8 +336,8 @@ Skip on small edits (fixing a color, adjusting one duration). Run on new composi - **[references/css-patterns.md](references/css-patterns.md)** — CSS+GSAP marker highlighting: highlight, circle, burst, scribble, sketchout. Deterministic, fully seekable. Read when adding visual emphasis to text. - **[references/typography.md](references/typography.md)** — Typography: font pairing, OpenType features, dark-background adjustments, font discovery script. **Always read** — every composition has text. - **[references/motion-principles.md](references/motion-principles.md)** — Motion design principles: easing as emotion, timing as weight, choreography as hierarchy, scene pacing, ambient motion, anti-patterns. Read when choreographing GSAP animations. -- **[visual-styles.md](visual-styles.md)** — 8 named visual styles (Swiss Pulse, Velvet Standard, Deconstructed, Maximalist Type, Data Drift, Soft Signal, Folk Frequency, Shadow Cut) with hex palettes, GSAP easing signatures, and shader pairings. Read when user names a style or when generating DESIGN.md. -- **[house-style.md](house-style.md)** — Default motion, sizing, and color palettes when no style is specified. +- **[visual-styles.md](visual-styles.md)** — 8 named visual styles (Swiss Pulse, Velvet Standard, Deconstructed, Maximalist Type, Data Drift, Soft Signal, Folk Frequency, Shadow Cut) with hex palettes, GSAP easing signatures, and shader pairings. Read when user names a style or when generating design.md. +- **[house-style.md](house-style.md)** — Default motion, sizing, and color palettes when no design.md is specified. - **[patterns.md](patterns.md)** — PiP, title cards, slide show patterns. - **[data-in-motion.md](data-in-motion.md)** — Data, stats, and infographic patterns. - **[references/transcript-guide.md](references/transcript-guide.md)** — Transcription commands, whisper models, external APIs, troubleshooting. diff --git a/skills/hyperframes/house-style.md b/skills/hyperframes/house-style.md index a5edc4b05..6d5161552 100644 --- a/skills/hyperframes/house-style.md +++ b/skills/hyperframes/house-style.md @@ -1,6 +1,6 @@ # House Style -Creative direction for compositions when no `visual-style.md` is provided. These are starting points — override anything that doesn't serve the content. +Creative direction for compositions when no `design.md` is provided. These are starting points — override anything that doesn't serve the content. ## Before Writing HTML From fad75f45b52a9d4abeec4ac9628894eb4b550eda Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Thu, 23 Apr 2026 12:43:00 -0700 Subject: [PATCH 02/37] =?UTF-8?q?fix(skills):=20address=20review=20?= =?UTF-8?q?=E2=80=94=20restore=20named-style=20path,=20align=20adherence?= =?UTF-8?q?=20check?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Restore named-style detection in Step 0: if user names a style or mood, look up visual-styles.md and generate a design.md before falling through to house-style defaults - Restore motion/style boundary: design.md defines appearance, house-style defines motion, design.md motion rules take precedence - Soften adherence check vocabulary: don't assume specific field names, match however the user labeled their palette/don'ts sections - Add house-style consistency check for no-design.md path: palette consistency across scenes + lazy defaults audit Co-Authored-By: Claude Opus 4.6 (1M context) --- skills/hyperframes/SKILL.md | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md index d695b0b50..f598a4be9 100644 --- a/skills/hyperframes/SKILL.md +++ b/skills/hyperframes/SKILL.md @@ -11,11 +11,17 @@ HTML is the source of truth for video. A composition is an HTML file with `data- ### Step 0: Design system -Check for a `design.md` in the project root. If one exists, read it — it defines colors, typography, motion, and mood for all compositions in this project. If none exists, follow [house-style.md](./house-style.md) defaults. +Check for a `design.md` in the project root: + +1. **design.md exists?** → Read it. It defines colors, typography, motion, and mood for all compositions in this project. +2. **User named a style or mood** (e.g., "Swiss Pulse", "dark and techy", "luxury brand")? → Read [visual-styles.md](./visual-styles.md) for matching presets. Generate a `design.md` with: `## Mood` (one paragraph), `## Colors` (bg, fg, accent hex values), `## Typography` (headline + body families and weights), `## What NOT to Do` (3–5 anti-patterns). Save to `design.md`. +3. **None of the above?** → Follow [house-style.md](./house-style.md) defaults. ### Using design.md during construction -If a `design.md` exists, it is the source of truth for all visual decisions. Use only the values it defines — colors, fonts, spacing, corners, depth, component treatments, and any other fields the user has added. Do not invent new colors, substitute fonts, or override its rules. If the composition needs a value the design.md doesn't cover, follow [house-style.md](./house-style.md) for that specific decision. +If a `design.md` exists, it is the source of truth for all visual decisions — colors, fonts, spacing, corners, depth, component treatments, and any other fields the user has added. Do not invent new colors, substitute fonts, or override its rules. If the composition needs a value the design.md doesn't cover, follow [house-style.md](./house-style.md) for that specific decision. + +design.md defines appearance. [house-style.md](./house-style.md) defines motion. If design.md includes motion rules, they take precedence for that specific property. ### Step 1: Plan @@ -294,15 +300,20 @@ Use `--no-contrast` to skip if iterating rapidly and you'll check later. If a `design.md` exists, verify the composition follows it after authoring. Read the HTML and check: -1. **Colors** — every hex value in the composition appears in design.md's palette (accent, muted, surface, bg, fg). Flag any invented colors. -2. **Typography** — font families and weights match design.md's headline/body spec. No substitutions. -3. **Corners** — border-radius values match the declared corner style. -4. **Spacing** — padding and gap values fall within the declared density range. -5. **Depth** — shadow usage matches the declared depth level (flat = none, subtle = light, layered = glows). -6. **"What NOT to Do"** — if design.md has a don'ts section, verify none are present. +1. **Colors** — every hex value in the composition appears in design.md's palette section (however the user labeled it: Colors, Palette, Theme, etc.). Flag any invented colors. +2. **Typography** — font families and weights match design.md's type spec. No substitutions. +3. **Corners** — border-radius values match the declared corner style, if specified. +4. **Spacing** — padding and gap values fall within the declared density range, if specified. +5. **Depth** — shadow usage matches the declared depth level, if specified (flat = none, subtle = light, layered = glows). +6. **Avoidance rules** — if design.md has a section listing things to avoid (commonly "What NOT to Do", "Don'ts", "Anti-patterns", or "Do's and Don'ts"), verify none are present. Report violations as a checklist. Fix each one before serving. +If no `design.md` exists (house-style-only path), verify: + +1. **Palette consistency** — the same bg, fg, and accent colors are used across all scenes. No per-scene color invention. +2. **No lazy defaults** — check the composition against house-style.md's "Lazy Defaults to Question" list. If any appear, they must be a deliberate choice for the content, not a default. + ### Animation Map After authoring animations, run the animation map to verify choreography: From e662755933e783060cb768a62e48a0dfb444607a Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Thu, 23 Apr 2026 12:30:40 -0700 Subject: [PATCH 03/37] feat(skills): add design picker workflow for creating design.md When no design.md exists, offer the user a visual picker to create one. Adds design-picker.md reference doc and design-picker.html template with 7 independent categories: theme, structure, palette, typography, corners, density, and depth. Live preview updates as user selects options. Co-Authored-By: Claude Opus 4.6 (1M context) --- skills/hyperframes/SKILL.md | 3 +- .../hyperframes/references/design-picker.md | 40 ++ .../hyperframes/templates/design-picker.html | 346 ++++++++++++++++++ 3 files changed, 388 insertions(+), 1 deletion(-) create mode 100644 skills/hyperframes/references/design-picker.md create mode 100644 skills/hyperframes/templates/design-picker.html diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md index f598a4be9..0eadda0cb 100644 --- a/skills/hyperframes/SKILL.md +++ b/skills/hyperframes/SKILL.md @@ -15,7 +15,7 @@ Check for a `design.md` in the project root: 1. **design.md exists?** → Read it. It defines colors, typography, motion, and mood for all compositions in this project. 2. **User named a style or mood** (e.g., "Swiss Pulse", "dark and techy", "luxury brand")? → Read [visual-styles.md](./visual-styles.md) for matching presets. Generate a `design.md` with: `## Mood` (one paragraph), `## Colors` (bg, fg, accent hex values), `## Typography` (headline + body families and weights), `## What NOT to Do` (3–5 anti-patterns). Save to `design.md`. -3. **None of the above?** → Follow [house-style.md](./house-style.md) defaults. +3. **No design.md and no named style?** → Ask: "Want to pick a visual style before we build? (yes = design picker, no = use defaults)". If yes → read [references/design-picker.md](references/design-picker.md) for the full picker workflow. If no → follow [house-style.md](./house-style.md) defaults. ### Using design.md during construction @@ -347,6 +347,7 @@ Skip on small edits (fixing a color, adjusting one duration). Run on new composi - **[references/css-patterns.md](references/css-patterns.md)** — CSS+GSAP marker highlighting: highlight, circle, burst, scribble, sketchout. Deterministic, fully seekable. Read when adding visual emphasis to text. - **[references/typography.md](references/typography.md)** — Typography: font pairing, OpenType features, dark-background adjustments, font discovery script. **Always read** — every composition has text. - **[references/motion-principles.md](references/motion-principles.md)** — Motion design principles: easing as emotion, timing as weight, choreography as hierarchy, scene pacing, ambient motion, anti-patterns. Read when choreographing GSAP animations. +- **[references/design-picker.md](references/design-picker.md)** — Create a design.md via visual picker. Read when no design.md exists and the user wants to create one. - **[visual-styles.md](visual-styles.md)** — 8 named visual styles (Swiss Pulse, Velvet Standard, Deconstructed, Maximalist Type, Data Drift, Soft Signal, Folk Frequency, Shadow Cut) with hex palettes, GSAP easing signatures, and shader pairings. Read when user names a style or when generating design.md. - **[house-style.md](house-style.md)** — Default motion, sizing, and color palettes when no design.md is specified. - **[patterns.md](patterns.md)** — PiP, title cards, slide show patterns. diff --git a/skills/hyperframes/references/design-picker.md b/skills/hyperframes/references/design-picker.md new file mode 100644 index 000000000..b2fcc4450 --- /dev/null +++ b/skills/hyperframes/references/design-picker.md @@ -0,0 +1,40 @@ +# Design Picker + +Create a `design.md` by serving a visual picker page where the user configures 7 independent categories. + +## Prerequisites + +Before generating options, read these style references — all options must comply: + +- [typography.md](typography.md) — banned font list, cross-category pairing (serif + sans or sans + mono, never two sans-serifs), weight contrast (300-400 body / 700-900 headline), video-sized text (60px+ headlines, 20px+ body, 16px+ labels) +- [../house-style.md](../house-style.md) — lazy defaults to avoid (no gradient text, no left-edge accent stripes, no pure #000/#fff, no identical card grids, no banned fonts) +- [motion-principles.md](motion-principles.md) — ease diversity, varied entry directions, scene structure + +## Building the picker + +1. Generate 2-3 visual directions based on the prompt. Each direction needs: name, mood, colors (bg/fg/accent), fonts (headline/body), energy level, and transition style. +2. Copy [../templates/design-picker.html](../templates/design-picker.html) to the project directory as `.hyperframes/pick-design.html`. +3. Replace `__ARCHITECTURES_JSON__`, `__PALETTES_JSON__`, and `__TYPEPAIRS_JSON__` with your generated options. The user picks one from each category independently — structure, palette, type pairing, plus theme (dark/light/full palette), corners, density, and depth. + +### Architecture data format + +Each architecture object must include a `preview_html` field — the HTML that renders in the preview panel. Use token placeholders that the template replaces at runtime: `{{bg}}`, `{{fg}}`, `{{ac}}`, `{{mt}}`, `{{hf}}`, `{{hw}}`, `{{bf}}`, `{{bw}}`, `{{cr}}` (corner radius), `{{pad}}`, `{{gap}}`, `{{shadow}}`, `{{g}}` (grid line color), `{{fg3}}`/`{{fg6}}`/`{{fg8}}`/`{{fg15}}` (fg at opacity), `{{ac3}}`/`{{ac5}}`/`{{ac25}}` (accent at opacity). + +**Every token must be used.** Apply `{{cr}}` to all cards, buttons, and containers. Apply `{{shadow}}` to elevated elements (cards, buttons, code blocks). Apply `{{pad}}` and `{{gap}}` to control spacing. If a token isn't used in the preview_html, that option will have no visible effect. + +**Density matters.** Each architecture preview must include 15+ distinct elements to give the user a real sense of the layout. Include: headline, subhead, body paragraph, label/overline, stat with number, secondary stat, quote/testimonial, attribution, card with title+body, second card (different treatment), code/command block, primary button, secondary button, list or tags, accent divider/rule, and a data element (table row, progress bar, or chart). + +Optionally include `components` (component styling rules) and `dos` (do's and don'ts) as strings — these appear in the generated design.md. + +**Layout constraint:** All preview HTML must use percentage widths or `max-width: 100%`. Use `flex-wrap: wrap` on all flex rows. Absolute-positioned decoratives must stay within a parent with `overflow: hidden`. + +**Security:** Architecture `preview_html` must not contain ` + + From 84e9ce60898123b45ae2a01f5b80693d35cb4137 Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Thu, 23 Apr 2026 12:44:41 -0700 Subject: [PATCH 04/37] =?UTF-8?q?fix(skills):=20address=20review=20?= =?UTF-8?q?=E2=80=94=20example=20arch,=20mkdir,=20server=20cleanup,=20port?= =?UTF-8?q?=20guidance?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add complete example architecture JSON object to design-picker.md showing all token placeholders, 15+ elements, and correct structure - Add mkdir -p .hyperframes before template copy - Add server cleanup instruction (kill %1 after user pastes design.md) - Add port guidance (8723 default, try next on conflict) - Fix subagent instruction: "only start from main conversation thread" - Integrate picker as step 3 in named-style detection flow Co-Authored-By: Claude Opus 4.6 (1M context) --- skills/hyperframes/references/design-picker.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/skills/hyperframes/references/design-picker.md b/skills/hyperframes/references/design-picker.md index b2fcc4450..0635daea0 100644 --- a/skills/hyperframes/references/design-picker.md +++ b/skills/hyperframes/references/design-picker.md @@ -13,7 +13,7 @@ Before generating options, read these style references — all options must comp ## Building the picker 1. Generate 2-3 visual directions based on the prompt. Each direction needs: name, mood, colors (bg/fg/accent), fonts (headline/body), energy level, and transition style. -2. Copy [../templates/design-picker.html](../templates/design-picker.html) to the project directory as `.hyperframes/pick-design.html`. +2. `mkdir -p .hyperframes` then copy [../templates/design-picker.html](../templates/design-picker.html) to `.hyperframes/pick-design.html`. 3. Replace `__ARCHITECTURES_JSON__`, `__PALETTES_JSON__`, and `__TYPEPAIRS_JSON__` with your generated options. The user picks one from each category independently — structure, palette, type pairing, plus theme (dark/light/full palette), corners, density, and depth. ### Architecture data format @@ -32,9 +32,21 @@ Optionally include `components` (component styling rules) and `dos` (do's and do **Palette variety:** Always include a mix of light, dark, and tinted backgrounds across the 6 palettes — even for calm/wellness prompts. +### Example architecture object + +```json +{ + "name": "Editorial Stack", + "description": "Vertical rhythm with large type, pull quotes, and data callouts", + "tag": "editorial / longform / narrative", + "mood": "Confident, unhurried, typographically driven", + "preview_html": "
Overline Label
The Headline Goes Here
Subheading text that introduces the narrative arc of this composition with enough words to fill two lines.
Body paragraph with real sentences. The quick brown fox jumps over the lazy dog. This gives a sense of text density and reading rhythm at the chosen type size.
2.4M
Primary Stat
87%
Secondary Stat
\"A pull quote that captures the key insight of the piece.\"
— Attribution Name
Card Title
Card body text with a different treatment than the main content area.
Accent Card
Second card with a tinted accent treatment for variety.
$ hyperframes render --output video.mp4
Tag OneTag TwoAccent Tag
Data row label1,234
" +} +``` + ## Serving and user selection -4. Serve the file with a simple HTTP server in the background: `cd && python3 -m http.server &`. Then verify: `curl -s -o /dev/null -w "%{http_code}" http://localhost:/.hyperframes/pick-design.html` — only share the link if it returns 200. Do NOT use `npx hyperframes preview` for the picker — it blocks. Do NOT start servers inside subagents — the parent handles serving. -5. Once the user picks, tell them: "Copy the design.md from the picker and paste it here." The user pastes the markdown back into the conversation. Save it to `design.md` in the project root, then proceed with construction. +4. Serve the file: `cd && python3 -m http.server 8723 &` (use port 8723 or any unused port above 8000; if the curl check fails, try the next port). Verify: `curl -s -o /dev/null -w "%{http_code}" http://localhost:8723/.hyperframes/pick-design.html` — only share the link if it returns 200. Do NOT use `npx hyperframes preview` for the picker — it blocks. Only start the HTTP server from the main conversation thread. If you are running as a dispatched task or subagent, return the file path and let the caller serve it. +5. Once the user picks, tell them: "Copy the design.md from the picker and paste it here." The user pastes the markdown back into the conversation. Save it to `design.md` in the project root. After the user pastes, kill the background server: `kill %1` or `kill $(lsof -ti:8723)`. Then proceed with construction. The design.md format is generated by the picker template — it includes mood, theme, structure, colors, typography, corners, spacing, depth, components, and do's/don'ts based on the user's selections. From a2c62df42ffa5666a49a3eba82df1f10c2787a48 Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Thu, 16 Apr 2026 16:06:46 -0700 Subject: [PATCH 05/37] feat(skills): require design.md first via visual-style skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Make design.md a prerequisite for every composition, not an optional picker step. Step 0a is now "Design system" and must complete before prompt expansion (Step 0b), because expansion output is supposed to cite design.md's palette, typography, and motion energy — expanding first produces generic breakdowns the downstream agents then ignore. Resolution order for design.md: 1. Existing design.md in project root → use as-is 2. Invoke /visual-style skill in Create mode → save output to design.md 3. references/design-picker.md (fallback if user prefers pre-built) 4. house-style.md defaults (only with explicit "skip design") Also expand prompt-expansion.md's scene-breakdown spec to require 2–5 decoratives per scene drawn from house-style's list, each using design.md's palette values. Spells out that "single ambient motion" means one looping motion applied to these decoratives, not one element total — this was the p1 regression root cause in the eval run. Co-Authored-By: Claude Opus 4.7 (1M context) --- skills/hyperframes/SKILL.md | 30 +++++++++++++ .../references/prompt-expansion.md | 44 +++++++++++++++++++ 2 files changed, 74 insertions(+) create mode 100644 skills/hyperframes/references/prompt-expansion.md diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md index 60f816e67..0f205bb31 100644 --- a/skills/hyperframes/SKILL.md +++ b/skills/hyperframes/SKILL.md @@ -9,6 +9,36 @@ HTML is the source of truth for video. A composition is an HTML file with `data- ## Approach +### Step 0a: Design system (always required, first) + +Run this BEFORE prompt expansion. Design direction shapes expansion output (atmosphere layers, motion energy, typography), so expanding first produces generic breakdowns that later ignore the palette. + +Every composition MUST have a `design.md` in the project root before construction. It is the source of truth for colors, typography, motion, spacing, and mood — every later step (expansion output, scene subagents, assembler) reads it. + +**Resolution order:** + +1. **Exists** — if `design.md` is already in the project root, read it and proceed to Step 1. +2. **Build one via the `visual-style` skill** — invoke the `/visual-style` skill (Skill tool, `skill: "visual-style"`) in "Create" mode. Ask the user the batched vibe questions the skill prescribes (mood, palette, typography, energy), then have it emit a full design spec. Save the result to `design.md` in the project root. +3. **Interactive picker (fallback)** — if the user prefers pre-built options instead of a guided build, read [references/design-picker.md](references/design-picker.md) and serve the picker. +4. **House-style defaults (last resort)** — only if the user explicitly says "skip design" or this is a tiny edit to an existing composition without a design.md. In that case, follow [house-style.md](./house-style.md) and write its palette + typography into `design.md` so downstream steps have a file to read. + +Do NOT begin prompt expansion or scene authoring without a `design.md`. Design direction affects expansion output (atmosphere layers, motion energy, typography choices) — expansion before design produces generic scene breakdowns that later ignore the palette. + +### Using design.md during construction + +`design.md` is the source of truth for all visual decisions. Use only the values it defines — colors, fonts, spacing, corners, depth, component treatments, and any other fields the user has added. Do not invent new colors, substitute fonts, or override its rules. If the composition needs a value the design.md doesn't cover, follow [house-style.md](./house-style.md) for that specific decision. + +**Passing design.md downstream:** + +- **Prompt expansion** — include the palette, typography, and mood/energy from design.md in the expanded prompt's style block. Every scene breakdown should reference the palette and note which decorative motifs belong. +- **Scene subagents** — each subagent receives the full `design.md` (or a tight summary of its values). Fragment authors apply only these values; house-style decoratives are added WITHIN the design.md's palette constraints. +- **Assembler** — reads design.md to populate any global CSS variables in the scaffold. + +### Step 0b: Prompt expansion + +If the user's prompt lacks scene-by-scene structure, expand it into a full production prompt. Read [references/prompt-expansion.md](references/prompt-expansion.md) for the full process and output format. The expanded prompt must cite design.md's palette, typography, and mood — not repeat them as generic defaults. Present the expanded prompt to the user for approval before proceeding. + +### Step 1: Plan Before writing HTML, think at a high level: 1. **What** — what should the viewer experience? Identify the narrative arc, key moments, and emotional beats. diff --git a/skills/hyperframes/references/prompt-expansion.md b/skills/hyperframes/references/prompt-expansion.md new file mode 100644 index 000000000..8aab52241 --- /dev/null +++ b/skills/hyperframes/references/prompt-expansion.md @@ -0,0 +1,44 @@ +# Prompt Expansion + +Expand a sparse user prompt into a full production prompt. Runs AFTER `design.md` is established (Step 0a) — the expansion consumes design.md and produces output that cites its palette, typography, and motion energy. + +## Prerequisites + +- `design.md` exists in the project root. If not, run Step 0a (Design system) first. Expansion without a design context produces generic scene breakdowns that later agents ignore. + +## When to expand + +A prompt needs expansion if it lacks: scene-by-scene structure, specific visual elements per scene, transition descriptions, or timing. + +**Sparse:** "make me a trailer about a killer alien on a spaceship" or "coconut water promo, tropical, 45 seconds" + +**Already expanded:** Has numbered scenes with timing, specific elements, transition rules, and animation direction — skip this step. + +## What to generate + +Expand into a full production prompt with these sections: + +1. **Title + style block** — cite design.md's palette (bg/fg/accent hex values), typography pairing, energy level, and mood. Do NOT invent a palette — quote the design.md values. +2. **Global animation rules** — parallax layers, micro-motion requirements, kinetic typography, pacing rules, transition style. Align energy with design.md (calm → slow eases, high energy → snappy eases). +3. **Scene-by-scene breakdown** — for each scene: + - Time range and title + - **Background layer (REQUIRED, 2-5 decoratives)** — pick from house-style's decorative list (radial glow / oversized ghost type / accent hairline rules / grid patterns / thematic decoratives) AND confirm each uses design.md's palette values. "Single ambient motion per scene" means one LOOPING MOTION applied to these decoratives, not one element total. + - **Midground (content)** — specific visual elements (not generic — "alien claw slides across wall" not "scary things happen") + - **Foreground (text + accents)** — text/typography with animation style + - Transition to next scene as a specific morph (what object becomes what) +4. **Recurring motifs** — visual threads that appear across multiple scenes, always drawn from design.md's palette and typography. +5. **Transition rules** — every scene-to-scene connection described as object morphing. Transition duration/ease should match design.md's energy level. +6. **Pacing curve** — where energy builds, peaks, and releases. +7. **Negative prompt** — what to avoid. Always include: "no colors outside design.md palette, no fonts outside design.md typography pair". + +## Output + +Write the expanded prompt to `.hyperframes/expanded-prompt.md` in the project directory. Do NOT dump it into the chat — it will be hundreds of lines. + +Tell the user: + +> "I've expanded your prompt into a full production breakdown. Review it here: `.hyperframes/expanded-prompt.md` +> +> It has [N] scenes across [duration] seconds with specific visual elements, transitions, and pacing. Edit anything you want, then let me know when you're ready to proceed." + +Only move to construction after the user approves or says to continue. From 11694e9e5ef6576da8f9212715845129a75bda15 Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Thu, 16 Apr 2026 16:32:27 -0700 Subject: [PATCH 06/37] docs(skills): move decorative rule to single source in house-style MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Prompt-expansion.md was re-stating house-style rules in its scene breakdown and negative-prompt sections. That's duplication — if house-style changes, expansion drifts. Fix: - Prerequisites now tell the expansion step to read house-style.md and design.md before generating. The expansion generates output that conforms to those rules; it doesn't re-state them. - Scene breakdown template names the three layer slots (background/midground/foreground) without re-stating the decorative-count rule or palette-compliance rule. - Negative-prompt no longer hard-codes palette/font rules — those live in design.md and house-style.md where they belong. - The "single ambient motion doesn't mean single element" clarification moves to house-style.md where the base rule lives, so any reader sees it next to the rule it clarifies. Co-Authored-By: Claude Opus 4.7 (1M context) --- skills/hyperframes/house-style.md | 2 ++ .../hyperframes/references/prompt-expansion.md | 17 +++++++++++------ 2 files changed, 13 insertions(+), 6 deletions(-) diff --git a/skills/hyperframes/house-style.md b/skills/hyperframes/house-style.md index a5edc4b05..f3e634bd7 100644 --- a/skills/hyperframes/house-style.md +++ b/skills/hyperframes/house-style.md @@ -44,6 +44,8 @@ Ideas (mix and match, 2-5 per scene): 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](references/motion-principles.md) for full rules. Quick: 0.3–0.6s, vary eases, combine transforms on entrances, overlap entries. diff --git a/skills/hyperframes/references/prompt-expansion.md b/skills/hyperframes/references/prompt-expansion.md index 8aab52241..a8ed8a945 100644 --- a/skills/hyperframes/references/prompt-expansion.md +++ b/skills/hyperframes/references/prompt-expansion.md @@ -4,7 +4,12 @@ Expand a sparse user prompt into a full production prompt. Runs AFTER `design.md ## Prerequisites -- `design.md` exists in the project root. If not, run Step 0a (Design system) first. Expansion without a design context produces generic scene breakdowns that later agents ignore. +Read before generating: + +- `design.md` — palette, typography, energy, mood. The expansion quotes these values; it does not invent any. +- [../house-style.md](../house-style.md) — its rules for Background Layer (2-5 decoratives), Color, Motion, Typography apply to every scene. The expansion does NOT re-state those rules; it writes output that conforms to them. + +If `design.md` doesn't exist yet, run Step 0a (Design system) first. Expansion without a design context produces generic scene breakdowns that later agents ignore. ## When to expand @@ -20,16 +25,16 @@ Expand into a full production prompt with these sections: 1. **Title + style block** — cite design.md's palette (bg/fg/accent hex values), typography pairing, energy level, and mood. Do NOT invent a palette — quote the design.md values. 2. **Global animation rules** — parallax layers, micro-motion requirements, kinetic typography, pacing rules, transition style. Align energy with design.md (calm → slow eases, high energy → snappy eases). -3. **Scene-by-scene breakdown** — for each scene: +3. **Scene-by-scene breakdown** — for each scene, three layers: - Time range and title - - **Background layer (REQUIRED, 2-5 decoratives)** — pick from house-style's decorative list (radial glow / oversized ghost type / accent hairline rules / grid patterns / thematic decoratives) AND confirm each uses design.md's palette values. "Single ambient motion per scene" means one LOOPING MOTION applied to these decoratives, not one element total. - - **Midground (content)** — specific visual elements (not generic — "alien claw slides across wall" not "scary things happen") - - **Foreground (text + accents)** — text/typography with animation style + - Background layer — list the decoratives (per the prerequisite rules) + - Midground — the specific content elements (not generic: "alien claw slides across wall" not "scary things happen") + - Foreground — text and typography with their animation style - Transition to next scene as a specific morph (what object becomes what) 4. **Recurring motifs** — visual threads that appear across multiple scenes, always drawn from design.md's palette and typography. 5. **Transition rules** — every scene-to-scene connection described as object morphing. Transition duration/ease should match design.md's energy level. 6. **Pacing curve** — where energy builds, peaks, and releases. -7. **Negative prompt** — what to avoid. Always include: "no colors outside design.md palette, no fonts outside design.md typography pair". +7. **Negative prompt** — what to avoid for this specific composition. ## Output From 63f430bea86feb0028ba7a1dc0b9dbf99384f045 Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Thu, 16 Apr 2026 16:53:26 -0700 Subject: [PATCH 07/37] feat(skills): always run prompt expansion, not gated on sparseness MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Expansion is not about lengthening a short prompt — it's about grounding the user's intent against design.md and house-style.md and producing a consistent intermediate that every downstream agent reads the same way. Even a fully-detailed user prompt benefits: - Color words ("warm", "cinematic") → resolved to design.md hex values - Decorative layers the user forgot → added explicitly per house-style - Vague transitions → specified as morph operations with duration/ease tied to design.md energy - Per-scene timing → verified to sum to stated total The eval showed p5 (fully-expanded brief) skipping this step and missing the benefit. When expansion runs on an already-expanded prompt, it's mostly pass-through, but it still binds the prompt to design.md and house-style — which is the contract downstream steps depend on. Single-scene compositions and trivial edits are the only exceptions. Co-Authored-By: Claude Opus 4.7 (1M context) --- skills/hyperframes/SKILL.md | 6 +++++- .../hyperframes/references/prompt-expansion.md | 17 ++++++++++++----- 2 files changed, 17 insertions(+), 6 deletions(-) diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md index 0f205bb31..de127873c 100644 --- a/skills/hyperframes/SKILL.md +++ b/skills/hyperframes/SKILL.md @@ -36,7 +36,11 @@ Do NOT begin prompt expansion or scene authoring without a `design.md`. Design d ### Step 0b: Prompt expansion -If the user's prompt lacks scene-by-scene structure, expand it into a full production prompt. Read [references/prompt-expansion.md](references/prompt-expansion.md) for the full process and output format. The expanded prompt must cite design.md's palette, typography, and mood — not repeat them as generic defaults. Present the expanded prompt to the user for approval before proceeding. +Always run on every composition (except single-scene pieces and trivial edits). This step grounds the user's intent against `design.md` and `house-style.md` and produces a consistent intermediate that every downstream agent — scene subagents, assembler, lint — reads the same way. + +Read [references/prompt-expansion.md](references/prompt-expansion.md) for the full process and output format. The expanded prompt quotes design.md's palette hex values, typography pair, and motion energy verbatim — it does not re-state generic defaults. Present the expanded prompt to the user for approval before proceeding. + +If the user's prompt is already scene-by-scene, the expansion is mostly pass-through, but it still binds the prompt to design.md and house-style — which is the contract the downstream steps depend on. ### Step 1: Plan Before writing HTML, think at a high level: diff --git a/skills/hyperframes/references/prompt-expansion.md b/skills/hyperframes/references/prompt-expansion.md index a8ed8a945..87f5c87fc 100644 --- a/skills/hyperframes/references/prompt-expansion.md +++ b/skills/hyperframes/references/prompt-expansion.md @@ -1,6 +1,8 @@ # Prompt Expansion -Expand a sparse user prompt into a full production prompt. Runs AFTER `design.md` is established (Step 0a) — the expansion consumes design.md and produces output that cites its palette, typography, and motion energy. +Run on every composition. Expansion is not about lengthening a short prompt — it's about grounding the user's intent against `design.md` and `house-style.md` and producing a consistent intermediate that every downstream agent reads the same way. + +Runs AFTER `design.md` is established (Step 0a). The expansion consumes design.md and produces output that cites its palette, typography, and motion energy verbatim. ## Prerequisites @@ -11,13 +13,18 @@ Read before generating: If `design.md` doesn't exist yet, run Step 0a (Design system) first. Expansion without a design context produces generic scene breakdowns that later agents ignore. -## When to expand +## Why always run it + +A detailed user prompt can still be ambiguous or under-specified in ways only the expansion step surfaces: -A prompt needs expansion if it lacks: scene-by-scene structure, specific visual elements per scene, transition descriptions, or timing. +- The user's color words ("warm", "cinematic") get resolved to design.md's exact hex values. +- Decorative layers that the user forgot to mention get added explicitly, per house-style. +- Transitions vaguely described ("cut", "crossfade") get specified as morph operations with duration and ease tied to design.md's energy. +- Per-scene timing gets verified to sum to the stated total. -**Sparse:** "make me a trailer about a killer alien on a spaceship" or "coconut water promo, tropical, 45 seconds" +If the user's prompt is already scene-by-scene, the expansion is shorter and largely pass-through, but it still binds the prompt to design.md and house-style — which is the contract the scene subagents and assembler depend on. -**Already expanded:** Has numbered scenes with timing, specific elements, transition rules, and animation direction — skip this step. +**Do not skip.** Single-scene compositions and trivial edits are the only exceptions. ## What to generate From 68969fbeb5b58d6b3a3f95896513912c9e6cf288 Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Thu, 16 Apr 2026 17:44:58 -0700 Subject: [PATCH 08/37] feat(skills): expansion is never pass-through, always enriches MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The p2 eval (sparse prompt, 6 scenes) was dense and alive because expansion had to invent atmosphere and micro-details to fill in the 1-sentence input. The scene subagents then built from that rich spec. p3/p5/p6 (detailed prompts) produced muted output because the expansion was framed as "largely pass-through" for already-detailed inputs. Scene subagents got a thin brief and built thin output. Make expansion always enrich, never pass-through: - Every user prompt is a *seed*, not a spec. Expansion takes what the user wrote and adds atmosphere, ambient motion, micro-details. User's content stays; expansion builds on top. - Scene-by-scene breakdown now enumerates 5 required fields per scene: background (2-5 decoratives with ambient motion), midground, foreground, micro-details (2-3 per scene: registration marks, tick indicators, monospace labels, background data streams, grid patterns), transition morph. - Framing note: the quality gap between a single-pass composition and a multi-scene-pipeline composition comes from this step. If expansion front-loads the richness, every scene subagent builds from a rich brief; every scene comes out alive. Addresses user feedback after the eval review: "the only significant difference I see is in p2" — because p2 was the only case where expansion had to enrich. Making enrichment mandatory everywhere. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../references/prompt-expansion.md | 31 ++++++++++++------- 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/skills/hyperframes/references/prompt-expansion.md b/skills/hyperframes/references/prompt-expansion.md index 87f5c87fc..c33b27f77 100644 --- a/skills/hyperframes/references/prompt-expansion.md +++ b/skills/hyperframes/references/prompt-expansion.md @@ -15,16 +15,22 @@ If `design.md` doesn't exist yet, run Step 0a (Design system) first. Expansion w ## Why always run it -A detailed user prompt can still be ambiguous or under-specified in ways only the expansion step surfaces: +**The expansion is never pass-through.** Every user prompt — no matter how detailed — is a _seed_. The expansion's job is to enrich it into a fully-realized per-scene production spec that the scene subagents can build from directly. -- The user's color words ("warm", "cinematic") get resolved to design.md's exact hex values. -- Decorative layers that the user forgot to mention get added explicitly, per house-style. -- Transitions vaguely described ("cut", "crossfade") get specified as morph operations with duration and ease tied to design.md's energy. -- Per-scene timing gets verified to sum to the stated total. +Even a detailed 7-scene brief lacks things only the expansion adds: -If the user's prompt is already scene-by-scene, the expansion is shorter and largely pass-through, but it still binds the prompt to design.md and house-style — which is the contract the scene subagents and assembler depend on. +- **Atmosphere layers per scene** (required 2–5 from house-style: radial glows, ghost type, hairline rules, grain, thematic decoratives) — the user's prompt almost never lists these; expansion adds them. +- **Secondary motion for every decorative** — breath, drift, pulse, orbit. A decorative without ambient motion feels dead. +- **Micro-details that make a scene feel real** — registration marks, tick indicators, monospace coord labels, typographic accents, code snippets in the background, grid patterns. Things the user didn't think to request. +- **Transition choreography at the object level** — not "crossfade" but "X expands outward and becomes Y". Specific duration, ease, and morph source/target. +- **Pacing beats within each scene** — where tension builds, where a hold lets the viewer breathe, where the accent word lands. +- **Exact hex values, typography parameters, ease choices** from design.md — no vagueness left for the scene subagent to guess. -**Do not skip.** Single-scene compositions and trivial edits are the only exceptions. +Expansion's job on a detailed prompt is not to summarize or pass through — it's to **take what the user wrote and make it richer**. The user's content stays; the atmosphere, ambient motion, and micro-details are added on top. That's what makes the difference between a scene that matches the brief and a scene that feels alive. + +The quality gap between a single-pass composition and a multi-scene-pipeline composition comes from this step. Expansion front-loads the richness so every scene subagent builds from a rich brief, not a terse one. + +**Do not skip. Do not pass through.** Single-scene compositions and trivial edits are the only exceptions. ## What to generate @@ -32,12 +38,13 @@ Expand into a full production prompt with these sections: 1. **Title + style block** — cite design.md's palette (bg/fg/accent hex values), typography pairing, energy level, and mood. Do NOT invent a palette — quote the design.md values. 2. **Global animation rules** — parallax layers, micro-motion requirements, kinetic typography, pacing rules, transition style. Align energy with design.md (calm → slow eases, high energy → snappy eases). -3. **Scene-by-scene breakdown** — for each scene, three layers: +3. **Scene-by-scene breakdown** — for each scene, enumerate: - Time range and title - - Background layer — list the decoratives (per the prerequisite rules) - - Midground — the specific content elements (not generic: "alien claw slides across wall" not "scary things happen") - - Foreground — text and typography with their animation style - - Transition to next scene as a specific morph (what object becomes what) + - **Background layer** — list the 2–5 decoratives (from house-style's list) with exact positioning, opacity values from design.md, and the ambient motion each uses (breath, drift, pulse, orbit). This is almost always richer than what the user's prompt specified — the user rarely lists atmosphere, you add it. + - **Midground** — content elements (not generic: "alien claw slides across wall" not "scary things happen"). Keep everything the user specified; add what's missing. + - **Foreground** — text, typography, animation style per text element. Type sizes and weights quoted from design.md. + - **Micro-details** — registration marks, tick indicators, monospace coord/meta labels, typographic accents, background data streams, grid patterns. These are what make a scene feel real. The user's prompt never lists them; expansion adds at least 2–3 per scene. + - **Transition out** — specific morph (what object becomes what, duration, ease), not just "cut" or "crossfade" 4. **Recurring motifs** — visual threads that appear across multiple scenes, always drawn from design.md's palette and typography. 5. **Transition rules** — every scene-to-scene connection described as object morphing. Transition duration/ease should match design.md's energy level. 6. **Pacing curve** — where energy builds, peaks, and releases. From 4819e69e1ddd3e6612d028bcba899eaa06af030d Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Tue, 28 Apr 2026 21:04:15 -0700 Subject: [PATCH 09/37] feat(skills): adopt google-labs-code/design.md spec with motion extension DESIGN.md now uses YAML front matter (machine-readable tokens) + markdown prose, following the google-labs-code/design.md format spec. Extended with a `motion:` namespace for video-specific tokens (energy, easing, duration, atmosphere layers, transition shaders). - step-2-design.md: full rewrite with token schema, section order, two complete examples (dark cinematic + light corporate) - visual-styles.md: all 8 presets now include YAML token blocks ready to copy into design.md front matter - SKILL.md: Step 0a explains new format, resolution order uses preset picker instead of visual-style plugin, Visual Identity Gate updated - prompt-expansion.md: references structured token paths instead of prose scraping - house-style.md: clarified design.md takes precedence Co-Authored-By: Claude Opus 4.6 (1M context) --- skills/hyperframes/SKILL.md | 47 +- skills/hyperframes/house-style.md | 2 +- .../references/prompt-expansion.md | 22 +- skills/hyperframes/visual-styles.md | 446 +++++++++++++----- .../references/step-2-design.md | 341 ++++++++----- 5 files changed, 613 insertions(+), 245 deletions(-) diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md index de127873c..9c56624e6 100644 --- a/skills/hyperframes/SKILL.md +++ b/skills/hyperframes/SKILL.md @@ -15,24 +15,39 @@ Run this BEFORE prompt expansion. Design direction shapes expansion output (atmo Every composition MUST have a `design.md` in the project root before construction. It is the source of truth for colors, typography, motion, spacing, and mood — every later step (expansion output, scene subagents, assembler) reads it. -**Resolution order:** +#### DESIGN.md format -1. **Exists** — if `design.md` is already in the project root, read it and proceed to Step 1. -2. **Build one via the `visual-style` skill** — invoke the `/visual-style` skill (Skill tool, `skill: "visual-style"`) in "Create" mode. Ask the user the batched vibe questions the skill prescribes (mood, palette, typography, energy), then have it emit a full design spec. Save the result to `design.md` in the project root. -3. **Interactive picker (fallback)** — if the user prefers pre-built options instead of a guided build, read [references/design-picker.md](references/design-picker.md) and serve the picker. +DESIGN.md uses the [google-labs-code/design.md](https://github.com/google-labs-code/design.md) spec, extended with a `motion:` namespace for video: + +- **YAML front matter** — machine-readable tokens (`colors`, `typography`, `rounded`, `spacing`, `components`, `motion`). These are normative values agents parse directly. +- **Markdown prose** — `## Overview`, `## Colors`, `## Typography`, `## Elevation`, `## Components`, `## Do's and Don'ts`. Prose explains the _why_ behind each token. + +Token references use `{path.to.token}` syntax: `{colors.primary}`, `{typography.headline}`, `{rounded.md}`. + +The `motion:` extension carries video-specific tokens: `energy` (calm/moderate/high), `easing` (entry/exit/ambient GSAP eases), `duration` (entrance/hold/transition in seconds), `atmosphere` (decorative layer list), and `transition` (shader name). + +#### Resolution order + +1. **Exists** — if `design.md` is already in the project root, read it and proceed to Step 1. If it lacks YAML front matter, extract its values into front matter and keep the prose. +2. **Style picker** — read [visual-styles.md](./visual-styles.md) for the 8 named presets. Each preset includes a complete YAML token block. Ask the user which mood fits, copy the token block into `design.md` front matter, then add prose sections. Customize colors/fonts to the user's brand. +3. **Guided build** — if no preset fits, ask 3 questions: + - What's the mood? (explosive / cinematic / fluid / technical / chaotic / warm) + - Light or dark canvas? + - Any specific brand colors, fonts, or visual references? + Then write a full DESIGN.md with YAML front matter + prose from the answers. 4. **House-style defaults (last resort)** — only if the user explicitly says "skip design" or this is a tiny edit to an existing composition without a design.md. In that case, follow [house-style.md](./house-style.md) and write its palette + typography into `design.md` so downstream steps have a file to read. Do NOT begin prompt expansion or scene authoring without a `design.md`. Design direction affects expansion output (atmosphere layers, motion energy, typography choices) — expansion before design produces generic scene breakdowns that later ignore the palette. ### Using design.md during construction -`design.md` is the source of truth for all visual decisions. Use only the values it defines — colors, fonts, spacing, corners, depth, component treatments, and any other fields the user has added. Do not invent new colors, substitute fonts, or override its rules. If the composition needs a value the design.md doesn't cover, follow [house-style.md](./house-style.md) for that specific decision. +`design.md` is the source of truth for all visual decisions. Use YAML front matter tokens as normative values — `{colors.primary}`, `{typography.headline}`, `{motion.easing.entry}`. Do not invent new colors, substitute fonts, or override its rules. If the composition needs a value design.md doesn't cover, follow [house-style.md](./house-style.md) for that specific decision. **Passing design.md downstream:** -- **Prompt expansion** — include the palette, typography, and mood/energy from design.md in the expanded prompt's style block. Every scene breakdown should reference the palette and note which decorative motifs belong. -- **Scene subagents** — each subagent receives the full `design.md` (or a tight summary of its values). Fragment authors apply only these values; house-style decoratives are added WITHIN the design.md's palette constraints. -- **Assembler** — reads design.md to populate any global CSS variables in the scaffold. +- **Prompt expansion** — cite YAML token paths (`{colors.accent}`, `{motion.energy}`, `{typography.headline.fontFamily}`) in the expanded prompt's style block. Every scene breakdown references the palette by token name. +- **Scene subagents** — each subagent receives the full `design.md` (or its YAML front matter). Fragment authors apply only these values; house-style decoratives are added WITHIN the design.md's palette constraints. +- **Assembler** — reads design.md front matter to populate global CSS variables in the scaffold. Maps `{colors.*}` → `var(--color-*)`, `{typography.*}` → font declarations, `{spacing.*}` → gap/padding values. ### Step 0b: Prompt expansion @@ -43,6 +58,7 @@ Read [references/prompt-expansion.md](references/prompt-expansion.md) for the fu If the user's prompt is already scene-by-scene, the expansion is mostly pass-through, but it still binds the prompt to design.md and house-style — which is the contract the downstream steps depend on. ### Step 1: Plan + Before writing HTML, think at a high level: 1. **What** — what should the viewer experience? Identify the narrative arc, key moments, and emotional beats. @@ -56,20 +72,19 @@ For small edits (fix a color, adjust timing, add one element), skip straight to ### Visual Identity Gate -Before writing ANY composition HTML, you MUST have a visual identity defined. Do NOT write compositions with default or generic colors. +Before writing ANY composition HTML, you MUST have a `design.md` with YAML front matter tokens. Do NOT write compositions with default or generic colors. Check in this order: -1. **DESIGN.md exists in the project?** → Read it. Use its exact colors, fonts, motion rules, and "What NOT to Do" constraints. -2. **visual-style.md exists?** → Read it. Apply its `style_prompt_full` and structured fields. (Note: `visual-style.md` is a project-specific file. `visual-styles.md` is the style library with 8 named presets — different files.) -3. **User named a style** (e.g., "Swiss Pulse", "dark and techy", "luxury brand")? → Read [visual-styles.md](./visual-styles.md) for the 8 named presets. Generate a minimal DESIGN.md with: `## Style Prompt` (one paragraph), `## Colors` (3-5 hex values with roles), `## Typography` (1-2 font families), `## What NOT to Do` (3-5 anti-patterns). -4. **None of the above?** → Ask 3 questions before writing any HTML: +1. **design.md exists in the project?** → Read it. Parse YAML front matter for token values. Use its exact `{colors.*}`, `{typography.*}`, `{motion.*}`, and "Do's and Don'ts" constraints. +2. **User named a style** (e.g., "Swiss Pulse", "dark and techy", "luxury brand")? → Read [visual-styles.md](./visual-styles.md) for the 8 named presets. Copy the matching YAML token block into a new `design.md`, add prose sections, customize to the user's brand. +3. **None of the above?** → Ask 3 questions before writing any HTML: - What's the mood? (explosive / cinematic / fluid / technical / chaotic / warm) - Light or dark canvas? - Any specific brand colors, fonts, or visual references? - Then generate a minimal DESIGN.md from the answers. + Then generate a full `design.md` with YAML front matter + prose from the answers. -Every composition must trace its palette and typography back to a DESIGN.md, visual-style.md, or explicit user direction. If you're reaching for `#333`, `#3b82f6`, or `Roboto` — you skipped this step. +Every composition must trace its palette and typography back to a `design.md` with structured tokens. If you're reaching for `#333`, `#3b82f6`, or `Roboto` — you skipped this step. For motion defaults, sizing, entrance patterns, and easing — follow [house-style.md](./house-style.md). The house style handles HOW things move. The DESIGN.md handles WHAT things look like. @@ -293,7 +308,7 @@ tl.from("#s2-heading", { x: -40, opacity: 0, duration: 0.6, ease: "expo.out" }, - 60px+ headlines, 20px+ body, 16px+ data labels for rendered video - `font-variant-numeric: tabular-nums` on number columns -When no `visual-style.md` or animation direction is provided, follow [house-style.md](./house-style.md) for aesthetic defaults. +When no `design.md` or animation direction is provided, follow [house-style.md](./house-style.md) for aesthetic defaults. ## Typography and Assets diff --git a/skills/hyperframes/house-style.md b/skills/hyperframes/house-style.md index f3e634bd7..cf6a869cd 100644 --- a/skills/hyperframes/house-style.md +++ b/skills/hyperframes/house-style.md @@ -1,6 +1,6 @@ # House Style -Creative direction for compositions when no `visual-style.md` is provided. These are starting points — override anything that doesn't serve the content. +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 YAML tokens take precedence; house-style fills gaps for values the design.md doesn't define. ## Before Writing HTML diff --git a/skills/hyperframes/references/prompt-expansion.md b/skills/hyperframes/references/prompt-expansion.md index c33b27f77..3a1ff79d8 100644 --- a/skills/hyperframes/references/prompt-expansion.md +++ b/skills/hyperframes/references/prompt-expansion.md @@ -2,13 +2,13 @@ Run on every composition. Expansion is not about lengthening a short prompt — it's about grounding the user's intent against `design.md` and `house-style.md` and producing a consistent intermediate that every downstream agent reads the same way. -Runs AFTER `design.md` is established (Step 0a). The expansion consumes design.md and produces output that cites its palette, typography, and motion energy verbatim. +Runs AFTER `design.md` is established (Step 0a). The expansion consumes design.md's YAML front matter tokens and produces output that cites them by token path. ## Prerequisites Read before generating: -- `design.md` — palette, typography, energy, mood. The expansion quotes these values; it does not invent any. +- `design.md` — parse YAML front matter for `colors`, `typography`, `motion`, `spacing`, `rounded`, `components` tokens. The expansion cites these by token path (`{colors.primary}`, `{motion.energy}`, `{typography.headline.fontFamily}`); it does not invent values. - [../house-style.md](../house-style.md) — its rules for Background Layer (2-5 decoratives), Color, Motion, Typography apply to every scene. The expansion does NOT re-state those rules; it writes output that conforms to them. If `design.md` doesn't exist yet, run Step 0a (Design system) first. Expansion without a design context produces generic scene breakdowns that later agents ignore. @@ -36,19 +36,19 @@ The quality gap between a single-pass composition and a multi-scene-pipeline com Expand into a full production prompt with these sections: -1. **Title + style block** — cite design.md's palette (bg/fg/accent hex values), typography pairing, energy level, and mood. Do NOT invent a palette — quote the design.md values. -2. **Global animation rules** — parallax layers, micro-motion requirements, kinetic typography, pacing rules, transition style. Align energy with design.md (calm → slow eases, high energy → snappy eases). +1. **Title + style block** — cite design.md's YAML tokens by path: `{colors.primary}`, `{colors.accent}`, `{typography.headline.fontFamily}`, `{motion.energy}`. Do NOT invent a palette — quote design.md token values. +2. **Global animation rules** — parallax layers, micro-motion requirements, kinetic typography, pacing rules, transition style. Use `{motion.easing.entry}` / `{motion.easing.exit}` / `{motion.easing.ambient}` and `{motion.duration.*}` from design.md. Align energy with `{motion.energy}` (calm → slow eases, high → snappy eases). 3. **Scene-by-scene breakdown** — for each scene, enumerate: - Time range and title - - **Background layer** — list the 2–5 decoratives (from house-style's list) with exact positioning, opacity values from design.md, and the ambient motion each uses (breath, drift, pulse, orbit). This is almost always richer than what the user's prompt specified — the user rarely lists atmosphere, you add it. + - **Background layer** — list the 2–5 decoratives (from `{motion.atmosphere}` list + house-style) with exact positioning, opacity values from `{colors.*}`, and the ambient motion each uses (breath, drift, pulse, orbit). The user rarely lists atmosphere; expansion adds it. - **Midground** — content elements (not generic: "alien claw slides across wall" not "scary things happen"). Keep everything the user specified; add what's missing. - - **Foreground** — text, typography, animation style per text element. Type sizes and weights quoted from design.md. - - **Micro-details** — registration marks, tick indicators, monospace coord/meta labels, typographic accents, background data streams, grid patterns. These are what make a scene feel real. The user's prompt never lists them; expansion adds at least 2–3 per scene. - - **Transition out** — specific morph (what object becomes what, duration, ease), not just "cut" or "crossfade" -4. **Recurring motifs** — visual threads that appear across multiple scenes, always drawn from design.md's palette and typography. -5. **Transition rules** — every scene-to-scene connection described as object morphing. Transition duration/ease should match design.md's energy level. + - **Foreground** — text using `{typography.headline}`, `{typography.body}`, `{typography.label}` tokens. Type sizes and weights quoted from design.md YAML. + - **Micro-details** — registration marks, tick indicators, monospace coord/meta labels, typographic accents, background data streams, grid patterns. These make a scene feel real. The user's prompt never lists them; expansion adds at least 2–3 per scene. + - **Transition out** — use `{motion.transition}` shader. Specific morph (what object becomes what), duration from `{motion.duration.transition}`, ease from `{motion.easing.exit}`. +4. **Recurring motifs** — visual threads across scenes, drawn from `{colors.*}` and `{typography.*}` tokens. +5. **Transition rules** — every scene-to-scene connection described as object morphing. Duration/ease from `{motion.duration.transition}` and `{motion.easing.*}`. 6. **Pacing curve** — where energy builds, peaks, and releases. -7. **Negative prompt** — what to avoid for this specific composition. +7. **Negative prompt** — what to avoid, informed by design.md's "Do's and Don'ts" section. ## Output diff --git a/skills/hyperframes/visual-styles.md b/skills/hyperframes/visual-styles.md index d1e8025c8..55f618815 100644 --- a/skills/hyperframes/visual-styles.md +++ b/skills/hyperframes/visual-styles.md @@ -1,14 +1,14 @@ # Visual Style Library -Named visual identities for HyperFrames videos. Each style is grounded in a real graphic design tradition. Use them to give your video a specific visual personality, not just generic "clean" or "bold." +Named visual identities for HyperFrames videos. Each style is grounded in a real graphic design tradition and expressed as a DESIGN.md-compatible token block. Use them as starters — copy the YAML into your project's `design.md` front matter, then customize. **How to pick:** Match mood first, content second. Ask: _"What should the viewer FEEL?"_ -**How to use:** Reference the style in your scene plan. Translate the style's principles into concrete composition decisions — palette choice, font selection, entrance patterns, transition type, ambient motion feel. +**How to use:** Copy the style's YAML token block into `design.md` front matter. Add `## Overview`, `## Colors`, `## Typography`, `## Elevation`, `## Components`, `## Do's and Don'ts` prose sections to complete the file. ## Quick Reference -| Style | Mood | Best for | Primary shader | +| Style | Mood | Best for | Transition shader | | --------------- | --------------------- | ---------------------------------- | --------------------------------- | | Swiss Pulse | Clinical, precise | SaaS, data, dev tools, metrics | Cinematic Zoom or SDF Iris | | Velvet Standard | Premium, timeless | Luxury, enterprise, keynotes | Cross-Warp Morph | @@ -25,161 +25,395 @@ Named visual identities for HyperFrames videos. Each style is grounded in a real **Mood:** Clinical, precise | **Best for:** SaaS dashboards, developer tools, APIs, metrics -- Black (`#1a1a1a`), white, ONE accent — electric blue (`#0066FF`) or amber (`#FFB300`) -- Helvetica or Inter Bold for headlines, Regular for labels. Numbers large (80–120px) -- Grid-locked compositions. Every element snaps to an invisible 12-column grid -- Animated counters count up from 0. Hard cuts, no decorative transitions -- Transitions: Cinematic Zoom or SDF Iris (precise, geometric) - -**GSAP signature:** `expo.out`, `power4.out`. Entries are fast and snap into place. Nothing floats. - -``` -Swiss Pulse: Black/white + one electric accent. Grid-locked compositions. -Numbers dominate the frame at 80-120px. Counter animations from 0. -Hard cuts or geometric transitions. Nothing decorative. +```yaml +name: Swiss Pulse +colors: + primary: "#1a1a1a" + on-primary: "#ffffff" + accent: "#0066FF" +typography: + headline: + fontFamily: Helvetica Neue + fontSize: 5rem + fontWeight: 700 + label: + fontFamily: Inter + fontSize: 0.875rem + fontWeight: 400 + stat: + fontFamily: Helvetica Neue + fontSize: 7rem + fontWeight: 700 +rounded: + none: 0px + sm: 2px +spacing: + sm: 8px + md: 16px + lg: 32px +motion: + energy: high + easing: + entry: "expo.out" + exit: "power4.in" + ambient: "none" + duration: + entrance: 0.4 + hold: 1.5 + transition: 0.6 + atmosphere: + - grid-lines + - registration-marks + transition: cinematic-zoom ``` +Grid-locked compositions. Every element snaps to an invisible 12-column grid. Numbers dominate the frame at 80–120px. Animated counters count up from 0. Hard cuts, no decorative transitions. Nothing floats. + --- ## 2. Velvet Standard — Massimo Vignelli **Mood:** Premium, timeless | **Best for:** Luxury products, enterprise software, keynotes, investor decks -- Black, white, ONE rich accent — deep navy (`#1a237e`) or gold (`#c9a84c`) -- Thin sans-serif, ALL CAPS, wide letter-spacing (`0.15em+`) -- Generous negative space. Symmetrical, centered, architectural precision -- Slow, deliberate. Sequential reveals with long holds. No frantic motion -- Transitions: Cross-Warp Morph (elegant, organic flow between scenes) - -**GSAP signature:** `sine.inOut`, `power1`. Nothing snaps — everything glides with intention. - -``` -Velvet Standard: Black, white, one rich accent. Thin ALL CAPS type with wide tracking. -Generous negative space. Sequential reveals, long holds. -Cross-Warp Morph transitions. Slow and deliberate — luxury takes its time. +```yaml +name: Velvet Standard +colors: + primary: "#0a0a0a" + on-primary: "#ffffff" + accent: "#1a237e" +typography: + headline: + fontFamily: Inter + fontSize: 3rem + fontWeight: 300 + letterSpacing: 0.15em + textTransform: uppercase + body: + fontFamily: Inter + fontSize: 1rem + fontWeight: 300 + lineHeight: 1.6 +rounded: + sm: 0px + md: 2px +spacing: + sm: 16px + md: 32px + lg: 64px +motion: + energy: calm + easing: + entry: "sine.inOut" + exit: "power1.in" + ambient: "sine.inOut" + duration: + entrance: 1.2 + hold: 3.0 + transition: 1.5 + atmosphere: + - subtle-grain + - hairline-rules + transition: cross-warp-morph ``` +Generous negative space. Symmetrical, centered, architectural precision. Thin sans-serif, ALL CAPS, wide letter-spacing. Sequential reveals with long holds. Nothing snaps — everything glides with intention. Luxury takes its time. + --- ## 3. Deconstructed — Neville Brody **Mood:** Industrial, raw | **Best for:** Tech news, developer launches, security products, punk-energy reveals -- Dark grey (`#1a1a1a`), rust orange (`#D4501E`), raw white (`#f0f0f0`) -- Type at angles, overlapping edges, escaping frames. Bold industrial weight -- Gritty textures: scan-line effects, glitch artifacts baked into the design -- Text SLAMS and SHATTERS. Letters scramble then snap to final position -- Transitions: Glitch shader or Whip Pan (breaks the rules, feels aggressive) - -**GSAP signature:** `back.out(2.5)`, `steps(8)`, `elastic.out(1.2, 0.4)`. Intentional irregularity. - -``` -Deconstructed: Dark grey #1a1a1a + rust orange #D4501E. Type at angles, escaping frames. -Scan-line glitch overlays. Text SLAMS and scrambles into place. -Glitch shader transitions. Industrial and raw — nothing should feel polished. +```yaml +name: Deconstructed +colors: + primary: "#1a1a1a" + on-primary: "#f0f0f0" + accent: "#D4501E" +typography: + headline: + fontFamily: Space Grotesk + fontSize: 4rem + fontWeight: 700 + label: + fontFamily: Space Mono + fontSize: 0.75rem + fontWeight: 700 + textTransform: uppercase +rounded: + none: 0px +spacing: + sm: 4px + md: 12px + lg: 24px +motion: + energy: high + easing: + entry: "back.out(2.5)" + exit: "steps(8)" + ambient: "elastic.out(1.2, 0.4)" + duration: + entrance: 0.3 + hold: 1.0 + transition: 0.5 + atmosphere: + - scan-lines + - glitch-artifacts + - grain-overlay + transition: glitch ``` +Type at angles, overlapping edges, escaping frames. Bold industrial weight. Gritty textures: scan-line effects, glitch artifacts baked into design. Text SLAMS and SHATTERS. Letters scramble then snap to final position. Intentional irregularity — nothing should feel polished. + --- ## 4. Maximalist Type — Paula Scher **Mood:** Loud, kinetic | **Best for:** Big product launches, milestone announcements, high-energy hype videos -- Bold saturated: red (`#E63946`), yellow (`#FFD60A`), black, white — maximum contrast -- Text IS the visual. Overlapping type layers at different scales and angles, filling 50–80% of frame -- Everything is kinetic: slamming, sliding, scaling. 2–3 second rapid-fire scenes -- Text layered OVER footage — never empty backgrounds -- Transitions: Ridged Burn (explosive, dramatic, impossible to ignore) - -**GSAP signature:** `expo.out`, `back.out(1.8)`. Fast arrivals, hard stops. - -``` -Maximalist Type: Red, yellow, black, white — max contrast. Text IS the visual. -Overlapping at different scales, 50-80% of frame. Everything in motion. -Ridged Burn transitions. No static moments — kinetic energy throughout. +```yaml +name: Maximalist Type +colors: + primary: "#0a0a0a" + on-primary: "#ffffff" + accent-red: "#E63946" + accent-yellow: "#FFD60A" +typography: + headline: + fontFamily: Anton + fontSize: 8rem + fontWeight: 400 + textTransform: uppercase + subhead: + fontFamily: Space Grotesk + fontSize: 3rem + fontWeight: 700 +rounded: + none: 0px +spacing: + sm: 0px + md: 8px +motion: + energy: high + easing: + entry: "expo.out" + exit: "back.out(1.8)" + ambient: "power3.out" + duration: + entrance: 0.3 + hold: 0.8 + transition: 0.4 + atmosphere: + - type-layers + - color-blocks + transition: ridged-burn ``` +Text IS the visual. Overlapping type layers at different scales and angles, filling 50–80% of frame. Bold saturated colors — maximum contrast. Everything kinetic: slamming, sliding, scaling. 2–3 second rapid-fire scenes. No static moments. Fast arrivals, hard stops. + --- ## 5. Data Drift — Refik Anadol **Mood:** Futuristic, immersive | **Best for:** AI products, ML platforms, data companies, speculative tech -- Iridescent: deep black (`#0a0a0a`), electric purple (`#7c3aed`), cyan (`#06b6d4`) -- Thin futuristic sans-serif — floating, weightless, minimal -- Fluid morphing compositions. Extreme scale shifts (micro → macro) -- Particles coalesce into numbers. Light traces data paths through the frame -- Transitions: Gravitational Lens or Domain Warp (otherworldly distortion) - -**GSAP signature:** `sine.inOut`, `power2.out`. Smooth, continuous, organic. Nothing hard. - -``` -Data Drift: Deep black #0a0a0a with electric purple #7c3aed and cyan #06b6d4. -Thin futuristic type, minimal text. Particles coalesce into numbers. -Gravitational Lens or Domain Warp transitions. Fluid, immersive, otherworldly. +```yaml +name: Data Drift +colors: + primary: "#0a0a0a" + on-primary: "#e0e0e0" + accent-purple: "#7c3aed" + accent-cyan: "#06b6d4" +typography: + headline: + fontFamily: Inter + fontSize: 2.5rem + fontWeight: 200 + letterSpacing: 0.05em + body: + fontFamily: Inter + fontSize: 0.875rem + fontWeight: 300 +rounded: + sm: 4px + md: 12px + full: 9999px +spacing: + sm: 16px + md: 32px + lg: 64px +motion: + energy: moderate + easing: + entry: "sine.inOut" + exit: "power2.out" + ambient: "sine.inOut" + duration: + entrance: 1.0 + hold: 2.5 + transition: 1.5 + atmosphere: + - particle-field + - light-traces + - radial-glow + transition: gravitational-lens ``` +Thin futuristic sans-serif — floating, weightless, minimal. Fluid morphing compositions. Extreme scale shifts (micro → macro). Particles coalesce into numbers. Light traces data paths through the frame. Smooth, continuous, organic. Nothing hard. + --- ## 6. Soft Signal — Stefan Sagmeister **Mood:** Intimate, warm | **Best for:** Wellness brands, personal stories, lifestyle products, human-centered apps -- Warm amber (`#F5A623`), cream (`#FFF8EC`), dusty rose (`#C4A3A3`), sage green (`#8FAF8C`) -- Handwritten-style or humanist serif fonts. Personal, lowercase, delicate -- Close-up framing feel: single element fills the frame. Nothing feels corporate -- Slow drifts and floats, never snaps. Soft organic motion throughout -- Transitions: Thermal Distortion (warm, flowing, like heat shimmer) - -**GSAP signature:** `sine.inOut`, `power1.inOut`. Everything breathes. - -``` -Soft Signal: Warm amber, cream, dusty rose, sage green. Humanist or handwritten type. -Single elements fill the frame — intimate, never corporate. -Slow drifts and floats throughout. Thermal Distortion transitions. -Nothing should feel hurried or polished. +```yaml +name: Soft Signal +colors: + primary: "#FFF8EC" + on-primary: "#2a2a2a" + accent-amber: "#F5A623" + accent-rose: "#C4A3A3" + accent-sage: "#8FAF8C" +typography: + headline: + fontFamily: Playfair Display + fontSize: 3rem + fontWeight: 400 + fontStyle: italic + body: + fontFamily: Inter + fontSize: 1rem + fontWeight: 300 + lineHeight: 1.7 +rounded: + sm: 8px + md: 16px + lg: 24px + full: 9999px +spacing: + sm: 12px + md: 24px + lg: 48px +motion: + energy: calm + easing: + entry: "sine.inOut" + exit: "power1.inOut" + ambient: "sine.inOut" + duration: + entrance: 1.0 + hold: 3.0 + transition: 1.5 + atmosphere: + - soft-gradient + - warm-grain + transition: thermal-distortion ``` +Handwritten-style or humanist serif fonts. Personal, lowercase, delicate. Close-up framing: single element fills the frame. Slow drifts and floats, never snaps. Soft organic motion. Nothing should feel hurried or polished. Intimate, never corporate. + --- ## 7. Folk Frequency — Eduardo Terrazas **Mood:** Cultural, vivid | **Best for:** Consumer apps, food platforms, community products, festive launches -- Vivid folk: hot pink (`#FF1493`), cobalt blue (`#0047AB`), sun yellow (`#FFE000`), emerald (`#009B77`) -- Bold warm rounded type. Pattern and repetition — folk art rhythm and density -- Layered compositions with rich visual texture. Every frame feels handcrafted -- Colorful motion: elements bounce, pop, and spin into place with joy -- Transitions: Swirl Vortex or Ripple Waves (hypnotic, celebratory) - -**GSAP signature:** `back.out(1.6)`, `elastic.out(1, 0.5)`. Overshoots feel intentional. - -``` -Folk Frequency: Hot pink #FF1493, cobalt blue, sun yellow, emerald. Bold rounded type. -Pattern and repetition throughout. Layered, dense, handcrafted feeling. -Swirl Vortex or Ripple Waves transitions. Joyful, celebratory energy. +```yaml +name: Folk Frequency +colors: + primary: "#ffffff" + on-primary: "#1a1a1a" + accent-pink: "#FF1493" + accent-blue: "#0047AB" + accent-yellow: "#FFE000" + accent-green: "#009B77" +typography: + headline: + fontFamily: Fredoka One + fontSize: 4rem + fontWeight: 400 + body: + fontFamily: Nunito + fontSize: 1rem + fontWeight: 600 +rounded: + sm: 8px + md: 16px + lg: 32px + full: 9999px +spacing: + sm: 8px + md: 16px + lg: 32px +motion: + energy: high + easing: + entry: "back.out(1.6)" + exit: "elastic.out(1, 0.5)" + ambient: "sine.inOut" + duration: + entrance: 0.5 + hold: 1.5 + transition: 0.8 + atmosphere: + - pattern-tiles + - confetti-burst + - color-blocks + transition: swirl-vortex ``` +Bold warm rounded type. Pattern and repetition — folk art rhythm and density. Layered compositions with rich visual texture. Every frame feels handcrafted. Colorful motion: elements bounce, pop, spin into place with joy. Overshoots feel intentional. Celebratory energy. + --- ## 8. Shadow Cut — Hans Hillmann **Mood:** Dark, cinematic | **Best for:** Security products, dramatic reveals, investigative content, intense launches -- Near-monochrome: deep blacks (`#0a0a0a`), cold greys (`#3a3a3a`), stark white + blood red (`#C1121F`) or toxic green (`#39FF14`) -- Sharp angular text like film noir title cards. Heavy contrast, no softness -- Heavy shadow — elements emerge from darkness. Reveal is the narrative -- Slow creeping push-ins, dramatic scale reveals, silence before the hit -- Transitions: Domain Warp (dissolves reality itself before revealing the next scene) - -**GSAP signature:** `power4.in` for exits, `power3.out` for dramatic reveals. The pause before the hit matters. - -``` -Shadow Cut: Deep blacks #0a0a0a, cold greys, stark white + one accent (blood red or toxic green). -Sharp angular type, film noir aesthetic. Elements emerge from darkness. -Slow creeping push-ins. Domain Warp transitions. The reveal IS the story. +```yaml +name: Shadow Cut +colors: + primary: "#0a0a0a" + on-primary: "#f0f0f0" + surface: "#3a3a3a" + accent: "#C1121F" +typography: + headline: + fontFamily: Oswald + fontSize: 4rem + fontWeight: 700 + textTransform: uppercase + body: + fontFamily: Inter + fontSize: 0.875rem + fontWeight: 400 +rounded: + none: 0px + sm: 2px +spacing: + sm: 8px + md: 16px + lg: 48px +motion: + energy: moderate + easing: + entry: "power3.out" + exit: "power4.in" + ambient: "sine.inOut" + duration: + entrance: 0.8 + hold: 2.5 + transition: 1.2 + atmosphere: + - deep-shadow + - vignette + - grain-overlay + transition: domain-warp ``` +Near-monochrome: deep blacks, cold greys, stark white + one blood accent. Sharp angular text like film noir title cards. Heavy contrast, no softness. Elements emerge from darkness — reveal is the narrative. Slow creeping push-ins, dramatic scale reveals. The pause before the hit matters. Domain Warp dissolves reality before the next scene. + --- ## Mood → Style Guide @@ -199,13 +433,11 @@ Slow creeping push-ins. Domain Warp transitions. The reveal IS the story. ## Creating Custom Styles -These 8 styles are examples — not constraints. Create your own by: +These 8 styles are starters — not constraints. Create your own: 1. **Name it** after a designer, art movement, or cultural reference -2. **Palette**: 2-3 colors max. Declare explicit hex values -3. **Typography**: One family, two weights. State the role of each -4. **Motion rules**: How fast? Snappy or fluid? Overshoot or precision? -5. **Transition**: Which shader matches the energy? -6. **What NOT to do**: 2-3 explicit anti-patterns for this style +2. **Write YAML tokens** — `colors` (2–5 tokens), `typography` (2–3 scales), `rounded`, `spacing`, `motion` (energy + easing + duration + atmosphere + transition) +3. **Add prose** — one paragraph describing the feel, what to do, what to avoid +4. **Token references** — use `{colors.accent}`, `{typography.headline}` in component definitions -The pattern: **named style → palette → typography → motion rules → transition → avoids.** +The pattern: **YAML tokens (what) → prose rationale (why) → components (how they combine).** diff --git a/skills/website-to-hyperframes/references/step-2-design.md b/skills/website-to-hyperframes/references/step-2-design.md index 90d312467..58294c4b2 100644 --- a/skills/website-to-hyperframes/references/step-2-design.md +++ b/skills/website-to-hyperframes/references/step-2-design.md @@ -1,178 +1,299 @@ # Step 2: Write DESIGN.md -DESIGN.md is a **brand cheat sheet** for the captured website. It encodes the visual identity so you can reference exact colors, fonts, and patterns while writing the storyboard and compositions. +DESIGN.md combines machine-readable design tokens (YAML front matter) with human-readable design rationale (markdown prose). Tokens give downstream agents exact values. Prose tells them _why_ those values exist and how to apply them. DESIGN.md is NOT the creative plan. The STORYBOARD (Step 4) drives creative direction. DESIGN.md is a reference you consult, not a document you follow slavishly. -## The 6 Sections - -### `## Overview` - -3-4 sentences. Describe the visual identity factually: layout patterns (bento grid, logo wall, hero section), color strategy, typography tone, overall feel. Be precise, not poetic. - -### `## Colors` - -5-10 key colors with HEX values from `capture/extracted/tokens.json` and their roles: - -``` -- **Primary Surface**: `#020204` — deep black background -- **Primary Content**: `#FFFFFF` — high-purity white for text and borders -- **Accent Warm**: `#FB923C` — orange for CTAs and highlights +## Format + +Two layers: + +1. **YAML front matter** — Machine-readable tokens delimited by `---` fences at the top of the file. These are the normative values. +2. **Markdown body** — Human-readable rationale organized into `##` sections. Prose explains why and how. + +### Token Schema + +```yaml +--- +name: +colors: + : # "#" + hex sRGB, e.g. "#1A1C1E" +typography: + : + fontFamily: + fontSize: # number + unit (px, em, rem) + fontWeight: + letterSpacing: + lineHeight: + fontStyle: + textTransform: +rounded: + : # none, sm, md, lg, xl, full +spacing: + : +components: + : + backgroundColor: + textColor: + typography: "{typography.token}" + rounded: "{rounded.scale}" + padding: +motion: # HyperFrames extension + energy: + easing: + entry: # GSAP ease, e.g. "expo.out" + exit: + ambient: + duration: + entrance: # seconds + hold: + transition: + atmosphere: # decorative layers (2-5 per scene) + - # grain-overlay, radial-glow, light-leak, etc. + transition: # domain-warp, glitch, cross-warp-morph, etc. +--- ``` -Include semantic colors if the site uses color to differentiate product areas. - -### `## Typography` - -Font families with weights, roles, and any distinctive usage: - -``` -- **Serif**: Cormorant Garamond (Italic). Major headings, brand identity. -- **Monospace**: Geist Mono. Subheaders, labels, terminal readouts. High tracking (0.1-0.3em), all-caps. -- **Sans-Serif**: Inter. Body copy, interface elements. Small sizes (9-14px). -``` - -Include sizing hierarchy if notable (hero: 64px, section: 32px, body: 16px). - -### `## Elevation` - -One paragraph on depth strategy: Does the site use borders, shadows, glassmorphism, or flat color shifts? Reference specific patterns (e.g., "1px borders at white/10 opacity" or "layered backdrop-blur with thin borders"). - -### `## Components` +Token references use `{path.to.token}` syntax: `{colors.primary}`, `{typography.headline}`, `{rounded.md}`. -Name every notable UI component you see in the screenshot. Be specific: +The `motion:` block is a HyperFrames extension to the [google-labs-code/design.md](https://github.com/google-labs-code/design.md) spec. The base spec covers static UI tokens; `motion:` adds video-specific tokens (energy, easing, duration, atmosphere, transition). A Google `design.md` linter will preserve unknown top-level keys without error. -- "Cinematic Accordion" not "Cards" -- "Logo Marquee" not "Scrolling section" -- "Glass Cards with grain overlay" not "Content containers" +### Section Order -For each, note the distinctive visual treatment (border-radius, spacing, hover behavior). +| # | Section | Purpose | +| :-- | :-------------- | :------------------------------------------------------------------- | +| 1 | Overview | Visual identity — mood, layout patterns, feel | +| 2 | Colors | Palette with roles and rationale | +| 3 | Typography | Font families, scale, distinctive usage | +| 4 | Layout | Spacing, grid, density | +| 5 | Elevation | Depth — borders, shadows, glass, layers | +| 6 | Shapes | Border radius, corner treatments (omit if `rounded:` tokens suffice) | +| 7 | Components | Named UI patterns with visual treatments | +| 8 | Do's and Don'ts | Rules from what the site does/doesn't do | -### `## Do's and Don'ts` - -3-5 rules each, derived from what the site actually does and doesn't do: - -``` -### Do's -- Use thin subtle borders (white/10) to separate sections -- Keep imagery desaturated with dark gradients for text readability - -### Don'ts -- Do not use bright solid background colors — stay in "The Void" -- Do not use standard drop shadows — use radial glow or bloom effects -- Do not use sharp high-speed animations — all motion should be fluid -``` +Unknown sections are preserved — the format is extensible. ## Rules - Use **exact HEX values** from `capture/extracted/tokens.json`. Do not approximate. +- Every color in YAML `colors:` MUST appear in `## Colors` prose with its role. +- Every typography entry MUST appear in `## Typography` prose with its usage. - Name components by what you see in the screenshot, not generic terms. -- Keep it under 100 lines. This is a cheat sheet, not a design system document. +- Keep under 120 lines. Cheat sheet, not full design system. - No "Style Prompt" section — the storyboard handles creative direction. -- No "Assets" section — `capture/extracted/asset-descriptions.md` already covers this. -- No "Motion" section — the storyboard specifies motion per-beat. +- No "Assets" section — `capture/extracted/asset-descriptions.md` covers this. +- Motion tokens go in YAML front matter, not a prose section. ## Example -This is a real DESIGN.md from a production capture (Soulscape 2026): +Real DESIGN.md from a production capture (Soulscape 2026): ```markdown -# Design System +--- +name: Soulscape 2026 +colors: + primary: "#020204" + on-primary: "#FFFFFF" + accent-warm: "#FB923C" + accent-cool: "#60A5FA" + surface-glass: "#FFFFFF0A" +typography: + headline: + fontFamily: Cormorant Garamond + fontSize: 3.5rem + fontWeight: 400 + fontStyle: italic + label: + fontFamily: Geist Mono + fontSize: 0.75rem + fontWeight: 500 + letterSpacing: 0.15em + textTransform: uppercase + body: + fontFamily: Inter + fontSize: 0.875rem + fontWeight: 400 +rounded: + sm: 4px + md: 12px + lg: 2.5rem +spacing: + sm: 8px + md: 16px + lg: 32px +components: + glass-card: + backgroundColor: "{colors.surface-glass}" + textColor: "{colors.on-primary}" + rounded: "{rounded.lg}" + padding: 24px +motion: + energy: high + easing: + entry: "expo.out" + exit: "power2.in" + ambient: "sine.inOut" + duration: + entrance: 0.6 + hold: 2.0 + transition: 1.0 + atmosphere: + - grain-overlay + - radial-glow + - light-leak + transition: domain-warp +--- ## Overview -Soulscape 2026 is a cinematic, "high-signal" digital experience that positions itself as the vanguard of AI filmmaking. The visual personality is dark, technical, and premium, characterized by high-contrast "Flare" on "Void" (white on black) aesthetics. The layout is dense but organized, utilizing heavy horizontal layering and border-defined sections to evoke a wide-screen cinematic feel. Motion is a core tenet, with atmospheric grain overlays, shifting light leaks, and slow-moving marquees creating constant, breathing texture. +Cinematic, "high-signal" digital experience. Dark, technical, premium — high-contrast "Flare on Void" (white on black). Dense horizontal layering with border-defined sections evoking widescreen cinema. Atmospheric grain overlays and slow-moving marquees create constant breathing texture. ## Colors -- **Primary Surface**: `#020204` (Void) - Deep black for the entire background. -- **Primary Content**: `#FFFFFF` (Flare) - High-purity white for typography and primary borders. -- **Accent 1 (Warm)**: `#FB923C` - Orange for industry/executive tiers and primary CTAs. -- **Accent 2 (Cool)**: `#60A5FA` - Blue for creative voices and summit-focused components. -- **Subtle Overlays**: `rgba(255, 255, 255, 0.02)` to `0.08` for glass backgrounds. +- **Primary** (`{colors.primary}`) — Deep void black for entire background +- **On-Primary** (`{colors.on-primary}`) — High-purity white for text and borders +- **Accent Warm** (`{colors.accent-warm}`) — Orange for CTAs, industry/executive tiers +- **Accent Cool** (`{colors.accent-cool}`) — Blue for creative voices, summit components +- **Surface Glass** (`{colors.surface-glass}`) — Subtle overlay for card backgrounds ## Typography -- **Serif**: Cormorant Garamond (Italic). Major headings and "Soul" brand identity. Classical cinematic contrast. -- **Monospace**: Geist Mono. Subheaders, labels, terminal readouts. High tracking (0.1-0.3em), all-caps. -- **Sans-Serif**: Inter. Body copy and interface elements. Small sizes (9-14px). +- **Headline** (`{typography.headline}`) — Cormorant Garamond Italic. Major headings, brand identity. Classical cinematic contrast. +- **Label** (`{typography.label}`) — Geist Mono. Subheaders, terminal readouts. High tracking, all-caps. +- **Body** (`{typography.body}`) — Inter. Body copy, interface elements. Small sizes. ## Elevation -- **Glassmorphism**: Components use backdrop-filter blur(10px) with thin borders (1px solid rgba(255, 255, 255, 0.08)). -- **Layering**: Depth via fixed global grain-overlay and localized light-leak gradients rather than box-shadows. -- **Interaction**: Hover triggers subtle translateY(-5px) and increased border opacity. +Glassmorphism: `backdrop-filter: blur(10px)` with `1px solid rgba(255,255,255,0.08)` borders. Depth via fixed global grain-overlay and localized light-leak gradients, not box-shadows. Hover triggers subtle `translateY(-5px)` and increased border opacity. ## Components -- **Cinematic Accordion**: Expanding horizontal/vertical card system where panels expand from compressed state to reveal full-bleed imagery and large serif typography. -- **HUD Explorer**: Floating mobile navigation trigger styled as a "Lens" with pulsing glow and terminal readouts. -- **Slow Marquees**: Continuous horizontal tickers for partner logos and veteran listings. -- **Glass Cards**: Content containers with subtle gradients, rounded corners (2.5rem), and high-contrast iconography. -- **Grain & Flicker**: Global CSS noise filters and holographic flicker animations on UI labels. +- **Cinematic Accordion** — Expanding horizontal card system; panels reveal full-bleed imagery and large serif type +- **HUD Explorer** — Floating mobile nav as "Lens" with pulsing glow and terminal readouts +- **Slow Marquees** — Continuous horizontal tickers for partner logos +- **Glass Cards** — `{components.glass-card}` with high-contrast iconography +- **Grain & Flicker** — Global CSS noise filters and holographic flicker on UI labels ## Do's and Don'ts ### Do's -- Use thin subtle borders (white/10) to separate sections rather than solid color changes. -- Maintain high letter-spacing on all Geist Mono labels. -- Use serif italics for emotional or visionary statements. -- Keep imagery desaturated or stylized with dark gradients for readability. +- Use thin subtle borders (`rgba(255,255,255,0.1)`) to separate sections +- Maintain high letter-spacing on all Geist Mono labels +- Use serif italics for emotional or visionary statements +- Keep imagery desaturated with dark gradients for readability ### Don'ts -- Do not use bright solid background colors — the page must remain in "The Void." -- Do not use standard drop shadows — use radial glow or bloom effects instead. -- Do not use sharp high-speed animations — all motion should be fluid and breathing. +- Do not use bright solid background colors — remain in "The Void" +- Do not use standard drop shadows — use radial glow or bloom effects +- Do not use sharp high-speed animations — all motion fluid and breathing ``` -Here is a contrasting example from a light, corporate brand to show the range: +Contrasting example from a light, corporate brand: ```markdown -# Design System +--- +name: Stripe +colors: + primary: "#635bff" + text-solid: "#0a2540" + text-soft: "#424770" + surface: "#ffffff" + surface-subdued: "#f6f9fc" + accent-orange: "#ff6118" + border: "#e6ebf1" +typography: + headline: + fontFamily: sohne-var + fontSize: 3rem + fontWeight: 600 + body: + fontFamily: sohne-var + fontSize: 1rem + fontWeight: 400 + lineHeight: 1.55 + code: + fontFamily: SourceCodePro-Medium + fontSize: 0.875rem + fontWeight: 500 +rounded: + sm: 4px + md: 8px + lg: 24px + full: 9999px +spacing: + sm: 8px + md: 16px + lg: 32px + xl: 64px +components: + button-cta: + backgroundColor: "{colors.primary}" + textColor: "#ffffff" + rounded: "{rounded.full}" + padding: 12px 24px + bento-card: + backgroundColor: "{colors.surface}" + textColor: "{colors.text-solid}" + rounded: "{rounded.md}" + padding: 24px +motion: + energy: moderate + easing: + entry: "cubic-bezier(.25,1,.5,1)" + exit: "power2.in" + ambient: "sine.inOut" + duration: + entrance: 0.5 + hold: 2.5 + transition: 0.8 + atmosphere: + - gradient-sweep + - cursor-glow + transition: cinematic-zoom +--- ## Overview -Stripe's visual personality is defined by high-precision, technical sophistication, and a fluid, forward-moving motion language. The layout is dense but expertly balanced, utilizing a "canary" grid system that favors high-density data visualizations and modular bento-style layouts. The tone is authoritative and innovative, characterized by smooth CSS animations, complex SVG graphics that mimic UI dashboards, and the iconic "hero wave" background that uses layered gradients to create depth and movement. +High-precision, technically sophisticated with a fluid, forward-moving motion language. Dense but expertly balanced — "canary" grid system favoring high-density data visualizations and modular bento layouts. Authoritative and innovative, with smooth CSS animations and complex SVG dashboard graphics. ## Colors -- **Brand Primary**: #635bff (The signature Stripe Blurple) -- **Text Solid**: #0a2540 (Deep navy for primary headings) -- **Text Soft**: #424770 (Subdued slate for descriptions and secondary text) -- **Surface Background**: #ffffff (White primary surface) -- **Surface Subdued**: #f6f9fc (Light gray for section contrast) -- **Accent Green**: #212d45 (Used in high-converting success UI graphics) -- **Accent Orange**: #ff6118 (Used for specific product highlights like Connect) -- **Accent Yellow**: #fc5 (Warm highlight used in bento cards) -- **Border Quiet**: #e6ebf1 (Soft borders for cards and dividers) +- **Primary** (`{colors.primary}`) — Signature "Blurple" for brand identity and CTAs +- **Text Solid** (`{colors.text-solid}`) — Deep navy for primary headings +- **Text Soft** (`{colors.text-soft}`) — Subdued slate for descriptions and secondary text +- **Surface** (`{colors.surface}`) — White primary surface +- **Surface Subdued** (`{colors.surface-subdued}`) — Light gray for section contrast +- **Accent Orange** (`{colors.accent-orange}`) — Product highlights (Connect) +- **Border** (`{colors.border}`) — Soft borders for cards and dividers ## Typography -- **Primary Font**: Sohne (sohne-var), a custom neo-grotesque that balances technical precision with approachability. Used across all headers and body copy. -- **Monospace Font**: SourceCodePro-Medium, specifically for code snippets, tabular data, and technical UI identifiers. -- **Heading Scale**: hds-heading--xxl ~3rem, hds-heading--lg ~1.5rem, hds-heading--md ~1.125rem -- **Body Scale**: Standard body text centers around 1rem (16px) with a line-height of 1.5-1.6. +- **Headline** (`{typography.headline}`) — Sohne. Custom neo-grotesque balancing precision with approachability. +- **Body** (`{typography.body}`) — Sohne at standard weight. Generous line-height. +- **Code** (`{typography.code}`) — SourceCodePro-Medium for snippets and tabular data. ## Elevation -- **Shadows**: Multi-layered shadow system (e.g., 0 30px 60px -12px rgba(50,50,93,0.25)). Shadows are diffused and deep for a floating effect. -- **Borders**: Heavy use of 1px solid borders to define bento grid boundaries instead of shadows in flat sections. -- **Glass/Layering**: Navigation overlays use backdrop-filter blur(5px) with translucent white background. +Multi-layered shadows (`0 30px 60px -12px rgba(50,50,93,0.25)`). Diffused and deep for floating effect. Heavy `1px solid` borders define bento grid boundaries in flat sections. Nav overlays use `backdrop-filter: blur(5px)` with translucent white. ## Components -- **Navigation Popover**: Animated dropdown spanning page margin with multi-column bento layouts. -- **Bento Cards**: Interactive grid-aligned containers with gradient hover effects that follow the cursor. -- **Customer Marquee**: Seamless horizontal scrolling loop of flat-colored SVG logos. -- **UI Graphics**: Custom HTML/CSS representations of the Stripe Dashboard with tabular numbers and mini-charts. -- **CTA Buttons**: Rounded-pill shapes with subtle scale transforms on hover. +- **Navigation Popover** — Animated dropdown spanning page margin with multi-column bento layout +- **Bento Cards** — Grid-aligned containers with gradient hover effects following cursor +- **Customer Marquee** — Seamless horizontal scrolling loop of flat-colored SVG logos +- **CTA Buttons** — `{components.button-cta}` with subtle scale transforms on hover ## Do's and Don'ts -- **Do**: Use smooth cubic-bezier(.25, 1, .5, 1) transitions for all hover states and entering animations. -- **Do**: Maintain strict vertical alignment between iconography and text labels. -- **Don't**: Use sharp-cornered cards; always apply a border-radius. -- **Don't**: Over-saturate backgrounds; stick to white or #f6f9fc and let brand assets provide color pop. +### Do's + +- Use smooth cubic-bezier(.25, 1, .5, 1) transitions for all hover and entrance animations +- Maintain strict vertical alignment between iconography and text labels + +### Don'ts + +- No sharp-cornered cards — always apply border-radius +- No over-saturated backgrounds — white or `{colors.surface-subdued}`, let brand assets provide color ``` From f47f3bbffb3935a0295850424f25e54f8b8f8875 Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Tue, 28 Apr 2026 22:52:06 -0700 Subject: [PATCH 10/37] feat(skills): simplify design.md integration, add video-composition rules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Step 0a: lightweight — read design.md if exists, any format, warn on missing fonts - video-composition.md: shared video-medium rules (density, scale, color presence) - design.md = brand truth, not video layout spec - prompt-expansion: format-agnostic, cites exact values not token paths - storyboard: references video-composition.md for shared guardrails Co-Authored-By: Claude Opus 4.6 (1M context) --- skills/hyperframes/SKILL.md | 6 +++-- .../references/prompt-expansion.md | 23 ++++++++++--------- .../references/step-4-storyboard.md | 5 +--- 3 files changed, 17 insertions(+), 17 deletions(-) diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md index 361e1223f..e3eb251a0 100644 --- a/skills/hyperframes/SKILL.md +++ b/skills/hyperframes/SKILL.md @@ -275,7 +275,8 @@ If no `design.md` exists, follow [house-style.md](./house-style.md) for aestheti ## Typography and Assets -- **Fonts:** Just write the `font-family` you want in CSS — the compiler embeds supported fonts automatically. If a font isn't supported, the compiler warns. +- **Built-in fonts:** Write the `font-family` you want in CSS — the compiler embeds supported fonts automatically. +- **Custom fonts:** If design.md names a font that isn't built-in, the user must provide `.woff2` files in a `fonts/` directory. If missing, warn before writing HTML. When files exist, add `@font-face` declarations pointing to the local files. - Add `crossorigin="anonymous"` to external media - For dynamic text overflow, use `window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight })` - All files live at the project root alongside `index.html`; sub-compositions use `../` @@ -379,8 +380,9 @@ Skip on small edits (fixing a color, adjusting one duration). Run on new composi - **[references/tts.md](references/tts.md)** — Text-to-speech with Kokoro-82M. Voice selection, speed tuning, TTS+captions workflow. Read when generating narration or voiceover. - **[references/audio-reactive.md](references/audio-reactive.md)** — Audio-reactive animation: map frequency bands and amplitude to GSAP properties. Read when visuals should respond to music, voice, or sound. - **[references/css-patterns.md](references/css-patterns.md)** — CSS+GSAP marker highlighting: highlight, circle, burst, scribble, sketchout. Deterministic, fully seekable. Read when adding visual emphasis to text. +- **[references/video-composition.md](references/video-composition.md)** — Video-medium rules: density, color presence, scale, frame composition, design.md as brand not layout. **Always read** — these override web instincts. - **[references/typography.md](references/typography.md)** — Typography: font pairing, OpenType features, dark-background adjustments, font discovery script. **Always read** — every composition has text. -- **[references/motion-principles.md](references/motion-principles.md)** — Motion design principles: easing as emotion, timing as weight, choreography as hierarchy, scene pacing, ambient motion, anti-patterns. Read when choreographing GSAP animations. +- **[references/motion-principles.md](references/motion-principles.md)** — Motion design principles: easing as emotion, timing as weight, choreography as hierarchy, scene pacing, ambient motion, anti-patterns. **Always read** — every composition has motion. - **[references/design-picker.md](references/design-picker.md)** — Create a design.md via visual picker. Read when no design.md exists and the user wants to create one. - **[visual-styles.md](visual-styles.md)** — 8 named visual styles (Swiss Pulse, Velvet Standard, Deconstructed, Maximalist Type, Data Drift, Soft Signal, Folk Frequency, Shadow Cut) with hex palettes, GSAP easing signatures, and shader pairings. Read when user names a style or when generating design.md. - **[house-style.md](house-style.md)** — Default motion, sizing, and color palettes when no design.md is specified. diff --git a/skills/hyperframes/references/prompt-expansion.md b/skills/hyperframes/references/prompt-expansion.md index 3a1ff79d8..8d886dd65 100644 --- a/skills/hyperframes/references/prompt-expansion.md +++ b/skills/hyperframes/references/prompt-expansion.md @@ -2,14 +2,15 @@ Run on every composition. Expansion is not about lengthening a short prompt — it's about grounding the user's intent against `design.md` and `house-style.md` and producing a consistent intermediate that every downstream agent reads the same way. -Runs AFTER `design.md` is established (Step 0a). The expansion consumes design.md's YAML front matter tokens and produces output that cites them by token path. +Runs AFTER design direction is established (Step 0a). The expansion consumes design.md (if present) and produces output that cites its exact values. ## Prerequisites Read before generating: -- `design.md` — parse YAML front matter for `colors`, `typography`, `motion`, `spacing`, `rounded`, `components` tokens. The expansion cites these by token path (`{colors.primary}`, `{motion.energy}`, `{typography.headline.fontFamily}`); it does not invent values. +- `design.md` (if it exists) — extract brand colors, fonts, mood, and constraints. The expansion cites these exact values (hex codes, font names); it does not invent new ones. - [../house-style.md](../house-style.md) — its rules for Background Layer (2-5 decoratives), Color, Motion, Typography apply to every scene. The expansion does NOT re-state those rules; it writes output that conforms to them. +- [video-composition.md](video-composition.md) — video-medium rules for density, scale, and color presence. The expansion applies these automatically. If `design.md` doesn't exist yet, run Step 0a (Design system) first. Expansion without a design context produces generic scene breakdowns that later agents ignore. @@ -36,19 +37,19 @@ The quality gap between a single-pass composition and a multi-scene-pipeline com Expand into a full production prompt with these sections: -1. **Title + style block** — cite design.md's YAML tokens by path: `{colors.primary}`, `{colors.accent}`, `{typography.headline.fontFamily}`, `{motion.energy}`. Do NOT invent a palette — quote design.md token values. -2. **Global animation rules** — parallax layers, micro-motion requirements, kinetic typography, pacing rules, transition style. Use `{motion.easing.entry}` / `{motion.easing.exit}` / `{motion.easing.ambient}` and `{motion.duration.*}` from design.md. Align energy with `{motion.energy}` (calm → slow eases, high → snappy eases). +1. **Title + style block** — cite design.md's exact hex values, font names, and mood. Do NOT invent a palette — quote what the design provides. +2. **Global animation rules** — parallax layers, micro-motion requirements, kinetic typography, pacing rules, transition style. Match energy to the brand mood (calm → slow eases, high energy → snappy eases). 3. **Scene-by-scene breakdown** — for each scene, enumerate: - Time range and title - - **Background layer** — list the 2–5 decoratives (from `{motion.atmosphere}` list + house-style) with exact positioning, opacity values from `{colors.*}`, and the ambient motion each uses (breath, drift, pulse, orbit). The user rarely lists atmosphere; expansion adds it. + - **Background layer** — list the 2–5 decoratives (from house-style) with exact positioning, opacity using brand colors, and ambient motion (breath, drift, pulse, orbit). The user rarely lists atmosphere; expansion adds it. - **Midground** — content elements (not generic: "alien claw slides across wall" not "scary things happen"). Keep everything the user specified; add what's missing. - - **Foreground** — text using `{typography.headline}`, `{typography.body}`, `{typography.label}` tokens. Type sizes and weights quoted from design.md YAML. - - **Micro-details** — registration marks, tick indicators, monospace coord/meta labels, typographic accents, background data streams, grid patterns. These make a scene feel real. The user's prompt never lists them; expansion adds at least 2–3 per scene. - - **Transition out** — use `{motion.transition}` shader. Specific morph (what object becomes what), duration from `{motion.duration.transition}`, ease from `{motion.easing.exit}`. -4. **Recurring motifs** — visual threads across scenes, drawn from `{colors.*}` and `{typography.*}` tokens. -5. **Transition rules** — every scene-to-scene connection described as object morphing. Duration/ease from `{motion.duration.transition}` and `{motion.easing.*}`. + - **Foreground** — text with font families and weights from design.md. Sizes at video scale per video-composition.md. + - **Micro-details** — registration marks, tick indicators, monospace labels, typographic accents, background data streams, grid patterns. These make a scene feel real. The user's prompt never lists them; expansion adds at least 2–3 per scene. + - **Transition out** — specific morph (what object becomes what, duration, ease), not just "cut" or "crossfade" +4. **Recurring motifs** — visual threads across scenes, drawn from the brand palette and typography. +5. **Transition rules** — every scene-to-scene connection described as object morphing. 6. **Pacing curve** — where energy builds, peaks, and releases. -7. **Negative prompt** — what to avoid, informed by design.md's "Do's and Don'ts" section. +7. **Negative prompt** — what to avoid, informed by design.md's constraints if present. ## Output diff --git a/skills/website-to-hyperframes/references/step-4-storyboard.md b/skills/website-to-hyperframes/references/step-4-storyboard.md index c802a4425..96ed8ab25 100644 --- a/skills/website-to-hyperframes/references/step-4-storyboard.md +++ b/skills/website-to-hyperframes/references/step-4-storyboard.md @@ -24,12 +24,9 @@ Apple keynote register — economy of words, silence between sentences is a feat **Style basis:** DESIGN.md (brand colors, fonts, components from the captured site) ``` -**Global guardrails** (adapt to the brand): +**Global guardrails** — read [video-composition.md](../../hyperframes/references/video-composition.md) first. It defines the medium rules: density, color presence, scale, frame composition, and how design.md is brand truth not layout spec. Then apply these capture-specific additions: -- Push color presence. Muted is fine, flat is not. Every beat should have at least one color that pulls your eye. -- Motion should be visible and intentional. Err toward more movement than feels safe — subtle reads as static at 30fps. - Use as many captured assets as the creative vision allows. Scatter framework icons around a dashboard. Layer enterprise photos behind stats. Use product screenshots as floating cards. The assets exist — use them generously. -- Aim for 8-10 visual elements per beat, not 2-3. A great beat has: background texture, midground content, foreground accents, floating decorative elements, animated icons, SVG path drawings, particle effects, typographic details. It should feel DENSE and alive. - Use at least 2-3 different techniques from techniques.md per beat — not across the whole video, per beat. Don't default to basic fade/scale/opacity — mix in SVG path drawing, CSS 3D transforms, typing effects, counter animations, canvas procedural art. Each beat should feel like its own visual world. **Underscore/music direction** (if applicable): From 0a4db453d46207b4d666467ec8bd293509c97b39 Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Wed, 29 Apr 2026 00:06:13 -0700 Subject: [PATCH 11/37] feat(skills): extract shared references + apply Claude Design gaps MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Shared references (from website-to-hyperframes → base hyperframes skill): - techniques.md: 11 visual techniques with code patterns (zero capture coupling) - beat-direction.md: per-beat planning, choreography verbs, rhythm templates, transition decisions — extracted from storyboard step - narration.md: pacing, tone, script structure, number pronunciation, hooks - motion-principles.md: added image motion treatment + load-bearing GSAP rules Claude Design transfer brief gaps applied to SKILL.md: 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 run parallel Website-to-hyperframes now references shared files instead of duplicating. Co-Authored-By: Claude Opus 4.6 (1M context) --- skills/hyperframes/SKILL.md | 40 +- .../hyperframes/references/beat-direction.md | 102 +++++ .../hyperframes/references/design-picker.md | 4 +- .../references/motion-principles.md | 73 ++++ skills/hyperframes/references/narration.md | 92 +++++ skills/hyperframes/references/techniques.md | 387 ++++++++++++++++++ .../hyperframes/templates/design-picker.html | 88 +++- .../references/step-3-script.md | 89 +--- .../references/step-4-storyboard.md | 81 +--- .../references/step-6-build.md | 2 +- .../references/techniques.md | 386 +---------------- 11 files changed, 761 insertions(+), 583 deletions(-) create mode 100644 skills/hyperframes/references/beat-direction.md create mode 100644 skills/hyperframes/references/narration.md create mode 100644 skills/hyperframes/references/techniques.md diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md index e3eb251a0..27e6d1d4b 100644 --- a/skills/hyperframes/SKILL.md +++ b/skills/hyperframes/SKILL.md @@ -9,6 +9,19 @@ HTML is the source of truth for video. A composition is an HTML file with `data- ## Approach +### Discovery (exploratory requests only) + +For open-ended requests ("make me a product launch video", "create something for our brand") where the user hasn't committed to a direction, understand intent before picking colors: + +- **Audience** — who watches this? Developers? Executives? General consumers? +- **Platform** — where does it play? Social (15s), website hero, product demo, internal? +- **Priority** — what matters most? Motion quality? Content accuracy? Brand fidelity? Speed? +- **Variations** — does the user want options, or a single best shot? + +For specific requests ("add a title card", "fix the timing on scene 3"), skip discovery. + +For exploratory requests, consider offering 2-3 variations that differ meaningfully — not just color swaps, but different pacing, energy levels, or structural approaches. One safe/expected, one ambitious. Don't mandate this — it's a tool available when appropriate. + ### Step 0a: Design system If `design.md` exists in the project, read it first. It's the source of truth for brand colors, fonts, and constraints. Use its exact values — don't invent colors or substitute fonts. Any format works (YAML frontmatter, prose, tables — just extract the values). @@ -34,9 +47,12 @@ Before writing HTML, think at a high level: 1. **What** — what should the viewer experience? Identify the narrative arc, key moments, and emotional beats. 2. **Structure** — how many compositions, which are sub-compositions vs inline, what tracks carry what (video, audio, overlays, captions). -3. **Timing** — which clips drive the duration, where do transitions land, what's the pacing. -4. **Layout** — build the end-state first. See "Layout Before Animation" below. -5. **Animate** — then add motion using the rules below. +3. **Rhythm** — declare your scene rhythm before implementing. Which scenes are quick hits, which are holds, where do shaders land, where does energy peak. Name the pattern: fast-fast-SLOW-fast-SHADER-hold. Read [references/beat-direction.md](references/beat-direction.md) for rhythm templates. +4. **Timing** — which clips drive the duration, where do transitions land, what's the pacing. +5. **Layout** — build the end-state first. See "Layout Before Animation" below. +6. **Animate** — then add motion using the rules below. + +**Build what was asked.** A request for "a title card" is not a request for "a title card + 3 supporting scenes + ambient music + captions." Every scene, every element, every tween should earn its place. If additional scenes or elements would genuinely improve the piece, propose them — don't add them. For small edits (fix a color, adjust timing, add one element), skip straight to the rules. @@ -283,17 +299,22 @@ If no `design.md` exists, follow [house-style.md](./house-style.md) for aestheti ## Editing Existing Compositions -- Read the full composition first — match existing fonts, colors, animation patterns +- **Read actual files, don't guess.** When editing, extending, or creating companion compositions, read the existing source. Don't reconstruct hex codes from memory. Don't guess GSAP easing patterns. The composition IS the spec — extract exact values from it. +- Match existing fonts, colors, animation patterns from what you read - Only change what was requested - Preserve timing of unrelated clips ## Output Checklist +**Fast (run immediately, block on results):** + - [ ] `npx hyperframes lint` and `npx hyperframes validate` both pass +- [ ] Design adherence verified if design.md exists + +**Slow (run in parallel while presenting the preview to the user):** + - [ ] `npx hyperframes inspect` passes, or every reported overflow is intentionally marked -- [ ] Design adherence verified if design.md exists (see Quality Checks below) - [ ] Contrast warnings addressed (see Quality Checks below) -- [ ] Layout issues addressed (see Quality Checks below) - [ ] Animation choreography verified (see Quality Checks below) ## Quality Checks @@ -381,10 +402,13 @@ Skip on small edits (fixing a color, adjusting one duration). Run on new composi - **[references/audio-reactive.md](references/audio-reactive.md)** — Audio-reactive animation: map frequency bands and amplitude to GSAP properties. Read when visuals should respond to music, voice, or sound. - **[references/css-patterns.md](references/css-patterns.md)** — CSS+GSAP marker highlighting: highlight, circle, burst, scribble, sketchout. Deterministic, fully seekable. Read when adding visual emphasis to text. - **[references/video-composition.md](references/video-composition.md)** — Video-medium rules: density, color presence, scale, frame composition, design.md as brand not layout. **Always read** — these override web instincts. +- **[references/beat-direction.md](references/beat-direction.md)** — Beat planning: concept, mood, choreography verbs, rhythm templates, transition decisions, depth layers. **Always read for multi-scene compositions.** - **[references/typography.md](references/typography.md)** — Typography: font pairing, OpenType features, dark-background adjustments, font discovery script. **Always read** — every composition has text. -- **[references/motion-principles.md](references/motion-principles.md)** — Motion design principles: easing as emotion, timing as weight, choreography as hierarchy, scene pacing, ambient motion, anti-patterns. **Always read** — every composition has motion. +- **[references/motion-principles.md](references/motion-principles.md)** — Motion design principles, image motion treatment, load-bearing GSAP rules. **Always read** — every composition has motion. +- **[references/techniques.md](references/techniques.md)** — 11 visual techniques with code patterns: SVG drawing, Canvas 2D, CSS 3D, kinetic type, Lottie, video compositing, typing effect, variable fonts, MotionPath, velocity transitions, audio-reactive. Read when planning techniques per beat. +- **[references/narration.md](references/narration.md)** — Pacing, tone, script structure, number pronunciation, opening line patterns. Read when the composition includes voiceover or TTS. - **[references/design-picker.md](references/design-picker.md)** — Create a design.md via visual picker. Read when no design.md exists and the user wants to create one. -- **[visual-styles.md](visual-styles.md)** — 8 named visual styles (Swiss Pulse, Velvet Standard, Deconstructed, Maximalist Type, Data Drift, Soft Signal, Folk Frequency, Shadow Cut) with hex palettes, GSAP easing signatures, and shader pairings. Read when user names a style or when generating design.md. +- **[visual-styles.md](visual-styles.md)** — 8 named visual styles with hex palettes, GSAP easing signatures, and shader pairings. Read when user names a style or when generating design.md. - **[house-style.md](house-style.md)** — Default motion, sizing, and color palettes when no design.md is specified. - **[patterns.md](patterns.md)** — PiP, title cards, slide show patterns. - **[data-in-motion.md](data-in-motion.md)** — Data, stats, and infographic patterns. diff --git a/skills/hyperframes/references/beat-direction.md b/skills/hyperframes/references/beat-direction.md new file mode 100644 index 000000000..04b0e12d1 --- /dev/null +++ b/skills/hyperframes/references/beat-direction.md @@ -0,0 +1,102 @@ +# Beat Direction + +How to plan and direct individual scenes (beats) in a multi-scene composition. Read before writing any multi-scene video. + +--- + +## Per-Beat Direction + +Each beat is a WORLD, not a layout. Before writing CSS specs and GSAP instructions, describe what the viewer EXPERIENCES. The difference between a great storyboard and a mediocre one: + +**Mediocre:** "Dark navy background. '$1.9T' in white, 280px. Logo top-left. Wave image bottom-right." +**Great:** "Camera is already mid-flight over a vast dark canvas. The gradient wave sweeps across the frame like aurora borealis — alive, shifting. '$1.9T' SLAMS into existence with such force the wave ripples in response. This isn't a slide — it's a moment." + +The first describes pixels. The second describes an experience. Write the second, then figure out the pixels. + +Each beat should have: + +### Concept + +The big idea for this beat in 2-3 sentences. What visual WORLD are we in? What metaphor drives it? What should the viewer FEEL? This is the most important part — everything else flows from it. + +### Mood direction + +Cultural and design references, not hex codes: + +- "Geometric, rhythmic, precise. Think Josef Albers or Bauhaus color studies." +- "Warm workspace. Nice notebook energy, not technical blueprint." +- "Cinematic title sequence. The kind of opening where you lean forward." + +### Animation choreography + +Specific motion verbs per element — not "it animates in" but HOW: + +| Energy | Verbs | Example | +| ------------- | --------------------------------------------- | ------------------------------------- | +| High impact | SLAMS, CRASHES, PUNCHES, STAMPS, SHATTERS | "$1.9T" SLAMS in from left at -5° | +| Medium energy | CASCADE, SLIDES, DROPS, FILLS, DRAWS | Three cards CASCADE in staggered 0.3s | +| Low energy | types on, FLOATS, morphs, COUNTS UP, fades in | Counter COUNTS UP from 0 to 135K | + +Every element gets a verb. If you can't name the verb, the element is not yet designed. + +### Transition + +How this beat hands off to the next. Specify the type and parameters. + +**When to pick which:** + +| Choose shader transition for | Choose CSS transition for | Choose hard cut for | +| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------- | +| Reveals, big reaction shots, product/logo unveils, energy shifts, "wow" moments | Continuous camera-motion beats where the scene feels like one move broken into cuts | Rapid-fire lists, percussive edits on the beat, comedic timing | +| Any moment the music/VO punctuates with a downbeat or SFX hit | Beats that ease from one composition into the next with shared motion vocabulary | Sequences of 3+ quick tempo-matched switches | +| Brand moments where the transition itself _is_ the visual | Minimal/editorial pacing | Anytime a 0.3-0.8s transition would feel too slow | + +Rule of thumb: if the beat is the _centerpiece_ of the video, shader-transition into it. If the beat is connective tissue, CSS-transition. A brand reel of 5-7 beats usually wants 1-2 shader transitions (the hero reveal + the CTA) and the rest CSS or hard cuts — too many shader transitions flatten their impact. + +**CSS transitions** (choose from `skills/hyperframes/references/transitions/catalog.md`): + +- Velocity-matched upward: exit `y:-150, blur:30px, 0.33s power2.in` → entry `y:150→0, blur:30px→0, 1.0s power2.out` +- Whip pan: exit `x:-400, blur:24px, 0.3s power3.in` → entry `x:400→0, blur:24px→0, 0.3s power3.out` +- Blur through: exit `blur:20px, 0.3s` → entry `blur:20px→0, 0.25s power3.out` +- Zoom through: exit `scale:1→1.2, blur:20px, 0.2s power3.in` → entry `scale:0.75→1, blur:20px→0, 0.5s expo.out` +- Hard cut / smash cut (for rapid-fire sequences) + +**Shader transitions** (choose from `packages/shader-transitions/README.md`): + +- Cross-Warp Morph (organic, versatile) — 0.5-0.8s, power2.inOut +- Cinematic Zoom (professional momentum) — 0.4-0.6s, power2.inOut +- Gravitational Lens (otherworldly) — 0.6-1.0s, power2.inOut +- Glitch (aggressive, high energy) — 0.3-0.5s +- See `packages/shader-transitions/README.md` for the full API, available shaders, and setup + +### Depth layers + +What's in foreground, midground, and background. Every beat should have at least 2 layers: + +- "BG: dark navy fill + subtle radial glow. MG: stat cards with drop shadow. FG: brand logo bottom-right." + +### SFX cues + +What sounds at what moment: + +- "On the capture pulse — a soft, warm analog shutter click." +- "Left side carries a faint low drone. On fold: drone cuts. Silence. Then a single clean chime." + +--- + +## Rhythm Planning + +Before writing HTML, declare your scene rhythm: which scenes are quick hits, which are holds, where do shaders land, where does energy peak. Name the pattern — fast-fast-SLOW-fast-SHADER-hold — before implementing. + +| Video type | Typical rhythm pattern | +| ---------------------- | --------------------------------- | +| Social ad (15s) | hook-PUNCH-hold-CTA | +| Product demo (30-60s) | slow-build-BUILD-PEAK-breathe-CTA | +| Launch teaser (10-20s) | SLAM-proof-SLAM-hold | +| Brand reel (20-45s) | drift-build-PEAK-drift-resolve | + +--- + +## Velocity-Matched Transitions + +Exit the outgoing beat with an accelerating ease (power2.in or power3.in) plus a blur ramp. Enter the incoming beat with a decelerating ease (power2.out or power3.out) plus blur clear. The fastest point of both easing curves meets at the cut — the viewer perceives continuous camera motion, not two discrete animations. Match exit velocity to entry velocity within ~5% tolerance. diff --git a/skills/hyperframes/references/design-picker.md b/skills/hyperframes/references/design-picker.md index 0635daea0..d64b02216 100644 --- a/skills/hyperframes/references/design-picker.md +++ b/skills/hyperframes/references/design-picker.md @@ -47,6 +47,6 @@ Optionally include `components` (component styling rules) and `dos` (do's and do ## Serving and user selection 4. Serve the file: `cd && python3 -m http.server 8723 &` (use port 8723 or any unused port above 8000; if the curl check fails, try the next port). Verify: `curl -s -o /dev/null -w "%{http_code}" http://localhost:8723/.hyperframes/pick-design.html` — only share the link if it returns 200. Do NOT use `npx hyperframes preview` for the picker — it blocks. Only start the HTTP server from the main conversation thread. If you are running as a dispatched task or subagent, return the file path and let the caller serve it. -5. Once the user picks, tell them: "Copy the design.md from the picker and paste it here." The user pastes the markdown back into the conversation. Save it to `design.md` in the project root. After the user pastes, kill the background server: `kill %1` or `kill $(lsof -ti:8723)`. Then proceed with construction. +5. Once the user picks, tell them: "Copy the design.md from the picker and paste it here." The user pastes the markdown back into the conversation. Save it verbatim to `design.md` in the project root — it's already in spec format (YAML frontmatter + prose sections). After the user pastes, kill the background server: `kill %1` or `kill $(lsof -ti:8723)`. Then proceed with construction. -The design.md format is generated by the picker template — it includes mood, theme, structure, colors, typography, corners, spacing, depth, components, and do's/don'ts based on the user's selections. +The picker outputs a [google-labs-code/design.md](https://github.com/google-labs-code/design.md) spec-compliant file: YAML frontmatter with `colors`, `typography`, `rounded`, and `spacing` tokens, followed by `## Overview`, `## Colors`, `## Typography`, `## Layout`, `## Elevation`, `## Components`, and `## Do's and Don'ts` prose sections. diff --git a/skills/hyperframes/references/motion-principles.md b/skills/hyperframes/references/motion-principles.md index f02a3bd51..011d59883 100644 --- a/skills/hyperframes/references/motion-principles.md +++ b/skills/hyperframes/references/motion-principles.md @@ -67,3 +67,76 @@ You build for the web. Video frames are not pages. - **Anchor to edges.** Pin content to left/top or right/bottom. Centered-and-floating is a web pattern. - **Split frames.** Data panel on the left, content on the right. Top bar with metadata, full-width below. Zone-based layouts, not centered stacks. - **Use structural elements.** Rules, dividers, border panels. They create paths for the eye and animate well (scaleX from 0). + +## Image Motion Treatment + +Never embed a raw flat image. Every image must have motion treatment: + +- **Perspective tilt**: use `gsap.set(el, { transformPerspective: 1200, rotationY: -8 })` + `box-shadow` — creates depth. Do NOT use CSS `transform: perspective(...)` as GSAP will overwrite it. +- **Slow zoom (Ken Burns)**: GSAP `scale: 1` → `1.04` over beat duration — makes photos cinematic +- **Device frame**: Wrap in a laptop/phone shape using CSS `border-radius` and `box-shadow` +- **Floating UI**: Extract a key element and animate it at a different z-depth for parallax +- **Scroll reveal**: Clip the image to a viewport window and animate `y` position + +## Load-Bearing GSAP Rules + +Rules below came out of two independent website-to-hyperframes builds (2026-04-20) where compositions lint-clean and still ship broken — elements that never appear, ambient motion that doesn't scrub, entrance tweens that silently kill their target. The linter cannot catch these; the rules must be followed by the author. + +- **No iframes for captured content.** Iframes do not seek deterministically with the timeline — the capture engine cannot scrub inside them, so they appear frozen (or blank) in the rendered output. If the source you're stylizing is a live web app, use the screenshots from `capture/` as stacked panels or layered images, not live embeds. + +- **Never stack two transform tweens on the same element.** A common failure: a `y` entrance plus a `scale` Ken Burns on the same ``. The second tween's `immediateRender: true` writes the element's initial state at construction time, overwriting whatever the first tween set — leaving the element invisible or offscreen with no lint warning. A secondary mechanism: `tl.from()` resets to its declared "from" state when the playhead is seeked past the timeline's end, so an element that looked correct in linear playback vanishes in the capture engine's non-linear seek. Fix one of two ways: + + ```html + + + + + + + + +
+ + ``` + +- **Prefer `tl.fromTo()` over `tl.from()` inside `.clip` scenes.** `gsap.from()` sets `immediateRender: true` by default, which writes the "from" state at timeline construction — before the `.clip` scene's `data-start` is active. Elements can flash visible, start from the wrong position, or skip their entrance entirely when the scene is seeked non-linearly (which the capture engine does). Explicit `fromTo` makes the state at every timeline position deterministic: + + ```js + // BRITTLE: immediateRender interacts badly with scene boundaries + tl.from(el, { opacity: 0, y: 50, duration: 0.6 }, t); + + // DETERMINISTIC: state is defined at both ends, no immediateRender surprise + tl.fromTo(el, { opacity: 0, y: 50 }, { opacity: 1, y: 0, duration: 0.6 }, t); + ``` + +- **Ambient pulses must attach to the seekable `tl`, never bare `gsap.to()`.** Auras, shimmers, gentle float loops, logo breathing — all of these must be added to the scene's timeline, not fired standalone. Standalone tweens run on wallclock time and do not scrub with the capture engine, so the effect is absent in the rendered video even though it looks correct in the studio preview: + + ```js + // BAD: lives outside the timeline, never renders in capture + gsap.to(".aura", { scale: 1.08, yoyo: true, repeat: 5, duration: 1.2 }); + + // GOOD: seekable, deterministic, renders + tl.to(".aura", { scale: 1.08, yoyo: true, repeat: 5, duration: 1.2 }, 0); + ``` + +- **Hard-kill every scene boundary, not just captions.** The caption hard-kill rule above generalizes: any element whose visibility changes at a beat boundary needs a deterministic `tl.set()` kill after its fade, because later tweens on the same element (or `immediateRender` from a sibling tween) can resurrect it. Apply to every element with an exit animation: + + ```js + tl.to(el, { opacity: 0, duration: 0.3 }, beatEnd); + tl.set(el, { opacity: 0, visibility: "hidden" }, beatEnd + 0.3); // deterministic kill + ``` + +These are the exact rules with the exact code examples — don't summarize or shorten them. They exist because compositions that lint clean still ship broken without them. diff --git a/skills/hyperframes/references/narration.md b/skills/hyperframes/references/narration.md new file mode 100644 index 000000000..c28fff2ee --- /dev/null +++ b/skills/hyperframes/references/narration.md @@ -0,0 +1,92 @@ +# Narration & Script + +How to write narration scripts for video compositions. Read when the composition includes voiceover or TTS. + +## Pacing + +- **2.5 words per second** is natural speaking pace +- 15s = ~37 words. 30s = ~75 words. 60s = ~150 words +- Leave room for pauses. Silence between sentences is a feature, not dead air +- The script should feel SHORTER than the video — visual breathing room matters + +## Tone + +Write like a person, not a brochure: + +- Use contractions: "it's", "you'll", "that's", "we've" +- Vary sentence length — short punchy phrases mixed with longer flowing ones +- Read it out loud. If it sounds robotic, rewrite it +- Avoid jargon unless the audience expects it + +## Number Pronunciation + +Write what you want the voice to say. TTS reads literally. + +| In the product | Write in script as | +| -------------- | --------------------------------- | +| 135+ | more than one hundred thirty five | +| $1.9T | nearly two trillion dollars | +| 99.999% | ninety nine point nine percent | +| 200M+ | over two hundred million | +| 10x | ten times | +| API | A P I | +| stripe.com | stripe dot com | + +The visual can show the exact figure while the voice rounds it. + +## Structure + +For product videos: + +1. **Hook** — what's surprising or impressive about this product? A bold claim, a provocative question, a contrast, or a striking number. This is the opening line. **Vary the hook type** — don't default to a stat every time. +2. **Story** — what does the product do? Who uses it? Keep it concrete. +3. **Proof** — stats, customer names, social proof. Real numbers from the product. +4. **CTA** — what should the viewer do? "Start building at stripe dot com." + +Not every video needs all four. A 15-second social ad might be Hook + Proof + CTA. A 60-second product tour uses all four with more Story. + +## The Opening Line + +The most important sentence in the video. It must create tension, curiosity, or surprise in the first 3 seconds. + +Patterns that work: + +- **A bold claim**: "The financial infrastructure that powers the internet economy." +- **A question that provokes**: "What if your database could think?" +- **A contrast**: "Your AI agent already knows how to make videos. It just needs the right format." +- **A number that shocks**: "Nearly two trillion dollars." (Use sparingly — not every video should open with a stat.) + +If the opening is generic ("Welcome to Stripe" / "Introducing our product"), start over. + +## Example + +From a 62-second product launch video (team reference): + +``` +Your AI agent already knows how to make videos. +It just needs the right format. + +This is Hyperframes. An open source framework. HTML in, video out. + +A div is a keyframe. Data attributes are your timeline. +CSS is your look. G-Sap is your animation engine. + +Anything a browser can render can be a frame in your video. + +CSS animations. G-Sap. Lottie. Shaders. Three.js. + +Drop in music, sound effects, footage — it all composes together. + +No new framework for the agent to learn. +Just HTML. + +The agent writes it. The renderer captures every frame as MP4. +It's deterministic. Identical outputs, every time. + +Give your agent the CLI. Tell it what to make. +Watch it build. + +Hyperframes. Go make something. +``` + +Note: ~140 words for 62 seconds — that's 2.3 words/sec, leaving room for pauses and visual breathing. diff --git a/skills/hyperframes/references/techniques.md b/skills/hyperframes/references/techniques.md new file mode 100644 index 000000000..b460fa845 --- /dev/null +++ b/skills/hyperframes/references/techniques.md @@ -0,0 +1,387 @@ +# Visual Techniques Reference + +10 proven techniques from production HyperFrames videos. Use these in your storyboard and compositions to create visually rich, professional output. Each technique includes a minimal code pattern you can adapt. + +These are NOT advanced — they're standard motion design patterns that every composition should use at least 2-3 of. + +--- + +## 1. SVG Path Drawing + +A path draws itself in real-time, like someone tracing with a pen. Use for revealing diagrams, arrows, connector lines, or brand marks. + +```html + + + + + +``` + +Use `path.getTotalLength()` to calculate the dasharray value dynamically. + +--- + +## 2. Canvas 2D Procedural Art + +Animated noise, particle fields, data visualizations — anything that evolves frame-by-frame. Drive it with a GSAP proxy. + +```html + + +``` + +The `hash()` function is deterministic — same frame renders identically every time. + +--- + +## 3. CSS 3D Transforms + +Perspective rotations create depth. Use for product showcases, card flips, architectural reveals. + +```html +
+
+
Product
+
Details
+
+
+ +``` + +Always set `perspective` on the parent, `transform-style: preserve-3d` on the animated element. + +--- + +## 4. Per-Word Kinetic Typography + +Words appear one-by-one, synced to transcript.json timestamps. The core technique for narration-driven videos. + +```html +
+ Anything + a + browser + can + render +
+ + +``` + +The slide distance DECAYS per word (80→12px) — mimics a camera settling. + +--- + +## 5. Lottie Animation + +Vector animations that play inside a composition. Use for logos, character animations, icons. + +```html + + + + +``` + +Or use lottie-web for more control: + +```javascript +var anim = lottie.loadAnimation({ + container: document.getElementById("anim"), + renderer: "svg", + loop: false, + autoplay: false, + path: "../capture/assets/lottie/animation-0.json", +}); +``` + +--- + +## 6. Video Compositing + +Embed real video footage inside compositions. Videos must be `muted` with `playsinline`. + +```html +
+ +
+ +``` + +The HyperFrames runtime handles video seeking and playback. + +--- + +## 7. Character-by-Character Typing + +Terminal typing effect using `tl.call()` to update text content character by character. + +```html +
+ ❯ + + +
+ +``` + +Use `ease: "steps(1)"` for cursor blink — creates discrete on/off. + +--- + +## 8. Variable Font Axis Animation + +Animate font-variation-settings to reshape glyphs in real-time. Works with variable fonts that have axes like optical size (opsz), weight (wght), softness (SOFT). + +```html + + +``` + +The glyph subtly reshapes as axes animate — optical size adjusts detail, weight changes thickness. + +--- + +## 9. GSAP MotionPathPlugin + +Animate an element along an arbitrary SVG path. Use for sliders following curves, particles along trajectories, guided reveals. + +```html + +
+ +``` + +--- + +## 10. Velocity-Matched Transitions + +Exit one beat and enter the next with matched velocities — creates perceived continuous motion. + +```javascript +// EXIT (in outgoing composition): accelerating with blur +tl.to( + ".content", + { + y: -150, + filter: "blur(30px)", + opacity: 0, + duration: 0.33, + ease: "power2.in", // accelerates + }, + beatDuration - 0.33, +); + +// ENTRY (in incoming composition): decelerating from blur +gsap.set(".content", { y: 150, filter: "blur(30px)" }); +tl.to( + ".content", + { + y: 0, + filter: "blur(0px)", + duration: 1.0, + ease: "power2.out", // decelerates + }, + 0, +); +``` + +The fastest point of both curves meets at the cut — the viewer perceives smooth camera motion. Match ease families: `.in` for exits, `.out` for entries. + +--- + +## 11. Audio-Reactive Animation + +Drive any GSAP-tweenable property from the playing audio. Bass pulses a logo on kick drums. Treble glows a CTA on cymbals. Amplitude breathes a background during quiet phrases. The result: motion that feels locked to the track in a way pre-authored tweens never can. + +**When to use:** Any video with music or dramatic narration — brand reels, product launches, hype edits. Skip for calm/tutorial pacing. + +**How it works:** Pre-extract audio frequency bands into a JSON file, then sample per-frame via `tl.call()`: + +```js +// audio-data.json: { fps: 30, totalFrames: 900, frames: [{ bands: [0.82, 0.45, 0.31, ...] }, ...] } +for (var f = 0; f < AUDIO_DATA.totalFrames; f++) { + tl.call( + (function (frame) { + return function () { + var bass = frame.bands[0]; // 0–1 + var treble = frame.bands[13]; + gsap.set(".logo", { scale: 1 + bass * 0.04 }); // 3–4% pulse on bass + gsap.set(".cta", { filter: `drop-shadow(0 0 ${treble * 24}px #00C3FF)` }); + }; + })(AUDIO_DATA.frames[f]), + [], + f / AUDIO_DATA.fps, + ); +} +``` + +Per-frame sampling is required — a single tween will not react. Use the extract script: + +```bash +python3 skills/gsap/scripts/extract-audio-data.py narration.wav --fps 30 --bands 16 -o audio-data.json +``` + +Keep text/logo intensity subtle (≤5% scale, ≤30% glow) — audio-reactive motion on tiny elements reads as jitter. Bigger backgrounds can push to 10–30%. + +**Never do:** equalizer bars, spectrum analyzers, waveform displays, strobing, rainbow color cycling. The audio provides _timing and intensity_; the visual vocabulary still comes from the brand. See `skills/hyperframes/references/audio-reactive.md` for the full API and anti-patterns. + +--- + +## When to Use What + +| Video energy | Techniques to combine | +| ------------------------------ | --------------------------------------------------------------- | +| High impact (launches, promos) | Per-word typography + velocity transitions + counter animations | +| Cinematic (tours, stories) | SVG path drawing + video compositing + 3D transforms | +| Technical (dev tools, APIs) | Character typing + Canvas 2D procedural + MotionPath | +| Premium (luxury, enterprise) | Variable font animation + Lottie + slow velocity transitions | +| Data-driven (stats, metrics) | Canvas 2D procedural + counter animations + SVG path drawing | diff --git a/skills/hyperframes/templates/design-picker.html b/skills/hyperframes/templates/design-picker.html index b89d22899..f85666382 100644 --- a/skills/hyperframes/templates/design-picker.html +++ b/skills/hyperframes/templates/design-picker.html @@ -306,31 +306,77 @@ pv.innerHTML = h; } -// Output +// Output — google-labs-code/design.md spec: YAML frontmatter + prose sections function showOutput() { if (picks.theme===null||picks.arch===null||picks.palette===null||picks.type===null||picks.corners===null||picks.density===null||picks.depth===null) return; var a=ARCHITECTURES[picks.arch], p=PALETTES[picks.palette], t=TYPEPAIRS[picks.type]; var th = THEMES[picks.theme], cr = CORNERS[picks.corners], dn = DENSITIES[picks.density], dp = DEPTHS[picks.depth]; - var useBg = (th.id === "palette" && p.background) ? p.background : th.bg; - var useFg = (th.id === "palette" && p.foreground) ? p.foreground : th.fg; - var md = "# Design System\n\n"; - md += "## Mood\n" + a.mood + "\n\n"; - md += "## Theme\n- Mode: " + th.name + "\n- Canvas: " + useBg + "\n- Content: " + useFg + "\n\n"; - md += "## Structure\n- Architecture: " + a.name + " — " + a.description + "\n\n"; - md += "## Colors\n"; - md += "- Accent: " + p.accent + "\n"; - if (p.muted) md += "- Muted: " + p.muted + "\n"; - if (p.surface) md += "- Surface: " + p.surface + "\n"; - md += "\n## Typography\n"; - md += "- Headline: " + t.headline.family + ", weight " + t.headline.weight + "\n"; - md += "- Body: " + t.body.family + ", weight " + t.body.weight + "\n"; - md += "- Size scale: 52px display, 32px heading, 20px subhead, 15px body, 12px caption\n"; - md += "- Tracking: -0.03em on display sizes, normal on body\n"; - md += "\n## Corners\n- Border radius: " + cr.name + " (" + cr.value + ")\n"; - md += "\n## Spacing\n- Density: " + dn.name + "\n- Padding: " + dn.padding + "\n- Gap: " + dn.gap + "\n"; - md += "\n## Depth & Elevation\n- Level: " + dp.name + " — " + dp.desc + "\n"; - if (a.components) md += "\n## Components\n" + a.components + "\n"; - if (a.dos) md += "\n## Do's and Don'ts\n" + a.dos + "\n"; + var bg = (th.id === "palette" && p.background) ? p.background : th.bg; + var fg = (th.id === "palette" && p.foreground) ? p.foreground : th.fg; + var ac = p.accent; + var mt = p.muted || p.mid || "#888888"; + var padVal = {Tight:"8px",Normal:"16px",Generous:"32px"}[dn.name] || "16px"; + var gapVal = {Tight:"8px",Normal:"16px",Generous:"28px"}[dn.name] || "16px"; + var shadowDesc = {Flat:"none",Subtle:"0 2px 8px rgba(0,0,0,0.1)",Layered:"0 4px 24px rgba(0,0,0,0.15)"}[dp.name] || "none"; + + // YAML frontmatter + var md = "---\n"; + md += "name: Untitled\n"; + md += "colors:\n"; + md += " primary: \"" + bg + "\"\n"; + md += " on-primary: \"" + fg + "\"\n"; + md += " accent: \"" + ac + "\"\n"; + md += " muted: \"" + mt + "\"\n"; + md += "typography:\n"; + md += " headline:\n"; + md += " fontFamily: " + t.headline.family + "\n"; + md += " fontSize: 3.5rem\n"; + md += " fontWeight: " + t.headline.weight + "\n"; + md += " letterSpacing: -0.03em\n"; + md += " body:\n"; + md += " fontFamily: " + t.body.family + "\n"; + md += " fontSize: 1rem\n"; + md += " fontWeight: " + t.body.weight + "\n"; + md += " lineHeight: 1.5\n"; + md += "rounded:\n"; + md += " md: " + cr.value + "\n"; + md += "spacing:\n"; + md += " md: " + padVal + "\n"; + md += " lg: " + gapVal + "\n"; + md += "---\n\n"; + + // Prose sections + md += "## Overview\n\n"; + md += a.mood + ". " + a.description + ". " + p.description + ".\n\n"; + + md += "## Colors\n\n"; + md += "- **Primary** (`" + bg + "`) — Canvas background\n"; + md += "- **On-Primary** (`" + fg + "`) — Text and content\n"; + md += "- **Accent** (`" + ac + "`) — CTAs, highlights, interactive elements\n"; + md += "- **Muted** (`" + mt + "`) — Secondary text, captions\n\n"; + + md += "## Typography\n\n"; + md += "- **Headline** — " + t.headline.family + " at weight " + t.headline.weight + ". Display and section headings.\n"; + md += "- **Body** — " + t.body.family + " at weight " + t.body.weight + ". Running text and UI labels.\n\n"; + + md += "## Layout\n\n"; + md += "- Structure: " + a.name + " — " + a.tag + "\n"; + md += "- Density: " + dn.name + " (" + dn.desc + ")\n"; + md += "- Corners: " + cr.name + " (" + cr.value + ")\n\n"; + + md += "## Elevation\n\n"; + md += dp.name + " — " + dp.desc + ".\n\n"; + + if (a.components) md += "## Components\n\n" + a.components + "\n\n"; + + md += "## Do's and Don'ts\n\n"; + if (a.dos) { + md += a.dos + "\n"; + } else { + md += "### Do's\n- Use accent color sparingly for maximum impact\n- Maintain consistent " + cr.name.toLowerCase() + " corners across all elements\n\n"; + md += "### Don'ts\n- Do not mix multiple accent colors\n- Do not use font weights outside the specified headline/body pair\n"; + } + document.getElementById("md-output").value = md; document.getElementById("md-overlay").classList.add("visible"); } diff --git a/skills/website-to-hyperframes/references/step-3-script.md b/skills/website-to-hyperframes/references/step-3-script.md index 28a0743cb..ea16e2294 100644 --- a/skills/website-to-hyperframes/references/step-3-script.md +++ b/skills/website-to-hyperframes/references/step-3-script.md @@ -6,91 +6,4 @@ The script is the backbone. Everything downstream — scene durations, animation Save as `SCRIPT.md` in the project directory. -## Pacing - -- **2.5 words per second** is natural speaking pace -- 15s = ~37 words. 30s = ~75 words. 60s = ~150 words -- Leave room for pauses. Silence between sentences is a feature, not dead air -- The script should feel SHORTER than the video — visual breathing room matters - -## Tone - -Write like a person, not a brochure: - -- Use contractions: "it's", "you'll", "that's", "we've" -- Vary sentence length — short punchy phrases mixed with longer flowing ones -- Read it out loud. If it sounds robotic, rewrite it -- Avoid jargon unless the audience expects it - -## Number Pronunciation - -Write what you want the voice to say. TTS reads literally. - -| On the website | Write in script as | -| -------------- | --------------------------------- | -| 135+ | more than one hundred thirty five | -| $1.9T | nearly two trillion dollars | -| 99.999% | ninety nine point nine percent | -| 200M+ | over two hundred million | -| 10x | ten times | -| API | A P I | -| stripe.com | stripe dot com | - -The visual can show the exact figure while the voice rounds it. - -## Structure - -For product videos from a website capture: - -1. **Hook** — what's surprising or impressive about this product? A bold claim, a provocative question, a contrast, or a striking number. This is the opening line. **Vary the hook type** — don't default to a stat every time. -2. **Story** — what does the product do? Who uses it? Keep it concrete. -3. **Proof** — stats, customer names, social proof. Real numbers from the website. -4. **CTA** — what should the viewer do? "Start building at stripe dot com." - -Not every video needs all four. A 15-second social ad might be Hook + Proof + CTA. A 60-second product tour uses all four with more Story. - -## The Opening Line - -The most important sentence in the video. It must create tension, curiosity, or surprise in the first 3 seconds. - -Patterns that work: - -- **A bold claim**: "The financial infrastructure that powers the internet economy." -- **A question that provokes**: "What if your database could think?" -- **A contrast**: "Your AI agent already knows how to make videos. It just needs the right format." -- **A number that shocks**: "Nearly two trillion dollars." (Use sparingly — not every video should open with a stat.) - -If the opening is generic ("Welcome to Stripe" / "Introducing our product"), start over. - -## Example - -From a 62-second product launch video (team reference): - -``` -Your AI agent already knows how to make videos. -It just needs the right format. - -This is Hyperframes. An open source framework. HTML in, video out. - -A div is a keyframe. Data attributes are your timeline. -CSS is your look. G-Sap is your animation engine. - -Anything a browser can render can be a frame in your video. - -CSS animations. G-Sap. Lottie. Shaders. Three.js. - -Drop in music, sound effects, footage — it all composes together. - -No new framework for the agent to learn. -Just HTML. - -The agent writes it. The renderer captures every frame as MP4. -It's deterministic. Identical outputs, every time. - -Give your agent the CLI. Tell it what to make. -Watch it build. - -Hyperframes. Go make something. -``` - -Note: ~140 words for 62 seconds — that's 2.3 words/sec, leaving room for pauses and visual breathing. +Read [../../hyperframes/references/narration.md](../../hyperframes/references/narration.md) for the full narration guide. diff --git a/skills/website-to-hyperframes/references/step-4-storyboard.md b/skills/website-to-hyperframes/references/step-4-storyboard.md index 96ed8ab25..6db26bea4 100644 --- a/skills/website-to-hyperframes/references/step-4-storyboard.md +++ b/skills/website-to-hyperframes/references/step-4-storyboard.md @@ -4,7 +4,7 @@ - **DESIGN.md** — your color palette, font rules, components, Do's/Don'ts. Every creative decision must be grounded in this brand identity. If it says "white backgrounds with purple accent" — plan light scenes, not dark moody ones. - **`capture/extracted/asset-descriptions.md`** — read EVERY line. This is your menu of available visuals. Each line describes what the image actually shows (e.g., "translucent ribbons in orange, pink, and purple on white background" or "a high-speed train under a dark starry sky"). Use these descriptions to decide which assets belong in which beat. Assets you don't understand from the description — view them directly before assigning. -- **[techniques.md](techniques.md)** — 11 visual techniques (SVG path drawing, Canvas 2D art, CSS 3D, per-word typography, Lottie, video compositing, typing effect, variable fonts, MotionPath, velocity transitions, audio-reactive). Pick 2-3 per beat and specify them in the storyboard. +- **[techniques.md](../../hyperframes/references/techniques.md)** — 11 visual techniques (SVG path drawing, Canvas 2D art, CSS 3D, per-word typography, Lottie, video compositing, typing effect, variable fonts, MotionPath, velocity transitions, audio-reactive). Pick 2-3 per beat and specify them in the storyboard. The storyboard is the creative north star. It tells the engineer exactly what to build for each beat — mood, camera, animations, transitions, assets, sound. Write it as if you're briefing a motion designer who's never seen the website. @@ -60,18 +60,9 @@ Before writing any beats, audit every captured asset. Print this table: ## Per-Beat Direction -Each beat is a WORLD, not a layout. Before writing CSS specs and GSAP instructions, describe what the viewer EXPERIENCES. The difference between a great storyboard and a mediocre one: +Read [beat-direction.md](../../hyperframes/references/beat-direction.md) for the general beat template: concept, mood, animation choreography (energy verbs), transitions (shader vs CSS vs hard cut decision matrix), depth layers, SFX cues, rhythm planning, and velocity-matched transitions. -**Mediocre:** "Dark navy background. '$1.9T' in white, 280px. Logo top-left. Wave image bottom-right." -**Great:** "Camera is already mid-flight over a vast dark canvas. The gradient wave sweeps across the frame like aurora borealis — alive, shifting. '$1.9T' SLAMS into existence with such force the wave ripples in response. This isn't a slide — it's a moment." - -The first describes pixels. The second describes an experience. Write the second, then figure out the pixels. - -Each beat should have: - -### Concept - -The big idea for this beat in 2-3 sentences. What visual WORLD are we in? What metaphor drives it? What should the viewer FEEL? This is the most important part — everything else flows from it. +In the capture pipeline, each beat also includes: ### VO cue @@ -81,14 +72,6 @@ Which narration line plays over this beat. What the viewer sees — described cinematically, not as CSS specs. Use camera language (pan, zoom, drift, settle). Describe at least 5 visual elements, not just text + background. Think in layers — what's moving in the foreground, midground, background simultaneously? -### Mood direction - -Cultural and design references, not hex codes: - -- "Geometric, rhythmic, precise. Think Josef Albers or Bauhaus color studies." -- "Warm workspace. Nice notebook energy, not technical blueprint." -- "Cinematic title sequence. The kind of opening where you lean forward." - ### Assets Which captured files to use, referenced by filename: @@ -97,64 +80,6 @@ Which captured files to use, referenced by filename: - "Logo: `capture/assets/svgs/stripe-logo.svg` — centered, fades in at 0.5s" - "Enterprise photo: `capture/assets/enterprise-accordion-hertz.png` — Ken Burns pan, 70% opacity overlay" -### Animation choreography - -Specific motion verbs per element — not "it animates in" but HOW: - -| Energy | Verbs | Example | -| ------------- | --------------------------------------------- | ------------------------------------- | -| High impact | SLAMS, CRASHES, PUNCHES, STAMPS, SHATTERS | "$1.9T" SLAMS in from left at -5° | -| Medium energy | CASCADE, SLIDES, DROPS, FILLS, DRAWS | Three cards CASCADE in staggered 0.3s | -| Low energy | types on, FLOATS, morphs, COUNTS UP, fades in | Counter COUNTS UP from 0 to 135K | - -Every element gets a verb. If you can't name the verb, the element is not yet designed. - -### Transition - -How this beat hands off to the next. Specify the type and parameters. - -**When to pick which:** - -| Choose shader transition for | Choose CSS transition for | Choose hard cut for | -| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------- | -| Reveals, big reaction shots, product/logo unveils, energy shifts, "wow" moments | Continuous camera-motion beats where the scene feels like one move broken into cuts | Rapid-fire lists, percussive edits on the beat, comedic timing | -| Any moment the music/VO punctuates with a downbeat or SFX hit | Beats that ease from one composition into the next with shared motion vocabulary | Sequences of 3+ quick tempo-matched switches | -| Brand moments where the transition itself _is_ the visual | Minimal/editorial pacing | Anytime a 0.3-0.8s transition would feel too slow | - -Rule of thumb: if the beat is the _centerpiece_ of the video, shader-transition into it. If the beat is connective tissue, CSS-transition. A brand reel of 5-7 beats usually wants 1-2 shader transitions (the hero reveal + the CTA) and the rest CSS or hard cuts — too many shader transitions flatten their impact. - -**CSS transitions** (choose from `skills/hyperframes/references/transitions/catalog.md`): - -- Velocity-matched upward: exit `y:-150, blur:30px, 0.33s power2.in` → entry `y:150→0, blur:30px→0, 1.0s power2.out` -- Whip pan: exit `x:-400, blur:24px, 0.3s power3.in` → entry `x:400→0, blur:24px→0, 0.3s power3.out` -- Blur through: exit `blur:20px, 0.3s` → entry `blur:20px→0, 0.25s power3.out` -- Zoom through: exit `scale:1→1.2, blur:20px, 0.2s power3.in` → entry `scale:0.75→1, blur:20px→0, 0.5s expo.out` -- Hard cut / smash cut (for rapid-fire sequences) - -**Shader transitions** (choose from `packages/shader-transitions/README.md`): - -- Cross-Warp Morph (organic, versatile) — 0.5-0.8s, power2.inOut -- Cinematic Zoom (professional momentum) — 0.4-0.6s, power2.inOut -- Gravitational Lens (otherworldly) — 0.6-1.0s, power2.inOut -- Glitch (aggressive, high energy) — 0.3-0.5s -- See `packages/shader-transitions/README.md` for the full API, available shaders, and setup - -**How velocity-matched CSS transitions work:** -Exit the outgoing beat with an accelerating ease (power2.in or power3.in) plus a blur ramp. Enter the incoming beat with a decelerating ease (power2.out or power3.out) plus blur clear. The fastest point of both easing curves meets at the cut — the viewer perceives continuous camera motion, not two discrete animations. Match exit velocity to entry velocity within ~5% tolerance. - -### Depth layers - -What's in foreground, midground, and background. Every beat should have at least 2 layers: - -- "BG: dark navy fill + subtle radial glow. MG: stat cards with drop shadow. FG: brand logo bottom-right." - -### SFX cues - -What sounds at what moment: - -- "On the capture pulse — a soft, warm analog shutter click." -- "Left side carries a faint low drone. On fold: drone cuts. Silence. Then a single clean chime." - --- ## Production Architecture diff --git a/skills/website-to-hyperframes/references/step-6-build.md b/skills/website-to-hyperframes/references/step-6-build.md index 0021ccaf2..3a028e1a6 100644 --- a/skills/website-to-hyperframes/references/step-6-build.md +++ b/skills/website-to-hyperframes/references/step-6-build.md @@ -5,7 +5,7 @@ - **DESIGN.md** — your color palette, fonts, components, and Do's/Don'ts. Every composition must use EXACT hex colors and font families from this file. If it says "white backgrounds" — use white, not dark. - **STORYBOARD.md** — the beat-by-beat plan you're executing. Each beat specifies assets, animations, transitions, and which techniques to use. - **`capture/extracted/asset-descriptions.md`** — when the storyboard assigns an asset to a beat, re-read the description to understand what it shows and how to position/style it correctly. -- **[techniques.md](techniques.md)** — code patterns for the 10 visual techniques. When the storyboard says "SVG path drawing" or "per-word kinetic typography" — read the code pattern from this file and adapt it. +- **[techniques.md](../../hyperframes/references/techniques.md)** — code patterns for the 10 visual techniques. When the storyboard says "SVG path drawing" or "per-word kinetic typography" — read the code pattern from this file and adapt it. - **transcript.json** — word-level timestamps that drive scene durations. **Split the work: spawn a sub-agent for each beat.** By this step your context is full of captured data, DESIGN.md, SCRIPT, STORYBOARD, and transcript. Building compositions on top of all that means the detailed rules below compete with thousands of tokens of prior work. Each sub-agent gets a fresh context focused on one beat — dramatically better output. diff --git a/skills/website-to-hyperframes/references/techniques.md b/skills/website-to-hyperframes/references/techniques.md index b460fa845..06a279ef3 100644 --- a/skills/website-to-hyperframes/references/techniques.md +++ b/skills/website-to-hyperframes/references/techniques.md @@ -1,387 +1,3 @@ # Visual Techniques Reference -10 proven techniques from production HyperFrames videos. Use these in your storyboard and compositions to create visually rich, professional output. Each technique includes a minimal code pattern you can adapt. - -These are NOT advanced — they're standard motion design patterns that every composition should use at least 2-3 of. - ---- - -## 1. SVG Path Drawing - -A path draws itself in real-time, like someone tracing with a pen. Use for revealing diagrams, arrows, connector lines, or brand marks. - -```html - - - - - -``` - -Use `path.getTotalLength()` to calculate the dasharray value dynamically. - ---- - -## 2. Canvas 2D Procedural Art - -Animated noise, particle fields, data visualizations — anything that evolves frame-by-frame. Drive it with a GSAP proxy. - -```html - - -``` - -The `hash()` function is deterministic — same frame renders identically every time. - ---- - -## 3. CSS 3D Transforms - -Perspective rotations create depth. Use for product showcases, card flips, architectural reveals. - -```html -
-
-
Product
-
Details
-
-
- -``` - -Always set `perspective` on the parent, `transform-style: preserve-3d` on the animated element. - ---- - -## 4. Per-Word Kinetic Typography - -Words appear one-by-one, synced to transcript.json timestamps. The core technique for narration-driven videos. - -```html -
- Anything - a - browser - can - render -
- - -``` - -The slide distance DECAYS per word (80→12px) — mimics a camera settling. - ---- - -## 5. Lottie Animation - -Vector animations that play inside a composition. Use for logos, character animations, icons. - -```html - - - - -``` - -Or use lottie-web for more control: - -```javascript -var anim = lottie.loadAnimation({ - container: document.getElementById("anim"), - renderer: "svg", - loop: false, - autoplay: false, - path: "../capture/assets/lottie/animation-0.json", -}); -``` - ---- - -## 6. Video Compositing - -Embed real video footage inside compositions. Videos must be `muted` with `playsinline`. - -```html -
- -
- -``` - -The HyperFrames runtime handles video seeking and playback. - ---- - -## 7. Character-by-Character Typing - -Terminal typing effect using `tl.call()` to update text content character by character. - -```html -
- ❯ - - -
- -``` - -Use `ease: "steps(1)"` for cursor blink — creates discrete on/off. - ---- - -## 8. Variable Font Axis Animation - -Animate font-variation-settings to reshape glyphs in real-time. Works with variable fonts that have axes like optical size (opsz), weight (wght), softness (SOFT). - -```html - - -``` - -The glyph subtly reshapes as axes animate — optical size adjusts detail, weight changes thickness. - ---- - -## 9. GSAP MotionPathPlugin - -Animate an element along an arbitrary SVG path. Use for sliders following curves, particles along trajectories, guided reveals. - -```html - -
- -``` - ---- - -## 10. Velocity-Matched Transitions - -Exit one beat and enter the next with matched velocities — creates perceived continuous motion. - -```javascript -// EXIT (in outgoing composition): accelerating with blur -tl.to( - ".content", - { - y: -150, - filter: "blur(30px)", - opacity: 0, - duration: 0.33, - ease: "power2.in", // accelerates - }, - beatDuration - 0.33, -); - -// ENTRY (in incoming composition): decelerating from blur -gsap.set(".content", { y: 150, filter: "blur(30px)" }); -tl.to( - ".content", - { - y: 0, - filter: "blur(0px)", - duration: 1.0, - ease: "power2.out", // decelerates - }, - 0, -); -``` - -The fastest point of both curves meets at the cut — the viewer perceives smooth camera motion. Match ease families: `.in` for exits, `.out` for entries. - ---- - -## 11. Audio-Reactive Animation - -Drive any GSAP-tweenable property from the playing audio. Bass pulses a logo on kick drums. Treble glows a CTA on cymbals. Amplitude breathes a background during quiet phrases. The result: motion that feels locked to the track in a way pre-authored tweens never can. - -**When to use:** Any video with music or dramatic narration — brand reels, product launches, hype edits. Skip for calm/tutorial pacing. - -**How it works:** Pre-extract audio frequency bands into a JSON file, then sample per-frame via `tl.call()`: - -```js -// audio-data.json: { fps: 30, totalFrames: 900, frames: [{ bands: [0.82, 0.45, 0.31, ...] }, ...] } -for (var f = 0; f < AUDIO_DATA.totalFrames; f++) { - tl.call( - (function (frame) { - return function () { - var bass = frame.bands[0]; // 0–1 - var treble = frame.bands[13]; - gsap.set(".logo", { scale: 1 + bass * 0.04 }); // 3–4% pulse on bass - gsap.set(".cta", { filter: `drop-shadow(0 0 ${treble * 24}px #00C3FF)` }); - }; - })(AUDIO_DATA.frames[f]), - [], - f / AUDIO_DATA.fps, - ); -} -``` - -Per-frame sampling is required — a single tween will not react. Use the extract script: - -```bash -python3 skills/gsap/scripts/extract-audio-data.py narration.wav --fps 30 --bands 16 -o audio-data.json -``` - -Keep text/logo intensity subtle (≤5% scale, ≤30% glow) — audio-reactive motion on tiny elements reads as jitter. Bigger backgrounds can push to 10–30%. - -**Never do:** equalizer bars, spectrum analyzers, waveform displays, strobing, rainbow color cycling. The audio provides _timing and intensity_; the visual vocabulary still comes from the brand. See `skills/hyperframes/references/audio-reactive.md` for the full API and anti-patterns. - ---- - -## When to Use What - -| Video energy | Techniques to combine | -| ------------------------------ | --------------------------------------------------------------- | -| High impact (launches, promos) | Per-word typography + velocity transitions + counter animations | -| Cinematic (tours, stories) | SVG path drawing + video compositing + 3D transforms | -| Technical (dev tools, APIs) | Character typing + Canvas 2D procedural + MotionPath | -| Premium (luxury, enterprise) | Variable font animation + Lottie + slow velocity transitions | -| Data-driven (stats, metrics) | Canvas 2D procedural + counter animations + SVG path drawing | +Moved to the shared hyperframes skill reference. Read [../../hyperframes/references/techniques.md](../../hyperframes/references/techniques.md). From 4886d460ff0e443acd721833c680d10c729f353a Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Wed, 29 Apr 2026 14:57:30 -0700 Subject: [PATCH 12/37] fix(skills): respect design.md background color, add light canvas guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Background color moved from "adapt for video" to "strict from design.md" — agents must not override the user's palette choice. Added specific guidance for making light canvases work cinematically: bolder borders, full-saturation accents, structural depth via rules/dividers, background texture. Co-Authored-By: Claude Opus 4.6 (1M context) --- skills/hyperframes/references/video-composition.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/skills/hyperframes/references/video-composition.md b/skills/hyperframes/references/video-composition.md index 20baf00b2..e0758eba0 100644 --- a/skills/hyperframes/references/video-composition.md +++ b/skills/hyperframes/references/video-composition.md @@ -6,9 +6,9 @@ Video frames are not web pages. These rules apply to every composition regardles design.md defines what the brand looks like: colors, fonts, personality, constraints. It does NOT define how to compose a video frame. Use brand colors at video-appropriate intensity — not at web-UI opacity. -**Strict from design.md:** hex values, font families, weight relationships, Do's and Don'ts. +**Strict from design.md:** hex values (including background color), font families, weight relationships, Do's and Don'ts. If the user chose a light canvas, use a light canvas. If they chose dark, use dark. Do not override their palette. -**Adapt for video:** background lightness, type sizes, spacing, decorative opacity, border weight, component treatments. A web UI card at `border: 1px solid #e2e3e6` with `box-shadow: 0 2px 4px rgba(0,0,0,0.06)` is invisible on video. The brand color is sacred; the application is yours. +**Adapt for video:** type sizes, spacing, decorative opacity, border weight, component treatments. A web UI card at `border: 1px solid #e2e3e6` with `box-shadow: 0 2px 4px rgba(0,0,0,0.06)` is invisible on video. The brand color is sacred; the application is yours. ## Density @@ -27,7 +27,7 @@ Aim for 8-10 visual elements per scene. Two of those should be decorative elemen Muted is fine. Flat is not. Every scene should have at least one color that pulls the eye. - Brand accent should be VISIBLE — not a 5% opacity glow lost in compression. 15-25% for atmospheric, full saturation for focal elements. -- Dark canvases make color pop. Light canvases need stronger accent application to avoid looking washed out. +- **Light canvases work differently than dark.** On dark: accent glows pop naturally. On light: use bolder borders (2px+ solid), stronger structural elements (rules, dividers), and full-saturation accent hits. Light backgrounds need texture (subtle grain, patterns) to avoid the "blank slide" feel. Don't switch to dark — make light cinematic. - Tint neutrals toward the brand hue. Dead gray reads as undesigned. ## Scale From 9d9154d213744f04ac69a6d351598f9a19783da0 Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Wed, 29 Apr 2026 14:58:51 -0700 Subject: [PATCH 13/37] feat(skills): prompt expansion uses beat-direction, picker generates contextual options MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Prompt expansion now uses beat-direction format: concept → mood → choreography verbs → depth layers → transition per scene. Adds rhythm declaration before scene breakdown. References beat-direction.md and video-composition.md. Design picker reference updated: generate architectures, palettes, and type pairings contextual to the user's prompt instead of generic options. 3-4 architectures, 5-6 palettes (always mix dark+light), 3 type pairings. Picker template output updated to emit spec-compliant design.md with YAML frontmatter + prose sections. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../hyperframes/references/design-picker.md | 7 +- .../references/prompt-expansion.md | 30 +- .../hyperframes/templates/design-picker.html | 1285 ++++++++++++----- 3 files changed, 920 insertions(+), 402 deletions(-) diff --git a/skills/hyperframes/references/design-picker.md b/skills/hyperframes/references/design-picker.md index d64b02216..c0cf22a7e 100644 --- a/skills/hyperframes/references/design-picker.md +++ b/skills/hyperframes/references/design-picker.md @@ -12,9 +12,12 @@ Before generating options, read these style references — all options must comp ## Building the picker -1. Generate 2-3 visual directions based on the prompt. Each direction needs: name, mood, colors (bg/fg/accent), fonts (headline/body), energy level, and transition style. +1. Generate options **contextual to the user's prompt**. A "product launch video" gets different architectures than a "data dashboard recap" or a "brand story." Each category should reflect the content: + - **3-4 architectures** — structural layouts that make sense for THIS content. A product launch needs a hook/proof/CTA structure. A data story needs stat grids and comparison layouts. A brand reel needs editorial flow with pull quotes. Name them evocatively (not "Layout A"). + - **5-6 palettes** — always include a mix of dark, light, and tinted backgrounds. Even for calm/wellness prompts, include at least one dark option. Name them after their personality ("Midnight Volt", "Warm Chalk"), not their colors. + - **3 type pairings** — serif+mono, grotesque+mono, display+sans. Cross-category pairings per typography.md. One safe, one editorial, one bold. 2. `mkdir -p .hyperframes` then copy [../templates/design-picker.html](../templates/design-picker.html) to `.hyperframes/pick-design.html`. -3. Replace `__ARCHITECTURES_JSON__`, `__PALETTES_JSON__`, and `__TYPEPAIRS_JSON__` with your generated options. The user picks one from each category independently — structure, palette, type pairing, plus theme (dark/light/full palette), corners, density, and depth. +3. Replace `__ARCHITECTURES_JSON__`, `__PALETTES_JSON__`, and `__TYPEPAIRS_JSON__` with your generated options. Use Python or a heredoc to inject JSON cleanly — don't hand-escape quotes in sed. The user picks one from each category independently — structure, palette, type pairing, plus theme (dark/light/full palette), corners, density, and depth. ### Architecture data format diff --git a/skills/hyperframes/references/prompt-expansion.md b/skills/hyperframes/references/prompt-expansion.md index 8d886dd65..f2aab09d5 100644 --- a/skills/hyperframes/references/prompt-expansion.md +++ b/skills/hyperframes/references/prompt-expansion.md @@ -9,8 +9,9 @@ Runs AFTER design direction is established (Step 0a). The expansion consumes des Read before generating: - `design.md` (if it exists) — extract brand colors, fonts, mood, and constraints. The expansion cites these exact values (hex codes, font names); it does not invent new ones. -- [../house-style.md](../house-style.md) — its rules for Background Layer (2-5 decoratives), Color, Motion, Typography apply to every scene. The expansion does NOT re-state those rules; it writes output that conforms to them. +- [beat-direction.md](beat-direction.md) — per-beat planning format (concept, mood, choreography verbs, transitions, depth layers, rhythm). The expansion outputs each scene using this format. - [video-composition.md](video-composition.md) — video-medium rules for density, scale, and color presence. The expansion applies these automatically. +- [../house-style.md](../house-style.md) — its rules for Background Layer (2-5 decoratives), Color, Motion, Typography apply to every scene. The expansion writes output that conforms to them. If `design.md` doesn't exist yet, run Step 0a (Design system) first. Expansion without a design context produces generic scene breakdowns that later agents ignore. @@ -38,18 +39,21 @@ The quality gap between a single-pass composition and a multi-scene-pipeline com Expand into a full production prompt with these sections: 1. **Title + style block** — cite design.md's exact hex values, font names, and mood. Do NOT invent a palette — quote what the design provides. -2. **Global animation rules** — parallax layers, micro-motion requirements, kinetic typography, pacing rules, transition style. Match energy to the brand mood (calm → slow eases, high energy → snappy eases). -3. **Scene-by-scene breakdown** — for each scene, enumerate: - - Time range and title - - **Background layer** — list the 2–5 decoratives (from house-style) with exact positioning, opacity using brand colors, and ambient motion (breath, drift, pulse, orbit). The user rarely lists atmosphere; expansion adds it. - - **Midground** — content elements (not generic: "alien claw slides across wall" not "scary things happen"). Keep everything the user specified; add what's missing. - - **Foreground** — text with font families and weights from design.md. Sizes at video scale per video-composition.md. - - **Micro-details** — registration marks, tick indicators, monospace labels, typographic accents, background data streams, grid patterns. These make a scene feel real. The user's prompt never lists them; expansion adds at least 2–3 per scene. - - **Transition out** — specific morph (what object becomes what, duration, ease), not just "cut" or "crossfade" -4. **Recurring motifs** — visual threads across scenes, drawn from the brand palette and typography. -5. **Transition rules** — every scene-to-scene connection described as object morphing. -6. **Pacing curve** — where energy builds, peaks, and releases. -7. **Negative prompt** — what to avoid, informed by design.md's constraints if present. + +2. **Rhythm declaration** — name the scene rhythm before detailing any scene. Example: `hook-PUNCH-breathe-CTA` or `slow-build-BUILD-PEAK-breathe-CTA`. See [beat-direction.md](beat-direction.md) for rhythm templates by video type. + +3. **Global rules** — parallax layers, micro-motion requirements, transition style, primary + accent transitions. Match energy to mood (calm → slow eases, high → snappy eases). + +4. **Per-scene beats** — for each scene, use the beat-direction format: + - **Concept** — the big idea in 2-3 sentences. What visual WORLD? What metaphor? What should the viewer FEEL? + - **Mood direction** — cultural/design references, not hex codes. ("Bauhaus color studies", "cinematic title sequence", "editorial calm") + - **Depth layers** — BG (2-5 decoratives with ambient motion), MG (content), FG (accents, structural elements, micro-details). 8-10 total elements per scene per video-composition.md. + - **Animation choreography** — specific verbs per element. High: SLAMS, CRASHES. Medium: CASCADE, SLIDES. Low: floats, types on, counts up. Every element gets a verb. If you can't name the verb, the element is not yet designed. + - **Transition out** — shader or CSS, with specific type and parameters. Not "crossfade" but "blur crossfade, 0.4s, power2.inOut." + +5. **Recurring motifs** — visual threads across scenes from the brand palette. + +6. **Negative prompt** — what to avoid, informed by design.md's constraints if present. ## Output diff --git a/skills/hyperframes/templates/design-picker.html b/skills/hyperframes/templates/design-picker.html index f85666382..de457c774 100644 --- a/skills/hyperframes/templates/design-picker.html +++ b/skills/hyperframes/templates/design-picker.html @@ -1,392 +1,903 @@ - + - - - -Design your visual direction - - - - -
-
Visual direction
-
Pick a structure, palette, and type. Preview updates live.
- -
-
Theme
-
Light or dark canvas.
-
-
-
-
Structure
-
Shape, layout, spatial feel.
-
-
-
-
Color palette
-
Accent colors applied to your theme.
-
-
-
-
Typography
-
Headline + body pairing.
-
-
-
-
Corners
-
Component border radius.
-
-
-
-
Density
-
Spacing between elements.
-
-
-
-
Depth
-
Shadows and layering.
-
-
-
- -
-
Select a structure to begin
-
- - - -
-
-
-
design.md — edit anything, then copy
-
- - + + + + Design your visual direction + + + +
+
Visual direction
+
+ Pick a structure, palette, and type. Preview updates live.
+ +
+
Theme
+
Light or dark canvas.
+
+
+
+
Structure
+
Shape, layout, spatial feel.
+
+
+
+
Color palette
+
Accent colors applied to your theme.
+
+
+
+
Typography
+
Headline + body pairing.
+
+
+
+
Corners
+
Component border radius.
+
+
+
+
Density
+
Spacing between elements.
+
+
+
+
Depth
+
Shadows and layering.
+
+
+
+ +
+
Select a structure to begin
-
- + + + +
+
+
+
+ design.md + — edit anything, then copy +
+
+ + +
+
+
+ +
+
-
-
- - - + + + From 42b422860c2e95f234170e0faae7a9e8fc5d7888 Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Wed, 29 Apr 2026 15:11:03 -0700 Subject: [PATCH 14/37] feat(skills): mood board first + contextual previews in design picker MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two-phase picker UI: Phase 1 shows 3-4 complete mood boards (architecture + palette + type combined), user picks a direction in one click. Phase 2 opens fine-tune panel with all categories pre-filled from the mood board selection. Quick wins: - Prompt-aware section descriptions via __PROMPT_JSON__ placeholder - Preview content uses real prompt text via {{prompt_headline}}/{{prompt_sub}} - "Recommended" badges on options matching the selected mood board - Phase navigation bar (Direction → Fine-tune) New data placeholders: - __MOODBOARDS_JSON__ — array of mood board objects with indices into architectures/palettes/typepairs - __PROMPT_JSON__ — title, headline, subline for contextual UI text Co-Authored-By: Claude Opus 4.6 (1M context) --- .../hyperframes/references/design-picker.md | 64 ++- .../hyperframes/templates/design-picker.html | 516 +++++++++++++----- 2 files changed, 433 insertions(+), 147 deletions(-) diff --git a/skills/hyperframes/references/design-picker.md b/skills/hyperframes/references/design-picker.md index c0cf22a7e..2684f8ce6 100644 --- a/skills/hyperframes/references/design-picker.md +++ b/skills/hyperframes/references/design-picker.md @@ -1,6 +1,6 @@ # Design Picker -Create a `design.md` by serving a visual picker page where the user configures 7 independent categories. +Two-phase visual picker: mood boards first (pick a complete direction), then fine-tune individual categories. ## Prerequisites @@ -12,12 +12,18 @@ Before generating options, read these style references — all options must comp ## Building the picker -1. Generate options **contextual to the user's prompt**. A "product launch video" gets different architectures than a "data dashboard recap" or a "brand story." Each category should reflect the content: - - **3-4 architectures** — structural layouts that make sense for THIS content. A product launch needs a hook/proof/CTA structure. A data story needs stat grids and comparison layouts. A brand reel needs editorial flow with pull quotes. Name them evocatively (not "Layout A"). - - **5-6 palettes** — always include a mix of dark, light, and tinted backgrounds. Even for calm/wellness prompts, include at least one dark option. Name them after their personality ("Midnight Volt", "Warm Chalk"), not their colors. - - **3 type pairings** — serif+mono, grotesque+mono, display+sans. Cross-category pairings per typography.md. One safe, one editorial, one bold. +1. Generate options **contextual to the user's prompt**. Each category should reflect the content: + - **3-4 mood boards** — complete visual directions combining architecture + palette + typography + density + depth. Each is a holistic identity the user can pick in one click. Name them evocatively ("Terminal Precision", "Editorial Warmth", "Bold Statement"). One safe/expected, one editorial, one ambitious. + - **3-4 architectures** — structural layouts that make sense for THIS content. Use `{{prompt_headline}}` and `{{prompt_sub}}` tokens in preview_html so previews show the user's actual content, not placeholder text. + - **5-6 palettes** — always include a mix of dark, light, and tinted backgrounds. Name them after personality. + - **3 type pairings** — serif+mono, grotesque+mono, display+sans. Cross-category pairings per typography.md. 2. `mkdir -p .hyperframes` then copy [../templates/design-picker.html](../templates/design-picker.html) to `.hyperframes/pick-design.html`. -3. Replace `__ARCHITECTURES_JSON__`, `__PALETTES_JSON__`, and `__TYPEPAIRS_JSON__` with your generated options. Use Python or a heredoc to inject JSON cleanly — don't hand-escape quotes in sed. The user picks one from each category independently — structure, palette, type pairing, plus theme (dark/light/full palette), corners, density, and depth. +3. Replace these placeholders using Python (don't hand-escape quotes in sed): + - `__ARCHITECTURES_JSON__` — array of architecture objects + - `__PALETTES_JSON__` — array of palette objects + - `__TYPEPAIRS_JSON__` — array of type pairing objects + - `__MOODBOARDS_JSON__` — array of mood board objects (see format below) + - `__PROMPT_JSON__` — object with prompt context (see format below) ### Architecture data format @@ -47,6 +53,52 @@ Optionally include `components` (component styling rules) and `dos` (do's and do } ``` +### Mood board data format + +Each mood board pre-selects one option from each category. The user picks a mood board in Phase 1, then fine-tunes in Phase 2 with those selections pre-filled. + +```json +{ + "name": "Terminal Precision", + "description": "Code-forward, data-dense, CLI energy. Dark canvas, monospace body, sharp corners.", + "theme": "dark", + "arch_index": 0, + "palette_index": 0, + "type_index": 0, + "corners_index": 0, + "density_index": 0, + "depth_index": 1, + "corners": "0px", + "padding": "12px", + "gap": "8px", + "shadow": "0 2px 16px rgba(0,230,255,0.15)" +} +``` + +Indices reference into the ARCHITECTURES, PALETTES, and TYPEPAIRS arrays. The template renders a mini preview of each mood board using its architecture's `preview_html` with the mood board's palette/type applied. + +### Prompt context data format + +```json +{ + "title": "AI Coding Assistant", + "headline": "Your Code, Understood.", + "subline": "An AI coding assistant that reads your entire codebase.", + "section_desc": "Layout options for your product launch" +} +``` + +`title` appears in the Phase 1 header. `headline` and `subline` replace `{{prompt_headline}}` and `{{prompt_sub}}` in architecture preview_html so previews show real content. + +### Content tokens in preview_html + +In addition to the standard design tokens (`{{bg}}`, `{{fg}}`, `{{ac}}`, etc.), architecture `preview_html` can use: + +- `{{prompt_headline}}` — the user's actual headline text +- `{{prompt_sub}}` — the user's actual subline text + +This makes previews contextual — the user sees their own content styled, not generic placeholders. + ## Serving and user selection 4. Serve the file: `cd && python3 -m http.server 8723 &` (use port 8723 or any unused port above 8000; if the curl check fails, try the next port). Verify: `curl -s -o /dev/null -w "%{http_code}" http://localhost:8723/.hyperframes/pick-design.html` — only share the link if it returns 200. Do NOT use `npx hyperframes preview` for the picker — it blocks. Only start the HTTP server from the main conversation thread. If you are running as a dispatched task or subagent, return the file path and let the caller serve it. diff --git a/skills/hyperframes/templates/design-picker.html b/skills/hyperframes/templates/design-picker.html index de457c774..cda01c1d2 100644 --- a/skills/hyperframes/templates/design-picker.html +++ b/skills/hyperframes/templates/design-picker.html @@ -17,19 +17,157 @@ height: 100vh; overflow: hidden; display: flex; + flex-direction: column; + } + + /* ── Phase navigation ── */ + .phase-bar { + display: flex; + border-bottom: 1px solid #222; + padding: 0 24px; + flex-shrink: 0; + } + .phase-tab { + padding: 14px 20px; + font-size: 13px; + font-weight: 600; + color: #555; + cursor: pointer; + border-bottom: 2px solid transparent; + transition: all 0.15s; + } + .phase-tab.active { + color: #fff; + border-bottom-color: #fff; + } + .phase-tab.disabled { + opacity: 0.3; + pointer-events: none; + } + + /* ── Phase containers ── */ + .phase { + display: none; + flex: 1; + overflow: hidden; + } + .phase.active { + display: flex; } + /* ── Phase 1: Mood boards ── */ + .mood-grid { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(400px, 1fr)); + gap: 20px; + padding: 28px; + overflow-y: auto; + flex: 1; + align-content: start; + } + .mood-card { + border: 2px solid #222; + border-radius: 16px; + overflow: hidden; + cursor: pointer; + transition: + border-color 0.15s, + transform 0.15s; + } + .mood-card:hover { + border-color: #444; + transform: translateY(-2px); + } + .mood-card.selected { + border-color: #fff; + } + .mood-preview { + height: 280px; + overflow: hidden; + position: relative; + } + .mood-preview > div { + transform-origin: top left; + } + .mood-info { + padding: 16px 20px; + border-top: 1px solid #222; + } + .mood-name { + font-size: 16px; + font-weight: 600; + margin-bottom: 4px; + } + .mood-desc { + font-size: 12px; + color: #888; + line-height: 1.4; + } + .mood-tokens { + display: flex; + gap: 6px; + margin-top: 10px; + } + .mood-token { + font-size: 10px; + color: #555; + background: #1a1a1a; + padding: 3px 8px; + border-radius: 4px; + } + + .mood-header { + padding: 28px 28px 0; + flex-shrink: 0; + } + .mood-header h2 { + font-size: 20px; + font-weight: 600; + margin-bottom: 4px; + } + .mood-header p { + font-size: 13px; + color: #666; + } + .mood-next { + padding: 16px 28px; + flex-shrink: 0; + display: flex; + justify-content: flex-end; + } + .mood-next-btn { + background: #fff; + color: #000; + border: none; + padding: 12px 28px; + border-radius: 10px; + font-size: 14px; + font-weight: 600; + cursor: pointer; + opacity: 0; + transform: translateY(10px); + transition: all 0.2s; + } + .mood-next-btn.visible { + opacity: 1; + transform: translateY(0); + } + .mood-next-btn:hover { + background: #ddd; + } + + /* ── Phase 2: Fine-tune ── */ .panel-left { width: 380px; min-width: 380px; - height: 100vh; + height: 100%; overflow-y: auto; border-right: 1px solid #222; padding: 28px 24px 120px; } .panel-right { flex: 1; - height: 100vh; + height: 100%; overflow-y: auto; overflow-x: hidden; } @@ -60,6 +198,7 @@ margin-bottom: 8px; cursor: pointer; transition: border-color 0.15s; + position: relative; } .option:hover { border-color: #444; @@ -84,6 +223,19 @@ text-transform: uppercase; letter-spacing: 0.05em; } + .opt-rec { + position: absolute; + top: 8px; + right: 12px; + font-size: 9px; + font-weight: 600; + color: #4ade80; + background: rgba(74, 222, 128, 0.1); + padding: 2px 8px; + border-radius: 4px; + text-transform: uppercase; + letter-spacing: 0.05em; + } .pal-swatches { display: flex; @@ -122,7 +274,6 @@ font-size: 14px; } - /* Chip options — small visual selectors in a row */ .chips { display: flex; gap: 8px; @@ -156,7 +307,6 @@ flex-shrink: 0; } - /* Theme toggle */ .theme-chip { flex: 1; min-width: 100px; @@ -172,15 +322,11 @@ margin-bottom: 6px; border: 1px solid rgba(255, 255, 255, 0.1); } - - /* Corner previews */ .corner-box { width: 28px; height: 28px; border: 2px solid #888; } - - /* Density previews */ .density-bars { display: flex; flex-direction: column; @@ -191,8 +337,6 @@ height: 4px; border-radius: 1px; } - - /* Depth previews */ .depth-square { width: 28px; height: 28px; @@ -227,7 +371,6 @@ background: #ddd; } - /* design.md output overlay */ .md-overlay { position: fixed; inset: 0; @@ -313,51 +456,75 @@ -
-
Visual direction
-
- Pick a structure, palette, and type. Preview updates live. -
+ +
+
1. Direction
+
2. Fine-tune
+
-
-
Theme
-
Light or dark canvas.
-
-
-
-
Structure
-
Shape, layout, spatial feel.
-
-
-
-
Color palette
-
Accent colors applied to your theme.
-
-
-
-
Typography
-
Headline + body pairing.
-
+ +
+
+

Pick a direction

+

+ Each option is a complete visual identity. Pick one, then fine-tune. +

-
-
Corners
-
Component border radius.
-
-
-
-
Density
-
Spacing between elements.
-
-
-
-
Depth
-
Shadows and layering.
-
+
+
+
-
-
Select a structure to begin
+ +
+
+
Fine-tune
+
+ Adjust any category. Preview updates live. +
+ +
+
Theme
+
Light or dark canvas.
+
+
+
+
Structure
+
Shape, layout, spatial feel.
+
+
+
+
Color palette
+
Accent colors applied to your theme.
+
+
+
+
Typography
+
Headline + body pairing.
+
+
+
+
Corners
+
Component border radius.
+
+
+
+
Density
+
Spacing between elements.
+
+
+
+
Depth
+
Shadows and layering.
+
+
+
+
+
Select a structure to begin
+
@@ -391,6 +558,9 @@ var ARCHITECTURES = __ARCHITECTURES_JSON__; var PALETTES = __PALETTES_JSON__; var TYPEPAIRS = __TYPEPAIRS_JSON__; + var MOODBOARDS = __MOODBOARDS_JSON__; + var PROMPT = __PROMPT_JSON__; + var picks = { theme: null, arch: null, @@ -441,6 +611,7 @@ { name: "Layered", desc: "Glows, vignettes, atmospheric depth" }, ]; + // Load fonts var fams = []; TYPEPAIRS.forEach(function (tp) { fams.push(tp.headline.family.replace(/ /g, "+") + ":wght@" + tp.headline.weight); @@ -466,12 +637,147 @@ return "rgba(" + r + "," + g + "," + b + "," + o + ")"; } - // Options + // Set prompt-aware UI text + if (PROMPT && PROMPT.title) { + document.getElementById("mood-title").textContent = "Pick a direction for: " + PROMPT.title; + } + if (PROMPT && PROMPT.section_desc) { + document.getElementById("arch-section-desc").textContent = PROMPT.section_desc; + } + + // ── Phase 1: Mood boards ── + var moodGrid = document.getElementById("mood-grid"); + var selectedMood = null; + + MOODBOARDS.forEach(function (mb, i) { + var card = document.createElement("div"); + card.className = "mood-card"; + + // Build a mini preview using the mood board's defaults + var tp = TYPEPAIRS[mb.type_index || 0]; + var pal = PALETTES[mb.palette_index || 0]; + var arch = ARCHITECTURES[mb.arch_index || 0]; + var thId = mb.theme || "dark"; + var th = + THEMES.find(function (t) { + return t.id === thId; + }) || THEMES[0]; + var bg = thId === "palette" ? pal.background : th.bg; + var fg = thId === "palette" ? pal.foreground : th.fg; + + var tokens = { + "{{bg}}": bg, + "{{fg}}": fg, + "{{ac}}": pal.accent, + "{{mt}}": pal.muted || pal.mid || al(fg, 0.4), + "{{hf}}": tp.headline.family, + "{{hw}}": tp.headline.weight, + "{{bf}}": tp.body.family, + "{{bw}}": tp.body.weight, + "{{cr}}": mb.corners || "4px", + "{{pad}}": mb.padding || "20px", + "{{gap}}": mb.gap || "16px", + "{{shadow}}": mb.shadow || "none", + "{{sf}}": al(fg, 0.06), + "{{g}}": al(fg, 0.06), + "{{fg3}}": al(fg, 0.03), + "{{fg6}}": al(fg, 0.06), + "{{fg8}}": al(fg, 0.08), + "{{fg15}}": al(fg, 0.15), + "{{ac3}}": al(pal.accent, 0.03), + "{{ac5}}": al(pal.accent, 0.05), + "{{ac25}}": al(pal.accent, 0.25), + "{{prompt_headline}}": (PROMPT && PROMPT.headline) || "Your Headline Here", + "{{prompt_sub}}": + (PROMPT && PROMPT.subline) || "A subline that introduces your product or idea.", + }; + + var preview = arch.preview_html || ""; + Object.keys(tokens).forEach(function (k) { + preview = preview.split(k).join(tokens[k]); + }); + + var tokenTags = [tp.headline.family, pal.name, CORNERS[mb.corners_index || 1].name] + .map(function (t) { + return '' + t + ""; + }) + .join(""); + + card.innerHTML = + '
' + + preview + + "
" + + '
' + + mb.name + + '
' + + mb.description + + '
' + + tokenTags + + "
"; + + card.onclick = function () { + moodGrid.querySelectorAll(".mood-card").forEach(function (c) { + c.classList.remove("selected"); + }); + card.classList.add("selected"); + selectedMood = i; + document.getElementById("mood-next-btn").classList.add("visible"); + }; + moodGrid.appendChild(card); + }); + + // ── Phase switching ── + function showPhase(name) { + document.querySelectorAll(".phase").forEach(function (p) { + p.classList.remove("active"); + }); + document.querySelectorAll(".phase-tab").forEach(function (t) { + t.classList.remove("active"); + }); + document.getElementById("phase-" + name).classList.add("active"); + document.getElementById("tab-" + name).classList.add("active"); + } + + function goToTune() { + if (selectedMood === null) return; + var mb = MOODBOARDS[selectedMood]; + + // Pre-fill picks from mood board + var thIdx = THEMES.findIndex(function (t) { + return t.id === (mb.theme || "dark"); + }); + if (thIdx >= 0) chipSel("theme", thIdx, document.getElementById("theme-options")); + if (mb.arch_index != null) + sel("arch", mb.arch_index, document.getElementById("arch-options")); + if (mb.palette_index != null) + sel("palette", mb.palette_index, document.getElementById("pal-options")); + if (mb.type_index != null) + sel("type", mb.type_index, document.getElementById("type-options")); + if (mb.corners_index != null) + chipSel("corners", mb.corners_index, document.getElementById("corner-options")); + if (mb.density_index != null) + chipSel("density", mb.density_index, document.getElementById("density-options")); + if (mb.depth_index != null) + chipSel("depth", mb.depth_index, document.getElementById("depth-options")); + + // Enable and switch to phase 2 + document.getElementById("tab-tune").classList.remove("disabled"); + showPhase("tune"); + } + + // ── Phase 2: Build options (same as before but with recommended badges) ── var archOpts = document.getElementById("arch-options"); ARCHITECTURES.forEach(function (a, i) { var el = document.createElement("div"); el.className = "option"; + var rec = + MOODBOARDS.length > 0 && + selectedMood !== null && + MOODBOARDS[selectedMood].arch_index === i + ? '
recommended
' + : ""; el.innerHTML = + rec + '
' + a.name + '
' + @@ -537,7 +843,7 @@ typeOpts.appendChild(el); }); - // Theme chips + // Theme/Corner/Density/Depth chips var themeOpts = document.getElementById("theme-options"); THEMES.forEach(function (th, i) { var el = document.createElement("div"); @@ -555,8 +861,6 @@ }; themeOpts.appendChild(el); }); - - // Corner chips var cornerOpts = document.getElementById("corner-options"); CORNERS.forEach(function (c, i) { var el = document.createElement("div"); @@ -574,8 +878,6 @@ }; cornerOpts.appendChild(el); }); - - // Density chips var densityOpts = document.getElementById("density-options"); DENSITIES.forEach(function (d, i) { var gaps = [3, 5, 8][i]; @@ -594,8 +896,6 @@ }; densityOpts.appendChild(el); }); - - // Depth chips var depthOpts = document.getElementById("depth-options"); DEPTHS.forEach(function (d, i) { var shadow = [ @@ -654,10 +954,6 @@ function renderPreview() { var pv = document.getElementById("preview"); - if (picks.arch === null && picks.theme === null) { - pv.innerHTML = '
Start by picking a theme and structure
'; - return; - } if (picks.arch === null) { pv.innerHTML = '
Pick a structure to see the preview
'; return; @@ -675,9 +971,8 @@ body: { family: "system-ui", weight: 400 }, }; var cr = picks.corners !== null ? CORNERS[picks.corners].value : "0px"; - var dn = picks.density !== null ? picks.density : 1; // 0=tight, 1=normal, 2=generous - var dp = picks.depth !== null ? picks.depth : 0; // 0=flat, 1=subtle, 2=layered - // "Full palette" mode uses palette bg/fg; light/dark use theme bg/fg + var dn = picks.density !== null ? picks.density : 1; + var dp = picks.depth !== null ? picks.depth : 0; var bg, fg; if (th.id === "palette" && p.background) { bg = p.background; @@ -687,14 +982,9 @@ fg = th.fg; } var ac = p.accent, - mt = p.muted || al(fg, 0.4), - sf = al(fg, 0.06); - // Density: padding and gap multipliers + mt = p.muted || al(fg, 0.4); var pad = [12, 20, 36][dn] + "px"; - var padN = [12, 20, 36][dn]; - var gapN = [8, 16, 28][dn]; - var gap = gapN + "px"; - // Depth: shadow — use accent glow on dark, dark drop on light + var gap = [8, 16, 28][dn] + "px"; var isDark = bg && bg[0] === "#" ? parseInt(bg.slice(1, 3), 16) < 80 : true; var shCol = isDark ? ac : fg; var shadow = [ @@ -702,60 +992,16 @@ "0 2px 16px " + al(shCol, isDark ? 0.15 : 0.1), "0 4px 32px " + al(shCol, isDark ? 0.3 : 0.18), ][dp]; - var hf = t.headline.family, - hw = t.headline.weight, - bf = t.body.family, - bw = t.body.weight; - var H = function (s) { - return ( - "font-family:'" + - hf + - "',sans-serif;font-weight:" + - hw + - ";font-size:" + - s + - "px;color:" + - fg + - ";" - ); - }; - var B = function (s) { - return ( - "font-family:'" + - bf + - "',monospace;font-weight:" + - bw + - ";font-size:" + - s + - "px;color:" + - mt + - ";" - ); - }; - var Bf = function (s) { - return ( - "font-family:'" + - bf + - "',monospace;font-weight:" + - bw + - ";font-size:" + - s + - "px;color:" + - fg + - ";" - ); - }; - // Token replacement — architecture provides preview_html with {{placeholders}} var tokens = { "{{bg}}": bg, "{{fg}}": fg, "{{ac}}": ac, "{{mt}}": mt, - "{{sf}}": sf, - "{{hf}}": hf, - "{{hw}}": hw, - "{{bf}}": bf, - "{{bw}}": bw, + "{{sf}}": al(fg, 0.06), + "{{hf}}": t.headline.family, + "{{hw}}": t.headline.weight, + "{{bf}}": t.body.family, + "{{bw}}": t.body.weight, "{{cr}}": cr, "{{pad}}": pad, "{{gap}}": gap, @@ -768,6 +1014,9 @@ "{{ac3}}": al(ac, 0.03), "{{ac5}}": al(ac, 0.05), "{{ac25}}": al(ac, 0.25), + "{{prompt_headline}}": (PROMPT && PROMPT.headline) || "Your Headline Here", + "{{prompt_sub}}": + (PROMPT && PROMPT.subline) || "A subline that introduces your product or idea.", }; var h = a.preview_html || @@ -775,14 +1024,14 @@ bg + ";padding:40px;min-height:100%;display:flex;align-items:center;justify-content:center;color:" + mt + - ';font-size:14px;">No preview available for this architecture
'; + ';font-size:14px;">No preview
'; Object.keys(tokens).forEach(function (k) { h = h.split(k).join(tokens[k]); }); pv.innerHTML = h; } - // Output — google-labs-code/design.md spec: YAML frontmatter + prose sections + // Output function showOutput() { if ( picks.theme === null || @@ -807,16 +1056,9 @@ var mt = p.muted || p.mid || "#888888"; var padVal = { Tight: "8px", Normal: "16px", Generous: "32px" }[dn.name] || "16px"; var gapVal = { Tight: "8px", Normal: "16px", Generous: "28px" }[dn.name] || "16px"; - var shadowDesc = - { - Flat: "none", - Subtle: "0 2px 8px rgba(0,0,0,0.1)", - Layered: "0 4px 24px rgba(0,0,0,0.15)", - }[dp.name] || "none"; - - // YAML frontmatter + var md = "---\n"; - md += "name: Untitled\n"; + md += "name: " + ((PROMPT && PROMPT.title) || "Untitled") + "\n"; md += "colors:\n"; md += ' primary: "' + bg + '"\n'; md += ' on-primary: "' + fg + '"\n'; @@ -840,16 +1082,13 @@ md += " lg: " + gapVal + "\n"; md += "---\n\n"; - // Prose sections md += "## Overview\n\n"; md += a.mood + ". " + a.description + ". " + p.description + ".\n\n"; - md += "## Colors\n\n"; md += "- **Primary** (`" + bg + "`) — Canvas background\n"; md += "- **On-Primary** (`" + fg + "`) — Text and content\n"; md += "- **Accent** (`" + ac + "`) — CTAs, highlights, interactive elements\n"; md += "- **Muted** (`" + mt + "`) — Secondary text, captions\n\n"; - md += "## Typography\n\n"; md += "- **Headline** — " + @@ -863,17 +1102,13 @@ " at weight " + t.body.weight + ". Running text and UI labels.\n\n"; - md += "## Layout\n\n"; md += "- Structure: " + a.name + " — " + a.tag + "\n"; md += "- Density: " + dn.name + " (" + dn.desc + ")\n"; md += "- Corners: " + cr.name + " (" + cr.value + ")\n\n"; - md += "## Elevation\n\n"; md += dp.name + " — " + dp.desc + ".\n\n"; - if (a.components) md += "## Components\n\n" + a.components + "\n\n"; - md += "## Do's and Don'ts\n\n"; if (a.dos) { md += a.dos + "\n"; @@ -885,7 +1120,6 @@ md += "### Don'ts\n- Do not mix multiple accent colors\n- Do not use font weights outside the specified headline/body pair\n"; } - document.getElementById("md-output").value = md; document.getElementById("md-overlay").classList.add("visible"); } From f7d289cdae2228fc79874181bb51e354a8ab7495 Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Wed, 29 Apr 2026 15:32:06 -0700 Subject: [PATCH 15/37] fix(skills): dynamic mood board count, fix url() quote bug in picker MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mood board count is now contextual — as many as the creative space warrants, not a fixed number. Documented the url() quoting bug: single quotes inside preview_html break style attributes. Use url(path) without quotes. Co-Authored-By: Claude Opus 4.6 (1M context) --- skills/hyperframes/references/design-picker.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/skills/hyperframes/references/design-picker.md b/skills/hyperframes/references/design-picker.md index 2684f8ce6..13a435600 100644 --- a/skills/hyperframes/references/design-picker.md +++ b/skills/hyperframes/references/design-picker.md @@ -13,8 +13,8 @@ Before generating options, read these style references — all options must comp ## Building the picker 1. Generate options **contextual to the user's prompt**. Each category should reflect the content: - - **3-4 mood boards** — complete visual directions combining architecture + palette + typography + density + depth. Each is a holistic identity the user can pick in one click. Name them evocatively ("Terminal Precision", "Editorial Warmth", "Bold Statement"). One safe/expected, one editorial, one ambitious. - - **3-4 architectures** — structural layouts that make sense for THIS content. Use `{{prompt_headline}}` and `{{prompt_sub}}` tokens in preview_html so previews show the user's actual content, not placeholder text. + - **Mood boards** — as many as the creative space warrants. A narrow prompt with specific assets might need 4-5 genuinely different directions. A wide-open prompt might need 8+. Every board must feel visually distinct — if two look similar, cut one. Each is a holistic identity: architecture + palette + type + density + depth in one click. Name them evocatively. Include at least one safe/expected, one editorial, and one ambitious option. + - **Architectures** — one per mood board minimum. Each must use different layout structure. If the user provided media assets, use them as background images in `preview_html` (use `url(path)` without quotes — single quotes inside `style='...'` break the attribute). Use `{{prompt_headline}}` and `{{prompt_sub}}` tokens so previews show real content. - **5-6 palettes** — always include a mix of dark, light, and tinted backgrounds. Name them after personality. - **3 type pairings** — serif+mono, grotesque+mono, display+sans. Cross-category pairings per typography.md. 2. `mkdir -p .hyperframes` then copy [../templates/design-picker.html](../templates/design-picker.html) to `.hyperframes/pick-design.html`. @@ -39,6 +39,8 @@ Optionally include `components` (component styling rules) and `dos` (do's and do **Security:** Architecture `preview_html` must not contain ` @@ -597,6 +645,7 @@

Pick a direction

Each option is a complete visual identity. Pick one, then fine-tune.

+
Palette