diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md index 2ec610cb4..61951dd2e 100644 --- a/skills/hyperframes/SKILL.md +++ b/skills/hyperframes/SKILL.md @@ -24,21 +24,21 @@ For exploratory requests, consider offering 2-3 variations that differ meaningfu ### Step 1: Design system -If `design.md` or `DESIGN.md` exists in the project, read it first (check both casings — they're different files on Linux). 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). +If a design spec exists in the project, read it first. Look in precedence order: `frame.md` → `design.md` → `DESIGN.md` (`design.md` and `DESIGN.md` are different files on Linux — check both casings; `frame.md` is always lowercase, no `FRAME.md` variant). `frame.md` is the preferred spec for video/hyperframes projects and wins if more than one exists; it uses the same format as `design.md`. 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). -If it names fonts you can't find locally (no `fonts/` directory with `.woff2` files, not a built-in font), warn the user before writing HTML: "design.md specifies [font name] but no font files found. Please add .woff2 files to `fonts/` or I'll fall back to [closest built-in alternative]." +If it names fonts you can't find locally (no `fonts/` directory with `.woff2` files, not a built-in font), warn the user before writing HTML: "the spec specifies [font name] but no font files found. Please add .woff2 files to `fonts/` or I'll fall back to [closest built-in alternative]." -If no `design.md` exists, offer the user a choice: +If no `frame.md` or `design.md` exists, offer the user a choice: 1. **User named a style or mood?** → Read [visual-styles.md](./visual-styles.md) for the 8 named presets. Pick the closest match. 2. **Want to browse options visually?** → Run the design picker: read [references/design-picker.md](references/design-picker.md) for the full workflow. This serves a visual picker page. The user configures mood, palette, typography, and motion in the browser, then copies the generated design.md and pastes it back into the conversation. 3. **Want to skip and go fast?** → Ask: mood, light or dark, any brand colors/fonts? Then pick a palette from [house-style.md](./house-style.md). -**design.md defines the brand. It does not define video composition rules.** Those come from [references/video-composition.md](references/video-composition.md) and [house-style.md](./house-style.md). Use brand colors at video-appropriate scale — not at web-UI opacity. +**The design spec defines the brand. It does not define video composition rules.** Those come from [references/video-composition.md](references/video-composition.md) and [house-style.md](./house-style.md). Use brand colors at video-appropriate scale — not at web-UI opacity. ### Step 2: Prompt expansion -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 reads the same way. +Always run on every composition (except single-scene pieces and trivial edits). This step grounds the user's intent against the design spec (`frame.md` or `design.md`) and `house-style.md` and produces a consistent intermediate that every downstream agent reads the same way. Read [references/prompt-expansion.md](references/prompt-expansion.md) for the full process and output format. @@ -356,12 +356,12 @@ 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 -If no `design.md` exists, follow [house-style.md](./house-style.md) for aesthetic defaults. +If no `frame.md` or `design.md` exists, follow [house-style.md](./house-style.md) for aesthetic defaults. ## Typography and Assets - **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. +- **Custom fonts:** If the spec (`frame.md` or `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 `../` @@ -378,7 +378,7 @@ If no `design.md` exists, follow [house-style.md](./house-style.md) for aestheti **Fast (run immediately, block on results):** - [ ] `npx hyperframes lint` and `npx hyperframes validate` both pass -- [ ] Design adherence verified if design.md exists +- [ ] Design adherence verified if a design spec (`frame.md` or `design.md`) exists **Slow (run in parallel while presenting the preview to the user):** @@ -423,18 +423,18 @@ 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: +If a design spec (`frame.md` or `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 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. +1. **Colors** — every hex value in the composition appears in the spec's palette section (however the user labeled it: Colors, Palette, Theme, etc.). Flag any invented colors. +2. **Typography** — font families and weights match the spec'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. +6. **Avoidance rules** — if the spec 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: +If no design spec 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. @@ -469,16 +469,16 @@ Skip on small edits (fixing a color, adjusting one duration). Run on new composi - **[references/captions.md](references/captions.md)** — Captions, subtitles, lyrics, karaoke synced to audio. Tone-adaptive style detection, per-word styling, text overflow prevention, caption exit guarantees, word grouping. Read when adding any text synced to audio timing. - **[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/video-composition.md](references/video-composition.md)** — Video-medium rules: density, color presence, scale, frame composition, the design spec 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, image motion treatment, load-bearing GSAP rules. **Always read** — every composition has motion. - **[references/techniques.md](references/techniques.md)** — 13 primitive animation techniques with code patterns: SVG drawing, Canvas 2D, CSS 3D, kinetic type, Lottie, video compositing, typing, variable fonts, MotionPath, velocity transitions, audio-reactive, clip-path reveals, WebGL shaders. Adapt the patterns — don't copy-paste. (For pre-built UI templates — terminal chrome, device mockups, moodboard layouts — see `registry/blocks/`.) - **[references/html-in-canvas-patterns.md](references/html-in-canvas-patterns.md)** — HTML-in-Canvas patterns: live DOM as GPU texture via `drawElementImage` + `layoutsubtree`. Shared boilerplate + ~6 effect recipes (iPhone/MacBook mockups, liquid glass, magnetic, portal, shatter, text cursor). Use for 1–3 hero beats per video. - **[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 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. +- **[references/design-picker.md](references/design-picker.md)** — Create a design.md via visual picker. Read when no `frame.md` or `design.md` exists and the user wants to create one. +- **[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 a design spec. +- **[house-style.md](house-style.md)** — Default motion, sizing, and color palettes when no `frame.md` or `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)** — Caption-side transcript handling: input formats, mandatory quality check, cleaning JS, OpenAI/Groq API fallback, "if no transcript exists" flow. (For the `transcribe` CLI invocation, model selection rules, and the `.en` gotcha, see the `hyperframes-media` skill.) diff --git a/skills/hyperframes/house-style.md b/skills/hyperframes/house-style.md index 892c2ebed..5a59bcc41 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 `design.md` is provided. These are starting points — override anything that doesn't serve the content. When a `design.md` exists, its brand values take precedence; house-style fills gaps. +Creative direction for compositions when no design spec (`frame.md` or `design.md`) is provided. These are starting points — override anything that doesn't serve the content. When a spec exists, its brand values take precedence; house-style fills gaps. ## Before Writing HTML @@ -44,7 +44,7 @@ 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. +**Decorative count vs motion count.** The "2-5 per scene" count refers to decorative _elements_. If a project's spec (`frame.md` or `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 diff --git a/skills/hyperframes/references/dynamic-techniques.md b/skills/hyperframes/references/dynamic-techniques.md index af271e39a..d67c95f61 100644 --- a/skills/hyperframes/references/dynamic-techniques.md +++ b/skills/hyperframes/references/dynamic-techniques.md @@ -4,7 +4,7 @@ You are here because SKILL.md told you to read this file before writing animatio ## Technique Selection by Energy -Captions are a constrained surface — the highlight and exit technique is closely tied to how much intensity the spoken content carries. The table below is a calibration reference. If DESIGN.md or the storyboard specifies a caption style, that overrides anything here. +Captions are a constrained surface — the highlight and exit technique is closely tied to how much intensity the spoken content carries. The table below is a calibration reference. If the design spec (`frame.md` or `design.md`) or the storyboard specifies a caption style, that overrides anything here. The core principle: **all energy levels use karaoke highlight as the baseline.** The difference is intensity — not the technique type. diff --git a/skills/hyperframes/references/prompt-expansion.md b/skills/hyperframes/references/prompt-expansion.md index e08075e52..6dc76d895 100644 --- a/skills/hyperframes/references/prompt-expansion.md +++ b/skills/hyperframes/references/prompt-expansion.md @@ -1,19 +1,19 @@ # Prompt Expansion -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. +Run on every composition. Expansion is not about lengthening a short prompt — it's about grounding the user's intent against the design spec (`frame.md` or `design.md`) and `house-style.md` and producing a consistent intermediate that every downstream agent reads the same way. -Runs AFTER design direction is established (Step 1). The expansion consumes design.md (if present) and produces output that cites its exact values. +Runs AFTER design direction is established (Step 1). The expansion consumes the design spec (`frame.md` or `design.md`, if present) and produces output that cites its exact values. ## Prerequisites 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. +- the design spec — `frame.md` → `design.md` → `DESIGN.md` (prefer `frame.md` if more than one exists) — extract brand colors, fonts, mood, and constraints. The expansion cites these exact values (hex codes, font names); it does not invent new ones. - [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 1 (Design system) first. Expansion without a design context produces generic scene breakdowns that later agents ignore. +If no design spec exists yet, run Step 1 (Design system) first. Expansion without a design context produces generic scene breakdowns that later agents ignore. ## Why always run it @@ -26,7 +26,7 @@ Even a detailed 7-scene brief lacks things only the expansion adds: - **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. +- **Exact hex values, typography parameters, ease choices** from the spec — no vagueness left for the scene subagent to guess. 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. @@ -38,7 +38,7 @@ 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. +1. **Title + style block** — cite the spec's exact hex values, font names, and mood. Do NOT invent a palette — quote what the design provides. 2. **Rhythm declaration** — name the scene rhythm before detailing any scene. Example: `hook-PUNCH-breathe-CTA` or `slow-build-BUILD-PEAK-breathe-CTA`. Derive the rhythm from the brand and the storyboard's emotional arc — see [beat-direction.md](beat-direction.md) for the considerations that drive this decision. @@ -53,7 +53,7 @@ Expand into a full production prompt with these sections: 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. +6. **Negative prompt** — what to avoid, informed by the spec's constraints if present. ## Output diff --git a/skills/hyperframes/references/video-composition.md b/skills/hyperframes/references/video-composition.md index e0758eba0..1c7621e9e 100644 --- a/skills/hyperframes/references/video-composition.md +++ b/skills/hyperframes/references/video-composition.md @@ -1,12 +1,12 @@ # Video Composition -Video frames are not web pages. These rules apply to every composition regardless of brand, style, or design.md. +Video frames are not web pages. These rules apply to every composition regardless of brand, style, or design spec. -## design.md Is Brand, Not Layout +## The Design Spec Is Brand, Not Layout -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. +The design spec (`frame.md` or `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 (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. +**Strict from the spec:** 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:** 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.