mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-17 15:24:19 +00:00
feat(skill): workflow audit batch 18 — invert default visual strategy + collapse DESIGN.md
After 11 eval branches all shipped screenshot-slideshow videos despite the library + 3-mode wiring existing, the audit found four screenshot-pull instructions in steps 0-3 that committed agents to "use captured assets" BEFORE the 3-mode framework had a chance to redirect. The library + 3-mode wiring were bandaid on a workflow that still defaulted to screenshots. Surgical edits — invert the default, fold in keywords that survive in agent context: 1. SKILL.md Step -1: new opening manifesto. "You're not making a video. You're making something that stops scrollers in the first 1.5 seconds and feels alive in every single frame — with motion, depth, momentum, like things exist in a physical world. Think about how to go viral." "Get everything you need yourself. Compose the load-bearing visuals." "Captured assets are accents and decorations, not the beat itself." 2. step-3 line 243: DELETE "Use captured screenshots over CSS recreations." Replace with "Compose the load-bearing visuals yourself. Build the kanban from cards. Draw the logo with SVG paths. Paint the gradient with shader noise. Captured assets decorate composed beats — they don't carry." 3. step-3 Asset Audit: reframe table from "assign assets to beats" to "audit which assets decorate composed beats." Delete "Minimum utilization" bullets that forced asset usage. Add "Composed bar" replacing them: "Every beat's primary visual comes from a composed scene; accents are layered on top to brand-inflect." 4. step-3 beat template: rename ### Assets to ### Composition + Accents. Beat template now structurally requires (a) composed scene cite + mode, (b) customization, and (c) optional accent assets. Most beats have 0-1 accent. 5. step-1-design.md: COLLAPSED from 615 → ~140 lines. 8-section spec → 3 sections (Visual Theme paragraph / Quick Reference / Iteration Guide). The Iteration Guide is the only load-bearing section sub-agents actually consult. Drop: mood-board prose, exhaustive component CSS tables, depth-elevation matrices, "what makes a great DESIGN.md" criteria. 6. step-3 Per-Beat Direction: add "Opener default: fast intro to stop the scrollers" at the top. Even cinematic videos start with a punch inside the first 1.0-1.5 seconds. 7. step-2 Question 3: reframe options around compose-first beats. "Build the kanban from divs in your brand palette, with the captured logo stamped top-left" instead of "the dashboard screenshot would look stunning mapped onto a 3D MacBook." Captured assets appear as accents in the options, not as the primary visual. Net effect: agents now read "stop scrollers / alive every frame / physical world / go viral" as the goal, "compose the load-bearing visual" as the strategy, and "assets decorate, they don't carry" as the rule. The 81-scene library is the proof; the workflow text is now pulling toward it, not against it.
This commit is contained in:
@@ -40,9 +40,19 @@ Users say things like:
|
||||
|
||||
---
|
||||
|
||||
## Step -1: Study the Example Library (REQUIRED before Step 0)
|
||||
## Step -1: What we're actually making (REQUIRED before Step 0)
|
||||
|
||||
**Read:** [examples/README.md](examples/README.md) — the HyperFrames Capability Showcase. Production-grade scenes for every technique HyperFrames can do, each composed 100% from divs/SVG/HTML/CSS/GSAP — zero captured screenshots, zero slideshow shortcuts.
|
||||
You're not making *a video*. You're making something that **stops scrollers** in the first 1.5 seconds and **feels alive in every single frame** — with motion, depth, momentum, like things exist in a physical world. **Think about how to go viral.** Slow intros are for cinematic trailers; videos shipping anywhere social or feed-based need a hook that beats the 1.5-second scroll threshold.
|
||||
|
||||
**Get everything you need yourself.** Compose the load-bearing visuals — kanban boards from cards-as-divs, logos from SVG paths, gradients from shader noise, counters via `tl.set()`, dashboards from layered panels, transitions from chromatic-split or ripple shaders. You are not limited to what was captured from the website. You can paint anything a browser can render. The 81 scenes in [`examples/`](examples/) are the bar — every one composed 100% from divs/SVG/canvas, zero captured screenshots, every frame moving.
|
||||
|
||||
**Captured assets are accents and decorations, not the beat itself.** The brand logo on the closer. A hero illustration as a depth layer. A gradient image painted into a parallax background. The brand mark stamped onto a composed product UI. These enhance the beats you compose; they don't replace them. The most suitable combinations weave composed motion together with captured brand inflections — but composed motion is what carries the video.
|
||||
|
||||
---
|
||||
|
||||
### Study the Example Library (mandatory)
|
||||
|
||||
**Read:** [examples/README.md](examples/README.md) — the HyperFrames Capability Showcase. 81 production-grade scenes for every technique HyperFrames can do, each composed 100% from divs/SVG/HTML/CSS/GSAP — zero captured screenshots, zero slideshow shortcuts.
|
||||
|
||||
**Why this comes first:** every prior round of pipeline iteration showed agents defaulting to "screenshot + Ken Burns + voiceover" regardless of what the prompt asked for. Zero of eleven isolated component-eval runs used HTML-in-canvas, SVG path drawing, counter animations, kinetic typography, or any of HyperFrames' powerful capabilities. The skill prose has been exhausted as a lever; the lever is what you pattern-match to. These examples are that.
|
||||
|
||||
|
||||
@@ -1,615 +1,157 @@
|
||||
# Step 1: Write DESIGN.md
|
||||
# Step 1: Write DESIGN.md (the brand-truth cheat sheet)
|
||||
|
||||
DESIGN.md is a **comprehensive brand cheat sheet** for the captured website. It encodes the full visual identity — colors, typography, component styles, spacing, depth — so you can reference exact values while building storyboard and compositions. The more precise this document, the more authentic your video will look.
|
||||
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 NOT the creative plan. The STORYBOARD drives creative direction. DESIGN.md is a reference you consult — it tells you what the brand looks like, not what the video should do.
|
||||
The composed scenes in [`examples/`](../examples/) are the visual reference. DESIGN.md is the brand inflection you layer on top: which color is "primary," which font is "headlines," what tone the brand carries — the load-bearing knobs sub-agents flip when building beats.
|
||||
|
||||
**User preferences always override brand rules.** The Do's/Don'ts in DESIGN.md describe what the WEBSITE does — but the VIDEO might deliberately break those rules. If a user says "I want bright colors even though the site is dark-themed" or "use serif fonts even though the brand is sans-serif" — follow the user. DESIGN.md is a reference for authenticity, not a constraint. Going off-brand is fine when the user explicitly wants it.
|
||||
**Target length: 60–120 lines.** Sub-agents read the Quick Reference and the Iteration Guide; everything else is over-investment.
|
||||
|
||||
You read `tokens.json` and `design-styles.json` in Step 0. If you still have that data clearly in context, use it and skip re-reading. If you don't remember the exact values — just re-read them. Don't guess.
|
||||
**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.
|
||||
|
||||
**Font availability check — do this before writing typography rules.** Check `capture/assets/fonts/` and cross-reference with what the site actually uses:
|
||||
You read `tokens.json` and `design-styles.json` in Step 0. If you remember the values, use them; if not, re-read. Don't guess.
|
||||
|
||||
- Hashed filenames (`f266e704a846645b-s.p.woff`) = Google Fonts subsets — these auto-resolve, you don't need @font-face
|
||||
- Recognizable filenames (`Charlie_Display-Light.woff2`) = brand fonts — but CHECK THE WEIGHT. If the site uses 700/Bold and only Light/Thin was captured, that weight doesn't exist. Write in DESIGN.md: "Charlie Display — only Light (300) captured. Bold (700) unavailable, use DM Sans 700 as fallback." Don't write DESIGN.md claiming "Charlie Display 700" when the file doesn't exist — sub-agents will try to use it and silently fall back to system-ui anyway.
|
||||
- Commercial fonts (GT Walsheim, Söhne, Graphik, Canela, etc.) are NEVER captured — they're hosted on brand CDNs, not bundled in the site. Flag these explicitly: "GT Walsheim not available in capture — use Inter 600 as substitute."
|
||||
**Font availability check — do this before writing anything else.** Check `capture/assets/fonts/` and cross-reference with what the site uses:
|
||||
|
||||
- **`capture/extracted/tokens.json`** — colors (top 20 HEX), font families, headings, sections, CSS variables
|
||||
- **`capture/extracted/design-styles.json`** — computed styles extracted from live DOM: typography hierarchy with exact font-size/weight/line-height per role, button styles, card styles, nav styles, spacing scale, border-radius scale, box-shadow values
|
||||
- Hashed filenames (`f266e704...woff`) = Google Fonts subsets → auto-resolve, no `@font-face` needed
|
||||
- Recognizable filenames (`BrandSans-Bold.woff2`) = brand fonts. **Check the weight** — if the site uses 700/Bold but only Light/Thin was captured, the bold doesn't exist. Note this explicitly: "GT Walsheim — only Light (300) captured; for Bold use Inter 700 fallback."
|
||||
- Commercial fonts (GT Walsheim, Söhne, Graphik, Canela) are NEVER captured — they're on brand CDNs. Flag explicitly: "Söhne not in capture; use Inter 600 as substitute."
|
||||
|
||||
`design-styles.json` is your primary data source for Sections 3-6. It gives you exact computed values — don't estimate from screenshots what you can read from this file. Cross-reference with screenshots for visual context and anything the extractor missed.
|
||||
|
||||
## The 8 Sections
|
||||
|
||||
Write every section below. **Document everything meaningful; skip what the brand doesn't actually use.** A site with 6 real button variants and 7 real colors should have a DESIGN.md with exactly those — not 12 padded variants and 10 colors invented to hit a target. Each section should feel like you reverse-engineered the site's design system from scratch — because that's exactly what you're doing.
|
||||
Sub-agents try to use the fonts you list. If you claim "Charlie Display 700" and the file doesn't exist, they silently fall back to system-ui. Be honest about what's available.
|
||||
|
||||
---
|
||||
|
||||
### `## 1. Visual Theme & Atmosphere`
|
||||
## The 3 sections to write
|
||||
|
||||
Write one substantial paragraph (5-7 sentences) describing the overall visual personality. Cover:
|
||||
### `## 1. Visual Theme (one paragraph)`
|
||||
|
||||
- Dark-first vs. light-first aesthetic
|
||||
- Contrast strategy (high-contrast, muted, vibrant)
|
||||
- Dominant visual elements (gradients, illustrations, photography, UI mockups)
|
||||
- Motion and animation philosophy (if visible from `animations.json`, lottie, webgl and etc.)
|
||||
- Overall mood:
|
||||
- What makes this design distinctive vs. generic
|
||||
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.
|
||||
|
||||
Then add a **Key Characteristics** bullet list (5-8 items) that captures the defining visual patterns. These should be specific enough that another designer could identify the site from the list alone.
|
||||
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.
|
||||
|
||||
**Example:**
|
||||
|
||||
```markdown
|
||||
## 1. Visual Theme & Atmosphere
|
||||
#### Colors
|
||||
|
||||
Framer's design system embodies a bold, forward-thinking aesthetic rooted in minimalist sophistication and dynamic energy. The visual language combines deep blacks and pure whites with electrifying accent colors that command attention, creating a stark contrast that feels contemporary and design-focused. The system prioritizes clarity and directness, leveraging generous whitespace and confident typography to communicate purpose. Motion, precision, and modular consistency underpin every decision, reflecting a platform built for designers who demand control and flexibility. The overall mood is aspirational yet approachable—professional without pretension, innovative without excess.
|
||||
|
||||
**Key Characteristics**
|
||||
|
||||
- High-contrast black and white foundation with electric blue accents
|
||||
- Minimal ornamentation with emphasis on typography and spacing
|
||||
- Bold, oversized display typefaces paired with lean sans-serif body text
|
||||
- Rounded button forms (`40px` and `100px` radius) balancing geometric precision
|
||||
- Neutral grays reserved for secondary content and disabled states
|
||||
- Clean, friction-free interaction patterns prioritizing speed and clarity
|
||||
- **Stripe Purple** (`#533AFD`): Primary CTA, interactive elements, focus rings — the brand's action signal
|
||||
- **Deep Navy** (`#061B31`): Primary text, headings — gravitas color
|
||||
- **Pure White** (`#FFFFFF`): Page background, card surfaces
|
||||
- **Light Gray** (`#F5F7FA`): Surface tier 2 (cards on white pages, alternating sections)
|
||||
- **Slate Blue** (`#273951`): Secondary text, subheadings, lower-emphasis content
|
||||
- **Light Slate** (`#64748D`): Metadata, captions, disabled-adjacent text
|
||||
- **Subtle Border** (`#D4DEE9`): Card borders, dividers
|
||||
- **Vibrant Orange** (`#FF6118`): Energy accent — gradient endpoints, highlight bursts (never primary)
|
||||
- **Error Red** (`#FF0022`): Validation errors
|
||||
- **Success Green** (`#4CD963`): Confirmation states
|
||||
```
|
||||
|
||||
---
|
||||
#### Fonts
|
||||
|
||||
### `## 2. Color Palette & Roles`
|
||||
|
||||
Organize colors into **semantic groups**, not a flat list. Extract from `tokens.json` and cross-reference with screenshots.
|
||||
|
||||
**Required groups:**
|
||||
|
||||
- **Primary** — the 1 or 2 dominant brand colors (background, foreground)
|
||||
- **Accent Colors** — the colors used for emphasis, CTAs, highlights (typically 1 or 2 or 3)
|
||||
- **Interactive** — hover states, link colors, focus indicators
|
||||
- **Neutral Scale** — the full grayscale used for text, borders, disabled states (6-10 values)
|
||||
- **Surface & Borders** — background surfaces, card backgrounds, divider colors, glass/transparent overlays
|
||||
- **Semantic / Status** — error, warning, success colors (if present)
|
||||
|
||||
Target **10-15 colors minimum**. Every real design system has at least this many distinct values.
|
||||
|
||||
For each color, provide:
|
||||
|
||||
1. A **brand-specific name** — not generic ("Accent 1") but evocative ("Stripe Purple", "Vibrant Orange", "Huly Orange", "Deep Navy", "Slate Blue", "Navy Slate", "Pure Black", "Subtle Border Light", "Lavender Tint", and etc.)
|
||||
2. The exact HEX value
|
||||
3. Where and how it's used (be specific: "Primary brand color used for CTAs, interactive elements, active states, and brand identity. Most frequently used across the system for maximum recognition and action emphasis." or "Primary text color for headings and critical content. Conveys trust, professionalism, and financial gravitas. Used in hero sections and primary messaging." or ")
|
||||
List font families (with availability notes) + the headline / body / mono trio if applicable:
|
||||
|
||||
**Example:**
|
||||
|
||||
```markdown
|
||||
### Accent Colors
|
||||
#### Fonts
|
||||
|
||||
- **Vibrant Orange** (`#FF6118`): Secondary accent for highlights, gradient endpoints, and supporting visual interest. Creates energy and draws attention to secondary actions and design flourishes.
|
||||
- **Slate Blue** (`#273951`): Muted secondary color for subheadings, secondary text, and layered content. Bridges the gap between deep navy and neutral tones.
|
||||
- **Display + Body:** `sohne-var` (variable 100–900, captured ✓) — weights 300 / 400 used in production
|
||||
- **Mono:** `"JetBrains Mono"` — code, metadata, technical content
|
||||
- **Fallback stack:** `-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif`
|
||||
|
||||
### Neutral Scale
|
||||
|
||||
- **Pure Black** (`#000000`): Primary text, borders, and structural elements. High-contrast element for maximum readability in standard body text and critical UI components.
|
||||
- **Pure White** (`#FFFFFF`): Primary background, card surfaces, and content areas. Ensures legibility and creates visual hierarchy through clean separation.
|
||||
- **Light Slate** (`#64748D`): Secondary text, metadata, and lower-emphasis content. Used for supporting information and contextual details.
|
||||
|
||||
and etc.
|
||||
The brand uses **size for hierarchy, weight for emphasis**. Display 1: 48px/300, Display 2: 32px/300, Body: 14px/400. Never use weights above 400 — this brand has no bold variant in production.
|
||||
```
|
||||
|
||||
That's the whole typography section. If sub-agents need exact line-heights or letter-spacing, they read `design-styles.json` directly.
|
||||
|
||||
---
|
||||
|
||||
### `## 3. Typography Rules`
|
||||
### `## 3. Iteration Guide` (the load-bearing section)
|
||||
|
||||
Three sub-sections:
|
||||
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.
|
||||
|
||||
#### Font Family
|
||||
**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.
|
||||
|
||||
List every font family with its fallback stack. Identify which is used for display/headings vs. body vs. code.
|
||||
**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.
|
||||
|
||||
**Example:**
|
||||
#### ❌ Generic vs ✅ site-specific
|
||||
|
||||
```markdown
|
||||
### Font Family
|
||||
| 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. |
|
||||
|
||||
- **Primary Font**: `sohne-var`, system fallback stack: `-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, sans-serif`
|
||||
- **Secondary Font**: Monospace for code/technical content: `"SF Mono", Monaco, "Cascadia Code", Roboto Mono, Courier New, monospace`
|
||||
```
|
||||
|
||||
#### Hierarchy Table
|
||||
|
||||
A markdown table with exact values. Fill in every row you can extract from the capture:
|
||||
|
||||
| Role | Font | Size | Weight | Line Height | Letter Spacing | Notes |
|
||||
| --------- | ---- | ---- | ------ | ----------- | -------------- | -------------------------------------------------------------------- |
|
||||
| Display 1 | ... | ... | ... | ... | ... | Hero headlines, major section titles. High impact, open letterforms. |
|
||||
| Display 2 | ... | ... | ... | ... | ... | Section headings, feature callouts. Prominent but subordinate to H1. |
|
||||
| Heading | ... | ... | ... | ... | ... | ... |
|
||||
| Body | ... | ... | ... | ... | ... | ... |
|
||||
| Caption | ... | ... | ... | ... | ... | ... |
|
||||
|
||||
If exact sizes aren't in `tokens.json`, estimate from screenshots or use anything else to get the sizes, might even fetch the website if you want. Approximate is better than missing.
|
||||
|
||||
#### Principles
|
||||
|
||||
3-5 bullet points about how the typography system works — what carries hierarchy (size vs. weight vs. color), how display faces differ from body, minimum sizes, letter-spacing patterns.
|
||||
|
||||
**Example**
|
||||
|
||||
```markdown
|
||||
### Principles
|
||||
|
||||
- **Lightness as Hierarchy**: Display and heading typography uses weight 300 (light) to create visual distinction while maintaining sophistication; body content uses weight 400 for readability.
|
||||
- **Generous Line Height**: All sizes employ line-height 1.15–1.3× of font size to ensure comfortable reading, especially on screens and in financial interfaces where clarity is paramount.
|
||||
- **Semantic Sizing**: Each size increment represents a distinct narrative role; avoid intermediate sizes to maintain system coherence.
|
||||
- **System Fallbacks**: The sans-serif stack prioritizes system fonts for performance; sohne-var loads as the primary for brand consistency.
|
||||
- **Variable Font Optimization**: sohne-var supports optical sizing and weight variations; leverage intermediate weights (350–450) for emphasis without introducing new sizes.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `## 4. Component Stylings`
|
||||
|
||||
This is the section that makes the difference between a useful reference and a vague mood board. For each notable component type, provide **exact CSS-level properties**. Not just "rounded cards" — exact border-radius, padding, shadow, hover state and etc. .
|
||||
|
||||
Target **12-16 components** total across all categories. Every real design system (Stripe, Airbnb, ElevenLabs, Linear) documents at least this many.
|
||||
|
||||
**Required component types** (include what's present on the site):
|
||||
|
||||
#### Buttons
|
||||
|
||||
For each button variant (primary, secondary/ghost, icon):
|
||||
|
||||
- Background, text color, padding, border-radius, border
|
||||
- Font size, weight, height
|
||||
- Box shadow (if any)
|
||||
- Hover, active, and disabled states
|
||||
|
||||
**Example**
|
||||
|
||||
```markdown
|
||||
### Buttons
|
||||
|
||||
#### Primary Button
|
||||
|
||||
- **Background**: `#533AFD`
|
||||
- **Text Color**: `#FFFFFF`
|
||||
- **Font Size**: `16px`
|
||||
- **Font Weight**: `400`
|
||||
- **Padding**: `15.5px 24px 16.5px 24px`
|
||||
- **Border Radius**: `4px`
|
||||
- **Border**: `none`
|
||||
- **Height**: `fit-content` (typically `48px` with padding)
|
||||
- **Line Height**: `16px`
|
||||
- **Hover State**: Background `#4329E8`, slight opacity shift to `0.95`
|
||||
- **Active State**: Background `#3720D4`, scale `0.98`
|
||||
- **Disabled State**: Background `#C9C3F0`, color `#FFFFFF`, cursor `not-allowed`
|
||||
|
||||
#### Secondary Button
|
||||
|
||||
- **Background**: `#FFFFFF`
|
||||
- **Text Color**: `#533AFD`
|
||||
- **Font Size**: `16px`
|
||||
- **Font Weight**: `400`
|
||||
- **Padding**: `15.5px 24px 16.5px 24px`
|
||||
- **Border Radius**: `4px`
|
||||
- **Border**: `1px solid #533AFD`
|
||||
- **Height**: `fit-content`
|
||||
- **Line Height**: `16px`
|
||||
- **Hover State**: Background `#F3F0FF`, border color `#4329E8`
|
||||
- **Active State**: Background `#E8E9FF`, border color `#3720D4`
|
||||
|
||||
#### Ghost Button (Text Only)
|
||||
|
||||
- **Background**: `transparent`
|
||||
- **Text Color**: `#533AFD`
|
||||
- **Font Size**: `14px`
|
||||
- **Font Weight**: `400`
|
||||
- **Padding**: `12px 0px 12px 0px`
|
||||
- **Border Radius**: `4px`
|
||||
- **Border**: `none`
|
||||
- **Height**: `40px`
|
||||
- **Line Height**: `14px`
|
||||
- **Hover State**: Background `rgba(83, 58, 253, 0.08)`, text color `#4329E8`
|
||||
- **Active State**: Background `rgba(83, 58, 253, 0.12)`, text color `#3720D4`
|
||||
- **Underline**: Optional on hover; text-decoration `underline` for semantic links
|
||||
```
|
||||
|
||||
#### Cards & Containers
|
||||
|
||||
- Background, border, border-radius, padding, box-shadow
|
||||
- Hover state changes
|
||||
|
||||
**Example**
|
||||
|
||||
````markdown
|
||||
#### Standard Card
|
||||
|
||||
- **Background**: `#FFFFFF`
|
||||
- **Text Color**: `#000000`
|
||||
- **Font Size**: `16px`
|
||||
- **Font Weight**: `400`
|
||||
- **Padding**: `32px` (internal content padding)
|
||||
- **Border Radius**: `5px`
|
||||
- **Border**: `1px solid #D4DEE9`
|
||||
- **Box Shadow**: `0px 1px 2px rgba(0, 0, 0, 0.04)`
|
||||
- **Line Height**: `normal`
|
||||
- **Hover State**: Border color `#B8CCDB`, shadow `0px 4px 12px rgba(0, 0, 0, 0.08)`
|
||||
|
||||
#### Feature Highlight Card
|
||||
|
||||
- **Background**: Linear gradient `180deg, rgba(83, 58, 253, 0.05) 0%, rgba(255, 97, 24, 0.03) 100%)`
|
||||
- **Text Color**: `#000000`
|
||||
- **Padding**: `36px`
|
||||
- **Border Radius**: `5px`
|
||||
- **Border**: `1px solid #E5EDF5`
|
||||
- **Box Shadow**: `none`
|
||||
|
||||
#### Gradient Overlay Container (Hero)
|
||||
|
||||
- **Background**: Diagonal linear gradient `135deg, #533AFD 0%, #FF6118 100%)`
|
||||
- **Opacity**: Layer as `rgba(..., 0.15)` over white background for subtle effect
|
||||
- **Text Color**: `#FFFFFF` or `#061B31` depending on overlay contrast
|
||||
|
||||
#### Other Components
|
||||
|
||||
Name and describe any distinctive components visible in screenshots:
|
||||
|
||||
- Logo marquees, testimonial carousels, pricing tables
|
||||
- Gradient overlays, glassmorphism panels, bento grids
|
||||
- Code blocks, terminal UIs, dashboard mockups
|
||||
|
||||
**Example**
|
||||
|
||||
```markdown
|
||||
## Badges
|
||||
|
||||
#### Status Badge (Success)
|
||||
|
||||
- **Background**: `#D1FAE5`
|
||||
- **Text Color**: `#065F46`
|
||||
- **Font Size**: `12px`
|
||||
- **Font Weight**: `500`
|
||||
- **Padding**: `4px 8px`
|
||||
- **Border Radius**: `3px`
|
||||
- **Border**: `1px solid #A7F3D0`
|
||||
|
||||
#### Status Badge (Alert)
|
||||
|
||||
- **Background**: `#FEE2E2`
|
||||
- **Text Color**: `#991B1B`
|
||||
- **Font Size**: `12px`
|
||||
- **Font Weight**: `500`
|
||||
- **Padding**: `4px 8px`
|
||||
- **Border Radius**: `3px`
|
||||
- **Border**: `1px solid #FECACA`
|
||||
|
||||
#### Status Badge (Info)
|
||||
|
||||
- **Background**: `#E8E9FF`
|
||||
- **Text Color**: `#533AFD`
|
||||
- **Font Size**: `12px`
|
||||
- **Font Weight**: `500`
|
||||
- **Padding**: `4px 8px`
|
||||
- **Border Radius**: `3px`
|
||||
- **Border**: `1px solid #C9C3F0`
|
||||
```
|
||||
````
|
||||
|
||||
For each, use the same property-level detail as buttons and cards. Name them descriptively — "Glass Card with grain overlay" not "Card."
|
||||
|
||||
---
|
||||
|
||||
### `## 5. Layout Principles`
|
||||
|
||||
Three sub-sections:
|
||||
|
||||
#### Spacing System
|
||||
|
||||
Identify the **base unit** (typically `4px` or `8px`) and list the full spacing scale with usage context:
|
||||
|
||||
**Example**
|
||||
|
||||
```markdown
|
||||
**Base Unit**: `4px`
|
||||
|
||||
**Scale Progression**:
|
||||
|
||||
- `4px`: Micro-spacing (between inline elements, tight component padding)
|
||||
- `8px`: Compact spacing (button group gaps, small component padding)
|
||||
- `12px`: Small spacing (form field padding, small card padding)
|
||||
- `16px`: Medium spacing (standard component padding, section gaps)
|
||||
- `20px`: Standard padding (card padding, navigation padding)
|
||||
- `32px`: Large spacing (section vertical spacing, container padding)
|
||||
- `40px`: Extra-large padding (hero section padding, feature block padding)
|
||||
- `60px`: Rhythm spacing (major section separation)
|
||||
- `64px`: Section padding (full-width container internal padding)
|
||||
- `80px`: Large section padding (hero sections, dramatic breaks)
|
||||
- `100px`: Page-level gap (between major layout blocks)
|
||||
- `160px`: Maximum margin (edge spacing on very wide layouts)
|
||||
|
||||
**Usage Context**:
|
||||
|
||||
- Inline elements and tight groupings: `4px`–`8px`
|
||||
- Form fields and buttons: `12px`–`16px`
|
||||
- Card and container interiors: `16px`–`20px`
|
||||
- Section separation: `32px`–`80px` depending on visual weight
|
||||
- Page edges and maximum padding: `40px`–`160px` depending on breakpoint
|
||||
```
|
||||
|
||||
#### Grid & Container
|
||||
|
||||
- Max width, column strategy (desktop/tablet/mobile if visible)
|
||||
- Section patterns (full-width vs. contained, alternating layouts)
|
||||
|
||||
**Example**
|
||||
|
||||
```markdown
|
||||
**Max Width**: `1440px` (inferred from navigation component)
|
||||
|
||||
**Column Strategy**:
|
||||
|
||||
- Desktop: 12-column grid with `20px` gutters
|
||||
- Tablet: 8-column grid with `16px` gutters
|
||||
- Mobile: 4-column grid with `12px` gutters
|
||||
|
||||
**Section Patterns**:
|
||||
|
||||
- Full-width sections use `0px` horizontal margin, internal padding of `40px`–`80px`
|
||||
- Contained sections use max-width `1440px`, center-aligned with auto margins
|
||||
- Feature blocks align to grid; maintain consistent left/right padding
|
||||
```
|
||||
|
||||
#### Border Radius Scale
|
||||
|
||||
List every border-radius value you observe with what uses it:
|
||||
|
||||
**Example**
|
||||
|
||||
```markdown
|
||||
- `0px`: Hard edges for precise, technical elements (form labels, small icons)
|
||||
- `4px`: Minimal rounding for compact, controlled elements (small badges, subtle containers)
|
||||
- `6px`: Standard rounding for inputs, small cards, and utility components
|
||||
- `8px`: Common rounding for cards, dropdowns, and medium components
|
||||
- `12px`: Soft rounding for larger containers, feature cards, and callouts
|
||||
- `15px`: Medium-rounded button style for secondary CTAs
|
||||
- `40px`: Highly rounded for icon buttons and compact rounded buttons
|
||||
- `100px`: Fully rounded (pill shape) for primary buttons and rounded badges
|
||||
```
|
||||
|
||||
#### Whitespace Philosophy
|
||||
|
||||
**Example**
|
||||
|
||||
```markdown
|
||||
Framer's design system embraces generous whitespace as a sign of confidence and clarity. Every element breathes. Vertical rhythm is deliberate—major sections are separated by `60px`–`100px`, creating scannable hierarchy. Horizontal breathing is equally important; content never touches viewport edges. The principle: more whitespace = higher perceived value and improved scanability. Negative space is active design, not emptiness.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `## 6. Depth & Elevation`
|
||||
|
||||
A table of shadow levels with exact CSS values and where each is used:
|
||||
|
||||
**Example**
|
||||
| Level | Treatment | Use |
|
||||
|-------|-----------|-----|
|
||||
| Flat (0) | No shadow; `box-shadow: none` | Inputs, text, most UI elements; default treatment |
|
||||
| Raised (1) | `box-shadow: 0px 2px 8px rgba(0, 0, 0, 0.1)` | Cards on white background, modals, floating elements |
|
||||
| Elevated (2) | `box-shadow: 0px 4px 12px rgba(0, 0, 0, 0.15)` | Dropdown menus, popovers, hovered cards |
|
||||
| Floating (3) | `box-shadow: 0px 8px 24px rgba(0, 0, 0, 0.2)` | Modals, overlays, important floating panels |
|
||||
| Maximum (4) | `box-shadow: 0px 16px 40px rgba(0, 0, 0, 0.25)` | Full-screen modals, critical overlays, top-level layers |
|
||||
|
||||
Then a short **Shadow Philosophy** paragraph: does the site use shadows sparingly or dramatically? Are they soft or hard? How do they behave on dark vs. light backgrounds?
|
||||
|
||||
**Example**
|
||||
|
||||
```markdown
|
||||
**Shadow Philosophy**: Framer minimizes depth, preferring flatness and clean lines. Shadows are used sparingly, primarily to signal interactive surfaces (hover states, modals, overlays) or to create layering distinction. On dark backgrounds, shadows are removed or inverted to `rgba(255, 255, 255, 0.1)`. Shadows are always soft-edged (high blur radius) to avoid harshness; hard or sharp shadows are avoided entirely. The goal is subtle depth cues, not dramatic visual separation.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `## 7. Do's and Don'ts`
|
||||
|
||||
5-8 rules each, derived from what the site **actually does**. These should be specific and actionable, not generic design advice.
|
||||
|
||||
**Do's** — patterns to follow:
|
||||
|
||||
- Reference exact values (colors, spacing, radius)
|
||||
- Reference specific component behaviors
|
||||
|
||||
**Don'ts** — patterns to avoid:
|
||||
|
||||
- Things the site explicitly avoids (e.g., "no gradients", "no decorative borders", "no serif fonts")
|
||||
- Common mistakes that would break the visual language
|
||||
|
||||
**Example:**
|
||||
|
||||
```markdown
|
||||
### Do
|
||||
|
||||
- **Use the primary blue (`#0000EE`) for all primary CTAs and interactive elements** to maintain brand recognition and semantic clarity
|
||||
- **Maintain consistent heading hierarchy**: Display faces for heroes, GT Walsheim Medium for sections, Inter for subsections
|
||||
- **Apply generous whitespace around hero and feature content**: minimum `40px` padding on mobile, `80px` on desktop
|
||||
- **Use bold black text (`#000000`) on white backgrounds and bright white (`#FFFFFF`) on dark backgrounds** for maximum contrast and legibility
|
||||
- \*\*Employ rounded buttons (`40px` radius for icon buttons, `15px` for secondary CTAs`) to soften hard edges and signal approachability
|
||||
- **Leverage Glass / overlay containers with `rgba(255, 255, 255, 0.9)` and backdrop blur for layered, sophisticated depth**
|
||||
- **Reserve semantic colors for their intended purposes**: red (`#FF0022`) for errors, yellow (`#FFBB00`) for warnings, green (`#4CD963`) for success
|
||||
- **Build responsive layouts with mobile-first spacing; use `12px`–`16px` on mobile, scale up to `40px`–`80px` on desktop**
|
||||
- **Ensure all interactive elements have clear hover and focus states** (color shift, underline, or background change)
|
||||
- **Use Inter Variable font for responsive typography** that scales gracefully across viewport sizes
|
||||
|
||||
### Don't
|
||||
|
||||
- **Don't mix primary colors within a single component**; choose one focal color (blue) and support it with neutrals
|
||||
- **Don't use small shadows or high-contrast shadows**; keep shadows soft (`blur: 8px` minimum) and use only where depth is necessary
|
||||
- **Don't apply inconsistent border radius across similar component types**; icon buttons are always `40px`, inputs are always `6px`
|
||||
- **Don't exceed line lengths of `75–80` characters** for body text; restrict content width to maintain readability
|
||||
- **Don't add decorative borders to most components**; prefer subtle backgrounds or shadows over visible strokes
|
||||
- **Don't crowd interactive elements**; maintain at least `12px` of padding between buttons, inputs, and other touchable areas
|
||||
- **Don't use gray text (`#999999`) for primary content**; reserve for disabled states, captions, and secondary metadata
|
||||
- **Don't apply color to body text except for links (`#0000EE`)**; let typography size and weight carry hierarchy
|
||||
- **Don't create custom gradients**; use solid colors from the palette; gradients weaken brand coherence
|
||||
- **Don't ignore focus states on keyboard navigation**; all interactive elements must have visible focus indicators (border or outline)
|
||||
```
|
||||
|
||||
**Example 2**
|
||||
|
||||
```markdown
|
||||
## Do
|
||||
|
||||
- **Use Stripe Purple (`#533AFD`) for all primary CTAs** — this is the system's action signal and is immediately recognizable to Stripe users
|
||||
- **Maintain 1.15–1.3× line-height for all body text** — ensures readability at any size and accessibility compliance
|
||||
- **Apply gradient overlays to hero/showcase sections** — use diagonal 135° from purple to orange with 10–15% opacity over white for depth
|
||||
- **Group related content into cards with consistent `5px` border-radius and `#D4DEE9` borders** — establishes visual coherence
|
||||
- **Employ generous whitespace (`24px`–`60px`) between major sections** — supports the premium, confident aesthetic
|
||||
- **Use Deep Navy (`#061B31`) for primary headings and crucial text** — high contrast ensures legibility and gravitas
|
||||
- **Stack form fields vertically with `8px` gaps and consistent `40px` heights** — ensures usability and visual rhythm
|
||||
- **Reserve the Vibrant Orange (`#FF6118`) for accents and gradient endpoints only** — overuse diminishes impact
|
||||
- **Implement focus states with `2px` purple border + subtle shadow** — meets accessibility standards and provides clear interaction feedback
|
||||
- **Test all color combinations for 4.5:1 contrast ratio minimum** — ensures WCAG AA compliance for financial content
|
||||
|
||||
### Don't
|
||||
|
||||
- **Don't use purple for passive elements** — it's reserved for interactive and primary-importance content only
|
||||
- **Don't apply shadows to hero sections or gradient overlays** — use color layering instead; shadows create visual noise
|
||||
- **Don't mix serif and sans-serif typefaces in the same interface** — sohne-var is the only font family; maintain consistency
|
||||
- **Don't create custom spacing values outside the scale** — always use multiples of `4px` to maintain rhythm
|
||||
- **Don't set line-height below `1.15×` font size** — risks accessibility and readability issues in financial contexts
|
||||
- **Don't forget to disable buttons** — always include disabled state with `#C9C3F0` background and `cursor: not-allowed`
|
||||
- **Don't overuse borders** — use subtle `#D4DEE9` or `#E5EDF5` only; reserve bold borders for interactive focus states
|
||||
- **Don't nest more than two levels of dropdown menus** — keeps navigation simple and mobile-friendly
|
||||
- **Don't apply color to text smaller than `14px` without sufficient contrast** — metadata at `12px` must maintain `#000000` or `#061B31`
|
||||
- **Don't forget gradient direction** — always use `135deg` (top-left to bottom-right) for consistency with Stripe's brand motion
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `## 8. Agent Prompt Guide`
|
||||
|
||||
This is the section agents consult most during Step 5 (Build). It has two parts:
|
||||
|
||||
#### Quick Color Reference
|
||||
|
||||
A flat lookup of the most-used values — no categories, just the answers:
|
||||
|
||||
**Example**
|
||||
|
||||
```markdown
|
||||
### Quick Color Reference
|
||||
|
||||
- **Primary CTA**: Primary Interactive (`#0000EE`)
|
||||
- **Secondary Interactive**: Primary Light (`#0099FF`)
|
||||
- **Accent Highlight**: Vibrant Purple (`#6600FF`)
|
||||
- **Background**: Pure White (`#FFFFFF`)
|
||||
- **Text / Content**: Solid Black (`#000000`)
|
||||
- **Secondary Text**: Light Gray (`#666666`)
|
||||
- **Disabled Text**: Ash Gray (`#999999`)
|
||||
- **Error State**: Error / Danger (`#FF0022`)
|
||||
- **Warning State**: Warning (`#FFBB00`)
|
||||
- **Success State**: Success (`#4CD963`)
|
||||
- **Dark Background**: Deep Gray (`#1A1A1A`)
|
||||
- **Subtle Border**: Stone Gray (`#222222`)
|
||||
```
|
||||
|
||||
#### Iteration Guide
|
||||
|
||||
Numbered rules that summarize the most important design decisions for _this brand specifically_. Each rule should be a single actionable sentence stating what to do, with the specific values from this site. These are the "if in doubt, do this" rules — the TL;DR of the entire DESIGN.md.
|
||||
|
||||
**How many rules:** Whatever this brand needs. A simple brand with a tight identity might be 5–6 rules; a complex design system might be 10–14. There's no count target. If you find yourself padding to hit a number, stop.
|
||||
|
||||
**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. Below are paired counter-examples showing the difference.
|
||||
|
||||
##### Generic vs site-specific
|
||||
|
||||
The left column is what an agent writes when it's pattern-matching to "what an iteration guide is supposed to look like." The right column is what an iteration guide is actually for.
|
||||
|
||||
**Color:**
|
||||
|
||||
| ❌ Generic — wrong | ✅ Site-specific — right |
|
||||
| ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Use the primary brand color for all primary CTAs and the secondary color for supporting actions. | 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. |
|
||||
|
||||
**Typography:**
|
||||
|
||||
| ❌ Generic — wrong | ✅ Site-specific — right |
|
||||
| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Use a clear typographic hierarchy with appropriate sizes for headings and body. | All type is sohne-var. H1 `48px`/300, H2 `32px`/300, H3 `26px`/300, body `14px`/400. Never use weights above 400 — this brand has no bold variant in production. |
|
||||
| Headings should be larger than body text. | Headlines are minimum `2.3×` body size. The brand never uses a heading smaller than `26px` even in dense table rows. |
|
||||
|
||||
**Spacing:**
|
||||
|
||||
| ❌ Generic — wrong | ✅ Site-specific — right |
|
||||
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Use consistent spacing throughout the design. | Spacing is from a fixed scale: `4, 8, 12, 16, 20, 24, 32, 40, 60` px. Section gaps are always `60–100px`. Card internal padding is always `32px`. There are no exceptions. |
|
||||
|
||||
**Components:**
|
||||
|
||||
| ❌ Generic — wrong | ✅ Site-specific — right |
|
||||
| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Buttons should have rounded corners and adequate padding. | Buttons are `40px` tall minimum with `15.5px 24px` padding. Primary radius is `4px`; pill-shape `9999px` radius is reserved for the floating chat trigger only. |
|
||||
| Cards have a subtle shadow for depth. | Cards have `1px solid #D4DEE9` border, `5px` radius, no shadow by default. On hover, shadow `0 4px 12px rgba(0,0,0,0.08)` and border shifts to `#B8CCDB`. |
|
||||
|
||||
The 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. The rule should name values, components, or constraints that don't apply to any other site.
|
||||
|
||||
##### One worked example (Framer)
|
||||
|
||||
For reference, here's what a tight iteration guide looks like for a real brand. Five rules — enough to encode the most load-bearing decisions, not so many that the document becomes a checklist.
|
||||
#### One worked example (Framer — 5 rules)
|
||||
|
||||
```markdown
|
||||
### Iteration Guide
|
||||
|
||||
1. **All interactive elements use Framer Blue (`#0000EE`)** as the primary signal — links, primary buttons, active states, focus indicators. Secondary interactions use `#0099FF` for hover-state shifts. There is no other interactive color in the system.
|
||||
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 is GT Walsheim Medium for headings, Inter for body**, with hierarchy enforced through size only — never color. H2 is `62px`, H5 is `85px`, body is `14px`, labels are `12px`/500. All text defaults to `#000000` on white, `#FFFFFF` on dark.
|
||||
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, and gap is a multiple of `4px`. Section gaps are `60–100px`. Never use odd values like `13px` or `17px` — the system has no place for them.
|
||||
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 are 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.
|
||||
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.
|
||||
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.
|
||||
```
|
||||
|
||||
Notice what's missing: there's no rule about "always use proper focus states for accessibility" or "responsive breakpoints should be mobile-first." Those things are true but they're true for every well-built site. The iteration guide is for the rules that distinguish _this_ site.
|
||||
|
||||
If your draft includes a rule like "all interactive elements require visible focus states" — delete it. It's not wrong, it's just not load-bearing for this brand.
|
||||
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. Do not approximate when exact values are available.
|
||||
- Name colors and components descriptively — "Huly Orange" not "Accent 1", "Glass Card with grain overlay" not "Card variant B."
|
||||
- When you can't extract exact values (e.g., hover states, animation durations), estimate from visual inspection and note it's estimated or try anything possible and available to you in order to find and extract.
|
||||
- Write prose sections (Theme, Shadow Philosophy, Principles) as genuine analysis, not template-filling. Each site's DESIGN.md should read differently because each site IS different.
|
||||
- Target 200-400 lines. This is a comprehensive reference, not a quick cheat sheet. For context: designmd.me's outputs for real sites (Stripe, Airbnb, Huly, Framer) run 350-440 lines.
|
||||
- No "Assets" section beyond 8 — `capture/extracted/asset-descriptions.md` is the full asset index.
|
||||
- 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.
|
||||
- Target **60–120 lines total.** This is a cheat sheet, not a system audit. Length is not virtue.
|
||||
- No "Assets" section — `capture/extracted/asset-descriptions.md` is the asset index.
|
||||
- No "Motion" section — the storyboard specifies motion per-beat.
|
||||
- No "Components" section beyond what fits in Quick Reference — sub-agents compose UIs from [`examples/`](../examples/), not from CSS specs in this document.
|
||||
- No "Depth & Elevation" tables — `examples/` scenes encode shadow language; you don't need to re-document it.
|
||||
|
||||
---
|
||||
|
||||
## Quick User Check (before moving to Step 2)
|
||||
|
||||
After writing DESIGN.md, do a 30-second sanity check with the user before proceeding. Brand extraction can go wrong — the "primary color" might be a UI chrome accent, the dominant font might be from a third-party widget, the dark theme might not reflect how the brand wants to present itself.
|
||||
|
||||
Show the user:
|
||||
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 you extracted]
|
||||
> - **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, I want light" / "we just rebranded, use [these values] instead") — update DESIGN.md now, not later. One minute here saves thirty minutes of rebuilding.
|
||||
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 great DESIGN.md
|
||||
---
|
||||
|
||||
A great DESIGN.md lets you recreate any element from the website without looking at the screenshots. If someone reads only this document, they should be able to:
|
||||
## What makes a useful DESIGN.md
|
||||
|
||||
1. Pick the right colors for any surface, text, or accent
|
||||
2. Set typography that looks like the original site
|
||||
3. Build a card, button, or nav bar that passes for the real thing
|
||||
4. Apply the right spacing, shadows, and border-radius
|
||||
5. Understand what to avoid so the design stays cohesive
|
||||
A sub-agent reading just your Quick Reference + Iteration Guide should be able to:
|
||||
|
||||
The test: could a designer build a new page for this brand using only your DESIGN.md? If yes, it's detailed enough.
|
||||
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.
|
||||
|
||||
@@ -48,43 +48,40 @@ Their answers modify the brand-derived baseline you built in Step 1. Don't overr
|
||||
|
||||
### Question 3: What do you SPECIFICALLY want to see?
|
||||
|
||||
This is the open-ended question, but guide the user toward specificity. Frame it like this:
|
||||
This is the open-ended question, but guide the user toward specificity. Frame the options around **composed beats with brand inflection** — not around "what asset gets used where." The video's load-bearing visuals will be composed from scratch (kanban from divs, dashboards from layered panels, transitions from shaders); the captured assets are accents that decorate those composed beats with this brand's identity.
|
||||
|
||||
Frame it like this:
|
||||
|
||||
> "Now that I've analyzed your site, here's what I have to work with:
|
||||
>
|
||||
> - [N] product screenshots showing [describe what they actually show — be specific]
|
||||
> - [N] assets: [describe the most interesting ones — hero images, icons, illustrations, photos]
|
||||
> - [If Lottie found: "Lottie animations at [paths] showing [what they do]"]
|
||||
> - [If shaders found: "Your site uses WebGL effects — [describe: gradient wave, particle system, etc.] — I can recreate or build on these"]
|
||||
> - [If videos found: "Product videos showing [content]"]
|
||||
> - Your brand's visual language: [2-3 sentences on what makes this brand's visual style distinctive]
|
||||
> - **Brand inflection** — [2-3 sentences on what makes this brand's visual language distinctive: dominant colors, font character, mood]
|
||||
> - **Composed library** — every product UI, transition, counter, sparkline, and effect can be built from scratch using the [`examples/`](../examples/) library (81 reference scenes — kanban, chat, dashboard, terminal, shader transitions, particle fields, 3D scenes, audio-viz, etc.)
|
||||
> - **Brand accents available** — [1-2 most distinctive captured assets that earn a place: SVG logo for stroke-draw opener, hero illustration for a depth layer, gradient image for ambient wash]
|
||||
> - **Anything genuinely worth using as content** (rare) — [If the capture has something truly unique that can't be composed: a custom Lottie, real product video, a one-of-a-kind illustration — name it]
|
||||
>
|
||||
> Based on what I found, the most interesting things I could do with this specific capture:
|
||||
> Based on this, the most interesting beats I could compose for you:
|
||||
>
|
||||
> - [Capability directly tied to something found — e.g., "Your hero gradient wave animation could become a living background driving the whole video" or "The dashboard screenshot would look stunning mapped onto a 3D MacBook with your brand's dark glassmorphism treatment"]
|
||||
> - [Another specific possibility — e.g., "Your SVG logo has clean paths — I could draw it stroke by stroke as an opener"]
|
||||
> - [Another — e.g., "You have 6 product feature screenshots — these could fly in as a rapid showcase grid or be revealed one by one on rotating cards"]
|
||||
> - [If the capture has something unusual: name it specifically]
|
||||
> - [Compose-first example grounded in the brand — e.g., "Build the kanban board from cards-as-divs in your brand palette, with the captured logo stamped top-left and your hero gradient washing the background as ambient depth."]
|
||||
> - [Another — e.g., "Open with your SVG logo drawing itself stroke-by-stroke over a shader bloom that recreates your site's hero gradient — composed motion, brand colors woven in."]
|
||||
> - [Another — e.g., "Six product feature panels composed from scratch — kanban, dashboard, terminal, file tree, calendar, chat — each in your palette, with your wordmark stamped on each as identity."]
|
||||
>
|
||||
> Beyond what's in the capture, I can also search for or create additional assets — 3D models, custom shaders, stock footage — if anything would make the video stronger. Read [capabilities-overview.md](capabilities-overview.md) for the full picture of what's possible.
|
||||
> Beyond what's in the capture, I can also create additional assets — 3D models, custom shaders, illustrations, stock footage — if anything would make the video go further. The goal is something that stops scrollers and feels alive in every frame, not something that crossfades through screenshots. Read [capabilities-overview.md](capabilities-overview.md) for the full picture of what's possible.
|
||||
>
|
||||
> Do you have any specific scenes, moments, or effects you want to see? To help you think about it, here are a few directions that would work for your specific site:
|
||||
> Do you have any specific moments, beats, or effects you want to see? To help you think about it, here are a few directions that would work for your specific brand:
|
||||
>
|
||||
> [Generate 2–3 example direction prompts grounded in _this_ capture. Each one should reference something the agent actually has access to — an asset, a screenshot, a feature, an effect on the site. The goal is to model the _specificity_ of useful direction, not to suggest these specific moments.
|
||||
> [Generate 2–3 example direction prompts grounded in _this_ brand's identity. Each should describe a **composed beat** that weaves in the brand inflection (color / font / accent asset). Model the _specificity_ — name the composed reference + the brand accent that decorates it.
|
||||
>
|
||||
> Good capture-grounded examples have the form: "[do something specific] with [an asset/feature/effect that was actually captured]."
|
||||
> Good compose-first examples have the form: "[Compose X scene from examples/] in [this brand's palette/font], with [captured accent] [decorating it in this specific way]."
|
||||
>
|
||||
> Bad examples — what NOT to write here:
|
||||
>
|
||||
> - "I want the hero screenshot to come in on a rotating MacBook" (only valid if there are product UI screenshots AND the brand suggests device mockups)
|
||||
> - "Show the pricing tiers flying in one by one" (only valid if there is a pricing page in the capture)
|
||||
> - "Start with the logo drawing itself" (only valid if the captured logo is SVG with clean strokes)
|
||||
>
|
||||
> The bad examples above are what an agent reaches for when it's not actually thinking about the captured site. Don't paste them — write 2–3 that come from _this_ site's screenshots, assets, copy, or distinctive elements.]
|
||||
> - "I want the hero screenshot to come in on a rotating MacBook" (asset-primary thinking — instead: "Compose the dashboard from divs and animate it inside a 3D MacBook")
|
||||
> - "Show the pricing tiers flying in one by one" (vague — instead: "Compose your 3 pricing tiers using `examples/04-composed-ui/scene-14-pricing-card-reveal/`, with your brand purple on the Pro tier")
|
||||
> - "Start with the logo drawing itself" (might be valid as an accent on a composed opener, but it can't be the whole opener — what else is happening?)]
|
||||
>
|
||||
> You don't need a complete vision — even one or two specific moments helps me build something you'll love. Or say 'surprise me' and I'll make the creative calls based on your brand."
|
||||
|
||||
**Important:** The capabilities you mention must come from what was actually captured. If there are no product screenshots, don't mention the MacBook reveal. If there are no Lottie files, don't mention Lottie. If there are no shaders, don't mention recreating them. Every bullet should be grounded in the actual capture data — generic capability lists feel like a sales pitch, not a collaboration.
|
||||
**Important:** The directions you propose must lead with **composed beats**, with captured assets as accents. If you find yourself describing "the [asset] flying in" or "the [screenshot] mapped onto [thing]" — flip it. Lead with what gets composed and built, mention the brand accent as decoration second. Generic capability lists feel like a sales pitch; asset-primary lists feel like a slideshow.
|
||||
|
||||
Present options:
|
||||
|
||||
|
||||
@@ -189,27 +189,28 @@ Do NOT hand-code a Three.js device scene from scratch. The registry block handle
|
||||
|
||||
---
|
||||
|
||||
## Asset Audit
|
||||
## Asset Audit (decoration only — composed beats carry the visual)
|
||||
|
||||
Before writing any beats, audit every captured asset. Print this table:
|
||||
Audit captured assets to pick **the ones that will decorate your composed beats** — the brand logo for opener and closer, a hero illustration as a depth layer behind composed UI, a gradient image as an ambient wash, the brand wordmark stamped onto a composed product UI. **The composed builds carry the visual story; the assets garnish them.** Aim for 2-4 accent assets total across the whole video — accent count, not content count. The brand mark almost always earns a place; everything else has to justify itself.
|
||||
|
||||
| Asset | Type | Assign to Beat | Role |
|
||||
| ------------------------------ | ---------- | -------------- | ------------------------------------- |
|
||||
| wave-fallback-desktop.png | Hero image | Beat 1 | Full-bleed animated background |
|
||||
| enterprise-accordion-hertz.png | Photo | Beat 3 | Enterprise credibility, Ken Burns pan |
|
||||
| stripe-logo.svg | SVG | Beat 1, Beat 5 | Brand mark opener + closer |
|
||||
| datavizstatic3x.png | Data viz | Beat 3 | Supporting visual behind stats |
|
||||
| icon-3.svg | Icon | SKIP | Decorative, too small |
|
||||
Print this table — but the "Role" column should always read as "accent / decoration / brand inflection," never as "primary visual for this beat":
|
||||
|
||||
and outline how many assets you have actually read/view from any sources or yourself.
|
||||
| Asset | Type | Use it as | Role |
|
||||
| ------------------------------ | ---------- | ------------------- | ------------------------------------------- |
|
||||
| stripe-logo.svg | SVG | Beat 1 + Beat N | Brand mark (opener stroke-draw, closer hold)|
|
||||
| wave-fallback-desktop.png | Gradient | Beat 3 bg layer | Ambient depth wash behind composed dashboard|
|
||||
| datavizstatic3x.png | Data viz | SKIP | Compose stats from `examples/09-counters-and-data/` instead |
|
||||
| enterprise-accordion-hertz.png | Photo | SKIP | Compose the customer-story UI from `examples/04-composed-ui/scene-15-testimonial-card/` |
|
||||
| icon-3.svg | Icon | SKIP | Decorative, too small to matter |
|
||||
|
||||
**Minimum utilization:**
|
||||
Mark assets `SKIP` when their composed equivalent already exists in [`examples/`](../examples/) — that's the strong default for product UI (dashboards, kanban, chat, terminal, file tree, calendar, etc.). The library covers them all.
|
||||
|
||||
- Use as many assets as applicable for specific video request and concept
|
||||
- Brand logo appears in the first AND last beat unless the concept of the video is specific or different
|
||||
- The site's signature visual (gradient wave, hero illustration, key product UI) must appear anyhow — it's the most recognizable brand elements
|
||||
- Every beat must have a meaning in a bigger picture (full video)
|
||||
- Every beat must be visually interesting and engaging unless it's on purpose very bold and minimal
|
||||
**Composed bar:**
|
||||
|
||||
- Every beat's primary visual comes from a composed scene (cite the matching `examples/` scene + mode in the beat's Composition + Accents section below)
|
||||
- Accents are layered on top — the brand mark, gradient washes, hero illustrations — to give the composed beat this brand's inflection
|
||||
- Every beat must feel alive in every frame (continuous motion — see Per-Beat Direction below)
|
||||
- Every beat must justify its place in the bigger picture (full video)
|
||||
|
||||
---
|
||||
|
||||
@@ -240,7 +241,9 @@ Use the pacing you decided at the top of this step. The beat count, duration, an
|
||||
|
||||
**Frame-filling rule:** When describing visuals per beat, specify sizes as FRAME FILL PERCENTAGES, not pixels. "Product screenshot fills 80% of frame" not "600px wide card."
|
||||
|
||||
**Use captured screenshots over CSS recreations.** The capture folder has real product UI — actual interfaces with real data, real colors, real chrome. You might or might not use them, but if you do, make it at full-bleed (100% frame width) with Ken Burns zoom or perspective tilt or 3D moving rotation or turn or whatever the best way you will find.
|
||||
**Compose the load-bearing visuals yourself.** Build the kanban from cards-as-divs. Draw the logo with SVG paths. Paint the gradient with shader noise. Animate the counter with `tl.set()`. The video should feel **alive in every frame** — motion that's continuous and tangible, **like things exist in a physical world**. Captured assets (brand logo, hero illustrations, gradient backgrounds, product photography) are accents you layer onto composed beats — they decorate, they don't carry. Find the most suitable combinations: composed UIs grounded in the brand's actual colors and fonts, with captured brand marks stamped in as identity, not as content. For every beat where the storyboard pull is "show the kanban / dashboard / chat / terminal," the answer is build it from [`examples/04-composed-ui/`](../examples/04-composed-ui/), not paste a screenshot.
|
||||
|
||||
**Opener default: fast intro to stop the scrollers.** Even a cinematic video should start with a punch — a flash, a shader bloom, a logo strike, a kinetic word build, a particle burst — anything that lands inside the first 1.0–1.5 seconds. Slow intros work for prestige trailers; videos shipping anywhere social or feed-based need a hook that beats the 1.5-second scroll threshold. Plan the opener as the most ambitious beat in the storyboard, not the gentlest one.
|
||||
|
||||
**CTA / closing beats** are consistently the weakest. Agents treat them as "logo + tagline + done." A good CTA should: make the logo entrance an event (SVG path draw, scale with overshoot, or anything awesome really), have continuous background motion, and hold only 2-3 seconds after the last spoken word — NOT 8-10 seconds of silence.
|
||||
|
||||
@@ -262,18 +265,24 @@ Which narration line plays over this beat (Also keep in mind the whole narration
|
||||
|
||||
What the viewer sees — described cinematically, not as CSS specs. Use camera language and production motion designer vocabulary (pan, zoom, drift, settle, and more of those words). Think in layers — what's supposed to happen in the foreground, midground, background simultaneously?
|
||||
|
||||
**For beats using captured screenshots:** specify which screenshot, how much of the frame it fills (%), and where text/labels go relative to the screenshot's safe zones (if there are any at all lol). Don't blindly center text over busy product UI or even on sides if it has something there.
|
||||
**For the rare beat where a captured asset is the primary visual** (e.g., a homepage-reveal beat where the literal site IS the subject, or a customer-photo beat where the photo is the content): specify which asset, how much of the frame it fills (%), and where text/labels go relative to its safe zones. Don't blindly center text over busy product UI. **These beats should be the exception, not the rule** — if every beat's primary visual is a captured asset, you've defaulted to the slideshow pattern the library exists to break.
|
||||
|
||||
### Assets
|
||||
### Composition + Accents
|
||||
|
||||
Every asset used in this beat — exact path from project root, exact usage intent. No vague references. Name the actual file from the capture and describe precisely how it's used.
|
||||
Two things, both required:
|
||||
|
||||
Format (these are FORMAT EXAMPLES showing how to write it, not actual files to use):
|
||||
**Composed (load-bearing — what carries the beat):**
|
||||
|
||||
- `capture/assets/<actual-filename>` — [what it is and exactly how it appears: fill %, motion, treatment, opacity, positioning]
|
||||
- `capture/assets/svgs/<actual-filename>` — [what it is and exactly how it enters and behaves]
|
||||
- Cite the matching scene from [`examples/`](../examples/) and the mode (`copy+mutate` / `recombine` / `fresh`). E.g. `examples/04-composed-ui/scene-01-kanban-board/`, mode: `copy+mutate`.
|
||||
- **Customize:** brand colors from DESIGN.md, content swap (real product data, not the example's), timing adjustments, narration-sync moments. Make this beat THIS brand's beat, not a recolored example.
|
||||
|
||||
Write this section for the real captured files from THIS project's asset audit above, not from memory.
|
||||
**Accents (decoration only — what brand-inflects the beat):**
|
||||
|
||||
- Optional. Most beats need 0-1 accent. Format: `capture/assets/<filename>` — how it appears: position, opacity, treatment, motion (e.g. `capture/assets/logo.svg` — top-left, 60×60, fades in at 0.4s, breathes during hold).
|
||||
- Common accent uses: brand logo stamped on composed UI, hero illustration as depth layer, gradient image as ambient bg wash, brand mark on a composed pricing card.
|
||||
- If a beat has no obvious accent need, leave this blank. The composed visual is enough.
|
||||
|
||||
Write this section for THIS project's actual brand and the assets audited above — not from memory.
|
||||
|
||||
### Text Animations
|
||||
|
||||
|
||||
Reference in New Issue
Block a user