docs(skills): prefer frame.md over design.md for video specs (#1180)

* docs(skills): prefer frame.md over design.md for video specs

Skills now look for a design spec in precedence order frame.md →
design.md → DESIGN.md when reading. frame.md is the preferred spec for
video/hyperframes projects (same format as design.md) and wins if more
than one exists.

Read-path mentions updated across SKILL.md, house-style.md,
prompt-expansion.md, video-composition.md, and dynamic-techniques.md.
Creation flows (design picker, visual-styles) still output design.md;
website-to-video skill untouched.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(skills): resolve frame.md/design.md consistency gaps from review

Address partial-migration contradictions flagged in review:
- video-composition.md: abstract the section header and intro line
  (line 3, "## The Design Spec Is Brand, Not Layout") so a reader does
  not hit design.md-only language before the abstracted body
- SKILL.md references index: "the design spec as brand not layout"
  (line 472), "generating a design spec" (line 480), and the Step 1
  conceptual aside (line 37)
- Note frame.md is always lowercase (no FRAME.md fallback) in the
  precedence note; switch prompt-expansion prerequisite to the same
  frame.md -> design.md -> DESIGN.md arrow notation

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

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.
+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 design.md's type spec. No substitutions.
+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.
+- **[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 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 a design spec.
-- **[house-style.md](house-style.md)** — Default motion, sizing, and color palettes when no design.md is specified.
+- **[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.)

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
 

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.
 

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
 

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.