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