takomi 2.5.1 → 2.5.4

package/assets/.agent/skills/website-to-video/references/step-1-design.md

@@ -1,333 +1,333 @@
-# Step 1: Write DESIGN.md (the brand-truth cheat sheet)
-
-DESIGN.md is a **brand-truth cheat sheet** — colors and fonts you'll **weave into your composed builds**. It is NOT a layout spec, not a moodboard, not a 400-line design system audit.
-
-DESIGN.md is the brand inflection sub-agents apply when building each beat: which color is "primary," which font is for headlines, what tone the brand carries — the load-bearing knobs they flip while building.
-
-**Target length: 250–350 lines.** Step 5 sub-agents read DESIGN.md to brand each beat — the more precise the component CSS values you encode here, the more brand-faithful the result. Going under 200 lines tends to produce generic dark-cinematic output because sub-agents have no brand component DNA to work from; going over 350 means you're over-investing in prose.
-
-**Fast-pacing exception:** For billboard-per-beat videos (short social ads where each beat is a single hero element on full-bleed background), a 50-line DESIGN.md with just colors + fonts + 3-5 do's/don'ts is enough. The Step 5 sub-agent prompt pastes brand values inline, so DESIGN.md depth only matters when the beats render full UIs.
-
-**User preferences always override brand rules.** If the user says "make it bright even though the site is dark" or "use serif fonts even though the brand is sans" — follow the user. DESIGN.md describes the captured website. The video might deliberately break that.
-
-**Read these now** — they're the inputs DESIGN.md is built from. Don't guess colors or sizes from screenshots:
-
-- `capture/extracted/tokens.json` — top brand colors (HEX) and font families with weight ranges.
-- `capture/extracted/design-styles.json` — computed CSS values from the live DOM: typography hierarchy (font-size, weight, line-height, letter-spacing per text role), button variants (background, padding, radius, shadow), card/container/nav styles, spacing scale, border-radius scale, box-shadow values with usage counts. **Primary data source for Sections 3–6 below.**
-
-**Font availability check — do this before writing anything else.** Read `capture/extracted/fonts-manifest.json`. The capture pipeline reads the OpenType `name` table embedded in every downloaded font file, so even hash-renamed Next.js/Webpack fonts are identified by their real family name (Inter, JetBrains Mono, Geist Mono, etc.). No guessing required.
-
-The manifest gives you two views:
-
-- `families[]` — one entry per distinct family with the weights captured, whether it's a variable font, and the files belonging to it
-- `files[]` — one entry per downloaded font with family, subfamily, weight, style, and any variation axes
-
-**How to use it:**
-
-- For each family you'll reference in DESIGN.md, name it by what's in `families[].family` (e.g. "Inter", not "f266e704 hashed font"). The hashed filenames are the `@font-face src` paths — they stay as-is on disk; only the display name comes from the manifest.
-- If a family has `variable: true` and `variationAxes` includes `"wght"`, you can use any weight 100-900 via `font-variation-settings: 'wght' <value>` even if only one static weight appears in the captured files. Note this in DESIGN.md so sub-agents know they have the full weight range available.
-- If the manifest's `unidentified[]` is non-empty, those files failed name-table extraction (rare — heavily subset fonts that strip metadata). Flag them as `unknown` in DESIGN.md and suggest a fallback rather than guessing.
-- Commercial fonts hosted on brand CDNs (GT Walsheim, Söhne, Graphik, Canela) won't be in the manifest because they aren't downloaded. Detect this by checking what the site uses (from `design-styles.json`) against what's in the manifest — anything used but missing is a CDN-hosted font. Flag explicitly: "Söhne not in capture; use Inter 600 as substitute."
-
-Sub-agents try to use the fonts you list. The manifest tells you exactly what's available — there's no excuse for claiming "Charlie Display 700" when no such file exists.
-
----
-
-## The 5 sections to write
-
-### `## 1. Visual Theme (one paragraph)`
-
-3–5 sentences describing the brand's visual personality. Cover: dark-first or light-first, contrast strategy, dominant visual elements (gradients, illustrations, photography, UI mockups), overall mood, what makes it distinctive vs. generic.
-
-This is the only prose section. Make it specific to _this_ brand — not template-filling. A sentence that could describe any well-designed website is not useful.
-
-**Example:**
-
-> Stripe's visual language is light-first and clean, with deep navy (`#061B31`) and pure white as the foundation. The accent stack — Stripe Purple (`#533AFD`) for CTAs, Vibrant Orange (`#FF6118`) for energetic emphasis — keeps interactive elements unmistakable. Type is sohne-var Light (300) for display, weight 400 for body; the brand achieves hierarchy through size and weight, never color shifts. The mood is confident financial-tech — premium without theatrical drama. Distinctive: gradient overlays at 135° between purple and orange appear as subtle washes over white backgrounds, never as bold focal elements.
-
----
-
-### `## 2. Quick Reference`
-
-A flat lookup of the values sub-agents grab while composing beats. Two sub-sections — keep them tight.
-
-#### Colors
-
-List 8–12 colors with brand-specific names + HEX + role. Not generic ("Accent 1") but evocative ("Stripe Purple", "Deep Navy", "Slate Border"). The name carries meaning; "blue 4" doesn't.
-
-**For each text-on-surface combination the brand uses, compute the WCAG AA contrast ratio and flag failing pairings explicitly.** A real failure mode from prior runs: the brand's secondary-text color (`#68686A`) on its dark panel color (`#18191B`) = 3.16:1, which fails AA's 4.5:1 minimum. Sub-agents faithfully reproduced the brand's color choice and the result was unreadable. Encode the safe / unsafe pairings here so sub-agents pick text colors by surface context, not by "this is the brand's secondary text color." The `/hyperframes-contrast` skill audits ratios — run it before finalizing DESIGN.md.
-
-**Example:**
-
-```markdown
-#### Colors
-
-- **Stripe Purple** (`#533AFD`): Primary CTA, interactive elements, focus rings — the brand's action signal
-  - On Pure White: 6.2:1 ✅ — On Deep Navy: 3.8:1 ⚠ AA-only-Large
-- **Deep Navy** (`#061B31`): Primary text on light surfaces, also a dark surface tier
-  - As text on Pure White: 17.4:1 ✅ — As surface: see Slate-on-Navy pairings below
-- **Pure White** (`#FFFFFF`): Page background, card surfaces
-- **Light Gray** (`#F5F7FA`): Surface tier 2 (cards on white pages, alternating sections)
-- **Slate Blue** (`#273951`): Secondary text on LIGHT surfaces
-  - On Pure White: 12.6:1 ✅ — On Light Gray: 11.8:1 ✅ — On Deep Navy: 1.4:1 ❌ DO NOT USE
-- **Light Slate** (`#64748D`): Metadata, captions on light surfaces only
-  - On Pure White: 4.8:1 ✅ — On Light Gray: 4.5:1 ✅ — On Deep Navy: 3.0:1 ❌ — On Dark Panel: 2.9:1 ❌
-  - **For dark-surface metadata, use `#9A9A9E` instead: 6.4:1 on Deep Navy ✅, 6.1:1 on Dark Panel ✅**
-- **Subtle Border** (`#D4DEE9`): Card borders, dividers (not text — borders don't need AA)
-- **Vibrant Orange** (`#FF6118`): Energy accent — gradient endpoints, highlight bursts (never primary text)
-- **Error Red** (`#FF0022`): Validation errors. On Pure White: 4.5:1 ✅
-- **Success Green** (`#4CD963`): Confirmation states. On Pure White: 1.7:1 ❌ — must be paired with a darker outline or use as accent on dark surfaces
-```
-
-**Where the brand's own palette fails WCAG**, document the substitute (like the `#9A9A9E` override above). Sub-agents pick the safe color by surface — and if the deviation matters to the brand identity, the user can revisit at Step 6.
-
-#### Fonts
-
-List font families with their role AND **the exact file path per family + weight** from `fonts-manifest.json`. Sub-agents will copy the `@font-face` block verbatim — if you only name the family without the path, sub-agents have to guess which `.woff2` file belongs to which family and get it wrong half the time (a real failure mode from prior runs: agents pointed `@font-face` for "ES Build Neutral" at the Inter `.woff2` files and the wordmark rendered in Inter).
-
-**Example:**
-
-````markdown
-#### Fonts
-
-- **Display:** `"ES Build Neutral"` — wordmarks, headlines
-  - 600: `capture/assets/fonts/14d7ce3e41dcbb66-s.p.woff2`
-  - 700: `capture/assets/fonts/e8b276476c0ac6fa-s.p.woff2`
-- **Body:** `"Inter"` (variable 100–900, captured ✓) — body, labels, UI
-  - 400: `capture/assets/fonts/9a8d3f06c4e89f2b-s.p.woff2`
-  - 600: `capture/assets/fonts/1b0b3615811be75b-s.p.woff2`
-- **Mono:** `"JetBrains Mono"` — code, metadata
-  - 400: `capture/assets/fonts/c7d2e9f5a1b3c8d4-s.p.woff2`
-- **Fallback stack:** `-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif`
-
-**`@font-face` block to paste in every composition** (sub-agents copy this verbatim — do not invent file paths):
-
-```css
-@font-face {
-  font-family: "ES Build Neutral";
-  src: url("capture/assets/fonts/14d7ce3e41dcbb66-s.p.woff2") format("woff2");
-  font-weight: 600;
-  font-display: block;
-}
-@font-face {
-  font-family: "Inter";
-  src: url("capture/assets/fonts/9a8d3f06c4e89f2b-s.p.woff2") format("woff2");
-  font-weight: 400;
-  font-display: block;
-}
-/* + any other family/weight combinations the storyboard's beats need */
-```
-````
-
-The brand uses **size for hierarchy, weight for emphasis**. Display 1: 48px/600, Display 2: 32px/600, Body: 14px/400. (Adjust to the actual brand's hierarchy.)
-
-````
-
-The exact `@font-face` block lets sub-agents copy verbatim instead of constructing one from inference. If a beat needs a weight that isn't in the manifest, flag it explicitly here: e.g., "ES Build Neutral 900 NOT in capture; use ES Build Neutral 700 as substitute, or fall back to Inter 700."
-
-That's the whole typography section. If sub-agents need exact line-heights or letter-spacing, they read `design-styles.json` directly.
-
----
-
-### `## 3. Component Stylings` (the build-step's spec sheet)
-
-This is the section sub-agents consult most when building beats in Step 5. **Without exact per-component CSS, sub-agents fall back to generic "dark bg + glow + centered text" patterns regardless of brand** — which is why every video starts looking the same. Encode the brand's actual component DNA here.
-
-Target **6-12 distinct components**. Document what the site actually uses; skip categories the brand doesn't have. For each component, name it descriptively ("Stripe Primary Button" not "Button 1") and provide exact CSS-level properties: background, text color, padding, border-radius, border, font size/weight, height, box-shadow, and any hover/active/disabled states.
-
-#### Buttons (always required)
-
-Cover every variant the site uses — typically Primary, Secondary/Ghost, and Icon. **Example:**
-
-```markdown
-#### Primary Button (Stripe Purple)
-
-- **Background:** `#533AFD`
-- **Text color:** `#FFFFFF`
-- **Font:** sohne-var 16px / 400
-- **Padding:** `15.5px 24px 16.5px 24px`
-- **Border radius:** `4px`
-- **Border:** none
-- **Height:** `48px` (with padding)
-- **Box shadow:** none
-- **Hover:** background `#4329E8`, opacity `0.95`
-- **Active:** background `#3720D4`, scale `0.98`
-- **Disabled:** background `#C9C3F0`, cursor `not-allowed`
-
-#### Secondary Button (outline)
-
-- **Background:** `#FFFFFF`
-- **Text color:** `#533AFD`
-- **Border:** `1px solid #533AFD`
-- **Padding / radius / font:** same as Primary
-- **Hover:** background `#F3F0FF`, border `#4329E8`
-
-#### Ghost Button (text-only link)
-
-- **Background:** transparent
-- **Text color:** `#533AFD`
-- **Font:** sohne-var 14px / 400
-- **Padding:** `12px 0`
-- **Hover:** background `rgba(83, 58, 253, 0.08)`, optional underline
-````
-
-#### Cards & Containers (always required if the site uses any)
-
-Document each distinct card type — Standard, Feature Highlight, Glass, Pricing, Testimonial — whatever this brand actually uses. **Example:**
-
-```markdown
-#### Standard Card
-
-- **Background:** `#FFFFFF`
-- **Border:** `1px solid #D4DEE9`
-- **Border radius:** `5px`
-- **Padding:** `32px`
-- **Box shadow:** `0 1px 2px rgba(0, 0, 0, 0.04)` (default), `0 4px 12px rgba(0, 0, 0, 0.08)` (hover)
-- **Hover:** border `#B8CCDB`
-
-#### Feature Highlight Card (gradient backdrop)
-
-- **Background:** linear-gradient(180deg, rgba(83, 58, 253, 0.05) 0%, rgba(255, 97, 24, 0.03) 100%)
-- **Border:** `1px solid #E5EDF5`
-- **Padding:** `36px`
-- **Box shadow:** none
-```
-
-#### Distinctive components (anything else the brand actually shows)
-
-Logo marquees, testimonial carousels, pricing tables, gradient overlays, glassmorphism panels, bento grids, code blocks, terminal UIs, dashboard mockups — name and document anything visually distinctive. Sub-agents will reach for these specs when the storyboard calls for a beat featuring the X.
-
-```markdown
-#### Glass Container (frosted overlay)
-
-- **Background:** `rgba(255, 255, 255, 0.9)`
-- **Border:** `1px solid rgba(255, 255, 255, 0.2)`
-- **Backdrop filter:** `blur(8px)`
-- **Use:** floating chat widgets, modal overlays, hero callouts only — the only place transparent fills appear in the system
-```
-
-**The rule:** if a sub-agent in Step 5 has to invent CSS values for a component this brand actually uses, you under-documented this section. The values should be lookup-able, not guessable.
-
----
-
-### `## 4. Spacing & Layout`
-
-The brand's rhythm. Three sub-sections, kept tight.
-
-#### Spacing scale
-
-Identify the **base unit** (typically `4px` or `8px`) and the full scale with usage context. **Example:**
-
-```markdown
-**Base unit:** `4px`
-
-| Token | Value   | Used for                                                  |
-| ----- | ------- | --------------------------------------------------------- |
-| xs    | `4px`   | Inline icon gaps, tight badge padding                     |
-| sm    | `8px`   | Button-group gaps, small component padding                |
-| md    | `16px`  | Card padding, form-field gaps, standard component spacing |
-| lg    | `32px`  | Section vertical spacing, large card padding              |
-| xl    | `60px`  | Major section separation                                  |
-| 2xl   | `100px` | Page-level rhythm, hero section padding                   |
-
-Never use odd values (`13px`, `17px`) — the system only uses multiples of 4.
-```
-
-#### Border-radius scale
-
-Every radius the site uses, with what uses it.
-
-```markdown
-- `0px`: Form labels, technical UI markers
-- `4px`: Primary buttons, inputs, small badges
-- `8px`: Standard cards, dropdowns
-- `12px`: Feature cards, larger callouts
-- `40px`: Icon buttons (square pill)
-- `9999px`: Pill-shaped CTAs, status chips
-```
-
-#### Whitespace philosophy (one paragraph)
-
-How does this brand use whitespace — generous and architectural? Tight and information-dense? Section gaps in the 60–100px range, or 20–40px? Document the brand's actual rhythm.
-
-```markdown
-Generous whitespace as confidence. Section gaps are always `60–100px`. Content never touches viewport edges — minimum `40px` horizontal padding on mobile, `80–160px` on desktop. The brand uses negative space as active design, not emptiness.
-```
-
----
-
-### `## 5. Iteration Guide` (the load-bearing section)
-
-5–10 numbered rules that encode the most important brand decisions. Each rule is a **single actionable sentence stating what to do, with the specific values from this site.** These are the "if in doubt, do this" rules sub-agents consult while composing beats.
-
-**The single most common failure mode is writing generic rules that could apply to any well-designed website.** A rule that doesn't name a specific value, a specific color, or a specific component this brand actually uses is doing nothing.
-
-**Test for any rule you write:** can you swap this brand for a different brand and have the rule still make sense? If yes, it's too generic. If no, ship it.
-
-#### ❌ Generic vs ✅ site-specific
-
-| Generic (delete)                                  | Site-specific (keep)                                                                                                                                                            |
-| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Use the primary brand color for CTAs.             | All primary CTAs use Stripe Purple (`#533AFD`). Secondary actions use white background with `#533AFD` border + text. **There is no third button color anywhere in the system.** |
-| Maintain visual hierarchy through color contrast. | Body text is `#000000` on white, `#FFFFFF` on dark. Metadata uses `#64748D` on white only — never on dark. The brand has no mid-gray text on dark backgrounds.                  |
-| Use clear typographic hierarchy.                  | All type is sohne-var. H1 `48px`/300, H2 `32px`/300, body `14px`/400. **Never use weights above 400** — this brand has no bold variant.                                         |
-| Use consistent spacing.                           | Spacing is from a fixed scale: `4, 8, 12, 16, 20, 24, 32, 40, 60` px. Section gaps are always `60–100px`. Card padding is always `32px`. No exceptions.                         |
-| Buttons should have rounded corners.              | Buttons are `40px` tall minimum, `4px` radius, `15.5px 24px` padding. Pill-shape `9999px` radius is reserved for the floating chat trigger only.                                |
-
-#### One worked example (Framer — 5 rules)
-
-```markdown
-### Iteration Guide
-
-1. **All interactive elements use Framer Blue (`#0000EE`)** — links, primary buttons, active states, focus indicators. Secondary uses `#0099FF` for hover. **No other interactive color exists in the system.**
-
-2. **Typography: GT Walsheim Medium for headings, Inter for body.** Hierarchy enforced through size only, never color. H2 `62px`, H5 `85px`, body `14px`, labels `12px`/500. Text defaults to `#000000` on white, `#FFFFFF` on dark.
-
-3. **Spacing is base-4** — every margin / padding / gap is a multiple of `4px`. Section gaps `60–100px`. **Never use odd values like `13px` or `17px`** — the system has no place for them.
-
-4. **Cards: white (`#FFFFFF`), `1px` border `#EFEFEF`, `8px` radius, `16–20px` padding, no shadow by default.** Dark-mode cards swap to `#1A1A1A` background with `#242424` border. Shadow only appears on hover.
-
-5. **Glass containers** use `rgba(255,255,255,0.9)` background, `1px` border `rgba(255,255,255,0.2)`, optional `backdrop-filter: blur(8px)`. **These are the only place transparent fills appear** — everywhere else uses solid color.
-```
-
-If your draft has a rule like "all interactive elements require visible focus states for accessibility" — delete it. Not wrong, just not load-bearing for _this_ brand.
-
----
-
-## Rules
-
-- Use **exact values** from `capture/extracted/tokens.json`. Cross-reference with screenshots when needed.
-- Name colors and components descriptively — "Stripe Purple" not "Accent 1."
-- When you can't extract exact values, estimate from visual inspection and note it.
-- No "Assets" section — `capture/extracted/asset-descriptions.md` is the asset index.
-- No "Motion" section — the storyboard specifies motion per-beat.
-- No separate "Components" section — Quick Reference is where components live.
-- No "Depth & Elevation" tables — shadow language is implied by the brand's mood (heavy shadows for premium, no shadows for flat/clean); sub-agents pick appropriate values without a table.
-
----
-
-## Quick User Check (before moving to Step 2)
-
-30-second sanity check before Step 2:
-
-> "Here's what I extracted as [Brand Name]'s visual identity:
->
-> - **Colors:** [primary], [accent], [2-3 others with roles]
-> - **Fonts:** [headline font], [body font]
-> - **Tone:** [1 sentence on the brand feel]
->
-> Does this match how you want the video to feel? Any corrections or overrides before I start the storyboard?"
-
-If the user has corrections ("use the blue, not the gray" / "ignore the dark mode" / "we just rebranded, use [these values] instead") — update DESIGN.md now. One minute here saves thirty minutes of rebuilding.
-
----
-
-## What makes a useful DESIGN.md
-
-A sub-agent reading just your Quick Reference + Iteration Guide should be able to:
-
-1. Pick the right color for any primary action, secondary action, body text, error state
-2. Pick the right font/weight/size for any headline, body, metadata
-3. Know which 2-3 rules they cannot break without losing the brand
-
-That's the test. If they can answer those three questions from a 60–120 line doc, you've nailed it. If they need to read 400 lines of mood-board prose to find a color, you've buried the signal.
+# Step 1: Write DESIGN.md (the brand-truth cheat sheet)
+
+DESIGN.md is a **brand-truth cheat sheet** — colors and fonts you'll **weave into your composed builds**. It is NOT a layout spec, not a moodboard, not a 400-line design system audit.
+
+DESIGN.md is the brand inflection sub-agents apply when building each beat: which color is "primary," which font is for headlines, what tone the brand carries — the load-bearing knobs they flip while building.
+
+**Target length: 250–350 lines.** Step 5 sub-agents read DESIGN.md to brand each beat — the more precise the component CSS values you encode here, the more brand-faithful the result. Going under 200 lines tends to produce generic dark-cinematic output because sub-agents have no brand component DNA to work from; going over 350 means you're over-investing in prose.
+
+**Fast-pacing exception:** For billboard-per-beat videos (short social ads where each beat is a single hero element on full-bleed background), a 50-line DESIGN.md with just colors + fonts + 3-5 do's/don'ts is enough. The Step 5 sub-agent prompt pastes brand values inline, so DESIGN.md depth only matters when the beats render full UIs.
+
+**User preferences always override brand rules.** If the user says "make it bright even though the site is dark" or "use serif fonts even though the brand is sans" — follow the user. DESIGN.md describes the captured website. The video might deliberately break that.
+
+**Read these now** — they're the inputs DESIGN.md is built from. Don't guess colors or sizes from screenshots:
+
+- `capture/extracted/tokens.json` — top brand colors (HEX) and font families with weight ranges.
+- `capture/extracted/design-styles.json` — computed CSS values from the live DOM: typography hierarchy (font-size, weight, line-height, letter-spacing per text role), button variants (background, padding, radius, shadow), card/container/nav styles, spacing scale, border-radius scale, box-shadow values with usage counts. **Primary data source for Sections 3–6 below.**
+
+**Font availability check — do this before writing anything else.** Read `capture/extracted/fonts-manifest.json`. The capture pipeline reads the OpenType `name` table embedded in every downloaded font file, so even hash-renamed Next.js/Webpack fonts are identified by their real family name (Inter, JetBrains Mono, Geist Mono, etc.). No guessing required.
+
+The manifest gives you two views:
+
+- `families[]` — one entry per distinct family with the weights captured, whether it's a variable font, and the files belonging to it
+- `files[]` — one entry per downloaded font with family, subfamily, weight, style, and any variation axes
+
+**How to use it:**
+
+- For each family you'll reference in DESIGN.md, name it by what's in `families[].family` (e.g. "Inter", not "f266e704 hashed font"). The hashed filenames are the `@font-face src` paths — they stay as-is on disk; only the display name comes from the manifest.
+- If a family has `variable: true` and `variationAxes` includes `"wght"`, you can use any weight 100-900 via `font-variation-settings: 'wght' <value>` even if only one static weight appears in the captured files. Note this in DESIGN.md so sub-agents know they have the full weight range available.
+- If the manifest's `unidentified[]` is non-empty, those files failed name-table extraction (rare — heavily subset fonts that strip metadata). Flag them as `unknown` in DESIGN.md and suggest a fallback rather than guessing.
+- Commercial fonts hosted on brand CDNs (GT Walsheim, Söhne, Graphik, Canela) won't be in the manifest because they aren't downloaded. Detect this by checking what the site uses (from `design-styles.json`) against what's in the manifest — anything used but missing is a CDN-hosted font. Flag explicitly: "Söhne not in capture; use Inter 600 as substitute."
+
+Sub-agents try to use the fonts you list. The manifest tells you exactly what's available — there's no excuse for claiming "Charlie Display 700" when no such file exists.
+
+---
+
+## The 5 sections to write
+
+### `## 1. Visual Theme (one paragraph)`
+
+3–5 sentences describing the brand's visual personality. Cover: dark-first or light-first, contrast strategy, dominant visual elements (gradients, illustrations, photography, UI mockups), overall mood, what makes it distinctive vs. generic.
+
+This is the only prose section. Make it specific to _this_ brand — not template-filling. A sentence that could describe any well-designed website is not useful.
+
+**Example:**
+
+> Stripe's visual language is light-first and clean, with deep navy (`#061B31`) and pure white as the foundation. The accent stack — Stripe Purple (`#533AFD`) for CTAs, Vibrant Orange (`#FF6118`) for energetic emphasis — keeps interactive elements unmistakable. Type is sohne-var Light (300) for display, weight 400 for body; the brand achieves hierarchy through size and weight, never color shifts. The mood is confident financial-tech — premium without theatrical drama. Distinctive: gradient overlays at 135° between purple and orange appear as subtle washes over white backgrounds, never as bold focal elements.
+
+---
+
+### `## 2. Quick Reference`
+
+A flat lookup of the values sub-agents grab while composing beats. Two sub-sections — keep them tight.
+
+#### Colors
+
+List 8–12 colors with brand-specific names + HEX + role. Not generic ("Accent 1") but evocative ("Stripe Purple", "Deep Navy", "Slate Border"). The name carries meaning; "blue 4" doesn't.
+
+**For each text-on-surface combination the brand uses, compute the WCAG AA contrast ratio and flag failing pairings explicitly.** A real failure mode from prior runs: the brand's secondary-text color (`#68686A`) on its dark panel color (`#18191B`) = 3.16:1, which fails AA's 4.5:1 minimum. Sub-agents faithfully reproduced the brand's color choice and the result was unreadable. Encode the safe / unsafe pairings here so sub-agents pick text colors by surface context, not by "this is the brand's secondary text color." The `/hyperframes-contrast` skill audits ratios — run it before finalizing DESIGN.md.
+
+**Example:**
+
+```markdown
+#### Colors
+
+- **Stripe Purple** (`#533AFD`): Primary CTA, interactive elements, focus rings — the brand's action signal
+  - On Pure White: 6.2:1 ✅ — On Deep Navy: 3.8:1 ⚠ AA-only-Large
+- **Deep Navy** (`#061B31`): Primary text on light surfaces, also a dark surface tier
+  - As text on Pure White: 17.4:1 ✅ — As surface: see Slate-on-Navy pairings below
+- **Pure White** (`#FFFFFF`): Page background, card surfaces
+- **Light Gray** (`#F5F7FA`): Surface tier 2 (cards on white pages, alternating sections)
+- **Slate Blue** (`#273951`): Secondary text on LIGHT surfaces
+  - On Pure White: 12.6:1 ✅ — On Light Gray: 11.8:1 ✅ — On Deep Navy: 1.4:1 ❌ DO NOT USE
+- **Light Slate** (`#64748D`): Metadata, captions on light surfaces only
+  - On Pure White: 4.8:1 ✅ — On Light Gray: 4.5:1 ✅ — On Deep Navy: 3.0:1 ❌ — On Dark Panel: 2.9:1 ❌
+  - **For dark-surface metadata, use `#9A9A9E` instead: 6.4:1 on Deep Navy ✅, 6.1:1 on Dark Panel ✅**
+- **Subtle Border** (`#D4DEE9`): Card borders, dividers (not text — borders don't need AA)
+- **Vibrant Orange** (`#FF6118`): Energy accent — gradient endpoints, highlight bursts (never primary text)
+- **Error Red** (`#FF0022`): Validation errors. On Pure White: 4.5:1 ✅
+- **Success Green** (`#4CD963`): Confirmation states. On Pure White: 1.7:1 ❌ — must be paired with a darker outline or use as accent on dark surfaces
+```
+
+**Where the brand's own palette fails WCAG**, document the substitute (like the `#9A9A9E` override above). Sub-agents pick the safe color by surface — and if the deviation matters to the brand identity, the user can revisit at Step 6.
+
+#### Fonts
+
+List font families with their role AND **the exact file path per family + weight** from `fonts-manifest.json`. Sub-agents will copy the `@font-face` block verbatim — if you only name the family without the path, sub-agents have to guess which `.woff2` file belongs to which family and get it wrong half the time (a real failure mode from prior runs: agents pointed `@font-face` for "ES Build Neutral" at the Inter `.woff2` files and the wordmark rendered in Inter).
+
+**Example:**
+
+````markdown
+#### Fonts
+
+- **Display:** `"ES Build Neutral"` — wordmarks, headlines
+  - 600: `capture/assets/fonts/14d7ce3e41dcbb66-s.p.woff2`
+  - 700: `capture/assets/fonts/e8b276476c0ac6fa-s.p.woff2`
+- **Body:** `"Inter"` (variable 100–900, captured ✓) — body, labels, UI
+  - 400: `capture/assets/fonts/9a8d3f06c4e89f2b-s.p.woff2`
+  - 600: `capture/assets/fonts/1b0b3615811be75b-s.p.woff2`
+- **Mono:** `"JetBrains Mono"` — code, metadata
+  - 400: `capture/assets/fonts/c7d2e9f5a1b3c8d4-s.p.woff2`
+- **Fallback stack:** `-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif`
+
+**`@font-face` block to paste in every composition** (sub-agents copy this verbatim — do not invent file paths):
+
+```css
+@font-face {
+  font-family: "ES Build Neutral";
+  src: url("capture/assets/fonts/14d7ce3e41dcbb66-s.p.woff2") format("woff2");
+  font-weight: 600;
+  font-display: block;
+}
+@font-face {
+  font-family: "Inter";
+  src: url("capture/assets/fonts/9a8d3f06c4e89f2b-s.p.woff2") format("woff2");
+  font-weight: 400;
+  font-display: block;
+}
+/* + any other family/weight combinations the storyboard's beats need */
+```
+````
+
+The brand uses **size for hierarchy, weight for emphasis**. Display 1: 48px/600, Display 2: 32px/600, Body: 14px/400. (Adjust to the actual brand's hierarchy.)
+
+````
+
+The exact `@font-face` block lets sub-agents copy verbatim instead of constructing one from inference. If a beat needs a weight that isn't in the manifest, flag it explicitly here: e.g., "ES Build Neutral 900 NOT in capture; use ES Build Neutral 700 as substitute, or fall back to Inter 700."
+
+That's the whole typography section. If sub-agents need exact line-heights or letter-spacing, they read `design-styles.json` directly.
+
+---
+
+### `## 3. Component Stylings` (the build-step's spec sheet)
+
+This is the section sub-agents consult most when building beats in Step 5. **Without exact per-component CSS, sub-agents fall back to generic "dark bg + glow + centered text" patterns regardless of brand** — which is why every video starts looking the same. Encode the brand's actual component DNA here.
+
+Target **6-12 distinct components**. Document what the site actually uses; skip categories the brand doesn't have. For each component, name it descriptively ("Stripe Primary Button" not "Button 1") and provide exact CSS-level properties: background, text color, padding, border-radius, border, font size/weight, height, box-shadow, and any hover/active/disabled states.
+
+#### Buttons (always required)
+
+Cover every variant the site uses — typically Primary, Secondary/Ghost, and Icon. **Example:**
+
+```markdown
+#### Primary Button (Stripe Purple)
+
+- **Background:** `#533AFD`
+- **Text color:** `#FFFFFF`
+- **Font:** sohne-var 16px / 400
+- **Padding:** `15.5px 24px 16.5px 24px`
+- **Border radius:** `4px`
+- **Border:** none
+- **Height:** `48px` (with padding)
+- **Box shadow:** none
+- **Hover:** background `#4329E8`, opacity `0.95`
+- **Active:** background `#3720D4`, scale `0.98`
+- **Disabled:** background `#C9C3F0`, cursor `not-allowed`
+
+#### Secondary Button (outline)
+
+- **Background:** `#FFFFFF`
+- **Text color:** `#533AFD`
+- **Border:** `1px solid #533AFD`
+- **Padding / radius / font:** same as Primary
+- **Hover:** background `#F3F0FF`, border `#4329E8`
+
+#### Ghost Button (text-only link)
+
+- **Background:** transparent
+- **Text color:** `#533AFD`
+- **Font:** sohne-var 14px / 400
+- **Padding:** `12px 0`
+- **Hover:** background `rgba(83, 58, 253, 0.08)`, optional underline
+````
+
+#### Cards & Containers (always required if the site uses any)
+
+Document each distinct card type — Standard, Feature Highlight, Glass, Pricing, Testimonial — whatever this brand actually uses. **Example:**
+
+```markdown
+#### Standard Card
+
+- **Background:** `#FFFFFF`
+- **Border:** `1px solid #D4DEE9`
+- **Border radius:** `5px`
+- **Padding:** `32px`
+- **Box shadow:** `0 1px 2px rgba(0, 0, 0, 0.04)` (default), `0 4px 12px rgba(0, 0, 0, 0.08)` (hover)
+- **Hover:** border `#B8CCDB`
+
+#### Feature Highlight Card (gradient backdrop)
+
+- **Background:** linear-gradient(180deg, rgba(83, 58, 253, 0.05) 0%, rgba(255, 97, 24, 0.03) 100%)
+- **Border:** `1px solid #E5EDF5`
+- **Padding:** `36px`
+- **Box shadow:** none
+```
+
+#### Distinctive components (anything else the brand actually shows)
+
+Logo marquees, testimonial carousels, pricing tables, gradient overlays, glassmorphism panels, bento grids, code blocks, terminal UIs, dashboard mockups — name and document anything visually distinctive. Sub-agents will reach for these specs when the storyboard calls for a beat featuring the X.
+
+```markdown
+#### Glass Container (frosted overlay)
+
+- **Background:** `rgba(255, 255, 255, 0.9)`
+- **Border:** `1px solid rgba(255, 255, 255, 0.2)`
+- **Backdrop filter:** `blur(8px)`
+- **Use:** floating chat widgets, modal overlays, hero callouts only — the only place transparent fills appear in the system
+```
+
+**The rule:** if a sub-agent in Step 5 has to invent CSS values for a component this brand actually uses, you under-documented this section. The values should be lookup-able, not guessable.
+
+---
+
+### `## 4. Spacing & Layout`
+
+The brand's rhythm. Three sub-sections, kept tight.
+
+#### Spacing scale
+
+Identify the **base unit** (typically `4px` or `8px`) and the full scale with usage context. **Example:**
+
+```markdown
+**Base unit:** `4px`
+
+| Token | Value   | Used for                                                  |
+| ----- | ------- | --------------------------------------------------------- |
+| xs    | `4px`   | Inline icon gaps, tight badge padding                     |
+| sm    | `8px`   | Button-group gaps, small component padding                |
+| md    | `16px`  | Card padding, form-field gaps, standard component spacing |
+| lg    | `32px`  | Section vertical spacing, large card padding              |
+| xl    | `60px`  | Major section separation                                  |
+| 2xl   | `100px` | Page-level rhythm, hero section padding                   |
+
+Never use odd values (`13px`, `17px`) — the system only uses multiples of 4.
+```
+
+#### Border-radius scale
+
+Every radius the site uses, with what uses it.
+
+```markdown
+- `0px`: Form labels, technical UI markers
+- `4px`: Primary buttons, inputs, small badges
+- `8px`: Standard cards, dropdowns
+- `12px`: Feature cards, larger callouts
+- `40px`: Icon buttons (square pill)
+- `9999px`: Pill-shaped CTAs, status chips
+```
+
+#### Whitespace philosophy (one paragraph)
+
+How does this brand use whitespace — generous and architectural? Tight and information-dense? Section gaps in the 60–100px range, or 20–40px? Document the brand's actual rhythm.
+
+```markdown
+Generous whitespace as confidence. Section gaps are always `60–100px`. Content never touches viewport edges — minimum `40px` horizontal padding on mobile, `80–160px` on desktop. The brand uses negative space as active design, not emptiness.
+```
+
+---
+
+### `## 5. Iteration Guide` (the load-bearing section)
+
+5–10 numbered rules that encode the most important brand decisions. Each rule is a **single actionable sentence stating what to do, with the specific values from this site.** These are the "if in doubt, do this" rules sub-agents consult while composing beats.
+
+**The single most common failure mode is writing generic rules that could apply to any well-designed website.** A rule that doesn't name a specific value, a specific color, or a specific component this brand actually uses is doing nothing.
+
+**Test for any rule you write:** can you swap this brand for a different brand and have the rule still make sense? If yes, it's too generic. If no, ship it.
+
+#### ❌ Generic vs ✅ site-specific
+
+| Generic (delete)                                  | Site-specific (keep)                                                                                                                                                            |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Use the primary brand color for CTAs.             | All primary CTAs use Stripe Purple (`#533AFD`). Secondary actions use white background with `#533AFD` border + text. **There is no third button color anywhere in the system.** |
+| Maintain visual hierarchy through color contrast. | Body text is `#000000` on white, `#FFFFFF` on dark. Metadata uses `#64748D` on white only — never on dark. The brand has no mid-gray text on dark backgrounds.                  |
+| Use clear typographic hierarchy.                  | All type is sohne-var. H1 `48px`/300, H2 `32px`/300, body `14px`/400. **Never use weights above 400** — this brand has no bold variant.                                         |
+| Use consistent spacing.                           | Spacing is from a fixed scale: `4, 8, 12, 16, 20, 24, 32, 40, 60` px. Section gaps are always `60–100px`. Card padding is always `32px`. No exceptions.                         |
+| Buttons should have rounded corners.              | Buttons are `40px` tall minimum, `4px` radius, `15.5px 24px` padding. Pill-shape `9999px` radius is reserved for the floating chat trigger only.                                |
+
+#### One worked example (Framer — 5 rules)
+
+```markdown
+### Iteration Guide
+
+1. **All interactive elements use Framer Blue (`#0000EE`)** — links, primary buttons, active states, focus indicators. Secondary uses `#0099FF` for hover. **No other interactive color exists in the system.**
+
+2. **Typography: GT Walsheim Medium for headings, Inter for body.** Hierarchy enforced through size only, never color. H2 `62px`, H5 `85px`, body `14px`, labels `12px`/500. Text defaults to `#000000` on white, `#FFFFFF` on dark.
+
+3. **Spacing is base-4** — every margin / padding / gap is a multiple of `4px`. Section gaps `60–100px`. **Never use odd values like `13px` or `17px`** — the system has no place for them.
+
+4. **Cards: white (`#FFFFFF`), `1px` border `#EFEFEF`, `8px` radius, `16–20px` padding, no shadow by default.** Dark-mode cards swap to `#1A1A1A` background with `#242424` border. Shadow only appears on hover.
+
+5. **Glass containers** use `rgba(255,255,255,0.9)` background, `1px` border `rgba(255,255,255,0.2)`, optional `backdrop-filter: blur(8px)`. **These are the only place transparent fills appear** — everywhere else uses solid color.
+```
+
+If your draft has a rule like "all interactive elements require visible focus states for accessibility" — delete it. Not wrong, just not load-bearing for _this_ brand.
+
+---
+
+## Rules
+
+- Use **exact values** from `capture/extracted/tokens.json`. Cross-reference with screenshots when needed.
+- Name colors and components descriptively — "Stripe Purple" not "Accent 1."
+- When you can't extract exact values, estimate from visual inspection and note it.
+- No "Assets" section — `capture/extracted/asset-descriptions.md` is the asset index.
+- No "Motion" section — the storyboard specifies motion per-beat.
+- No separate "Components" section — Quick Reference is where components live.
+- No "Depth & Elevation" tables — shadow language is implied by the brand's mood (heavy shadows for premium, no shadows for flat/clean); sub-agents pick appropriate values without a table.
+
+---
+
+## Quick User Check (before moving to Step 2)
+
+30-second sanity check before Step 2:
+
+> "Here's what I extracted as [Brand Name]'s visual identity:
+>
+> - **Colors:** [primary], [accent], [2-3 others with roles]
+> - **Fonts:** [headline font], [body font]
+> - **Tone:** [1 sentence on the brand feel]
+>
+> Does this match how you want the video to feel? Any corrections or overrides before I start the storyboard?"
+
+If the user has corrections ("use the blue, not the gray" / "ignore the dark mode" / "we just rebranded, use [these values] instead") — update DESIGN.md now. One minute here saves thirty minutes of rebuilding.
+
+---
+
+## What makes a useful DESIGN.md
+
+A sub-agent reading just your Quick Reference + Iteration Guide should be able to:
+
+1. Pick the right color for any primary action, secondary action, body text, error state
+2. Pick the right font/weight/size for any headline, body, metadata
+3. Know which 2-3 rules they cannot break without losing the brand
+
+That's the test. If they can answer those three questions from a 60–120 line doc, you've nailed it. If they need to read 400 lines of mood-board prose to find a color, you've buried the signal.