hyperframes/skills/website-to-video/references/step-1-design.md

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:

#### 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:

#### 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:

#### 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.

#### 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:

**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.

- `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.

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)

### 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.