VibeCurb plugin for Cursor
Hero-section pipeline for building Awwwards/FWA-tier hero sections. Extracts design direction from reference images, provides six hero architectures with
---
name: awwwards-hero-section
description: Hero-section pipeline for building Awwwards/FWA-tier hero sections. Extracts design direction from reference images, provides six hero architectures with implementation blueprints, and enforces the fundamentals that separate award-winning heroes from generic AI output - viewport-scale typography, single focal point, extreme whitespace, tight palette. Hero-only. Pair with other skills for full pages.
---
# Awwwards-Tier Hero Section
> This skill is HERO-SECTION ONLY. It does not govern full pages, navigation systems, footers, or feature sections. It fires when the user asks for a hero, a landing header, an above-the-fold section, or provides reference screenshots of hero designs.
---
## The Pipeline
```
┌──────────────────────────────────────────────────────────────────────┐
│ │
│ BRIEF IN ──→ Phase 1: Read ──→ Phase 2: Architecture │
│ (extract signals) (pick one, commit) │
│ │
│ ──→ Phase 3: Build │
│ (type, palette, atmosphere, │
│ motion, mobile) │
│ │
│ ──→ Phase 4: Verify │
│ (visual diff against reference) │
│ │
│ Each phase has a ✓ Quality Gate. Failing a gate blocks the next. │
│ │
└──────────────────────────────────────────────────────────────────────┘
```
---
## Phase 1: Read the Reference
Before writing any code, extract design signals from the user's reference images (or infer from their brief). Do not project your own aesthetic onto the reference. Read what is actually there.
### → Extract these signals from each image
| Signal | What to look for |
|---|---|
| **Mode** | Light or Dark background |
| **Focal element** | What dominates the viewport? Massive typography, 3D object, full-bleed photography, product mockup, abstract shape, video, scattered floating elements |
| **Typography style** | Serif, sans-serif, or mixed. Massive or restrained. Uppercase or mixed-case. Tight-tracked or normal. Italic presence |
| **Text-to-image relationship** | Text sits ABOVE image (layered)? BESIDE it (split)? BEHIND a subject (masked)? INSIDE it (clipped)? INTERTWINED with inline images between words? |
| **Layout gravity** | Where does visual weight sit? Center? Bottom-left? Split across edges? Full-bleed? |
| **Color count** | Count distinct hues - award-winning heroes almost always use 2-3 max |
| **Navigation style** | Floating pill? Flat horizontal? Split (logo left, links right)? Minimal (logo + menu only)? |
| **Micro-details** | Rotating text badges, monospace metadata labels, glassmorphic cards, showreel links, CTA pill style |
### → Output a Hero Extraction before generating code
State in 2-3 lines exactly what you extracted:
> *"Hero Extraction: Dark mode, centered 3D card carousel with CSS perspective as focal element, massive sans-serif heading below in mixed-case, monospace micro-label above, single ghost CTA, floating pill nav. Palette: off-black + white + one muted accent. Feels like: dark cinematic agency with depth-layered cards."*
### → If no reference images are provided
Ask exactly ONE question: *"Do you want this hero closer to [dark cinematic] or [light editorial]? And what's the brand name + one-line value prop?"*
If you can infer from context (e.g., user said "AI startup" or "luxury agency"), skip the question and declare your Hero Extraction.
### ✓ Quality Gate: Read
Before moving to Phase 2, confirm:
- You have extracted all 8 signals from the reference (or inferred them from the brief)
- You have written the Hero Extraction summary
- You know the mode (light/dark), the focal element, and the palette direction
---
## Phase 2: Pick an Architecture
Select ONE architecture from the six below that best matches the reference. Do not blend two architectures. Commit fully to one.
---
### Architecture A: The Cinematic Center
*Best for: dark cinematic agency sites, immersive product launches, atmospheric brand pages*
The heading sits centered in the viewport. A cinematic visual (3D render, product shot, atmospheric photography) fills the background or floats behind/around the text. The CTA is a single centered pill or ghost button below the heading.
```
[viewport container: relative, min-h-[100dvh], overflow-hidden]
[background visual: absolute inset-0, object-cover or positioned 3D element]
[content overlay: relative z-10, flex flex-col items-center justify-center text-center]
[optional eyebrow: small mono label]
[H1: massive centered, max 2-3 lines]
[optional subtext: max 20 words, muted color]
[CTA: single pill button]
```
The background visual uses `position: absolute; inset: 0` with `object-fit: cover` (for images) or centered absolute positioning (for 3D/illustrations). Text sits on top via `position: relative; z-index: 10`. If text readability suffers, add a scrim gradient overlay between the image and text layers (`bg-gradient-to-t from-black/60 via-black/20 to-transparent`).
---
### Architecture B: The Asymmetric Split
*Best for: bold agency homepages, AI/tech product launches, statement brand pages*
Massive heading on one side (usually left, occupying 55-65% width). Supporting content (subtext, CTA, or a visual asset) on the other side, vertically offset. The two halves do NOT align to the same baseline - deliberate vertical tension.
```
[viewport container: min-h-[100dvh], grid grid-cols-1 lg:grid-cols-[1.2fr_1fr] items-end lg:items-center gap-8 lg:gap-0]
[left: H1, massive, left-aligned, takes up most of the width]
[right: subtext + CTA OR visual asset, vertically offset from the H1 baseline]
```
Use `items-end` on the left column and `items-start` on the right (or vice versa) to create vertical tension. The heading should feel like it anchors the page to one side. On mobile (`< 768px`), collapse to single column, full-width.
---
### Architecture C: The Full-Bleed Subject
*Best for: athlete/personal brand sites, product photography heroes, editorial fashion or lifestyle*
A full-viewport photograph or 3D render IS the hero. Typography is overlaid directly on the image - either at the top-left, bottom-left, or bleeding across the bottom edge. No separate "text area" - the image and text coexist in the same spatial plane.
```
[viewport container: relative, min-h-[100dvh], overflow-hidden]
[full-bleed image: absolute inset-0, object-cover]
[gradient scrim: absolute inset-0, bg-gradient-to-t from-black/70 via-transparent to-black/20]
[content: absolute bottom-0 left-0 p-12 lg:p-20, z-10]
[H1: massive, white, mix-blend-mode: difference OR on top of scrim]
[optional CTA]
```
The text MUST be readable against the photo. Use either a gradient scrim layer OR `mix-blend-mode: difference` on the text (which inverts text color against the background). Scrim is safer, blend mode is bolder. On mobile, increase scrim opacity.
---
### Architecture D: The Typographic Poster
*Best for: creative studio portfolios, personal brand statements, typography-led editorial*
Typography IS the visual. There is no hero image. The heading itself, at viewport-bleeding scale, IS the graphic element. Words may be split across the viewport edges. Different weights, sizes, or italics within the same heading create visual texture.
```
[viewport container: min-h-[100dvh], flex flex-col justify-between p-8 lg:p-16]
[top: nav or micro-label]
[center: H1 at viewport-scale (10vw-15vw), possibly split into multiple positioned lines]
[bottom: CTA or micro-metadata strip]
```
Use `font-size: clamp(4rem, 12vw, 16rem)`. Words can be positioned with `text-align: left` on line 1, `text-align: right` on line 2, creating diagonal visual flow. Mix `font-weight: 900` with `font-weight: 300` or `font-style: italic` within the same heading using `<span>` wrappers.
---
### Architecture E: The Inline-Image Typography
*Best for: creative agency hero sections, brand pages with personality, editorial homepages*
Massive typography with small, rounded images embedded BETWEEN words in the headline. The images sit inline at type-height, acting as visual punctuation. The heading reads as a sentence with tiny photo interruptions.
```
[viewport container: min-h-[100dvh], flex items-center justify-center]
[H1: massive, contains <span> wrappers for inline images]
"Build " [inline-image: w-16 h-10 rounded-full object-cover align-middle mx-1] " a quieter, " [inline-image] " smarter AI agency presence."
```
```css
/* BLUEPRINT: Inline hero images
WHY: The images must match the x-height of the surrounding text.
They are punctuation, not focal elements. Making them too large
turns the heading into a gallery instead of a sentence. */
.inline-hero-img {
display: inline-block;
width: clamp(3rem, 5vw, 5rem);
height: clamp(2rem, 3.5vw, 3.5rem);
border-radius: 9999px; /* pill shape */
object-fit: cover;
vertical-align: middle;
margin-inline: 0.25em;
}
```
On mobile, the inline images can either scale down with the text or stack below the heading (`hidden md:inline-block`).
---
### Architecture F: The Layered Depth (Z-Axis Composition)
*Best for: portfolio showcases, SaaS product demos, multi-project agency displays*
Multiple visual elements (cards, images, UI mockups) are arranged at different depths using CSS `perspective` and `transform: rotateY() rotateX()`. A single element is "closest" (largest, front-center). Others recede into the background (smaller, rotated, lower opacity). Typography anchors the composition above or below.
```
[viewport container: min-h-[100dvh], relative, perspective: 1200px on parent]
[card layer: absolute, multiple cards with varying transform: rotateY(Xdeg) translateZ(Ypx)]
[front card: scale(1), translateZ(0), centered]
[left card: rotateY(25deg), translateZ(-200px), scale(0.85), opacity-70]
[right card: rotateY(-25deg), translateZ(-200px), scale(0.85), opacity-70]
[text layer: relative z-10, positioned below or overlapping the card cluster]
[H1]
[CTA]
```
```css
/* BLUEPRINT: Perspective card shelf
WHY: perspective-origin centers the vanishing point.
preserve-3d lets child transforms create real depth.
backface-visibility prevents render flicker on rotation. */
.perspective-container {
perspective: 1200px;
perspective-origin: center center;
}
.depth-card {
transform-style: preserve-3d;
transition: transform 0.8s cubic-bezier(0.16, 1, 0.3, 1);
backface-visibility: hidden;
}
```
⚠ **Drift Warning:** The #1 AI failure mode for this architecture is scattering 8-10 cards randomly across the screen at random rotations. The layout MUST have a clear focal card (front-center, full opacity, largest) with 2-4 supporting cards receding symmetrically into depth. Think Apple TV app shelf, not a card explosion.
---
### ✓ Quality Gate: Architecture
Before moving to Phase 3, confirm:
- You selected ONE architecture from A-F
- Your selection matches the Hero Extraction from Phase 1
- You are not blending two architectures
---
## Phase 3: Build the Hero
### → Typography
Hero headings are not "big text." They are architectural elements that structure the entire viewport.
**Font selection - pick ONE from the appropriate row:**
| Vibe | Strong candidates (pick one) |
|---|---|
| Clean modern / tech / SaaS | `Geist`, `Satoshi`, `Cabinet Grotesk`, `Outfit`, `PP Neue Montreal` |
| Bold statement / agency | `Clash Display`, `Cabinet Grotesk`, `Monument Extended`, `Sohne Breit` |
| Editorial / luxury | `PP Editorial New`, `GT Sectra Display`, `Canela`, `Reckless Neue` (serif only when reference shows serif) |
| Condensed / industrial | `Bebas Neue`, `Oswald`, `Barlow Condensed`, `Archivo Black` |
⚠ **Drift Warning:** `Inter`, `Roboto`, `Open Sans`, `Poppins`, `Arial`, and `Helvetica` are body fonts, not display fonts. Using them as a hero heading font produces generic output regardless of how good the layout is. If the reference uses one of these, verify carefully - at hero scale, Inter and Geist look nearly identical, and Geist is the display-grade choice.
**Heading CSS blueprint:**
```css
/* BLUEPRINT: Hero heading
WHY: clamp() makes the heading responsive without breakpoints.
Negative letter-spacing is critical at large sizes - positive
tracking on massive text creates a loose, amateurish feel.
line-height below 1.0 lets ascenders and descenders overlap
slightly, which looks intentional at display scale. */
.hero-heading {
font-size: clamp(2.5rem, 7vw, 8rem);
font-weight: 700;
letter-spacing: -0.03em;
line-height: 0.95;
text-wrap: balance;
max-width: 18ch; /* prevents 4+ line wraps */
}
/* For 1-3 word headings, go larger */
.hero-heading--short {
font-size: clamp(4rem, 14vw, 18rem);
letter-spacing: -0.05em;
line-height: 0.85;
}
```
**Supporting text hierarchy:**
| Element | Specification |
|---|---|
| **Eyebrow** (above heading) | `font-size: 0.75rem`, `letter-spacing: 0.12em`, `text-transform: uppercase`, monospace or geometric sans. Muted color (`text-white/50` dark, `text-zinc-500` light) |
| **Subtext** (below heading) | `font-size: clamp(1rem, 1.25vw, 1.25rem)`, `max-width: 45ch`, `line-height: 1.6`, muted color. Never more than 20 words |
| **CTA button** | Solid pill (`rounded-full px-8 py-3.5`) OR ghost pill (`rounded-full px-8 py-3.5 border border-white/20`). `font-size: 0.875rem`, `letter-spacing: 0.05em`, uppercase. ONE CTA max. No secondary "Learn more" links |
---
### → Palette
Maximum 3 hues in the hero. This is not a suggestion - it is what separates award-winning heroes from busy ones.
**Dark hero palette:**
```css
/* BLUEPRINT: Dark hero atmosphere
WHY: #0a0a0a reads as black but has enough data for
subtle gradients to register. Pure #000000 is a dead
flat surface that cannot hold atmospheric effects. */
.hero-dark {
background: #0a0a0a;
color: #f5f5f5;
/* Accent: one muted hue, used on max 1-2 small elements */
}
```
**Light hero palette:**
```css
.hero-light {
background: #FAFAF9; /* or #F5F5F0 or #FDFBF7 - warm cream, not pure white */
color: #1a1a1a; /* or #111111 - near-black, not pure black */
/* Accent: one considered hue */
}
```
⚠ **Drift Warning:** More than one saturated accent in the hero guarantees a busy, unfocused feel. One accent on CTAs and active states. Everything else is the base palette (background + text + muted text).
---
### → Atmosphere
Do not use flat `bg-black` or flat `bg-white`. Heroes need depth.
**Dark mode - radial ambient glow:**
```css
/* BLUEPRINT: Ambient glow
WHY: A barely-visible radial gradient centered slightly
above the midpoint creates the illusion of a light source,
adding depth without any visible element. At 0.03 opacity
it's felt, not seen. */
.hero-dark::before {
content: '';
position: absolute;
inset: 0;
background: radial-gradient(ellipse 60% 50% at 50% 40%, rgba(255,255,255,0.03) 0%, transparent 70%);
pointer-events: none;
}
```
**Noise grain overlay:**
```css
/* BLUEPRINT: Film grain
WHY: Breaks the digital flatness of solid CSS backgrounds.
position:fixed prevents the grain from scrolling with content.
pointer-events:none makes it non-interactive.
0.04 opacity is the threshold where grain is felt but
doesn't interfere with text readability. */
.hero-dark::after {
content: '';
position: fixed;
inset: 0;
background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)' opacity='0.04'/%3E%3C/svg%3E");
pointer-events: none;
z-index: 50;
}
```
**Light mode - subtle warm radial:**
```css
.hero-light {
background: radial-gradient(ellipse at 30% 20%, rgba(250,235,215,0.4) 0%, transparent 50%), #FAFAF9;
}
```
---
### → Motion
Every hero MUST have an entry animation. Static mount looks broken.
```tsx
/* BLUEPRINT: Staggered hero entry (Motion / motion-react)
WHY: The stagger (0.12s between children) creates a
cascade effect. blur(8px)→blur(0) adds perceived quality
beyond simple fade-in. The custom cubic-bezier gives a
snappy deceleration that feels physical, not computed. */
const heroVariants = {
hidden: {},
visible: {
transition: { staggerChildren: 0.12, delayChildren: 0.1 }
}
};
const itemVariants = {
hidden: { opacity: 0, y: 30, filter: "blur(8px)" },
visible: {
opacity: 1,
y: 0,
filter: "blur(0px)",
transition: {
duration: 0.8,
ease: [0.16, 1, 0.3, 1] // custom ease-out
}
}
};
// Apply: <motion.div variants={heroVariants} initial="hidden" animate="visible">
// <motion.h1 variants={itemVariants}>...</motion.h1>
// <motion.p variants={itemVariants}>...</motion.p>
// <motion.div variants={itemVariants}>CTA</motion.div>
// </motion.div>
```
**Sequence:** Background fades in first (0ms) → heading slides up + deblurs (100ms) → subtext slides up (220ms) → CTA slides up (340ms). Total reveal under 800ms.
**CTA hover physics:**
```css
/* BLUEPRINT: CTA hover
WHY: translateY(-2px) creates a subtle lift. The custom
cubic-bezier makes the return-to-rest feel weighted, not
springy. scale(0.98) on active gives tactile press feedback. */
.hero-cta {
transition: all 0.5s cubic-bezier(0.16, 1, 0.3, 1);
}
.hero-cta:hover {
transform: translateY(-2px);
box-shadow: 0 8px 30px rgba(0,0,0,0.12);
}
.hero-cta:active {
transform: translateY(0) scale(0.98);
}
```
**Parallax structure (if reference implies it):**
```html
<!-- BLUEPRINT: Parallax-ready DOM
WHY: Separate layers let you apply different scroll
speeds via JS transform. will-change hints the GPU
to prepare for animation. The actual parallax offset
uses useScroll + useTransform from Motion, NOT
window.addEventListener('scroll'). -->
<section class="hero relative min-h-[100dvh] overflow-hidden">
<div class="hero-bg absolute inset-0 will-change-transform">
<img ... class="w-full h-full object-cover" />
</div>
<div class="hero-content relative z-10">
...
</div>
</section>
```
**Rotating text badge (if reference shows it):**
```css
/* BLUEPRINT: Rotating badge
WHY: 12s is slow enough to be ambient, not distracting.
Use SVG textPath along a circle for curved text.
Place in a bottom corner (absolute bottom-8 left-8),
not floating randomly. */
.rotating-badge {
width: 100px;
height: 100px;
animation: spin 12s linear infinite;
}
@media (prefers-reduced-motion: reduce) {
.rotating-badge { animation: none; }
}
@keyframes spin {
to { transform: rotate(360deg); }
}
```
---
### → Mobile Collapse
Every architecture MUST degrade cleanly below `768px`.
| Element | Mobile behavior |
|---|---|
| **Heading** | Scale down via `clamp()`. Never smaller than `2rem` on mobile |
| **Layout** | All multi-column splits collapse to `flex-col` or `grid-cols-1` |
| **Inline images** (Architecture E) | Either scale proportionally with text or hide (`hidden md:inline-block`) |
| **3D perspective cards** (Architecture F) | Remove all `rotateY`/`rotateX` transforms below `md`. Stack vertically or show only the focal card |
| **Full-bleed images** (Architecture C) | Increase scrim gradient opacity for text readability |
| **Touch targets** | All CTAs minimum `44px` tap target height |
| **Horizontal overflow** | Wrap hero in `overflow-x-hidden` to prevent 3D-transformed elements from creating scrollbars |
---
### → Performance
| Rule | Why |
|---|---|
| Animate ONLY `transform` and `opacity` | These are GPU-composited. Animating `top`, `left`, `width`, `height` triggers layout recalculation on every frame |
| `will-change: transform` only on actively animating elements | Overusing `will-change` wastes GPU memory. Remove after animation completes |
| `backdrop-filter: blur()` only on fixed/sticky elements | Applying blur to scrolling hero backgrounds tanks frame rate |
| Hero image uses `loading="eager"` (or `priority` in Next.js) | The hero image is above-the-fold - lazy loading causes LCP failure |
| Noise/grain on `position: fixed` pseudo-element | Never on a scrolling container - it repaints on every frame |
| Gate ALL animations behind `prefers-reduced-motion` | Use Motion's `useReducedMotion()` or CSS `@media (prefers-reduced-motion: reduce)` |
---
### ✓ Quality Gate: Build
Before moving to Phase 4, confirm:
- Architecture from Phase 2 was followed without blending
- Heading font is a display font, not a body font
- Heading uses fluid `clamp()` and is minimum `text-5xl` equivalent at desktop
- Heading wraps to max 2-3 lines on 1440px desktop
- Letter-spacing is tightened (negative tracking) on the heading
- Line-height is compressed (< 1.1) on the heading
- Color palette uses max 3 hues
- Hero uses `min-h-[100dvh]`, not `h-screen`
- Entry animation is present (staggered fade-up-deblur)
- All animations use only `transform` and `opacity`
- Mobile collapse is explicit
---
## Phase 4: Verify
Compare your hero against the reference (or against the Hero Extraction if no reference was provided). Walk through every category. Any FAIL blocks delivery.
### Composition Diff
| Check | PASS/FAIL |
|---|---|
| ONE focal point dominates the viewport (not 3+ competing elements) | |
| Hero fits in one viewport on 1440x900 without scrolling to find CTA | |
| Heading wraps to max 2-3 lines on desktop | |
| Content is vertically centered or intentionally anchored (not shoved to the top) | |
| Whitespace feels extreme and intentional (not cramped, not accidental) | |
### Typography Diff
| Check | PASS/FAIL |
|---|---|
| Heading font is NOT Inter, Roboto, Open Sans, Poppins, or Arial | |
| Heading font-size uses fluid `clamp()` | |
| Letter-spacing on heading is negative | |
| Line-height on heading is below 1.1 | |
| Subtext is max 20 words, muted color, constrained width | |
### Color Diff
| Check | PASS/FAIL |
|---|---|
| Max 3 distinct hues in the entire hero | |
| Background has atmosphere (grain, glow, warm tint) - not flat `bg-black` or `bg-white` | |
| No AI-purple/blue gradient backgrounds | |
| No neon accents, no mesh blobs, no rainbow | |
### Component Diff
| Check | PASS/FAIL |
|---|---|
| Maximum ONE CTA in the hero (no secondary "Learn more" links) | |
| CTA has hover + active states with custom easing | |
| No "Scroll to explore" / bouncing chevron / scroll indicators | |
| No trust logos / "Used by" badges inside the hero | |
| No version labels (v0.6, BETA) unless the brief is literally a product launch | |
| No emojis anywhere | |
### Motion Diff
| Check | PASS/FAIL |
|---|---|
| Entry animation is present (not instant static mount) | |
| Total entry reveal completes in under 800ms | |
| `prefers-reduced-motion` is respected | |
| No animation on `top`, `left`, `width`, or `height` | |
### Mobile Diff
| Check | PASS/FAIL |
|---|---|
| Layout collapses cleanly below 768px | |
| No horizontal overflow | |
| Touch targets minimum 44px | |
| Heading minimum 2rem on mobile | |
| Text is readable over images (scrim opacity increased if needed) | |
### Content Diff
| Check | PASS/FAIL |
|---|---|
| No AI copywriting cliches ("Elevate", "Seamless", "Unleash", "Next-Gen", "Revolutionize") | |
| No em-dashes - use periods, commas, or colons | |
| No placeholder images using generic stock (use `picsum.photos/seed/{keyword}/{w}/{h}`) | |
| The hero would not look out of place on awwwards.com | |
---
## The Core Principles
These are the fundamentals that separate award-winning heroes from generic AI output. They apply regardless of which architecture you pick.
> **One focal point.** The hero has ONE dominant visual element. Count elements competing for attention at the same scale. If the count exceeds 2, reduce until one clearly dominates.
> **Viewport-scale typography.** Hero headings are architectural elements, not "big text." Minimum `clamp(2.5rem, 7vw, 8rem)`. For 1-3 word headings: `clamp(4rem, 12vw, 15rem)`. Tight tracking. Compressed line-height.
> **Extreme whitespace.** The background is not wasted space - it IS the design. Content vertically centered via flex/grid, not pushed to the top with excessive padding.
> **Tight palette.** Max 3 hues. Dark heroes: off-black + white + one accent. Light heroes: warm cream + near-black + one accent. More than one saturated accent destroys focus.
> **Fits one viewport.** The entire composition (nav + heading + subtext + CTA + focal visual) must be visible without scrolling on 1440x900.Motion design pipeline for building Awwwards/Apple-tier animations, micro-interactions, scroll sequences, page transitions, and kinetic typography. Enfo
---
name: awwwards-motion-design
description: Motion design pipeline for building Awwwards/Apple-tier animations, micro-interactions, scroll sequences, page transitions, and kinetic typography. Enforces the principles that separate award-winning motion from generic CSS transitions - intentional easing, scroll-linked choreography, staggered reveals, magnetic interactions, text splitting, parallax depth, morphing state transitions, and the invisible micro-animations that make interfaces feel alive. Every animation must justify its existence, respect reduced-motion, and run at 60fps. Motion is choreography, not decoration.
---
# Awwwards-Tier Motion Design
> This skill fires when the user asks for animations, transitions, micro-interactions, scroll effects, page transitions, kinetic typography, parallax, hover physics, loading sequences, or anything that involves making a web interface feel alive and premium. Motion is the language of quality - the difference between a static page and an experience that feels like it was hand-crafted by a studio charging $200k per project.
---
## The Pipeline
```
┌───────────────────────────────────────────────────────────────────────┐
│ │
│ BRIEF IN ──→ Phase 1: Motion Audit ──→ Phase 2: Choreography │
│ (classify, extract (sequence map, timing │
│ motion intent) sheet, easing palette) │
│ │
│ ──→ Phase 3: Build │
│ (implement layer by layer: │
│ entry → scroll → hover → │
│ transitions → ambient) │
│ │
│ ──→ Phase 4: Motion Diff │
│ (60fps check, feel check, │
│ reduced-motion audit) │
│ │
│ Each phase has a ✓ Quality Gate. Failing a gate blocks the next. │
│ │
└───────────────────────────────────────────────────────────────────────┘
```
---
## The Core Doctrine
Before touching any code, internalize these. They override every aesthetic preference. The quality bar is **Apple keynote presentations, Linear app, Stripe homepage, Vercel dashboard, Raycast.** If your animation would look out of place on apple.com, it is not good enough.
> **The Apple Standard.** Apple does not use generic CSS transitions. Apple uses spring physics - animations that overshoot, settle, and breathe like physical objects. Every interaction on iOS feels like touching a real thing: buttons compress, sheets slide with momentum, elements settle with a gentle bounce. Your animations must achieve this same physical, tangible quality. If an element moves and it feels "digital" or "computed" rather than "physical" or "alive," the easing is wrong.
> **Every animation must have a reason.** If you cannot answer "why does this move?" with a functional answer (guides attention, communicates state change, provides feedback, establishes spatial relationship), remove the animation. Motion without purpose is noise.
> **The best animations are invisible.** The user should not think "that's a nice animation." They should think "this feels good." If the animation draws attention to ITSELF rather than to the CONTENT, it is too much. Apple never makes you wait for an animation to finish. The animation serves the interaction, not the other way around.
> **Cohesion is everything.** A page where every animation uses the same easing family, the same intensity level, and the same motion language feels like one studio built it. A page where fade-ups coexist with bouncy springs, slide-lefts, and scale-pops feels like a committee. **Pick ONE motion personality and enforce it everywhere.** Cohesion with fewer animations will always beat variety with full coverage. If forced to choose, sacrifice coverage for consistency - a page with 8 beautifully coordinated animations beats a page with 30 mismatched ones.
> **Spring physics over cubic-bezier.** The era of `cubic-bezier(0.25, 0.1, 0.25, 1)` as the pinnacle of easing is over. Material Design 3 Expressive has moved to spring-based motion. Apple has used spring animations since iOS 7. The web has caught up: CSS `linear()` enables true spring physics with overshoot and settle. Use spring-derived easing for EVERY primary animation. Reserve cubic-bezier only for ambient/background motion where spring overshoot would be inappropriate.
> **Easing IS the animation.** A 300ms linear transition and a 300ms spring transition have the same duration but completely different character. The curve is what separates a $200k studio site from a template. There is no such thing as a "default" ease. Every curve is a deliberate, conscious choice with a specific emotional character.
> **Stagger creates hierarchy.** When multiple elements animate, they cannot all move at once. Stagger is the motion equivalent of visual hierarchy - it tells the eye where to look first, second, third. Apple staggers with millisecond precision. So do you.
> **Motion respects the user.** Every animation gates behind `prefers-reduced-motion`. No exceptions. Users who set this flag have vestibular disorders, motion sensitivity, or simply prefer stillness. Reduced motion does not mean no animation - it means no translation, no parallax, no scale, no spring overshoot. Opacity-only fades at reduced duration are acceptable.
> **Every element earns its motion budget.** On marketing/landing pages, this means full coverage - every visible element gets at least one form of motion (entry, scroll reveal, hover, or ambient). A static element in an animated page is a dead pixel in a living display. On functional app UI, motion follows a frequency gate:
>
> | Usage frequency | Motion budget |
> |---|---|
> | 100+ times/day (keyboard shortcuts, command palette, core nav) | **ZERO animation. Ever.** Speed is the experience. |
> | Tens of times/day (hover states, list navigation, toggles) | Minimal - fast, nearly imperceptible feedback only |
> | Occasional (modals, drawers, toasts, settings panels) | Standard motion from the easing palette |
> | Rare / first-time (onboarding, empty states, success, celebration) | Full delight budget - springs, bounce, stagger generosity |
>
> **Hard rule:** Keyboard-initiated actions NEVER animate. A command palette that animates open/closed 200 times a day trains users to hate it. The fastest interface wins.
---
## The Animation Coverage Mandate
This is the non-negotiable rule: **every visible element gets motion.** Not "most elements." Not "the important ones." Every element. Walk through the page element by element and assign motion from this table. If an element does not appear in this table, it still gets at minimum a scroll-triggered fade-in.
### → Mandatory Element Animation Map
Fill this table for EVERY element on the page. Every row must have at least one ✓. Any empty row = incomplete implementation.
| Element | Entry Animation | Scroll Reveal | Hover/Focus State | Ambient/Micro | Assigned |
|---|---|---|---|---|---|
| **Navigation bar** | Slide down + fade from top | - | Link underline slide, spring-scale menu items | - | ✓ |
| **Logo** | Fade in (first element, 0ms delay) | - | Subtle scale(1.05) on hover | - | ✓ |
| **Nav links** | Stagger fade-in left-to-right | - | Sliding underline + color shift | - | ✓ |
| **Hero heading** | Word-by-word masked reveal OR char split | - | - | - | ✓ |
| **Hero subtext** | Fade-up-deblur (stagger after heading) | - | - | - | ✓ |
| **Hero CTA button** | Scale-in + fade (last hero element) | - | Pressure depth (compress + inner shadow) + lift + ripple on click | Subtle glow pulse | ✓ |
| **Hero background** | Scale(1.05→1) + fade (Ken Burns settle) | Parallax slow | - | Gradient shift OR grain movement | ✓ |
| **Section headings** | - | Word-by-word masked reveal OR fade-up-deblur | - | - | ✓ |
| **Section subtext** | - | Fade-up (stagger 80ms after heading) | - | - | ✓ |
| **Body paragraphs** | - | Line-by-line reveal OR fade-up | - | - | ✓ |
| **Cards** | - | Stagger fade-up (80ms increment per card) | Lift(-4px) + shadow expand + border glow + 3D tilt | - | ✓ |
| **Card icons/images** | - | Scale-in (after card reveals) | Subtle rotate or color shift on card hover | - | ✓ |
| **Card titles** | - | Part of card reveal | Color shift on card hover | - | ✓ |
| **Card descriptions** | - | Part of card reveal | Opacity increase on card hover | - | ✓ |
| **Images** | - | Clip-path wipe reveal OR scale-in | Ken Burns zoom on hover | - | ✓ |
| **Buttons (all)** | - | Fade-up with parent | Pressure depth + lift + shadow + ripple click | - | ✓ |
| **Links (inline)** | - | Part of parent reveal | Sliding underline + color shift | - | ✓ |
| **Input fields** | - | Fade-up with parent | Border glow on focus + label float | - | ✓ |
| **Badges/pills** | - | Scale-in + fade | Background color shift on hover | Subtle bounce float | ✓ |
| **Dividers/lines** | - | Width expand from center (scaleX 0→1) | - | - | ✓ |
| **Testimonial quotes** | - | Fade-up-deblur + slide | - | - | ✓ |
| **Avatars** | - | Scale-in with border ring animation | Ring pulse on hover | - | ✓ |
| **Stats/numbers** | - | Counter animation (count up from 0) | - | - | ✓ |
| **Footer** | - | Fade-up (last section) | Link underline slides | - | ✓ |
| **Footer links** | - | Stagger reveal | Underline slide + color shift | - | ✓ |
| **Social icons** | - | Stagger scale-in | Lift + color shift to brand color | - | ✓ |
| **Background shapes** | - | - | - | Floating animation + parallax | ✓ |
| **Decorative elements** | - | Rotate-in or scale-in | - | Slow spin or float | ✓ |
| **Scroll indicator** | Fade-in after hero loads | - | - | Gentle bounce loop | ✓ |
| **Progress bars** | - | Width expand (scaleX 0→1) with easing | - | - | ✓ |
| **Tooltips** | - | - | Float up + fade from trigger | - | ✓ |
| **Accordions** | - | Fade-up with parent | Border/bg shift on hover | Smooth height expand | ✓ |
| **Tabs** | - | Fade-up with parent | Background shift | Sliding indicator + content crossfade | ✓ |
| **Modals** | - | - | - | Backdrop fade + content scale-in | ✓ |
| **Toast/notifications** | - | - | - | Slide-in from edge + auto-dismiss | ✓ |
⚠ **Drift Warning:** The #1 failure is animating the hero and first section, then leaving everything below the fold completely static. EVERY section must have scroll-triggered reveals. EVERY interactive element must have hover feedback. Walk the page top-to-bottom and verify coverage. If you scroll and find a section that just "sits there" without animating in, the implementation is broken.
### → Coverage Verification Sweep
After building all animations, perform this sweep. Open the page and scroll top to bottom at a natural reading pace. For EVERY element that enters the viewport:
1. **Does it animate into view?** If no → add a scroll reveal
2. **Can you hover it?** If yes → does it have hover feedback? If no → add hover state
3. **Is it interactive (clickable, focusable)?** If yes → does it have active/focus states? If no → add them
4. **Is it decorative?** If yes → does it have ambient motion (float, rotate, pulse)? If no → add it
5. **Is it a text element?** If yes → does it have at minimum a fade-up reveal? If no → add it
A page with 100% animation coverage feels alive. A page with 80% coverage has dead spots that the eye catches immediately.
---
## Phase 1: Motion Audit
Before writing any code, classify the motion requirements.
### → Classify the Motion Context
| Field | Your answer |
|---|---|
| **Page type** | Marketing landing page / Product app / Portfolio / E-commerce / Editorial / Dashboard |
| **Motion density** | Minimal (Apple-style restraint) / Moderate (Stripe-level) / Rich (Awwwards experimental) |
| **Primary motion purpose** | Guide attention / Communicate state / Create atmosphere / Reveal content / Delight |
| **Scroll behavior** | Standard scroll / Scroll-linked animations / Scroll-jacked sections / Sticky reveals |
| **Page transitions** | None (SPA with instant swap) / Crossfade / Slide / Morph / Custom sequence |
| **Framework** | Vanilla CSS/JS / Framer Motion (React) / GSAP / Motion One / CSS-only |
### → Lock the Motion Personality (MANDATORY)
This is the single most important decision in the entire pipeline. Every animation on the page must belong to the SAME personality. A page that mixes personalities feels like three different developers animated it.
Pick ONE:
| Personality | Character | Easing core | Duration range | Signature move | Reference |
|---|---|---|---|---|---|
| **Surgical** | Crisp, fast, zero overshoot. Every motion is functional, nothing decorative. Clean as a scalpel. | `--ease-out` + `--ease-snap` | 100-250ms | Instant feedback, razor-sharp stagger | Linear app, Raycast, Vercel dashboard |
| **Physical** | Spring-based, tactile, objects have weight. Motion has overshoot, settle, momentum. Feels like touching real things. | `--spring-snappy` + `--spring-smooth` | 300-600ms (spring settle) | Spring entries, momentum drag, press compression | Apple.com, iOS, Dynamic Island |
| **Cinematic** | Dramatic, slow-build, theatrical reveals. The page IS the show. Scroll-linked narratives. | `--ease-dramatic` + `--spring-smooth` | 500-900ms | Clip-path reveals, text splitting, scroll-pinned sequences | Stripe homepage, Awwwards experimental |
Once locked, the personality constrains EVERYTHING downstream: which curves to use, how fast, how much stagger, whether to use springs, whether to use ambient motion. **Do not mix personalities.** A surgical page with one bouncy spring element is broken. A cinematic page with a 100ms tooltip snap is broken. Consistency is what makes motion feel like "one mind designed this."
### → Identify Motion Layers
Walk through the page and tag every element that should move. Classify each into one of these layers:
| Motion Layer | What it covers | Priority |
|---|---|---|
| **Entry** | First-paint reveals, above-the-fold load animation | P0 - must have |
| **Scroll** | Elements revealing as user scrolls, parallax, sticky sequences | P0 - must have |
| **Hover/Focus** | Button lifts, card tilts, link underlines, pressure depth effects | P0 - must have |
| **State** | Page transitions, tab switches, modal open/close, accordion, menu | P1 - should have |
| **Ambient** | Floating elements, gradient shifts, particle systems, cursor glow | P2 - polish layer |
| **Kinetic** | Text splitting, character-by-character reveals, word rotators | P2 - polish layer |
### → Output the Motion Brief
State in 2-3 lines the motion strategy. **Must include the locked personality name.**
> *"Motion Brief: PHYSICAL personality. Staggered spring entries on all sections (--spring-snappy). Scroll-triggered reveals with 20% viewport threshold. Press compression on all interactive elements. Spring-smooth text reveals on section headings. No ambient particles (personality conflict). Easing core: spring-snappy for entries, spring-smooth for state changes, ease-snap for hover only."*
### ✓ Quality Gate: Audit
Before moving to Phase 2, confirm:
- Motion context is classified (page type, density, purpose)
- **Motion Personality is locked** (Surgical / Physical / Cinematic)
- Every moving element is tagged to a motion layer
- The Element Animation Map is filled for EVERY element on the page - no empty rows
- Motion Brief is written (includes personality name)
- Framework is selected
---
## Phase 2: Choreography
Motion is choreography. Every element has an entrance cue, a duration, an easing curve, and a relationship to the elements around it. This phase creates the timing sheet - the musical score of the page.
### → The Easing Palette
This is the single most important section in the entire skill. The easing palette defines the emotional language of every animation on the page. Using the wrong curve is like playing a wrong note in a symphony - even non-musicians can feel it.
The palette has THREE tiers, ordered by quality. Use the highest tier your browser support allows.
---
**TIER 1: Spring Physics via CSS `linear()` - THE GOLD STANDARD**
This is what Apple uses. This is what Material Design 3 Expressive uses. This is what separates $200k studio sites from templates. CSS `linear()` enables true spring physics with overshoot and settle - something `cubic-bezier()` fundamentally cannot achieve.
```css
/* BLUEPRINT: Spring-based easing palette via CSS linear()
WHY: Real spring physics create motion that feels PHYSICAL.
Objects in the real world don't follow cubic-bezier curves -
they have mass, momentum, and elasticity. Springs overshoot
their target and settle back, which reads as "alive" to the
human eye. This is why every iOS animation feels tangible.
These curves were generated from spring physics simulations
with specific mass/stiffness/damping parameters. The linear()
function plots the spring's position at discrete time steps,
which the browser interpolates smoothly between. */
:root {
/* 1. APPLE SNAPPY SPRING - Primary entrance/reveal easing
Physics: mass=1, stiffness=400, damping=30
Character: Explosive start, tiny overshoot (~2%), soft settle.
This is the iOS sheet-present / notification-arrive curve.
Use on: hero entries, scroll reveals, modal opens, everything
that "arrives" on screen. This is your DEFAULT curve. */
--spring-snappy: linear(
0, 0.009, 0.035 2.1%, 0.141 4.4%, 0.723 12.9%,
0.938 16.7%, 1.017 19.4%, 1.067 22.5%, 1.089 26.0%,
1.079 30.3%, 1.049 36.0%, 1.024 42.6%, 1.011 50.3%,
1.004 59.2%, 1.001 69.3%, 1
);
--spring-snappy-duration: 0.55s;
/* 2. APPLE SMOOTH SPRING - State changes, position shifts
Physics: mass=1, stiffness=200, damping=24
Character: Gentle acceleration, visible overshoot (~5%),
two-phase settle. Feels like a precision instrument.
This is the iOS page-transition / tab-switch curve.
Use on: page transitions, tab switches, carousel slides,
anything moving from position A to position B. */
--spring-smooth: linear(
0, 0.004, 0.016 2.3%, 0.063 4.7%, 0.141 7.2%,
0.25 9.9%, 0.601 16.5%, 0.815 21.0%, 0.929 25.2%,
0.987 29.0%, 1.025 33.5%, 1.042 38.0%, 1.04 43.5%,
1.027 50.0%, 1.013 57.5%, 1.005 67.0%, 1.001 79.0%, 1
);
--spring-smooth-duration: 0.7s;
/* 3. APPLE BOUNCY SPRING - Playful micro-interactions
Physics: mass=1, stiffness=500, damping=18
Character: Very fast, pronounced overshoot (~12%), visible
bounce-settle. Feels playful, energetic, delightful.
Use SPARINGLY on: toggles, like buttons, notification pops,
small badges, emoji reactions. NEVER on large elements. */
--spring-bouncy: linear(
0, 0.014, 0.055 1.8%, 0.218 3.7%, 0.867 8.5%,
1.085 10.7%, 1.212 12.9%, 1.264 15.0%, 1.262 17.0%,
1.217 19.5%, 1.098 24.0%, 1.035 28.5%, 0.993 33.0%,
0.981 38.0%, 0.988 45.0%, 0.998 55.0%, 1.001 68.0%, 1
);
--spring-bouncy-duration: 0.5s;
/* 4. MATERIAL 3 EMPHASIZED - Google's expressive motion standard
Source: Material Design 3 motion spec (legacy cubic-bezier fallback)
Character: Very slow start, dramatic acceleration, gentle decelerate.
This is the M3 "emphasized" transition for container transforms,
shared element transitions, and FAB expansions.
Use on: container morphs, expand/collapse, shared transitions. */
--m3-emphasized: cubic-bezier(0.05, 0.7, 0.1, 1.0);
--m3-emphasized-duration: 0.5s;
/* 5. MATERIAL 3 EMPHASIZED as SPRING - for spring-capable contexts
Physics: mass=1, stiffness=300, damping=22
The spring equivalent of M3 Emphasized - with the overshoot
that Google's spec now recommends via their spring system. */
--m3-spring: linear(
0, 0.007, 0.029 2.0%, 0.118 4.2%, 0.508 10.9%,
0.797 15.4%, 0.951 19.2%, 1.029 22.2%, 1.074 25.6%,
1.088 29.2%, 1.075 33.6%, 1.045 39.5%, 1.02 46.5%,
1.007 55.0%, 1.001 66.0%, 1
);
--m3-spring-duration: 0.6s;
}
```
---
**TIER 2: Premium Cubic-Bezier Curves - STRONG FALLBACK**
For browsers that don't support `linear()`, or for secondary animations where spring overshoot would be inappropriate (ambient motion, background transitions, color shifts).
```css
:root {
/* 6. SNAPPY DECEL - Tier 2 fallback for spring-snappy
The best cubic-bezier approximation of the Apple snappy spring,
minus the overshoot. Still far better than CSS keyword easings.
Use when linear() is unavailable, or for secondary reveals. */
--ease-out: cubic-bezier(0.16, 1, 0.3, 1);
/* 7. SMOOTH IN-OUT - for ambient position shifts
Neither Material 3 nor Apple style - this is the Awwwards
agency standard for smooth lateral movements, carousel
auto-play, and background panning. */
--ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
/* 8. ENERGETIC SNAP - for hover responses, interactive feedback
Faster than --ease-out, designed for immediate tactile response.
The curve front-loads 80% of the motion into the first 30% of
the duration, creating a "snap" sensation. */
--ease-snap: cubic-bezier(0.22, 1, 0.36, 1);
/* 9. DRAMATIC IN-OUT - for hero reveals, cinematic entrances
Extremely slow start ("winding up"), explosive middle,
graceful deceleration. Use for the ONE theatrical moment
per page - the hero heading reveal, a page transition wipe. */
--ease-dramatic: cubic-bezier(0.77, 0, 0.175, 1);
/* 10. CUBIC SPRING APPROXIMATION - bouncy without linear()
The y2 value exceeds 1.0, causing overshoot. This is the
closest cubic-bezier can get to a spring. Less natural than
linear() springs but works everywhere. */
--ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
}
```
---
**TIER 3: CSS Keyword Easings - BANNED**
`ease`, `ease-in`, `ease-out`, `ease-in-out`, `linear` - these CSS keywords are the typographic equivalent of Comic Sans. They have zero character, zero intentionality, zero soul. They exist because browsers needed a default, not because any designer chose them.
| CSS Keyword | Why it's banned | What to use instead |
|---|---|---|
| `ease` | Generic curve that matches nothing. The "I didn't think about this" easing. | `--spring-snappy` or `--ease-out` |
| `ease-in` | Slow start, fast end - objects accelerating into a wall. Almost never what you want. | `--ease-dramatic` (if you need a slow start) |
| `ease-out` | Better than `ease`, but still a bland, characterless deceleration. | `--spring-snappy` or `--ease-out` (the custom one) |
| `ease-in-out` | The "I want this to look smooth" default that looks like nothing. | `--spring-smooth` or `--ease-in-out` (the custom one) |
| `linear` | Objects don't move at constant speed in nature. Feels robotic and dead. | Only acceptable for `animation-timing-function` on infinite loops (marquees, spinners) |
⚠ **Drift Warning:** If you write `transition: all 0.3s ease` ANYWHERE in the codebase, the implementation has failed the quality bar. Every transition must use a named curve from the palette. No exceptions. No shortcuts. The easing palette is the DNA of the entire motion experience.
---
**→ The Three-Curve Maximum (CRITICAL)**
This is the constraint that creates cohesion. From the 10 curves above, each project picks exactly **THREE** - one primary, one secondary, one utility. Every animation on the page uses one of these three. No exceptions. Three curves from the same family sound like one voice; ten curves sound like a committee.
| Personality | Primary (entries, reveals) | Secondary (state changes, transitions) | Utility (hover, feedback, ambient) |
|---|---|---|---|
| **Surgical** | `--ease-out` | `--ease-in-out` | `--ease-snap` |
| **Physical** | `--spring-snappy` | `--spring-smooth` | `--ease-snap` |
| **Cinematic** | `--ease-dramatic` | `--spring-smooth` | `--ease-in-out` |
These are the recommended presets. You MAY substitute one curve if the project demands it (e.g., swap `--spring-bouncy` for `--spring-snappy` on a playful product) but you MUST NOT exceed three total. If you find yourself reaching for a fourth curve, one of your first three was chosen wrong.
**→ How to choose between Tier 1 and Tier 2:**
| Animation type | Use this tier | Why |
|---|---|---|
| **Hero entry, page load reveals** | Tier 1 (`--spring-snappy`) | First impression. Must feel physical and premium. |
| **Scroll reveals** | Tier 1 (`--spring-snappy`) | User sees dozens of these. Each one must feel alive. |
| **Button/card hover** | Tier 2 (`--ease-snap`) | Hover is fast and functional. Spring overshoot on hover feels jittery. |
| **Button click/active** | Tier 1 (`--spring-bouncy`) | Click feedback benefits from the satisfying "pop" of a spring bounce. |
| **Modal/dialog open** | Tier 1 (`--spring-smooth`) | Modals are spatial - they arrive from somewhere. Springs make this feel real. |
| **Tab switch/carousel** | Tier 1 (`--spring-smooth`) | Position changes need momentum and settle. |
| **Background color shift** | Tier 2 (`--ease-in-out`) | Color doesn't have mass. Springs on color feel wrong. |
| **Gradient animation** | Tier 2 (`--ease-in-out`) or `linear` | Ambient motion. No spring needed. |
| **Page transition** | Tier 1 (`--spring-smooth`) | Page navigation is a major spatial event. Must feel physical. |
| **Tooltip appear** | Tier 2 (`--ease-snap`) | Fast, functional, non-theatrical. |
| **Accordion expand** | Tier 1 (`--spring-snappy`) or Tier 1 (`--m3-spring`) | Height changes with spring settle feel premium. |
| **Floating/ambient** | CSS `linear` keyword | Continuous loops don't need easing - constant speed IS correct. |
---
**→ Framer Motion / Motion spring equivalents:**
```tsx
/* BLUEPRINT: Framer Motion spring presets matching the CSS palette
WHY: When using Framer Motion (React), use these spring configs
instead of the CSS linear() values. Framer Motion's spring()
computes physics natively, giving even smoother results than
the CSS approximation. These match the FEEL of the CSS palette. */
const springs = {
// Matches --spring-snappy: fast, minimal overshoot
snappy: { type: "spring", stiffness: 400, damping: 30, mass: 1 },
// Matches --spring-smooth: gentle, visible settle
smooth: { type: "spring", stiffness: 200, damping: 24, mass: 1 },
// Matches --spring-bouncy: playful pop
bouncy: { type: "spring", stiffness: 500, damping: 18, mass: 1 },
// Matches --m3-spring: Material 3 emphasized
emphasized: { type: "spring", stiffness: 300, damping: 22, mass: 1 },
// For hover responses (no spring, just fast decel)
snap: { type: "tween", duration: 0.35, ease: [0.22, 1, 0.36, 1] },
};
// Usage:
// <motion.div transition={springs.snappy} />
// <motion.div transition={springs.smooth} />
```
---
**→ GSAP spring equivalents:**
```javascript
/* BLUEPRINT: GSAP spring-like easing
WHY: GSAP doesn't use spring physics natively, but its
CustomEase plugin can replicate the feel. For standard use,
these "power" easings are the closest GSAP equivalents. */
// snappy: "power3.out" or CustomEase
// smooth: "power2.inOut"
// bouncy: "back.out(1.7)" - the 1.7 controls overshoot amount
// dramatic: "expo.inOut"
// snap: "power4.out"
// For true springs in GSAP, use the gsap-spring plugin:
// gsap.to(".element", { x: 100, ease: "spring({stiffness: 400, damping: 30})" });
```
### → The Timing Sheet
Map every animation in sequence. This is the score.
| Element | Trigger | Delay | Duration | Easing | Transform | Notes |
|---|---|---|---|---|---|---|
| Nav | Page load | 0ms | 600ms | --ease-out | opacity 0→1, y -20→0 | First element to appear |
| Hero eyebrow | Page load | 100ms | 700ms | --ease-out | opacity 0→1, y 20→0, blur 8→0 | Stagger start |
| Hero heading | Page load | 200ms | 800ms | --ease-out | opacity 0→1, y 30→0, blur 8→0 | Core focal point |
| Hero subtext | Page load | 320ms | 700ms | --ease-out | opacity 0→1, y 20→0 | After heading lands |
| Hero CTA | Page load | 440ms | 600ms | --ease-out | opacity 0→1, y 20→0, scale 0.95→1 | Last hero element |
| Section heading | Scroll (20% visible) | 0ms | 800ms | --ease-out | opacity 0→1, y 40→0 | Per section |
| Cards | Scroll (15% visible) | 0/80/160ms | 700ms | --ease-out | opacity 0→1, y 30→0 | Stagger per card |
| CTA buttons | Hover | 0ms | 500ms | --ease-snap | y 0→-2px, shadow increase | Immediate response |
| Cards | Hover | 0ms | 400ms | --ease-snap | y 0→-4px, shadow increase | Lift effect |
**Timing Rules:**
| Rule | Value | Why |
|---|---|---|
| Maximum total entry sequence | 800ms | Beyond 800ms, the page feels slow to load |
| Stagger increment | 80-150ms | Below 80ms feels simultaneous. Above 150ms feels sluggish |
| Hover response | ≤ 150ms perceived start | The user must feel instant feedback |
| Scroll reveal duration | 600-900ms | Long enough to notice, short enough to not obstruct |
| Page transition | 300-500ms | Fast enough to not break flow, slow enough to register |
| Micro-interaction (toggle, checkbox) | 200-350ms | Functional feedback, not theatrical |
⚠ **Drift Warning:** The #1 AI animation failure is making everything too slow. A 1.5-second fade-in on every section makes the page feel like it's loading, not revealing. Keep scroll reveals under 900ms. Keep hover responses under 500ms. Keep total page entry under 800ms.
### → Stagger Choreography
Stagger is not "delay each item by 100ms." Stagger follows visual hierarchy.
**Correct stagger order (top to bottom = first to last):**
```
1. Container/background (instant or 0ms)
2. Primary content (heading, hero image) - 100ms
3. Supporting content (subtext, description) - 220ms
4. Interactive elements (CTAs, buttons) - 340ms
5. Decorative elements (badges, accents) - 440ms
```
**Stagger within grids (cards, features):**
```
For a 3-column grid, stagger left-to-right:
Card 1: 0ms
Card 2: 80ms
Card 3: 160ms
For a 2x3 grid, stagger top-left to bottom-right:
Row 1: 0ms, 80ms, 160ms
Row 2: 120ms, 200ms, 280ms
```
⚠ **Drift Warning:** Never stagger more than 6-8 items. If you have 12 cards, stagger the first 4-6, then bring the rest in together. A 12-item stagger takes 1.2+ seconds and the user loses patience watching items appear one by one.
### ✓ Quality Gate: Choreography
Before moving to Phase 3, confirm:
- Easing palette is defined (not using CSS keyword easings)
- Timing sheet covers every moving element
- No animation exceeds 900ms duration
- Total page entry sequence is under 800ms
- Stagger increments are 80-150ms
- Stagger follows visual hierarchy, not DOM order
- No more than 6-8 items are individually staggered
---
## Phase 3: Build the Motion (Framework-Agnostic Rules)
Implement layer by layer. Each layer builds on the previous one. Do not skip layers. **Never output massive boilerplate code blocks.** Instead, apply the following constraints when generating the actual code:
### Physical Correctness Rules
These apply to EVERY animation regardless of layer. Violations are automatic quality gate failures.
| Rule | Specification | Why |
|---|---|---|
| **Never `scale(0)`** | Start from `scale(0.9)` minimum, paired with `opacity: 0`. Range: `0.9-0.97` for UI, `0.95-0.97` for subtle entries. | Nothing in the physical world appears from absolute nothingness. `scale(0)` reads as a rendering glitch, not an entrance. |
| **Origin-aware transforms** | Popovers, tooltips, and dropdowns set `transform-origin` to the trigger element's position. **Modals are exempt** - modals stay `transform-origin: center` because they are viewport-anchored, not trigger-anchored. | Elements that grow from their source point create a spatial story. Elements that grow from their own center feel disconnected from the action that summoned them. |
| **Universal press feedback** | Every pressable element: `:active { transform: scale(0.97); transition: transform 160ms var(--ease-snap) }`. Subtle range: `0.95-0.98`. | A button that visually compresses on press confirms the interface registered the action. Missing press feedback makes the UI feel unresponsive regardless of actual latency. |
| **Ban `transition: all`** | Always specify exact properties: `transition: transform 200ms var(--ease-out), opacity 200ms var(--ease-out)`. | `transition: all` animates every property that changes - including `background-color`, `box-shadow`, `border` - causing off-GPU paint operations and visual artifacts. |
| **Asymmetric timing** | Deliberate user actions (press, hold, destructive confirm) = slow. System response (release, dismiss, confirm) = fast. Example: hold-to-delete overlay fills over `2s linear` on press, snaps back in `200ms var(--ease-out)` on release. | Slow where the user is deciding gives them control. Fast where the system responds gives them confidence. Symmetric timing feels mechanical. |
---
### Layer 1: Entry Animations (Page Load)
Every above-the-fold element needs a choreographed entrance.
- **Constraint:** Use staggered entry animations based on visual hierarchy (Containers → Headings → Subtext → CTAs → Decorators).
- **CSS:** Use `@keyframes` with `transform: translateY(24px)` and `filter: blur(6px)` to `0`, applying `--ease-out`. Stagger via `animation-delay`.
- **Framer Motion:** Use `staggerChildren: 0.12`. Children should fade-up and deblur.
- **GSAP:** Use `gsap.timeline()` with `.from()` tweens. Set `ease: "power3.out"`. Overlap tweens with `-=0.5`.
### Layer 2: Scroll-Triggered Reveals
Elements below the fold reveal as the user scrolls them into view.
- **Constraint:** Do not use scroll-jacking (preventing default scroll). Use scroll-linked (scrub) or threshold-triggered reveals.
- **Vanilla JS:** Use `IntersectionObserver` with a threshold of `0.15` and `rootMargin: "-50px"`. Unobserve after first trigger to prevent janky re-animation. Add an `is-visible` class that triggers CSS transitions.
- **GSAP:** Use `ScrollTrigger`. For sticky narrative sections, use `pin: true` and `scrub: 1` to link animation progress directly to scroll position.
### Layer 3: Interruptibility Rules
Animations that can be re-triggered before completing (toasts stacking, toggles, accordion spam, rapid hovers) MUST handle interruption gracefully. An animation that restarts from zero on re-trigger creates visual stutter.
| Mechanism | Behavior on interrupt | Use when |
|---|---|---|
| **CSS transitions** | Retargets from current value - smooth mid-flight reversal | Hovers, toggles, accordion expand/collapse, any rapidly-triggered state change |
| **CSS `@keyframes`** | Restarts from frame 0 - causes jump | One-shot reveals that fire once (scroll reveals with `unobserve`), ambient loops |
| **CSS `@starting-style`** | Defines entry state without JS - browser transitions from starting values on first render | Element entry animations without `useEffect` hacks. Modern replacement for `data-mounted` patterns |
| **WAAPI (`element.animate()`)** | JS control with CSS-thread performance. Hardware-accelerated, interruptible, zero library overhead | Programmatic sequences where you need JS timing control but CSS performance |
| **Springs (Framer Motion / GSAP)** | Carries velocity through interruption - the gold standard | Gesture-driven motion, drag interactions, anything a user can grab mid-flight |
**The 500ms rule:** If a user can trigger the same animation twice within 500ms (rapid clicking, hover flicking, toast spam), it MUST use CSS transitions or springs. Keyframes will stutter.
### Layer 8: State Transitions
Smooth transitions between UI states (modals, accordions, tabs).
- **Modals:** Use the native `<dialog>` element. Fade the `::backdrop` and scale/translate the dialog itself to create a 2-layer lifting effect. Modal scales from `scale(0.95)` + `opacity: 0`, never `scale(0)`. `transform-origin: center` (modals are viewport-anchored).
- **Accordions:** Use CSS Grid `grid-template-rows: 0fr` to `1fr` for smooth height animations without JS calculations.
- **Tabs:** Do not just crossfade active states. Use a sliding indicator (absolute positioned line) that `transform: translateX` to the active tab's coordinates for a physical connection.
- **Crossfade polish:** When two states visibly overlap during a crossfade (old content and new content both partially visible), add `filter: blur(2px)` during the mid-transition to blend them into one perceived transformation. Keep blur under `16px` - heavy blur is GPU-expensive, especially in Safari.
### Layer 8.5: Gesture & Drag Physics
For any draggable, swipeable, or dismissable surface (drawers, sheets, toasts, cards, carousels):
| Principle | Implementation |
|---|---|
| **Velocity-based dismissal** | Do not require dragging past a fixed distance threshold. Compute velocity: `Math.abs(dragDistance) / elapsedMs`. If `> 0.11`, dismiss regardless of distance. A quick flick is enough. |
| **Momentum projection** | On release, project the resting position using exponential decay: `projectedEnd = current + (velocity / 1000) * decayRate / (1 - decayRate)` where `decayRate ≈ 0.998`. Snap to the nearest target from the projected point, not the release point. |
| **Rubber-banding at boundaries** | When dragging past a natural edge (e.g., pulling a drawer above its max height), apply progressive resistance: `rubberband(overshoot, dimension, 0.55) = (overshoot * dimension * 0.55) / (dimension + 0.55 * abs(overshoot))`. Never hard-stop - the element should slow continuously like a physical object. |
| **Pointer capture** | Call `element.setPointerCapture(e.pointerId)` on drag start. This ensures tracking continues even when the pointer leaves the element's bounds. |
| **Multi-touch protection** | Once a drag begins, ignore additional touch points: `if (isDragging) return`. Switching fingers mid-drag without this causes the element to jump to the new position. |
| **Velocity handoff** | When the gesture ends and the spring animation begins, pass the finger's release velocity as the spring's initial velocity. There must be zero visual seam between the drag phase and the settle animation. |
### Layer 9: Loading and Preloader Sequences
- **Constraint:** Keep preloaders minimal. A simple expanding line (scaleX) with a numeric counter is more premium than a spinning circle.
- **Timing:** Never enforce artificial minimum load times over 2.5s. When resources (`document.fonts.ready`, images) are loaded, wipe the preloader away (e.g., via `clip-path`) and immediately trigger the Layer 1 Hero Entry.
### Layer 10: Signature Micro-Animations
Select exactly **1 to 3** of these per page. Restraint is what makes them signature - if everything is special, nothing is. Apply them only to the ONE element that deserves maximum attention (the hero heading, OR the primary CTA, OR the featured visual - not all three). The rest of the page uses the standard reveal vocabulary. This contrast is what makes the signature moment land.
1. **Text Scramble / Decode:** For hero headings or numbers. Cycle through random characters (`!<>-_\\/[]{}-=+*^?#_`) before locking into the real text.
2. **Border Draw:** Instead of fading a border, use pseudo-elements scaling from `0` to `1` on `scaleX`/`scaleY` with staggered delays to look like a pen tracing the edge.
3. **Ripple Click:** On primary buttons, spawn a radial-gradient circle exactly at `e.clientX / e.clientY` (cursor position) and scale it up to `4x` while fading opacity to `0`.
4. **Shimmer Loading:** For async data. Use a linear-gradient angled at `-20deg` moving from `200%` to `-200%` `background-position`.
5. **Morphing Blob Background:** For hero depth. Use an absolute positioned element with an 8-value `border-radius` (e.g., `60% 40% 30% 70% / 60% 30% 70% 40%`) animated over ~8 seconds.
6. **Tilt Parallax Cards:** On hover, track mouse position and apply slight `translate(x,y)` shifts to internal layers based on a `data-depth` multiplier to create a 3D diorama effect.
7. **Tooltip Float-Up:** Add a 100ms hover delay before floating tooltips up from below. Prevents accidental flashes when cursor passes by. **Skip-delay rule:** Once any tooltip in a group is already open, subsequent tooltips in the same toolbar/group open instantly with zero delay and zero animation. This makes the entire toolbar feel fast.
8. **Magnetic Cursor Elements:** Interactive elements that subtly pull toward the cursor when it enters their proximity zone (~40px). Use spring interpolation on the offset - direct mouse tracking feels robotic, spring-interpolated tracking feels alive.
8. **Gradient Border:** Use a `conic-gradient` with `@property --gradient-angle` animated linearly over 3 seconds to create a living, spinning edge.
9. **Cursor Trail:** If requested, use a small dot tracking exactly to the cursor, and a larger hollow circle that follows with a slight lerp (delay) for an elastic feel. Hide on touch devices.
10. **Clip-Path Reveals:** For major section transitions, reveal the next section by expanding a circle `clip-path: circle(0% at 50% 50%)` to `150%`.
## Phase 4: Motion Diff
Compare your animations against the Motion Brief and Timing Sheet. Walk through every category. Any FAIL blocks delivery.
### ⚡ Coverage Check (MANDATORY - Run First)
| Check | PASS/FAIL |
|---|---|
| **Every heading** on the page has a scroll reveal or entry animation | |
| **Every paragraph/body text** has at minimum a fade-up reveal | |
| **Every card** has a scroll reveal AND a hover state (lift + shadow) | |
| **Every button** has hover (lift/wipe/color) + active (press) + focus-visible states | |
| **Every link** has a hover underline animation or color shift | |
| **Every image** has a reveal animation (clip-path, scale-in, or fade) | |
| **Every input** has a focus state (glow, border shift, or label animation) | |
| **Every section** has scroll-triggered entry (no section just "sits there") | |
| **Every decorative element** has ambient motion (float, rotate, pulse) | |
| **Every divider/line** animates in (scaleX expansion or fade) | |
| **Every icon** has hover feedback (color, scale, or rotation shift) | |
| **Stats/numbers** count up from 0 when scrolled into view | |
| **Nav bar** has an entry animation on page load | |
| **Footer** has scroll-triggered stagger reveal on its contents | |
| Scroll the entire page top-to-bottom: ZERO static elements found | |
⚠ **If any row is FAIL, go back and add the missing animation before proceeding.** This is not optional. A page with 90% animation coverage has dead spots that destroy the premium feel.
### Feel Check
| Check | PASS/FAIL |
|---|---|
| Page entry completes in under 800ms total | |
| No element "pops" into existence without any animation | |
| Stagger follows visual hierarchy (heading before subtext before CTA) | |
| Scroll reveals trigger at a natural point (~15-20% element visibility) | |
| Hover feedback is immediate (perceived start ≤ 150ms) | |
| No animation feels "slow" or makes the user wait | |
| No animation draws attention to ITSELF rather than to the content | |
| **Cohesion test:** mute the page to just motion (blur your eyes). Do ALL animations feel like they belong to the same family? Same speed range, same intensity, same personality? | |
| **The compound test:** does the page feel "premium" without any single animation being showy? The goal is 20 invisible correct choices, not 1 theatrical one | |
### Easing Check
| Check | PASS/FAIL |
|---|---|
| No CSS keyword easings (ease, ease-in, ease-out) on visible animations | |
| All entry animations use --ease-out (snappy decel) | |
| All hover interactions use --ease-snap (energetic out) | |
| All state transitions use --ease-in-out (smooth) | |
| Easing palette is consistent across the entire page | |
### Performance Check
| Check | PASS/FAIL |
|---|---|
| All animations use ONLY `transform` and `opacity` (except clip-path reveals and filter:blur entries) | |
| No animations on `top`, `left`, `width`, `height`, `margin`, `padding` | |
| No `transition: all` anywhere - every transition specifies exact properties | |
| `will-change` is applied only to elements that are actively animating | |
| `will-change` is removed after animation completes (for one-shot animations) | |
| No `backdrop-filter` on scrolling elements (only fixed/sticky) | |
| Scroll listeners use `{ passive: true }` | |
| Page maintains 60fps during all animations (check DevTools → Performance) | |
| No layout thrashing (reading layout → writing layout in a loop) | |
| Framer Motion: no `x`/`y`/`scale` shorthand props on heavy pages - use `animate={{ transform: "translateX(100px)" }}` for GPU acceleration | |
| No CSS variable on a parent driving child transforms (e.g., `--swipe-amount`) - set `transform` directly on the element to avoid style recalculation storms | |
### Accessibility Check
| Check | PASS/FAIL |
|---|---|
| All motion respects `prefers-reduced-motion: reduce` | |
| Reduced motion fallback is opacity-only fade (no transforms, no parallax, no spring overshoot) | |
| Hover animations gated behind `@media (hover: hover) and (pointer: fine)` - touch devices fire hover on tap, causing false activation | |
| Split text has `aria-label` preserving the original text | |
| No essential information is conveyed ONLY through animation | |
| Focus states are visible and not obscured by animations | |
| Auto-playing animations (marquee, floats, gradients) can be paused (WCAG 2.2.2) | |
| Custom cursor does not appear on touch devices | |
### Technical Check
| Check | PASS/FAIL |
|---|---|
| Scroll reveal uses IntersectionObserver, not scroll event listener | |
| Scroll-linked animations use `scrub` (not triggered by scroll events) | |
| Touch devices have `smoothTouch: false` if using Lenis | |
| No scroll-jacking (overriding native scroll behavior) without clear justification | |
| Parallax is disabled on mobile (too janky on underpowered devices) | |
| Custom cursor is disabled on mobile/touch | |
| Preloader shows content within 3 seconds maximum | |
| No FOUC (flash of unstyled content) before animations initialize | |
### Composition Check
| Check | PASS/FAIL |
|---|---|
| Maximum 2-3 complex animations running simultaneously on screen | |
| No competing motion (two elements fighting for attention at the same time) | |
| Ambient motion (floats, gradients) does not compete with interactive motion | |
| Animation density matches the Motion Brief (minimal/moderate/rich) | |
| **Personality lock held:** every animation on the page belongs to the locked personality (Surgical/Physical/Cinematic). Zero personality drift. | |
| **Three-curve maximum held:** only 3 easing curves are used across the entire page. Grep the CSS - if you find a 4th curve, the palette leaked. | |
| **Intensity consistency:** scroll reveals all use the SAME transform distance (e.g., all `translateY(24px)`, not a mix of 20/30/40/60). Hover lifts all use the SAME offset (e.g., all `-4px`, not a mix). Stagger delays all use the SAME increment. | |
| Signature micro-animations are on at most 1-3 focal elements, not scattered everywhere | |
---
## The Anti-Patterns
These are the specific failures that turn premium motion into amateur animation. Check for all of them.
### ❌ The Franken-Motion
Different sections use different easing families - springs here, dramatic curves there, linear snaps elsewhere. Each animation is fine in isolation but the page feels like a patchwork quilt. **Fix:** Lock a personality in Phase 1 and enforce the Three-Curve Maximum. Every animation must belong to the same easing family. If the hero uses `--spring-snappy`, the scroll reveals use `--spring-snappy`. If the cards hover with `--ease-snap`, ALL interactive elements hover with `--ease-snap`. Cohesion is the #1 predictor of whether a page feels "premium" or "messy."
### ❌ The Slow Reveal
Everything fades in over 1.5 seconds. The page feels like it's buffering. **Fix:** Keep reveals under 800ms. The user came for content, not a curtain call.
### ❌ The Scroll Carnival
Every element has a different animation: this one slides left, that one bounces, this one rotates in. **Fix:** Use ONE reveal animation (fade-up-deblur) for all scroll reveals. Consistency reads as intentional.
### ❌ The Hover Disco
Buttons scale to 1.1x, cards rotate, links flash different colors. **Fix:** Hover effects should be subtle: 2px lift + shadow expansion for cards, background-color shift for buttons. The user shouldn't be startled.
### ❌ The Parallax Soup
Five layers of parallax on every section. Foreground, midground, background, all moving at different speeds. **Fix:** Maximum 2 parallax layers per viewport. One subtle background shift, one element float. More is motion sickness.
### ❌ The Text Disassembly
Every heading character-splits and reassembles from random positions. **Fix:** Character-split maximum ONE heading per page. Use word-reveal on section headings. Use simple fade-up on everything else.
### ❌ The Infinite Preloader
A 5-second preloader with elaborate animations before the content appears. **Fix:** Preloader maximum 2.5 seconds. If content loads faster, end sooner. Never add artificial delay.
### ❌ The Missing Reduced Motion
No `prefers-reduced-motion` media query anywhere. **Fix:** Every single animation must gate behind `prefers-reduced-motion: reduce` with an opacity-only fallback.
### ❌ The Layout Animator
Animating `width`, `height`, `top`, `left`, `padding`, `margin`, or `border-radius`. **Fix:** Only animate `transform` and `opacity`. Use `transform: scale()` instead of `width`/`height`. Use `transform: translate()` instead of `top`/`left`.
---
## Framework Decision Matrix
| If the project uses... | Use this motion stack |
|---|---|
| **Vanilla HTML/CSS/JS** | CSS keyframes + transitions + IntersectionObserver. Add GSAP only for scroll-pinning or complex timelines |
| **React (no framework)** | Framer Motion (`motion/react`). It handles AnimatePresence, layout animations, and gesture detection |
| **Next.js** | Framer Motion + View Transitions API for page transitions |
| **Vue** | `<Transition>` / `<TransitionGroup>` components + GSAP for scroll |
| **Astro** | View Transitions API (built-in) + CSS animations + GSAP for scroll |
| **Svelte** | Built-in `transition:` and `animate:` directives + GSAP for scroll |
**When to reach for GSAP:**
- Scroll-pinned (sticky) sequences where content changes as you scroll
- Horizontal scroll sections
- Complex timelines with overlapping animations
- Text splitting with SplitText plugin (premium, but best-in-class)
**When CSS is enough:**
- Entry animations (keyframes + animation-delay)
- Hover states (transitions)
- Simple scroll reveals (IntersectionObserver + CSS transitions)
- Floating/ambient motion (keyframes + infinite)
- Accordion/tab state changes (transitions)
---
## The Apple-Level Motion Standards
These are the non-negotiable standards that separate Apple/Awwwards motion from everything else. They apply regardless of framework. Memorize them.
> **Spring physics are mandatory.** Use CSS `linear()` spring curves or Framer Motion springs for EVERY primary animation (entries, reveals, modals, transitions). Cubic-bezier is acceptable only for secondary motion (hovers, color shifts, ambient). If the page feels "digital" instead of "physical," the easing is wrong.
> **Material 3 Expressive is the baseline.** Google's M3 Expressive easing - `cubic-bezier(0.05, 0.7, 0.1, 1.0)` - is the MINIMUM quality for any transition. If your easing is less intentional than this, replace it.
> **Every curve is a conscious choice.** The same 400ms animation with `ease`, `cubic-bezier(0.16, 1, 0.3, 1)`, and a spring `linear()` produces three completely different emotional responses: generic, professional, and alive. You must be able to justify WHY you chose each curve.
> **Stagger creates narrative.** Elements appearing simultaneously is a data dump. Elements appearing in sequence is a story. The stagger order IS your visual hierarchy. Apple staggers with 80-120ms precision.
> **Motion is restraint with intensity.** The most awarded sites have fewer animations, not more - but each one is more sophisticated. A single spring-physics text reveal with word masking is worth more than 20 generic fade-ins. Quality over quantity, always.
> **Performance is non-negotiable.** A 45fps animation is worse than no animation. Only animate `transform`, `opacity`, and `filter`. Test on a throttled CPU. If it's not 60fps, simplify until it is. Use `will-change` surgically.
> **Reduced motion is not optional.** Every animation gates behind `prefers-reduced-motion`. The reduced version uses opacity-only fades at shorter durations. No transforms, no parallax, no spring overshoot, no scroll-linked sequences.
> **The acid test.** Take a screenshot of your page. Put it next to apple.com, linear.app, vercel.com, or stripe.com. If your motion design looks like it belongs on a different planet, start over. If it looks like it could be a page on one of those sites, you've passed.Below-the-fold landing page sections pipeline. Companion to awwwards-hero. Covers feature showcases, social proof, pricing, process/how-it-works, case studie
---
name: awwwards-sections
description: Below-the-fold landing page sections pipeline. Companion to awwwards-hero. Covers feature showcases, social proof, pricing, process/how-it-works, case studies, stats/metrics, CTA banners, FAQs, footers, and visual break sections. Enforces the same Awwwards/FWA-tier quality gates - no generic 3-card grids, no icon+heading+paragraph repeats, no stock photography, no AI-purple gradients. Each section has named architectures with CSS blueprints, a page-level sequencing system, and a final composition diff.
---
# Awwwards-Tier Landing Page Sections
> This skill covers EVERYTHING BELOW THE HERO. It does not govern hero sections (use `awwwards-hero` for that) or animations/micro-interactions (use `awwwards-motion` for those). It fires when the user asks for a full landing page, additional sections, feature blocks, pricing, testimonials, footers, or any below-the-fold content.
> **Pairing rule:** When building a full landing page, run `awwwards-hero` for the hero, then this skill for every section below it. If motion is requested, layer `awwwards-motion` on top of both.
---
## The Pipeline
```
┌──────────────────────────────────────────────────────────────────────────┐
│ │
│ BRIEF IN ──→ Phase 1: Page Read ──→ Phase 2: Section Sequence │
│ (extract page goals, (pick sections, order them, │
│ audience, conversion assign architectures) │
│ intent) │
│ │
│ ──→ Phase 3: Build Section by Section │
│ (typography, layout, content, │
│ transitions between sections) │
│ │
│ ──→ Phase 4: Page Composition Diff │
│ (rhythm, variety, conversion flow, │
│ anti-slop audit) │
│ │
│ Each phase has a ✓ Quality Gate. Failing a gate blocks the next. │
│ │
└──────────────────────────────────────────────────────────────────────────┘
```
---
## Phase 1: Page Read
Before choosing sections, understand the PAGE as a whole. A landing page is a persuasion sequence, not a stack of unrelated blocks.
### → Extract these page signals
| Signal | What to determine |
|---|---|
| **Conversion goal** | What does this page want the visitor to DO? (Sign up, book a call, buy, download, explore portfolio) |
| **Visitor sophistication** | Technical buyers who need specs? Consumers who need emotion? Investors who need traction? |
| **Objection sequence** | What stops the visitor from converting? (Trust, price, complexity, "is this legit?", "will this work for me?") |
| **Content density** | Does the product/service have 3 features or 30? Simple value prop or complex platform? |
| **Visual assets available** | Product screenshots, case study images, team photos, client logos, video? Or text-only? |
| **Hero handoff** | What did the hero establish? (mood, palette, typography, focal element) - sections must continue this, not restart |
### → Output a Page Read before selecting sections
> *"Page Read: SaaS landing for technical PMs. Conversion goal: start free trial. Objection sequence: (1) 'what does it actually do?' → feature showcase needed, (2) 'who else uses this?' → social proof needed, (3) 'what does it cost?' → pricing needed, (4) 'is the team legit?' → brief about section. Hero established: dark mode, Geist typography, muted indigo accent, cinematic center architecture. Sections must continue this palette and type system."*
### ✓ Quality Gate: Page Read
Before moving to Phase 2, confirm:
- You know the conversion goal
- You have identified the top 3 visitor objections in order
- You understand what the hero already established (palette, typography, mood)
- You will NOT reset the design language below the fold
---
## Phase 2: Section Sequence
Select and ORDER sections. The sequence matters more than individual section quality - a page is a narrative, not a parts bin.
### → The Persuasion Sequence Framework
Landing pages follow a conversion psychology order. Not every page needs every section, but the ORDER is non-negotiable:
```
HERO (handled by awwwards-hero)
↓
1. WHAT - Feature/Value showcase (answer "what does this do?")
↓
2. PROOF - Social proof, logos, testimonials (answer "who else trusts this?")
↓
3. HOW - Process/How-it-works (answer "how does it actually work?")
↓
4. RESULTS - Case studies, stats, metrics (answer "what results does it get?")
↓
5. PRICING - Tiers, plans, comparison (answer "what does it cost?")
↓
6. OBJECTION KILLER - FAQ, comparison vs alternatives (answer remaining doubts)
↓
7. FINAL CTA - Conversion banner (last push before they leave)
↓
8. FOOTER - Navigation, legal, social links
```
### → Section selection rules
| Page type | Minimum sections | Recommended |
|---|---|---|
| **SaaS landing** | Feature + Proof + Pricing + CTA + Footer | + How-it-works + Stats |
| **Agency/studio** | Feature (portfolio) + Proof + Process + CTA + Footer | + Case studies + Pricing |
| **Personal portfolio** | Work showcase + About + CTA + Footer | + Testimonials + Process |
| **Product launch** | Feature + Proof + CTA + Footer | + Stats + Pricing |
| **Event/conference** | Speakers + Schedule + CTA + Footer | + Proof + FAQ |
### → Visual Rhythm Rules
These prevent the "wall of same" problem where every section looks identical:
| Rule | Why |
|---|---|
| **Alternate layout direction** | If Section A has content-left / visual-right, Section B must NOT repeat this. Alternate, center, or use full-width |
| **Alternate background tone every 2-3 sections** | Dark → slightly lighter dark → dark. Or light → very subtle tint → light. Never 5+ sections on identical backgrounds |
| **One "visual break" section per page** | A full-bleed image, a single giant stat, or a horizontal scroll strip. Breaks the grid pattern |
| **Typography scale shifts** | Feature headings might be `text-4xl`. The next section heading drops to `text-2xl` with a different weight. Then the CTA banner goes back to `text-5xl`. Monotone scale = monotone page |
| **Max 2 grid-based sections in a row** | If you used a 3-column grid for features, the next section CANNOT be another 3-column grid. Use asymmetric split, full-width, or centered single-column |
### ✓ Quality Gate: Sequence
Before moving to Phase 3, confirm:
- Sections follow the persuasion sequence order
- No two adjacent sections share the same layout pattern
- Background tones alternate appropriately
- At least one visual break exists in the page
- The section count matches the content density (don't pad a simple product with 12 sections)
---
## Phase 3: Build - Section Architectures
Each section type below has named architectures. Pick ONE architecture per section. Do not blend.
---
### SECTION TYPE: Feature / Value Showcase
Shows WHAT the product/service does. This is the first section below the hero - it must answer the visitor's #1 question immediately.
---
#### Feature Architecture A: The Bento Grid
*Best for: products with 4-6 distinct features of varying importance*
An asymmetric grid where the primary feature gets 2x the space. NOT a uniform grid - one cell dominates, others support.
```
[section container: py-24 lg:py-32, max-w-7xl mx-auto px-6]
[section eyebrow: small mono label, muted]
[section heading: text-4xl lg:text-5xl, max-w-3xl, mb-16]
[bento grid: grid grid-cols-2 lg:grid-cols-3 gap-4 lg:gap-6]
[primary cell: col-span-2, row-span-2, rounded-2xl, p-8-12, bg-subtle]
[feature visual: product screenshot or illustration, 60% of cell]
[feature text: heading + 1-2 line description below]
[secondary cell: rounded-2xl, p-6-8, bg-subtle]
[icon or small visual]
[heading + description]
[secondary cell: ...]
[accent cell: different bg tone or bordered, same structure]
```
```css
/* BLUEPRINT: Bento grid
WHY: auto-rows with minmax prevents cells from collapsing.
The primary cell uses col-span-2 to dominate without explicit px widths.
gap-4 is tight enough to feel connected, loose enough to breathe. */
.bento-grid {
display: grid;
grid-template-columns: repeat(3, 1fr);
grid-auto-rows: minmax(200px, auto);
gap: 1rem;
}
.bento-primary {
grid-column: span 2;
grid-row: span 2;
}
/* Mobile: stack to single column */
@media (max-width: 768px) {
.bento-grid {
grid-template-columns: 1fr;
}
.bento-primary {
grid-column: span 1;
grid-row: span 1;
}
}
```
⚠ **Drift Warning:** Bento grids fail when all cells are the same size with the same padding and the same icon-heading-text pattern. ONE cell must dominate. Vary cell heights. Use different content types (visual in one, stat in another, testimonial quote in a third).
---
#### Feature Architecture B: The Stacked Showcase
*Best for: products with 2-3 major features that each deserve dedicated space*
Each feature gets its own full-width row with alternating layout direction. Left-right, right-left, left-right. Each row is a mini-split with a large visual on one side and text on the other.
```
[section container: py-24 lg:py-32, space-y-24 lg:space-y-32]
[feature row 1: grid grid-cols-1 lg:grid-cols-2 gap-12 items-center]
[text side: heading + description + optional bullet points]
[visual side: product screenshot, rounded-2xl, shadow-xl]
[feature row 2: grid grid-cols-1 lg:grid-cols-2 gap-12 items-center]
[visual side: product screenshot] ← ORDER REVERSED
[text side: heading + description]
[feature row 3: repeat pattern]
```
⚠ **Drift Warning:** The alternation MUST be visual, not just CSS order. On desktop, the image physically sits on the opposite side. Use `lg:order-1` / `lg:order-2` to control visual placement independent of DOM order (DOM order should be text-first for accessibility).
---
#### Feature Architecture C: The Single Spotlight
*Best for: one hero feature that defines the product, or a product demo/video section*
One massive visual (product screenshot, video embed, interactive demo) centered with minimal text above. The visual IS the section.
```
[section container: py-24 lg:py-32, max-w-6xl mx-auto px-6, text-center]
[eyebrow: mono label]
[heading: text-3xl lg:text-4xl, max-w-2xl mx-auto, mb-4]
[subtext: text-lg, muted, max-w-xl mx-auto, mb-12]
[visual: rounded-2xl overflow-hidden, shadow-2xl, border border-white/10]
[product screenshot or video, full-width within container]
[optional floating detail cards: absolute positioned, showing UI details]
```
---
### SECTION TYPE: Social Proof
Answers "who else trusts this?" - the single most powerful conversion element after the hero.
---
#### Proof Architecture A: The Logo Strip
*Best for: B2B SaaS with recognizable client logos*
A single horizontal row of client logos, muted to grayscale, on a slightly different background tone. NO "Trusted by" heading in large text - the logos speak for themselves.
```
[section: py-12 lg:py-16, border-y border-white/5 (dark) or border-black/5 (light)]
[optional small label: "Trusted by teams at" - text-xs, muted, uppercase, tracking-wide, mb-6, text-center]
[logo row: flex items-center justify-center gap-12 lg:gap-16, flex-wrap]
[each logo: h-6 lg:h-8, opacity-40 hover:opacity-80, transition, grayscale]
```
```css
/* BLUEPRINT: Logo strip
WHY: Grayscale + low opacity prevents logos from competing with
the page's own brand colors. Hover reveals the real logo color,
adding a subtle interactive layer. The strip sits in a band
(border-y) to visually separate it without heavy background changes. */
.logo-strip img {
height: 2rem;
filter: grayscale(100%);
opacity: 0.4;
transition: all 0.4s cubic-bezier(0.16, 1, 0.3, 1);
}
.logo-strip img:hover {
filter: grayscale(0%);
opacity: 0.8;
}
```
---
#### Proof Architecture B: The Testimonial Cascade
*Best for: service businesses, agencies, consumer products - where human voice sells*
2-3 large testimonial cards in an asymmetric layout. NOT a uniform grid. One testimonial is larger/featured. Include real names, real titles, real photos (or quality avatars).
```
[section container: py-24 lg:py-32, max-w-7xl mx-auto px-6]
[section heading: left-aligned or centered, mb-16]
[testimonial grid: grid grid-cols-1 lg:grid-cols-3 gap-6]
[featured card: lg:col-span-2, bg-subtle, rounded-2xl, p-8-10]
[large quote: text-xl lg:text-2xl, font-medium, leading-relaxed, mb-6]
[author row: flex items-center gap-4]
[avatar: w-12 h-12 rounded-full]
[name + title: text-sm]
[secondary card: bg-subtle, rounded-2xl, p-8]
[quote: text-base, mb-6]
[author row]
[secondary card: bg-subtle, rounded-2xl, p-8]
[quote: text-base, mb-6]
[author row]
```
⚠ **Drift Warning:** Testimonial cards that all look identical with the same padding, same text size, and centered alignment are the #1 AI slop pattern for proof sections. ONE card must be visually dominant. Vary sizes. Consider pulling a single powerful sentence as a large display quote above the grid.
---
#### Proof Architecture C: The Metric Bar
*Best for: products with impressive numbers - users, revenue processed, uptime, speed*
3-4 large numbers in a horizontal strip, each with a tiny label below. Numbers are the largest text on the page outside the hero heading. Let the numbers breathe.
```
[section: py-16 lg:py-24, border-y border-white/5]
[metrics row: grid grid-cols-2 lg:grid-cols-4 gap-8, max-w-5xl mx-auto, text-center]
[metric]
[number: text-4xl lg:text-5xl, font-semibold, tracking-tight]
[label: text-sm, muted, mt-2]
[metric]
[number] [label]
...
```
```css
/* BLUEPRINT: Metric counter
WHY: Tabular figures prevent layout shift during count-up animations.
The numbers should feel monumental - they are social proof encoded
as typography. */
.metric-number {
font-variant-numeric: tabular-nums;
font-size: clamp(2rem, 4vw, 4rem);
font-weight: 600;
letter-spacing: -0.02em;
}
```
---
### SECTION TYPE: Process / How It Works
Answers "how does this actually work?" - reduces perceived complexity.
---
#### Process Architecture A: The Numbered Steps
*Best for: 3-5 step processes, onboarding flows, service delivery timelines*
Vertically stacked steps with large step numbers, connected by a subtle vertical line. Each step has a heading and 1-2 line description. Optionally, a visual on the side that changes per step.
```
[section container: py-24 lg:py-32, max-w-5xl mx-auto px-6]
[section heading + subtext, centered, mb-16]
[steps: relative, space-y-16]
[vertical line: absolute left-6 top-0 bottom-0 w-px bg-white/10 (dark)]
[step: flex gap-8 items-start]
[number circle: w-12 h-12 rounded-full border-2, flex items-center justify-center, relative z-10, bg-background]
[number: text-lg font-semibold]
[content]
[heading: text-xl font-medium, mb-2]
[description: text-base muted, max-w-lg]
```
---
#### Process Architecture B: The Horizontal Flow
*Best for: simple 3-step processes, visual learners, SaaS onboarding*
3 steps laid out horizontally with connecting arrows or lines between them. Each step has an icon or small visual, a heading, and a short description.
```
[section: py-24 lg:py-32]
[heading, centered, mb-16]
[flow: grid grid-cols-1 md:grid-cols-3 gap-0, max-w-5xl mx-auto]
[step: px-8, relative]
[icon or visual: w-12 h-12, mb-4]
[heading: text-lg font-medium, mb-2]
[description: text-sm muted]
[connector arrow: hidden on mobile, absolute right-0 top-1/4] ← between steps only
```
⚠ **Drift Warning:** This is the highest-risk architecture for AI slop - three identical boxes with icons is the default bad output. Save it ONLY for genuinely simple 3-step flows. If you have more than 3 steps, or complex steps, use Architecture A instead.
---
### SECTION TYPE: Case Studies / Results
Answers "what results does this actually get?" - proof with depth.
---
#### Case Study Architecture A: The Card Gallery
*Best for: agencies, studios, portfolios with visual work*
Large image cards in a 2-column asymmetric grid. One card is taller, creating visual tension. Each card shows a project image with the client name and a one-line result overlaid or below.
```
[section: py-24 lg:py-32, max-w-7xl mx-auto px-6]
[heading + subtext, mb-16]
[gallery: grid grid-cols-1 lg:grid-cols-2 gap-6]
[card: group, rounded-2xl, overflow-hidden, aspect-[4/3] or aspect-[3/4] - VARY]
[image: w-full h-full object-cover, transition group-hover:scale-105]
[overlay: absolute bottom-0 inset-x-0, p-6, bg-gradient-to-t from-black/60 to-transparent]
[client name: text-lg font-semibold, text-white]
[result line: text-sm text-white/70]
```
---
#### Case Study Architecture B: The Single Deep Dive
*Best for: one flagship case study that tells a story*
Full-width section dedicated to a single client story. Large hero image for the case study, followed by a 2-column layout with the challenge on one side and the results (with metrics) on the other.
```
[section: py-24 lg:py-32]
[case study image: full-width, max-h-[60vh], object-cover, rounded-2xl mx-6]
[content: grid grid-cols-1 lg:grid-cols-2 gap-12, max-w-6xl mx-auto, px-6, mt-12]
[left: challenge]
[label: "THE CHALLENGE", mono, muted, mb-4]
[text: leading-relaxed]
[right: results]
[label: "THE RESULTS", mono, muted, mb-4]
[metrics: 2-3 large numbers with labels]
[text: brief summary]
```
---
### SECTION TYPE: Pricing
Answers "what does it cost?" - must feel transparent, not overwhelming.
---
#### Pricing Architecture A: The Clean Tiers
*Best for: SaaS with 2-3 plans*
2-3 pricing cards side by side. The recommended plan is visually elevated (different background, subtle border glow, or "Popular" badge). Cards are NOT identical height - the popular plan can be slightly taller.
```
[section: py-24 lg:py-32, max-w-5xl mx-auto px-6]
[heading + subtext, centered, mb-4]
[optional billing toggle: monthly/annual, centered, mb-12]
[pricing grid: grid grid-cols-1 md:grid-cols-3 gap-6 items-start]
[plan card: rounded-2xl, border, p-8]
[plan name: text-lg font-medium, mb-2]
[plan description: text-sm muted, mb-6]
[price: text-4xl font-semibold + period label, mb-8]
[feature list: space-y-3, text-sm]
[feature: flex items-center gap-3, check icon + text]
[CTA button: w-full, mt-8]
[popular plan: same structure but - bg-accent/5, border-accent/20, ring-1 ring-accent/10]
[badge: "Most popular" - absolute or inline, small pill]
```
⚠ **Drift Warning:** Pricing cards with 15+ features listed in tiny text are unreadable. Max 6-8 features per card. Lead with the differentiating features, not the ones shared across all plans.
---
#### Pricing Architecture B: The Comparison Table
*Best for: complex products with many differentiating features*
A full comparison matrix below simplified plan cards. The cards show price + CTA only. The table below shows detailed feature comparisons with checkmarks.
```
[plan summary: grid grid-cols-3, each card minimal - name + price + CTA]
[comparison table: mt-12, w-full]
[table head: plan names as columns]
[table body: feature categories as groups]
[category heading: font-semibold, bg-subtle, full-width]
[feature rows: text-sm, check/x/dash per plan]
```
---
### SECTION TYPE: FAQ
Kills remaining objections. The last defense before the final CTA.
---
#### FAQ Architecture A: The Accordion
*Best for: 5-8 common questions*
Single-column accordion with smooth expand/collapse. Questions are left-aligned, answers expand below with gentle height animation. A subtle rotation on the chevron/plus icon.
```
[section: py-24 lg:py-32, max-w-3xl mx-auto px-6]
[heading, centered or left, mb-12]
[accordion: divide-y divide-white/10]
[item: py-5]
[trigger: flex justify-between items-center, cursor-pointer, w-full]
[question: text-base font-medium, text-left]
[icon: w-5 h-5, transition rotate, text-muted]
[answer panel: overflow-hidden, transition max-height]
[answer text: text-sm muted, pt-4, leading-relaxed, max-w-2xl]
```
```css
/* BLUEPRINT: Accordion animation
WHY: max-height transition is the simplest pure-CSS accordion.
grid-template-rows: 0fr → 1fr is smoother but requires
wrapping content in an inner div with overflow:hidden.
The cubic-bezier gives a snappy open, gentle close. */
.faq-answer {
display: grid;
grid-template-rows: 0fr;
transition: grid-template-rows 0.35s cubic-bezier(0.16, 1, 0.3, 1);
}
.faq-answer[data-open="true"] {
grid-template-rows: 1fr;
}
.faq-answer > div {
overflow: hidden;
}
```
---
### SECTION TYPE: Final CTA Banner
The last conversion push. This section exists ONLY to get the click.
---
#### CTA Architecture A: The Full-Width Banner
*Best for: any page - this is the universal closer*
A full-width band with a contrasting background (if the page is dark, consider a slightly lighter dark or a subtle gradient). Large heading, short subtext, single prominent CTA button.
```
[section: py-20 lg:py-28, text-center]
[optional subtle background: bg-gradient or slightly shifted tone]
[heading: text-3xl lg:text-5xl, font-semibold, tracking-tight, mb-4]
[subtext: text-lg muted, max-w-xl mx-auto, mb-8]
[CTA button: large pill, px-10 py-4, font-medium]
```
⚠ **Drift Warning:** CTA banners with 3 buttons, a form, social links, and a paragraph of text are anti-patterns. ONE heading. ONE button. That's it. The simplicity is the persuasion.
---
#### CTA Architecture B: The Split CTA
*Best for: pages where you want to show a visual alongside the final push*
Two-column split: compelling visual (product shot, illustration, or abstract) on one side, heading + CTA on the other. The visual reinforces the value prop one last time.
```
[section: py-24 lg:py-32, grid grid-cols-1 lg:grid-cols-2 gap-12 items-center, max-w-6xl mx-auto px-6]
[visual side: rounded-2xl, overflow-hidden]
[text side]
[heading: text-3xl lg:text-4xl, font-semibold, mb-4]
[subtext: muted, mb-8]
[CTA button]
```
---
### SECTION TYPE: Footer
Not an afterthought. The footer is the last thing a visitor sees if they scroll to the bottom without converting.
---
#### Footer Architecture A: The Minimal Strip
*Best for: landing pages, product launches - pages with a single conversion goal*
A single row: logo on the left, essential links in the center, social icons on the right. No multi-column mega-footer.
```
[footer: border-t border-white/10, py-8 lg:py-12, px-6]
[inner: max-w-7xl mx-auto, flex flex-col lg:flex-row items-center justify-between gap-6]
[logo: h-6 or text-lg font-semibold]
[links: flex gap-6, text-sm, muted, hover:text-white transition]
[right: flex items-center gap-4]
[social icons: w-5 h-5 each, muted, hover:text-white]
[copyright: text-center lg:text-left, text-xs, muted, mt-8 lg:mt-0]
```
---
#### Footer Architecture B: The Structured Footer
*Best for: multi-page sites, SaaS products, agencies - where navigation matters*
Multi-column grid with link categories. Logo + tagline on the far left, 3-4 link columns, newsletter signup on the far right.
```
[footer: border-t border-white/10, py-16 lg:py-20, px-6]
[inner: max-w-7xl mx-auto, grid grid-cols-2 lg:grid-cols-5 gap-8]
[brand col: lg:col-span-1]
[logo]
[tagline: text-sm muted, mt-3, max-w-xs]
[link col: space-y-3]
[column heading: text-sm font-semibold, mb-4]
[link: text-sm muted hover:text-white]
...
[link col] [link col]
[newsletter col: lg:col-span-1]
[heading: text-sm font-semibold, mb-4]
[email input + submit button: flex]
[bottom bar: mt-12 pt-8 border-t border-white/5, flex justify-between, text-xs muted]
[copyright]
[legal links: privacy, terms]
```
---
### SECTION TYPE: Visual Break
Prevents "wall of same" - a breathing moment in the page.
---
#### Break Architecture A: The Full-Bleed Image
A single full-width atmospheric image with no text overlay. Serves as a palette cleanser between content-heavy sections.
```
[section: py-0, -mx-6 or full-bleed via 100vw trick]
[image: w-full, h-[40vh] lg:h-[60vh], object-cover]
```
---
#### Break Architecture B: The Giant Stat
One massive number or statement centered in a generous vertical space. Nothing else.
```
[section: py-24 lg:py-40, text-center]
[stat: text-6xl lg:text-8xl, font-semibold, tracking-tight]
[label: text-sm muted, mt-4]
```
---
#### Break Architecture C: The Horizontal Marquee
A continuous scrolling strip of text, logos, or tags. CSS-only, no JS required.
```
[section: py-6, overflow-hidden, border-y border-white/5]
[marquee track: flex gap-8, animate-scroll]
[items repeated 2x for seamless loop]
```
```css
/* BLUEPRINT: CSS marquee
WHY: Translating the full width then resetting creates a seamless loop.
Duplicating the content ensures no gaps during the loop.
30s is slow enough to be ambient. */
@keyframes marquee-scroll {
0% { transform: translateX(0); }
100% { transform: translateX(-50%); }
}
.marquee-track {
animation: marquee-scroll 30s linear infinite;
width: max-content;
}
```
---
### ✓ Quality Gate: Build
Before moving to Phase 4, confirm for EACH section:
- Architecture was followed without blending
- Content is realistic (no "Lorem ipsum", no "[Feature Name]" placeholders)
- Section heading uses a DIFFERENT scale than the previous section's heading
- Background tone is NOT identical to the adjacent section
- The section could stand alone on Awwwards SOTD nominees
---
## Phase 4: Page Composition Diff
After all sections are built, audit the FULL PAGE as a composition. This catches problems that only appear when sections are stacked together.
### Visual Rhythm Diff
| Check | PASS/FAIL |
|---|---|
| No two adjacent sections share the same layout direction (both left-aligned, both centered, etc.) | |
| No two adjacent sections have identical background colors | |
| At least ONE visual break section exists somewhere in the page | |
| Section headings vary in scale (not all `text-4xl`) | |
| Grid sections are separated by non-grid sections | |
### Content Quality Diff
| Check | PASS/FAIL |
|---|---|
| No placeholder text ("Lorem ipsum", "[Feature Name]", "Description goes here") | |
| No AI cliches ("Elevate", "Seamless", "Unleash", "Next-Gen", "Revolutionize") | |
| Feature descriptions are specific, not generic ("Process 10k API calls/sec" not "Lightning fast performance") | |
| Testimonial quotes sound human, not corporate | |
| Stats use specific numbers, not rounded ("12,847 teams" not "10,000+ teams") | |
### Conversion Flow Diff
| Check | PASS/FAIL |
|---|---|
| Persuasion sequence order is maintained (WHAT → PROOF → HOW → RESULTS → PRICE → OBJECTIONS → CTA) | |
| CTA is repeated max 2-3 times across the full page (hero CTA + final CTA + optionally one mid-page) | |
| The final CTA section exists and is NOT the footer | |
| No more than 3 sections exist between the hero CTA and the next CTA opportunity | |
### Anti-Slop Diff
| Check | PASS/FAIL |
|---|---|
| No section uses the icon + heading + paragraph × 3 equal columns pattern (the #1 AI default) | |
| No generic stock photography (use product screenshots, illustrations, or `picsum.photos/seed/{keyword}/{w}/{h}`) | |
| No AI-purple/blue gradient backgrounds | |
| No "gradient mesh blob" backgrounds | |
| No cards-inside-cards-inside-cards nesting | |
| No section has more than 3 competing CTAs | |
| Feature cards are NOT all the same height with the same padding and the same structure | |
### Mobile Composition Diff
| Check | PASS/FAIL |
|---|---|
| All multi-column layouts collapse to single column below 768px | |
| Section spacing reduces proportionally on mobile (`py-24 → py-16`) | |
| No horizontal overflow on any section | |
| Images scale or hide appropriately | |
| Touch targets minimum 44px | |
---
## Section Transition Patterns
How sections connect to each other is as important as the sections themselves. Do NOT just stack sections with identical padding.
### → Background Transitions
| Pattern | When to use |
|---|---|
| **Subtle tone shift** | `bg-[#0a0a0a]` → `bg-[#111111]` → `bg-[#0a0a0a]`. 90% of transitions. Nearly invisible but prevents flatness |
| **Border separator** | `border-t border-white/5` between sections. Clean, editorial |
| **Gradient bleed** | Section A's background gradient bleeds into Section B's top edge. Creates flow |
| **Hard contrast** | Dark section → light section or vice versa. Use sparingly (max once per page) for dramatic effect |
### → Spacing Rhythm
| Section type | Vertical padding |
|---|---|
| Content-heavy (features, pricing, FAQ) | `py-24 lg:py-32` |
| Visual break (image, stat, marquee) | `py-8 lg:py-16` or `py-0` |
| Proof strip (logos) | `py-12 lg:py-16` |
| CTA banner | `py-20 lg:py-28` |
| Footer | `py-12 lg:py-20` |
---
## The Core Principles (Sections)
These apply to every section regardless of architecture:
> **Sections are not islands.** Every section must feel like it belongs to the same page as the hero. Same palette, same type system, same visual language. A section that could be dropped into any random landing page is a generic section.
> **Show, don't tell.** Product screenshots beat feature lists. Real metrics beat adjectives. Client logos beat "trusted by thousands." Visual evidence converts harder than written claims.
> **Vary the rhythm.** A page where every section is `py-32, centered heading, 3-column grid, repeat` is a wall. Alternate densities, layout directions, background tones, and content types.
> **Kill the third card.** If you catch yourself making a 3-equal-card grid for the third time on the same page, stop. Use a different architecture. The 3-card grid is the most overused pattern in web design.
> **One section, one job.** Each section answers ONE visitor question. If a section is trying to showcase features AND display testimonials AND show pricing, split it into separate sections.Premium brand-kit image generation skill for producing identity-studio-grade brand boards. Fires when the user asks for brand kits, logo concepts, identity system
---
name: brandkit-gen
description: Premium brand-kit image generation skill for producing identity-studio-grade brand boards. Fires when the user asks for brand kits, logo concepts, identity systems, brand-system presentations, or brand-guidelines decks. Enforces an 8-phase pipeline - Visual Reference Acquisition (Phase 0), Brand Strategy, Identity Architecture, Panel Composition, Prompt Engineering, Visual Diff, Panel Surgery (Phase 6), Logo Originality Gate (Phase 7) - with quality gates at every phase. Phase 0 asks for a visual reference image and auto-generates a REFERENCE INSTRUCTION block that extracts texture, layout, and color DNA while blocking name/logo/palette cloning. Phase 6 enables single-panel regeneration and Figma compositing when individual panels fail. Phase 7 forces a geometry-difference audit between the generated mark and the reference image's symbol. 14 visual modes (including 4 reference-calibrated modes trained against Polished Snow, Nexus, Lumora, Thesis, and NORI studio work), 6 board layouts (including Mega System for 18-21 panels), logo hard constraints (3-primitive cap, favicon gate, one-sentence geometry rule), 25-point pre-flight checklist, detailed mockup specs (website hero, social media profile, app icon dock, physical products), and aggressive anti-slop protocol. Image generation only. Does not write code.
---
# Brand-Kit Image Generation
> This skill fires when the user asks to generate brand-kit images, logo concept boards, identity system overviews, brand-guidelines decks, brand-system presentations, or any composed image showing a brand system across multiple panels. You are a senior identity designer presenting to a client. Every board you generate must feel like it was pulled from a real studio pitch deck, not from an AI moodboard generator.
---
# THE HARD OUTPUT RULE - READ FIRST
**Generate ONE composed brand-kit board per request. Always.**
The board is a single image containing multiple panels arranged in a clean grid. Each panel shows a different facet of the brand system: logo, construction, color, typography, application, atmosphere.
- One brand requested → 1 board image
- Multiple concepts → 1 board per concept (announce each)
- Refinement pass → 1 updated board
Default format: landscape, 4:3 or 16:10 aspect ratio. Override only if the user specifies otherwise.
This is not a collection of separate images. It is one composed presentation board. The grid, gutters, and panel relationships ARE the design.
---
# THE CORE DOCTRINE
Before entering the pipeline, internalize these. They override every aesthetic preference. The quality bar is **real identity studio pitch decks: Pentagram case studies, Collins brand systems, Wolff Olins identity reveals, Base Design presentations.** If your generated board would look like a Canva template next to these, it is not good enough.
> **A brand board is a visual argument.** It is not decoration. It is not a moodboard. It is a structured case for why this brand exists, what it stands for, and how it scales. Every panel must contribute evidence to that argument.
> **The logo is the thesis statement.** It carries the brand's core metaphor in reduced form. A logo that does not connect to the brand idea is a clip-art icon with a name next to it. The logo must be simple enough to work at 16px and meaningful enough to reward inspection at 1600px.
> **Restraint is the premium signal.** Generic AI brand output is loud, busy, and scattered. Premium identity work is quiet, sparse, and intentional. When in doubt, remove an element. The board should feel like it has too much space, not too little.
> **One idea per board.** The board presents ONE brand direction. Not three options. Not a comparison. One committed identity system explored across multiple applications. If the user wants alternatives, generate separate boards announced sequentially.
> **Consistency IS the system.** The logo mark must appear identically across every panel where it shows. The palette must thread through every panel. The type hierarchy must be the same in the tagline panel and the UI mockup panel. If any panel feels like it belongs to a different brand, the system is broken.
---
# THE PIPELINE
```
┌──────────────────────────────────────────────────────────────────────┐
│ │
│ BRIEF IN ──→ Phase 0: Visual Reference Acquisition │
│ (ask for inspiration image, generate │
│ REFERENCE INSTRUCTION block, extract │
│ texture/layout/color DNA, block cloning) │
│ │
│ ──→ Phase 1: Brand Strategy │
│ (extract signals, infer meaning, │
│ commit to the brand's core idea) │
│ │
│ ──→ Phase 2: Identity Architecture │
│ (commit to combinatorial picks: │
│ visual mode, board layout, logo method, │
│ symbol logic, palette, type, canvas) │
│ │
│ ──→ Phase 3: Panel Composition │
│ (assign role + anchor + energy to each panel, │
│ enforce rhythm and variety) │
│ │
│ ──→ Phase 4: Prompt Engineering │
│ (build structured prompt from blueprint, │
│ include anti-pattern bans, │
│ prepend REFERENCE INSTRUCTION if Phase 0 active) │
│ │
│ ──→ Phase 5: Visual Diff │
│ (audit against strategy, check for │
│ AI default drift, verify identity coherence) │
│ │
│ ──→ Phase 6: Panel Surgery │
│ (identify weak panels, regenerate individually, │
│ guide Figma compositing for manual replacement) │
│ │
│ ──→ Phase 7: Logo Originality Gate │
│ (geometry-difference audit between generated │
│ mark and reference symbol, force divergence) │
│ │
│ Each phase has a ✓ Quality Gate. Failing a gate blocks the next. │
│ │
└──────────────────────────────────────────────────────────────────────┘
```
---
## Phase 0: Visual Reference Acquisition
The single biggest quality lever in brand-kit generation is a **visual reference image.** Text-only prompts consistently produce generic output. A high-quality reference image from a real studio (Pentagram, Collins, Base Design, or Behance case studies) anchors the AI model to a specific quality bar and aesthetic DNA.
### → Step 1: Ask for a Reference Image
If the user has NOT provided a reference image, ask:
> *"Do you have a brand board, moodboard, or visual identity you admire? Attach it as an image - I'll extract its visual DNA (texture, layout rhythm, color logic, typography contrast) and build your board at the same quality bar without copying the source."*
If the user skips or declines, proceed to Phase 1 without a reference. The rest of the pipeline works without it - Phase 0 is an accelerator, not a requirement.
### → Step 2: Analyze the Reference Image
When the user provides a reference, analyze it for these DNA strands:
| DNA Strand | What to extract |
|---|---|
| **Surface Treatment** | What is the background material? Risograph grain, airbrush diffusion, clean paper, dark matte, gradient mesh, halftone dot pattern, film grain |
| **Layout Formula** | How are panels arranged? Floating cards on canvas, edge-to-edge tiles, mixed full-bleed + framed, asymmetric bento |
| **Card/Panel Structure** | Are panels flat rectangles, floating rounded cards with margins, outlined frames, or overlapping layers? What is the relationship between card and canvas? |
| **Color Architecture** | What is the dominant/accent split? How many hues? Is it monochromatic + one accent, duotone, triadic, analogous? What specific hex range? |
| **Typography Contrast** | What is the type scale? Editorial serif + grotesque sans? Monospace + display? What is the ratio of heading to label? |
| **Illustration Style** | Isometric 3D, flat vector, photographic, duotone, stencil/halftone, architectural wireframe, retro-modern |
| **Logo Presentation** | Is the mark shown as solid white, gradient-filled, stenciled/dotted, outlined, embossed, 3D rendered? |
| **Unique Signature Moves** | What makes THIS reference special? (e.g., Lockbox's floating charcoal cards on pastel paper, Lumora's chromatic airbrush diffusion, Thesis's soft gradient blobs) |
### → Step 3: Generate the REFERENCE INSTRUCTION Block
Build a `REFERENCE INSTRUCTION` block that goes at the **top of the final prompt** (Phase 4). This block has two halves:
**Half 1: EXTRACT (what to replicate):**
Describe the surface treatment, layout formula, card structure, color architecture, typography contrast, and illustration style using precise, visual language. Reference specific hex values, texture names, and spatial relationships.
**Half 2: BLOCK (what NOT to copy):**
Explicitly ban cloning the reference's logo mark, brand name, tagline, specific illustrations/icons, and exact color palette. Force the AI to apply the reference's QUALITY STANDARD to a completely new identity.
### → REFERENCE INSTRUCTION Template
```
REFERENCE INSTRUCTION - [REFERENCE NAME] AESTHETIC REPRODUCTION:
You must replicate the EXACT [surface treatment] and [layout formula] of the attached moodboard image:
1. [DNA STRAND 1 - e.g., SURFACE TREATMENT]: [precise description with hex values and texture names]
2. [DNA STRAND 2 - e.g., CARD STRUCTURE]: [precise description of card-to-canvas relationship]
3. [DNA STRAND 3 - e.g., ILLUSTRATION STYLE]: [precise description]
4. [DNA STRAND 4 - e.g., COLOR SYSTEM LAYOUT]: [precise description of how colors are presented]
5. [DNA STRAND 5 - e.g., UNIQUE SIGNATURE MOVE]: [what makes the reference special]
DO NOT copy the "[reference brand name]" name, DO NOT copy [describe reference logo geometry], DO NOT copy [reference-specific illustrations/icons], and DO NOT use [reference's exact palette] - apply [your chosen palette] instead.
```
### → Quality Signal: Image Resolution
If the user provides a low-resolution reference (under 512px), warn them:
> *"Your reference image is low-res - the AI can still extract the aesthetic direction, but higher resolution (1024px+) will give sharper typography, cleaner textures, and more faithful reproduction of fine details like grain and color gradients."*
Proceed regardless. Low-res references still dramatically outperform no reference at all.
### ✓ Quality Gate: Reference Acquisition
Before moving to Phase 1, confirm:
- Reference image has been analyzed (or user declined to provide one)
- All 8 DNA strands are extracted (if reference provided)
- REFERENCE INSTRUCTION block is written with both EXTRACT and BLOCK halves
- The BLOCK half explicitly bans the reference's logo, name, and palette
- The REFERENCE INSTRUCTION block is ready to prepend to the Phase 4 prompt
---
## Phase 1: Brand Strategy
Before generating anything, extract the brand's meaning. Do not skip this. The entire visual system flows from the strategy. A board built without strategy is just arranged rectangles.
### → Extract these signals
| Signal | What to look for |
|---|---|
| **Category** | Developer tool / AI product / Security / Fintech / Consumer app / Gaming / Voice AI / Compliance / Drone-robotics / Luxury / Editorial / Productivity / Health / Education / Creative tool / Enterprise SaaS |
| **Audience** | Who uses this product and what do they care about? Engineers, executives, consumers, creators, operators |
| **Product function** | What does the product actually do? Build, protect, convert, speak, automate, monitor, create, organize |
| **Emotional promise** | What feeling does the brand deliver? Confidence, precision, freedom, safety, delight, control, clarity |
| **Cultural position** | Where does the brand sit? Premium-serious, playful-accessible, technical-expert, warm-human, bold-creative |
| **Trust level** | How much trust must the brand project? High (security, finance, health) / Medium (SaaS, productivity) / Low-barrier (consumer, gaming) |
| **Visual world** | What does this brand's universe look like? Dark terminals, warm paper, clean glass, industrial metal, organic nature |
| **Core metaphor** | The single abstract idea the brand embodies. Building, shielding, navigating, illuminating, orchestrating |
| **What to avoid** | Explicit anti-signals from the brief. "Not corporate," "not playful," "not generic AI" |
| **Reference quality** | If references are provided: extract grid style, spacing, density, typography scale, accent logic, image treatment |
### → Output the Brand Strategy Brief
State in 3-5 lines the identity direction you are committing to:
> *"Strategy Brief: Dark developer-tool identity for an AI coding agent. Category: developer infrastructure. Audience: senior engineers who ship fast and distrust marketing fluff. Core metaphor: the scaffold - the invisible structure that holds everything together while you build. Emotional promise: quiet confidence and precision. Trust level: high, earned through restraint. Visual world: near-black panels, monospace accents, construction diagrams, terminal chrome. The brand should feel like it was designed by an engineer who also studied typography."*
### → If the brief is vague
Ask exactly ONE question: *"What's the brand name, what does the product do in one line, and is the energy closer to [dark technical] or [light editorial]?"*
If you can infer from context, skip the question and declare your Strategy Brief.
### → Brand-to-Symbol Mapping
Use this to derive symbol logic from the strategy. Do not pick symbols randomly. The symbol must connect to the product's core action or metaphor.
| Product Verb | Symbol Pool |
|---|---|
| Build / create / ship | Scaffold, frame, block, cursor, cornerstone, beam |
| Protect / monitor / guard | Boundary, watchtower, iris, perimeter, seal |
| Connect / integrate / bridge | Node, junction, handshake, bridge, thread |
| Analyze / search / discover | Lens, trace, signal, radar, spectrum |
| Automate / orchestrate / flow | Loop, relay, conductor, chain, rhythm |
| Speak / communicate / assist | Pulse, waveform, beacon, dialogue, resonance |
| Organize / manage / control | Grid, register, index, calibration, dial |
| Compete / win / perform | Edge, apex, vector, strike, crown |
| Design / craft / refine | Chisel, press, specimen, plate, mark |
| Grow / nurture / sustain | Root, canopy, cycle, bloom, terroir |
### ✓ Quality Gate: Strategy
Before moving to Phase 2, confirm:
- All 10 signals are extracted (or inferred)
- Brand Strategy Brief is written (3-5 lines, committed direction)
- Core metaphor is identified and specific (not "innovation" or "technology")
- Symbol pool is narrowed to 2-3 candidates from the mapping table
- You have NOT started generating any images yet
---
## Phase 2: Identity Architecture (The Combinatorial Engine)
For each category below, commit to ONE option based on the strategy. Do not blend. Do not hedge. Pick and commit. The picks must be internally consistent.
---
### → Visual Mode (pick 1)
Choose the mode that matches the brand's category and cultural position. Each mode defines the board's tonal universe - canvas, accents, logo logic, and mood.
#### Mode 1: Dark Developer / Builder
Use for: developer tools, coding agents, infrastructure, automation, AI builders.
- **Canvas:** near-black `#0a0a0a` to `#1a1a1a`
- **Accents:** cyan `#00d4aa`, electric blue `#3b82f6`, coral `#f97066`, or lime `#84cc16`
- **Visual cues:** monospace accents, command lines, terminal windows, prompt bars, subtle grid, pixel or CRT texture
- **Logo logic:** cursor + frame, bolt + build speed, scaffold + monogram, terminal glyph + symbol, modular construction mark
- **Palette example:** `#0a0a0a` base / `#1a1a1a` surface / `#f0ede8` text / `#00d4aa` accent
- **Mood:** precise, sharp, confident, builder-native
#### Mode 2: Dark Product / Operator
Use for: business tools, growth tools, sales agents, automation, productivity SaaS.
- **Canvas:** black to deep charcoal `#0f0f0f`
- **Accents:** amber `#f59e0b`, red `#ef4444`, warm gold `#d4a853`
- **Visual cues:** glowing UI chips, card systems, segmented flows, icon rows, reward/progress motifs, minimal hero text
- **Logo logic:** signal, gift, path, operator mark, switch, loop, command system
- **Palette example:** `#0f0f0f` base / `#1c1917` surface / `#fafaf9` text / `#f59e0b` accent
- **Mood:** fast, operational, tactical, premium
#### Mode 3: Dark Nature / Calm System
Use for: strategy tools, travel, wellness, climate, quiet premium SaaS.
- **Canvas:** deep forest `#0d1a0f` to charcoal `#141414`
- **Accents:** lime `#a3e635`, sage `#86efac`, mist blue `#7dd3fc`
- **Visual cues:** misty landscapes, image UI circles, soft overlays, calm page labels, dark editorial grid
- **Logo logic:** path, leaf, moon, horizon, compass, portal, folded mark
- **Palette example:** `#0d1a0f` base / `#1a2e1c` surface / `#e8f5e9` text / `#a3e635` accent
- **Mood:** calm, trustworthy, focused
#### Mode 4: Dark Security / Threat Intelligence
Use for: cybersecurity, compliance monitoring, network products, threat detection.
- **Canvas:** black to deep navy `#0a0e1a`
- **Accents:** red `#ef4444`, electric blue `#3b82f6`, amber warning `#f59e0b`
- **Visual cues:** shield forms, radar lines, threat labels, subtle motion traces, alert chips, controlled gradients
- **Logo logic:** shield, raptor, eye, watch, boundary, protected core, iris
- **Palette example:** `#0a0e1a` base / `#111827` surface / `#e2e8f0` text / `#ef4444` accent
- **Mood:** serious, vigilant, precise
#### Mode 5: Light Editorial / Compliance
Use for: legal tech, privacy, compliance, documents, trust-first brands, institutional.
- **Canvas:** warm ivory `#fdfbf7` to cream `#faf5ef`
- **Accents:** deep blue `#1e40af`, crimson `#b91c1c`, gold `#b8860b`
- **Visual cues:** paper texture, small serif labels, seals / badges, color wheel / palette object, calm stationery
- **Logo logic:** seal, dog, shield, document, stamp, monogram, embossed mark
- **Palette example:** `#fdfbf7` base / `#f5f0e8` surface / `#1a1a1a` text / `#1e40af` accent
- **Mood:** trustworthy, refined, institutional but modern
#### Mode 6: Luxury / Beauty / Fashion
Use for: beauty, fashion, hospitality, premium services, high-end consumer.
- **Canvas:** ivory `#faf8f5` to stone `#e8e0d5` to espresso `#2c1810`
- **Accents:** gold `#c9a961`, blush `#e8b4b8`, deep burgundy `#722f37`
- **Visual cues:** serif wordmark, elegant monogram, paper grain, embossing, product labels, editorial crops, soft shadows
- **Logo logic:** monogram, seal, petal, vessel, ritual object, refined typographic mark
- **Palette example:** `#faf8f5` base / `#e8e0d5` surface / `#2c1810` text / `#c9a961` accent
- **Mood:** tasteful, adult, visually expensive
#### Mode 7: Voice / Communication
Use for: voice AI, chat products, assistants, speech technology, audio platforms.
- **Canvas:** deep indigo `#0f0720` to charcoal `#121212`
- **Accents:** lilac `#c084fc`, soft purple `#a78bfa`, warm pink `#f472b6`
- **Visual cues:** waveform motifs, mic elements, phone crops, command input, app icon, orbital rings
- **Logo logic:** wave + initial, sound orb, speech path, microphone abstraction, pulse ring
- **Palette example:** `#0f0720` base / `#1a1030` surface / `#f0e6ff` text / `#c084fc` accent
- **Mood:** fluid, intelligent, intimate
#### Mode 8: Cultural / Experimental
Use for: music, creative tools, events, gaming-adjacent, cultural products, studios.
- **Canvas:** near-black `#0a0a0a` to warm charcoal `#1f1a15`
- **Accents:** bold red `#e11d48`, electric yellow `#facc15`, hot orange `#f97316`
- **Visual cues:** halftone textures, CRT grain, analog print effects, bold accent color, poster-style panels, unexpected image crops
- **Logo logic:** custom wordmark, icon with attitude, symbolic mascot, print-inspired mark
- **Palette example:** `#0a0a0a` base / `#1f1a15` surface / `#fafaf9` text / `#e11d48` accent
- **Mood:** memorable, creative, still controlled
#### Mode 9: Enterprise SaaS / Productivity
Use for: project management, collaboration, analytics, B2B platforms, workflow tools.
- **Canvas:** cool gray `#f8fafc` to slate `#f1f5f9`
- **Accents:** indigo `#4f46e5`, teal `#0d9488`, blue `#2563eb`
- **Visual cues:** clean card systems, subtle grid overlays, metric strips, structured navigation, tab systems, clean iconography
- **Logo logic:** grid, block, check, path, stack, module, structured monogram
- **Palette example:** `#f8fafc` base / `#f1f5f9` surface / `#0f172a` text / `#4f46e5` accent
- **Mood:** professional, clear, trustworthy, approachable
(Omitted for brevity - same as input)
...
#### Mode 10: Gaming / Betting / Competition
Use for: esports, betting platforms, competitive apps, game studios, reward systems.
- **Canvas:** deep black `#050505` to dark purple `#0d0015`
- **Accents:** neon green `#22c55e`, gold `#eab308`, hot pink `#ec4899`
- **Visual cues:** dice, gems, card motifs, signal flashes, trophy elements, speed lines, bold typography, reward UI chips
- **Logo logic:** dice + brand, gem + initial, card suit + symbol, crown + mark, lightning + game element
- **Palette example:** `#050505` base / `#0d0015` surface / `#f0f0f0` text / `#22c55e` accent
- **Mood:** electric, rewarding, high-energy but controlled
#### Mode 11: Warm Editorial / Humanist
Use for: AI products with humanist positioning, knowledge platforms, research tools, education, cultural institutions, brands that want to signal intellectual depth.
This mode draws directly from studio reference work (Polished Snow, Nexus) where classical art, Renaissance painting, and botanical illustration carry the brand's conceptual weight. The imagery IS the argument - it says "we are built on centuries of human thought."
- **Canvas:** warm cream `#faf5ef` to ivory `#fdfbf7`
- **Accents:** muted gold `#b8a472`, deep navy `#1a2744`, warm stone `#8c7b6b`
- **Visual cues:** Renaissance or classical painting panels treated with pixel-halftone or mosaic texture, botanical illustrations, warm editorial cards, serif-italic emphasis words, art-historical imagery as brand-world panels, social media profile cards, editorial website hero mockups
- **Logo logic:** extremely simple geometric marks - 2-3 shapes maximum (e.g., four offset squares, rounded cross in circle). The logo must be so simple it disappears next to the rich imagery. Complexity lives in the image-world, not the mark
- **Typography:** serif + sans pairing. Use serif italic for one emphasis word in the tagline (e.g., "Connecting human potential with infinite *intelligence*"). Display sans for headings, refined serif for accents
- **Image-world:** Classical paintings, Renaissance scenes, flowers, Greek/Roman architecture - but ALWAYS treated with a brand-specific texture (pixel-mosaic, halftone, duotone wash). Raw unprocessed fine art looks like a Wikipedia illustration. Treated fine art looks like a brand decision
- **Color system:** horizontal bar strips showing warm neutrals derived from the art - sand, cream, stone, steel blue, gold, navy
- **Palette example:** `#faf5ef` base / `#f0e8da` surface / `#1a1a1a` text / `#b8a472` gold accent / `#1a2744` navy secondary
- **Mood:** considered, intelligent, warm, institutional-modern, the visual equivalent of a well-lit library
#### Mode 12: Saturated Studio / Agency
Use for: creative agencies, design studios, branding firms, creative SaaS products, marketing platforms, brands that sell craft.
This mode draws from studio reference work (Lumora) where vibrant gradient-noise textures become the entire visual world. No photography. No stock imagery. The brand IS the material.
- **Canvas:** the brand's primary saturated color IS the canvas (e.g., electric orange `#ff4d00`, deep pink `#e91e8c`, vivid purple `#6f2dbd`). Panels sit ON the saturation
- **Accents:** complementary to the primary saturation - navy `#1a1a4e` on orange, white `#fafafa` on pink, warm terracotta on purple
- **Visual cues:** noise-gradient backgrounds (mesh gradients with grain), geometric logo construction diagrams with Venn-diagram logic and labeled concept intersections ("Strategic Vision" + "Humanistic Touch" = "Brand Factor"), business card mockups in multiple color variants, radial gradient burst backgrounds, dark variant panels showing the system's versatility
- **Logo logic:** geometric flower/petal forms constructed from overlapping circles. The construction diagram panel must show the circles and their intersections - the logo emerges from the geometry. Label the concept zones. This is the proof that the mark is designed, not decorated
- **Typography:** modern geometric sans, strong scale contrast (very large display + very small labels), white on saturated backgrounds
- **Image-world:** gradient-noise textures ARE the brand - blurred mesh gradients, grainy color fields, radial glows. These are not backgrounds. They are the visual world. Zero photography
- **Color system:** named color chips on dark backgrounds - "Flame Orange #FF4D00", "Deep Iris #6F2DBD" - or gradient arcs showing the full noise palette
- **Palette example:** `#ff4d00` primary / `#6f2dbd` secondary / `#1a1a4e` dark surface / `#fafafa` text / `#e8b4b8` tertiary
- **Mood:** confident, vibrant, craft-forward, studio energy, the visual equivalent of a designer's desk covered in Pantone chips
#### Mode 13: Soft Gradient / Calm Tech
Use for: design tools, creative feedback platforms, thoughtful consumer products, calm SaaS, meditation apps, gentle AI products.
This mode draws from studio reference work (Thesis) where soft organic gradient blobs and gentle color washes create atmosphere without noise. Restraint is confidence.
- **Canvas:** white `#fafafa` to pale lavender `#f0ecf5` to soft blue `#edf2fb`
- **Accents:** one strong brand color - electric blue `#3366ff`, soft coral `#f08080`, or warm periwinkle `#6366f1` - used for logo, CTAs, and one tagline panel background
- **Visual cues:** soft organic gradient blobs (peach-to-blue, lavender-to-periwinkle) flowing across panels, clean minimal cards with rounded corners, dark-mode UI variant panels showing the brand in both modes, tagline panels with generous negative space
- **Logo logic:** simple geometric mark - a triangle resting against a rectangle (play/forward), a rounded square with one corner pulled, an abstract arrow from two shapes. The logo is EXTREMELY clean. No more than 2 shapes. The gradient world does the emotional work; the logo does the structural work
- **Typography:** clean geometric sans, medium weight, generous letter-spacing. No serif. The type should feel open, not tight
- **Image-world:** organic gradient blobs and soft color washes as brand atmosphere - not decoration, not background. These gradients are the brand's visual weather. They shift across panels like light through a window
- **Color system:** full gradient tint-to-shade strips - each brand color shown from its lightest 5% tint to its darkest 95% shade as a horizontal bar. This is a material study, not a swatch
- **Palette example:** `#fafafa` base / `#f0ecf5` surface / `#1a1a2e` text / `#3366ff` accent / `#f08080` secondary
- **Mood:** calm, considered, modern, quietly confident, the visual equivalent of a deep breath
#### Mode 14: Bold Neon / Creative OS
Use for: creative platforms, consumer creative tools, design OS products, gaming-adjacent brands, merch-heavy brands, products that live in physical space as much as on screen.
This mode draws from studio reference work (NORI) where the brand system covers EVERY conceivable touchpoint. The board is not 9 panels - it is 18-21. The brand exists in the world: on hoodies, in app docks, on membership cards, on packaging.
- **Canvas:** true black `#000000` to deep charcoal `#0a0a0a`
- **Accents:** 3-4 neon colors, ALL named with hex codes: Electric Purple `#7A5CFF`, Neon Lime `#CCFF00`, Coral Burst `#FF6A4D`, Sky Blue `#4SD6FF`, Soft Cream `#F5F3EE`
- **Visual cues:** iridescent gradient glass panels, neon-on-dark variety, physical product mockups (product box 3/4 angle, branded hoodie with logo on chest, membership card with chip detail and member number), app icon in a home screen dock alongside real app shapes, circular badge/stamp with border text, process flow icons (Capture → Organize → Create → Share), website hero section with full nav and CTA, repeated logo pattern as texture/wallpaper
- **Logo logic:** bold mark from rounded bars - ribbon, knot, X-shape, crossed strokes. The mark must be thick enough to read on black at any size. Show it at MULTIPLE scales: giant on the cover panel, medium on the product box, small on the membership card, tiny on the app icon. Show it on multiple backgrounds: black, neon lime, electric purple, white. Show it as a repeating pattern tile
- **Typography:** full Aa specimen panel with weight scale (Light / Regular / Medium / Bold) + number row (0 1 2 3 4 5 6 7 8 9) + custom display face name. This is the most typographically detailed mode
- **Image-world:** iridescent gradient glass + dark product photography (box on dark surface, hoodie flat-lay) + lifestyle application (card in hand, box on desk, app icon in context). The brand is PHYSICAL
- **Color system:** named chips on dark background - each swatch is a rounded rectangle with the color name in small caps above and the hex code below. ALL swatches shown together in a horizontal row
- **Palette example:** `#000000` base / `#0a0a0a` surface / `#F5F3EE` text / `#7A5CFF` accent-1 / `#CCFF00` accent-2 / `#FF6A4D` accent-3 / `#4SD6FF` accent-4
- **Mood:** energetic, bold, physical, creative-native, the visual equivalent of unboxing a premium creative tool
**This mode REQUIRES the Mega System layout (see below).** A 3×3 grid cannot contain the touchpoint breadth this mode demands.
### → Selecting the Mode
Read the Brand Strategy Brief from Phase 1. Match the category, audience, and cultural position to the most fitting mode. Each mode defines the board's tonal universe - canvas, accents, logo logic, and mood.
If the brand sits between two modes, pick the one that better serves the core metaphor. Do not blend modes - a "Dark Developer" board with "Luxury" accents is confused, not versatile.
If the brief describes a category not covered by these 14 modes, construct a custom mode by:
1. Picking the closest mode as a starting point
2. Swapping the palette and accent to match the brief
3. Adjusting the visual cues to match the product's world
4. Declaring the custom mode explicitly before proceeding
---
### → Board Layout (pick 1)
| # | Layout | Grid | When to use |
|---|---|---|---|
| 1 | **Full Identity System** | 3 × 3 | Complete brand presentation, maximum panel variety |
| 2 | **Cinematic Deck Overview** | 2 × 3 | Focused presentation, editorial pacing, reference-deck feel |
| 3 | **Compact Concept Board** | 2 × 2 | Quick concept, logo-focused, tight and punchy |
| 4 | **Horizontal Brand Strip** | 1 × 3 | Social media header, compact showcase, billboard energy |
| 5 | **Wide Contact Sheet** | 4 × 2 | Comprehensive system view, photography-led brands |
| 6 | **Mega System** | 6 × 3 or 7 × 3 | Every conceivable touchpoint. Required for Mode 14. Use for creative OS brands, consumer platforms, merch-heavy brands |
Default if unspecified: 3 × 3 for new brands, 2 × 3 for refinement passes. Mode 14 defaults to Mega System.
### → Mega System Panel Breakdown (18-21 panels)
When using Layout 6, fill the grid with ALL of these touchpoints. The point is exhaustive coverage - proving the brand works everywhere.
**Identity Core (4 panels):**
1. Logo cover - mark + wordmark on brand primary background, massive negative space
2. Logo on alternative background - the mark on its secondary color (e.g., white on neon lime, black on cream)
3. Construction proof - geometric construction diagram showing ≤3 guide circles/rectangles, labeled concept intersections if using Venn-diagram approach
4. Logo pattern tile - the mark repeated as a seamless pattern/texture filling the entire panel
**Digital Applications (3-4 panels):**
5. Website hero section - full hero with nav bar (logo + 3-4 links), headline (5-10 words), subhead, CTA button, trust badges. Not wireframe - a real hero
6. App icon on home screen dock - rounded-rectangle icon alongside recognizable app shapes (Messages, Camera, Music), with notification badge
7. Social media profile card - Twitter/X style: brand avatar (logo mark), @handle, bio line (tagline), follower/following counts, optional header image in brand style
8. Notification/UI card - toast notification, "Project synced - NORI Drive - 2m ago ✓" style
**Physical Applications (3-4 panels):**
9. Business card - front face showing logo, name, title, contact. Optionally show back face in a second variant
10. Product packaging - box at 3/4 angle showing two faces, logo + tagline visible
11. Branded merch - hoodie or tee with logo placement on chest, clean garment, dark or light fabric
12. Membership/ID card - credit-card proportions, chip detail, member number, logo, brand color
**System Panels (3-4 panels):**
13. Color system - named chips with hex codes, ALL swatches labeled: "Electric Purple #7A5CFF", "Neon Lime #CCFF00"
14. Typography specimen - large Aa + weight scale (Light / Regular / Medium / Bold) + number row (0 1 2 3 4 5 6 7 8 9)
15. Process/flow icons - 4-5 step process (Capture → Organize → Create → Share) with simple icons and arrows
16. Circular badge/stamp - the logo mark in a circular stamp with border text (brand name or tagline around the perimeter)
**Brand World (2-3 panels):**
17. Campaign tagline panel - bold tagline on brand-color background, large display type, one or two lines max
18. Brand-world image - art-directed atmospheric image matching the mode's image-world approach
19. Lifestyle application - the product in context (card in hand, box on desk, app on phone in café)
**Optional extras (for 7×3 = 21 panels):**
20. Secondary tagline/headline variant
21. Brand mark on unexpected surface (sticker, vinyl, event wristband)
---
### → Canvas Treatment (pick 1)
| # | Treatment | Character |
|---|---|---|
| 1 | **Pure field** | Solid charcoal or ivory with soft ambient depth, lets panels breathe |
| 2 | **Textured paper** | Warm, craft-oriented, print studio feel, subtle grain |
| 3 | **Technical grid** | Precise, engineered, construction-drawing energy |
| 4 | **Material surface** | Stone, concrete, leather, or metal - tactile and premium |
| 5 | **Gradient depth** | Soft tonal shift from edge to center, cinematic atmosphere |
| 6 | **Branded color field** | The board canvas IS the brand's primary color (e.g., medium blue, forest green, warm terracotta). Panels sit on a saturated brand surface instead of neutral dark/light. Bold, ownable, immediately distinctive |
| 7 | **Perforated / industrial** | Perforated metal, pegboard, mesh, or industrial panel texture behind panels. Adds tactile depth and framing without competing with content |
---
### → Logo Concept Method (pick 1, combine 2 maximum)
Do not design a logo randomly. Pick a method that connects the mark to the brand's meaning.
#### Method 1: Monogram + Meaning
Combine the brand initial with a metaphor. Use negative space, cuts, folds, or geometry. Do not make a boring letter icon.
Examples:
- `K` + kite / frame / direction
- `N` + path / folded system
- `S` + sound wave / speech flow
- `A` + ascent / architecture / momentum
#### Method 2: Product Action
Turn the product's main action into an abstract symbol. Make it premium, not literal.
Examples:
- build → frame, scaffold, block, cursor
- protect → shield, boundary, watch mark
- convert → switch, arrow, transformation shape
- speak → waveform, mic, pulse
#### Method 3: Metaphor Fusion
Combine two meaningful ideas into one reduced mark. The fusion should be subtle and readable at small sizes.
Examples:
- owl + drone vision
- shield + mountain
- moon + waveform
- cursor + lightning speed
- dice + mobile game economy
#### Method 4: Negative Space
Use empty space to create intelligence. The hidden element should be discoverable on second look.
Examples:
- hidden arrow in letter spacing
- protected center inside a shield form
- cutout initial revealing a secondary shape
- eye formed by crossing geometric shapes
#### Method 5: Construction Geometry
Create a mark from a clear geometric system - circles, diagonal cuts, grids, frames, modular blocks, orbital paths, crosshairs, measured linework. One panel on the board can show the construction logic.
#### Method 6: Image-Filled Letterform
Clip brand-world imagery INSIDE the logo letterform or mark. The letter becomes a window into the brand's visual world - landscapes, textures, product imagery masked by the letterform shape. The outer shape reads as the mark; the interior imagery reads as atmosphere.
Examples:
- Brand initial filled with nature photography (fields, forests, skies)
- Monogram containing product screenshots or UI fragments
- Symbol shape masking a cinematic landscape color-graded to the palette
- Abstract mark filled with brand-colored texture or material
The image inside must be art-directed to the brand palette. Random stock imagery inside a letter is not this method - it is clip art. The masked image must feel intentional, like the brand's world is literally contained within the mark.
---
### → Logo Hard Constraints (All Must Pass)
Regardless of which method you pick, the final logo must satisfy ALL of these. If any fails, the mark is not ready.
1. **3-primitive maximum**: The entire mark must be constructible from ≤3 geometric primitives (circles, rectangles, triangles, lines, arcs). If you need more shapes, it is too complex. Reference calibration: Polished Snow = 4 squares. Thesis = 1 triangle + 1 rectangle. Nexus = 1 rounded cross + 1 circle. These are real studio logos. Match their simplicity.
2. **Favicon test**: Must be recognizable and distinct at 16×16 pixels. If detail disappears at favicon scale, cut it until it doesn't.
3. **One-sentence geometry**: You must be able to describe the mark as: "It's a [shape] [operation] a [shape]." Example: "It's two overlapping rounded squares with the intersection removed." If the sentence needs an "and" or comma splice, the mark is too complex.
4. **Inversion test**: Must work identically in black-on-white AND white-on-black. No color-dependent forms.
5. **Wordmark pairing**: Must sit cleanly next to the brand name set in the chosen typography. If the mark fights the wordmark's proportions, adjust.
6. **Pattern tile test**: Must work as a repeating pattern when tiled. If it falls apart or creates visual noise, the geometry isn't balanced.
### → Logo Anti-Patterns (Hard Bans)
Generating any of these is a pipeline failure. These are the most common AI logo defaults:
- ❌ **Metallic/chrome 3D logos** - Logos are flat. No bevels, no reflections, no faux-3D rendering.
- ❌ **Brain/neuron networks** - The single most cliché AI logo. Absolute ban.
- ❌ **Globe with swoosh** - 1990s corporate identity. Dead.
- ❌ **Shield with wings** - The laziest security logo.
- ❌ **Interlocking rings** - Unless you are the Olympics, no.
- ❌ **Meaningless sparkle bursts** - Stars and sparkles are decoration, not design.
- ❌ **Infinity symbols** - Overused to meaninglessness.
- ❌ **Overcomplicated crests** - If it has >3 elements, it's an illustration, not a logo.
- ❌ **Gradient-dependent marks** - If the logo needs a gradient to be recognizable, the form is weak.
- ❌ **Thin hairline marks** - Must reproduce at small sizes. Hairlines break.
- ❌ **Random letterform distortion** - Stretching, warping, or melting a letter is not logo design.
- ❌ **Clipart-style icons** - The mark must feel constructed, not downloaded.
---
### → Logo Reduction Ladder
After picking a method, walk the reduction ladder. Start with meaning and compress until only the essential shape remains.
```
STEP 1: MEANING SENTENCE
"This brand is about [core metaphor] applied to
[product action] for [audience]."
STEP 2: VISUAL TRANSLATION
Convert the sentence into 3-5 candidate shapes.
Each shape must connect to a word in the sentence.
STEP 3: COMPRESSION
Take the strongest candidate. Reduce it:
- Can it work in one continuous stroke?
- Can it be built from ≤ 3 geometric primitives?
- Does it hold meaning at 16px?
- Would a stranger guess the industry within 2 tries?
If any answer is no, reduce further.
STEP 4: LETTER INTEGRATION (optional)
If the brand initial adds meaning, integrate it.
The letter must modify the shape, not sit next to it.
A pure symbol is better than a forced monogram.
STEP 5: SYSTEM TEST
The final mark must pass all five:
- Works as a favicon (16×16)
- Works as an app icon (1024×1024)
- Works in single color (no gradients required)
- Works reversed (light on dark AND dark on light)
- Looks intentional next to Apple, Linear, or Stripe logos
```
Most AI logos fail because they ADD elements instead of removing them. The ladder forces reduction.
### → Logo Consistency Protocol (Anti-Morphing)
The logo must appear identical in every panel. When the mark drifts between panels - gaining petals, losing arms, shifting proportions - the board fails as a system. Modern image models can hold consistency, but only when the prompt is precise enough to leave zero room for interpretation.
**The Frozen Logo Description**
Write one sentence of exact geometry for the mark. This sentence is copy-pasted verbatim into every panel assignment where the logo appears. No synonyms, no rephrasing, no shorthand between panels.
Bad (vague, invites drift):
> "The Lumenova logo, a golden cross-like shape"
Good (frozen, precise):
> "The Lumenova logo: exactly four identical rounded squares arranged in a plus/cross formation, overlapping at their corners, with the top-left and bottom-right squares in orange #FF7A00 and the top-right and bottom-left squares in amber #E8A000"
**Rules for the frozen description:**
1. **State the exact count.** "Exactly 4 rounded squares", "exactly 2 overlapping circles", "exactly 3 diagonal bars." The word "exactly" locks the count.
2. **Name the spatial arrangement.** Not "arranged nicely" - say "in a 2×2 grid with the center gap removed" or "stacked vertically" or "overlapping at their 25% intersection."
3. **Include colors with hex codes.** "In orange #FF7A00" not "in a warm orange."
4. **Paste the frozen description into EVERY panel.** Every panel that shows the logo - anchor, business card, app icon, lanyard, laptop screen, merch - gets the identical sentence:
```
Panel 1 (Anchor): [frozen logo description] centered at large scale on dark canvas
Panel 4 (Proof - Card): [frozen logo description] at small scale on the card face
Panel 5 (Proof - App Icon): [frozen logo description] at icon scale in rounded-rect frame
Panel 7 (Proof - Merch): [frozen logo description] on the chest of a dark hoodie
```
5. **Add a global instruction** at the top of the prompt: "The logo mark must appear IDENTICAL in every panel. Same shapes, same proportions, same colors, same arrangement across all panels."
---
### → Typography Character (pick 1)
| # | Type | Energy | Pairing Guidance |
|---|---|---|---|
| 1 | **Compressed display sans** | Industrial, dramatic, high-impact | Pair with light-weight body sans for contrast |
| 2 | **Clean geometric grotesk** | Modern, approachable, startup-friendly | Pair with monospace for technical brands |
| 3 | **Refined neo-grotesk** | Polished, agency-grade, premium tech | Self-sufficient, use weight variation for hierarchy |
| 4 | **Editorial serif** | Tasteful, institutional, considered | Pair with clean sans for modern tension |
| 5 | **Monospace technical** | Engineer-native, terminal-adjacent, precise | Pair with a single display sans for headings |
| 6 | **Expressive display** | Bold, statement, creative, memorable | Pair with a quiet body sans to let it breathe |
---
### → Color Discipline (pick 1 palette structure)
| Structure | Application |
|---|---|
| **Monochrome + single accent** | Near-black + white + one saturated hue. The accent carries the entire system. Most versatile |
| **Analogous triad** | Three hues within 60° on the color wheel. Harmonious, subtle, sophisticated |
| **Complementary anchor** | One dominant + one opposite for tension. Use the complement sparingly (CTA, highlights only) |
| **Material-derived** | Colors extracted from a real material (wood, stone, copper, ink). Tactile and grounded |
| **Heritage duo** | Two historically associated colors (navy + gold, forest + cream, black + red). Institutional gravitas |
Rules that apply to every palette:
- Accents must repeat across panels. One appearance is not a system
- No random rainbow unless the brief explicitly requests it
- No default AI purple-blue gradient glow unless the brand is literally about AI and the strategy justifies it
- One accent can carry an entire identity. Two accents maximum across the board
- The palette must include specific hex values or clear color descriptions - never "nice colors"
---
### → Tagline Energy (pick 1)
| Energy | Example Pattern | When |
|---|---|---|
| **Declarative** | "Nothing random." / "Build better." | Confident brands, established positioning |
| **Interrogative** | "What will you build today?" | Invitational brands, tools, platforms |
| **Imperative** | "Ship it." / "On guard." | Action-oriented brands, operational tools |
| **Fragment** | "Every mission. Under control." | Dramatic brands, cinematic positioning |
The tagline must be short (under 8 words), specific to the brand, and free of corporate filler. No "Elevate your workflow." No "Seamless solutions for modern teams." No "Unleash the power of."
---
### ✓ Quality Gate: Architecture
Before moving to Phase 3, confirm:
- ONE visual mode selected and declared
- ONE option selected from each remaining category (no blending)
- Picks are internally consistent (Dark Developer mode + Monospace technical type + Monochrome accent = valid. Warm Luxury mode + Monospace technical type = probably wrong)
- Logo concept method connects to the core metaphor from Phase 1
- Color discipline matches the visual mode's palette example
- Tagline energy matches the brand's cultural position
- You can explain WHY each pick was made in one sentence
---
## Phase 3: Panel Composition
Each panel in the grid gets a specific role, a composition anchor, and an energy level. The board must have rhythm - not every panel can be loud, and not every panel can be quiet.
### → The Argument Structure
A brand board is a visual argument. Each panel plays a role in that argument. The roles are not content types ("color panel," "type panel"). They are rhetorical positions. What matters is what each panel PROVES, not what content category it belongs to.
Five roles. Every board must include all five. Some roles can appear in multiple panels.
| Role | What it proves | Panel count |
|---|---|---|
| **Anchor** | This is the brand. The mark, the name, the core visual identity at rest. Maximum restraint, maximum negative space | Exactly 1 |
| **Proof** | The brand works on real surfaces. Digital screens, physical objects, environmental contexts. Not theoretical - applied | 2-3 panels |
| **System** | The brand is governed by rules. Color relationships, type hierarchy, spacing logic, component vocabulary. The rules are visible | 1-2 panels |
| **World** | The brand has atmosphere. Photography, texture, material, cinematic mood. The brand exists in a place, not just on a screen | Exactly 1 |
| **Signal** | The brand communicates. A tagline, a command, a URL, a statement. One piece of language that captures the brand's voice | Exactly 1 |
### → Default Panel Systems
#### 3 × 3 Board: Full Identity System
```
┌─────────────────┬─────────────────┬─────────────────┐
│ │ │ │
│ ANCHOR │ SYSTEM │ PROOF │
│ (the mark) │ (how it's │ (where it │
│ │ built) │ lives) │
├─────────────────┼─────────────────┼─────────────────┤
│ │ │ │
│ SIGNAL │ SYSTEM │ PROOF │
│ (the voice) │ (the rules) │ (another │
│ │ │ surface) │
├─────────────────┼─────────────────┼─────────────────┤
│ │ │ │
│ PROOF │ WORLD │ SYSTEM │
│ (one more │ (the mood) │ (the details) │
│ surface) │ │ │
└─────────────────┴─────────────────┴─────────────────┘
```
Default panel content mapping:
1. **Logo Cover** - Large logo and wordmark, minimal title, strong negative space
2. **Logo Construction** - Symbol breakdown, grid, geometry, or negative-space logic
3. **Digital Application** - Browser chrome, app header, terminal, dashboard fragment, or app icon
4. **Brand Essence** - One short tagline, large readable typography, sparse composition
5. **Color System** - Swatches, gradient strips, color discs, material chips, or palette cards
6. **Typography** - Large type specimen, alphabet row, or primary/secondary type pairing
7. **Physical Application** - Card, folder, badge, poster, label, seal, packaging, or object mockup
8. **Image Direction** - Cinematic landscape, product crop, halftone poster, editorial scene, material texture
9. **System Detail** - UI chips, input bar, command line, icon row, badge system, component strip, pattern detail
#### 2 × 3 Board: Compressed Argument
```
┌─────────────────┬─────────────────┐
│ ANCHOR │ PROOF │
├─────────────────┼─────────────────┤
│ SYSTEM │ WORLD │
├─────────────────┼─────────────────┤
│ SIGNAL │ PROOF │
└─────────────────┴─────────────────┘
```
Same 5 roles, fewer panels. Each panel carries more weight. The Anchor panel must be even more restrained.
### → Panel Rhythm Rules
- Never place two Quiet panels adjacent to each other
- Never place three Technical panels in a row
- The board must contain at least one Emotional panel and one Functional panel
- The Anchor panel is always position 1 (top-left)
- The most atmospheric panel should not be position 1
### → Panel Composition Anchors
Assign one per panel. Across the board, at least 3 different anchors must appear.
| Anchor | Description |
|---|---|
| **Dead center** | Content centered both axes, maximum symmetry, confident restraint |
| **Top-left gravity** | Content anchored top-left, reading-order natural, editorial |
| **Bottom-right detail** | Small element anchored bottom-right, system-detail energy |
| **Offset bleed** | Content deliberately pushed to one edge, bleeds into gutter |
| **Full-fill** | Content fills the entire panel edge to edge (images, color fields) |
| **Stacked vertical** | Elements stacked top-to-bottom with clear vertical hierarchy |
### → Premium Detail Language
Use details like these sparingly to reward closer inspection:
- Small page numbers in panel corners (e.g., "01" bottom-right)
- Tiny footer labels or section markers (e.g., "COLORS" or "TYPEFACE")
- Precise alignment marks or construction lines at low opacity
- Thin rules separating sub-elements within a panel
- Low-opacity texture overlays (grain, halftone, noise)
- One highlighted word in the tagline using the accent color
- Browser chrome with a realistic URL bar and navigation dots
- Rounded rectangle frames for contained images
- Subtle drop shadows between panel layers
- App icon on a realistic phone homescreen with notification badge
- Social media profile card (X/Twitter style) with avatar, handle, bio, and Follow button
- Color system panel with labeled strips and visible hex values
- Perforated metal or material texture framing an image panel
- Device mockup (laptop, phone) on a dark surface showing the brand's website
Do not overuse them. Three to five details across the entire board. Premium detail is discovered, not announced.
### ✓ Quality Gate: Composition
Before moving to Phase 4, confirm:
- Every panel has a role, anchor, and energy level assigned
- Panel rhythm varies (no adjacent duplicates in energy)
- At least 3 different composition anchors appear across panels
- Anchor panel is position 1
- Board contains at least 1 Emotional and 1 Functional panel
- Premium details are planned (3-5, not more)
---
## Phase 4: Prompt Engineering
Build one structured prompt for the complete board using the blueprint below. Fill in every field. Skipping fields produces generic output.
**If Phase 0 produced a REFERENCE INSTRUCTION block**, prepend it at the very top of the prompt BEFORE the blueprint. The REFERENCE INSTRUCTION block anchors the AI model to the reference image's quality bar and aesthetic DNA. The blueprint then fills in the brand-specific content below it.
### → The Prompt Blueprint
```
PROMPT BLUEPRINT - Brand-Kit Board: [BRAND NAME]
──────────────────────────────────────────────────
BRAND STRATEGY:
Category: [from Phase 1]
Audience: [from Phase 1]
Core metaphor: [from Phase 1]
Emotional promise: [from Phase 1]
Logo idea: [how the mark combines symbol + name + metaphor]
BOARD FORMAT:
Layout: [from Phase 2 - e.g., "3×3 grid"]
Aspect ratio: [4:3 or 16:10]
Canvas: [from Phase 2 - e.g., "near-black #0a0a0a charcoal field
with subtle paper texture, strong 12px gutters
between panels, rounded-lg panel corners"]
VISUAL MODE:
[from Phase 2 - e.g., "Dark Developer: near-black panels,
monospace accents, terminal chrome, cyan #00d4aa accent"]
PANEL ASSIGNMENTS:
Panel 1: [role] - [what to show] - [anchor] - [energy]
Panel 2: [role] - [what to show] - [anchor] - [energy]
...
Panel N: [role] - [what to show] - [anchor] - [energy]
LOGO:
Method: [from Phase 2 - e.g., "Monogram + Meaning: the letter K
is cut diagonally to reveal a kite shape in the
negative space"]
Symbol: [from Phase 1 symbol pool]
Construction: [how the mark is built - e.g., "constructed on a
circular grid with 15-degree increments, single
continuous stroke, works at 16px"]
Frozen description: [EXACT geometric sentence - copy this verbatim
into every panel assignment where the logo appears.
Include shape count, arrangement, and colors.
e.g., "exactly two overlapping rounded rectangles
rotated 45°, forming a diamond intersection,
in white #FFFFFF on dark backgrounds"]
Variants shown: [wordmark, icon mark, badge, app icon]
GLOBAL CONSISTENCY RULE: The logo mark must appear IDENTICAL in
every panel where it is shown. Same number of shapes, same
proportions, same colors, same spatial arrangement. Do not add,
remove, rotate, or modify any element of the mark between panels.
TYPOGRAPHY:
Character: [from Phase 2]
Heading treatment: [e.g., "compressed all-caps display,
tight tracking, used for brand name
and tagline only"]
System labels: [e.g., "small monospace, uppercase, wide
tracking, 60% opacity, used for panel
labels and page numbers"]
PALETTE:
Structure: [from Phase 2]
Base: [e.g., "#0a0a0a near-black"]
Surface: [e.g., "#1a1a1a dark panel fill"]
Primary text: [e.g., "#f0ede8 warm off-white"]
Muted text: [e.g., "rgba(240,237,232,0.5)"]
Accent: [e.g., "#00d4aa teal - used on logo mark,
CTA elements, and active states"]
TAGLINE:
Text: [the actual tagline]
Energy: [from Phase 2]
ATMOSPHERE:
[e.g., "subtle film grain at 2% opacity across canvas,
soft ambient glow behind logo cover panel, halftone
treatment on the image-direction panel, no hard shadows
between panels - depth comes from surface color
difference only"]
PREMIUM DETAILS:
[list the 3-5 planned details - e.g.,
"page number '01' bottom-right of panel 1,
construction grid lines at 15% opacity in panel 2,
realistic URL 'app.brandname.com' in browser chrome,
one word of tagline highlighted in accent color"]
WHAT THIS IS NOT:
[explicit anti-patterns - e.g.,
"NOT a Canva brand board template.
NOT random icons floating on a gradient.
NOT an overdesigned logo with 6 colors.
NOT a collage of unrelated mockups.
NOT tiny illegible text pretending to be a system.
NOT a generic startup pitch deck slide."]
```
### → The Jaw-Dropper Executive Prompt (2026 Sleek Format)
For modern 2026 image generation models that thrive on dense, high-signal, executive-level instructions without verbose boilerplate, use this sleek, jaw-dropping prompt template:
```
Create a premium 3×3 visual identity board for [BRAND NAME].
Brand strategy:
- category: [CATEGORY]
- audience: [AUDIENCE]
- personality: [TRAITS]
- emotional promise: [PROMISE]
- core metaphor: [METAPHOR]
- logo idea: [SYMBOL LOGIC + FROZEN GEOMETRY SENTENCE]
Board format: 3×3, 4:3 aspect ratio
Visual mode: [minimal editorial / digital modernist / pixel modernist / institutional trust / product utility / cultural experimental]
Include: logo cover, construction rationale, wordmark system, brand essence, color system, typography, application, imagery direction, system detail.
```
### ✓ Quality Gate: Prompt
Before generating, confirm:
- Complete prompt follows the blueprint structure (no fields skipped)
- WHAT THIS IS NOT section includes at least 4 specific anti-patterns
- Palette is fully specified with hex values
- Logo construction is described specifically (not "a nice logo")
- **Frozen logo description is written and copy-pasted into EVERY panel assignment where the logo appears** (§ Logo Consistency Protocol)
- **Global consistency rule is included at the top of the prompt**
- Panel assignments match Phase 3 composition plan
- Typography character is consistent across all panel descriptions
- Tagline is under 8 words and free of corporate filler
---
## Phase 5: Visual Diff
After generating the board, audit it against the strategy and architecture picks. Walk through every check. Any FAIL means re-generating with a corrected prompt.
### Logo Diff
| Check | PASS/FAIL |
|---|---|
| Logo is simple enough to work as a 16px favicon | |
| Logo connects to the core metaphor from Phase 1 | |
| **Logo is IDENTICAL across every panel** - same number of shapes, same proportions, same arrangement, same colors. Compare the anchor panel mark to EVERY other appearance (mockups, app icon, card, merch). If any element was added, removed, rotated, or resized, this is a FAIL. | |
| Logo uses the concept method committed in Phase 2 | |
| Logo is not a generic lightning bolt, brain icon, or shield without strategic justification | |
| Logo wordmark is legible and the typeface matches the typography character | |
| **Logo does NOT clone the reference image's mark** - different geometric DNA, different shape vocabulary, different construction method. Run the geometry-difference test (§ Reference Usage Protocol) | |
| Logo passes the 3-primitive cap from § Logo Hard Constraints | |
| Logo passes the one-sentence geometry test from § Logo Hard Constraints | |
### Composition Diff
| Check | PASS/FAIL |
|---|---|
| Grid is clean with consistent gutters between all panels | |
| Panel edges are aligned (no random offsets or overlaps) | |
| At least 3 different composition anchors appear across panels | |
| Panel energy rhythm varies (no three adjacent panels at the same energy) | |
| Anchor panel is position 1 (top-left) and has maximum negative space | |
| The board reads as ONE identity, not a collection of unrelated rectangles | |
### Palette Diff
| Check | PASS/FAIL |
|---|---|
| One dominant palette threads through every panel | |
| Accent color appears in at least 3 panels (not just one) | |
| No rogue colors appear that were not in the palette specification | |
| No AI-default purple-blue gradient glow (unless strategy justifies it) | |
| Dark boards use off-black (#0a0a0a range), not pure black (#000000) | |
| Light boards use warm off-white, not pure white (#FFFFFF) | |
### Typography Diff
| Check | PASS/FAIL |
|---|---|
| Text is sparse: brand name, one tagline, one URL, section labels, UI chips only | |
| No tiny illegible paragraphs or fake body copy | |
| Tagline is large enough to read comfortably | |
| Typography character is consistent across all panels (same family, same hierarchy) | |
| Panel labels and page numbers (if present) use a secondary type style | |
### Identity System Diff
| Check | PASS/FAIL |
|---|---|
| The board answers: what does this brand represent? | |
| The board answers: what is the core metaphor? | |
| The board answers: how does the logo express that? | |
| The board answers: how does the system scale across digital, physical, and atmospheric applications? | |
| The board answers: why does the whole thing feel ownable (not interchangeable with any other brand)? | |
---
## Phase 6: Panel Surgery
After the Visual Diff, some boards will have 4-5 excellent panels and 1-2 weak ones. Instead of regenerating the entire board (which risks losing the good panels), use **Panel Surgery** - regenerate individual panels as standalone cards and composite them into the final board.
### → When to trigger Panel Surgery
Panel Surgery activates when:
- The Visual Diff identifies 1-2 specific panel failures while the majority of panels pass
- A panel's content clashes with the overall aesthetic (e.g., a random oil painting in a digital-modern board)
- A panel's visual weight or density is significantly off from its neighbors
- The user explicitly identifies specific panels they dislike while approving the rest
Do NOT use Panel Surgery when:
- More than 3 panels fail the Visual Diff (regenerate the entire board instead)
- The logo mark is the problem (that's Phase 7's job)
- The overall aesthetic direction is wrong (go back to Phase 0 or Phase 2)
### → Step 1: Diagnose the Weak Panel
For each weak panel, identify the specific failure:
| Failure Type | Example | Fix Strategy |
|---|---|---|
| **Medium Clash** | An oil painting of clouds in a digital-modern board | Replace with content that matches the board's medium (e.g., typography specimen, architectural diagram, software UI) |
| **Color Clash** | A panel introduces earthy beige tones in an electric chromatic board | Regenerate with the board's exact palette hex values |
| **Visual Weight Mismatch** | A nearly empty panel next to dense, saturated panels | Add structured content (swatches, type specimen, UI elements) to balance density |
| **Content Irrelevance** | A panel shows generic stock-energy imagery unconnected to the brand | Replace with brand-specific content (product UI, construction grid, application mockup) |
| **Filler Energy** | A panel exists to fill the grid but adds no new information | Either remove the panel (reduce grid size) or assign it a specific functional role |
### → Step 2: Write the Single-Panel Prompt
Generate the replacement panel as a **standalone card image** using a prompt that:
1. **References the existing board** - attach the current board as context so the AI matches the aesthetic
2. **Specifies the exact panel role** - what this card should show (e.g., "Typography & Color Token Specimen")
3. **Locks the palette** - include exact hex values from the board's color system
4. **Matches the surface treatment** - specify the same texture, grain, and card structure as the rest of the board
5. **Sets the aspect ratio** - match the panel's proportions in the grid (usually 4:3 for a single panel)
### → Single-Panel Prompt Template
```
REFERENCE INSTRUCTION - PANEL REPLACEMENT:
Use the attached brand board image as a reference for the exact surface treatment, color palette, typography style, and card structure. This replacement panel must look like it was always part of the board.
Create a single high-resolution [PANEL ROLE] card on [SURFACE DESCRIPTION - e.g., "crisp off-white paper (#F4F4F6) with subtle print registration marks"].
Include:
- [SPECIFIC CONTENT 1 - e.g., "Large editorial serif specimen showing 'Aa Bb Cc' and the brand wordmark"]
- [SPECIFIC CONTENT 2 - e.g., "Four rectangular color swatches: Tangerine (#FF521B), Cobalt (#3D4AE0), Fuchsia (#E8206A), Obsidian (#111111)"]
Visual style: [MATCH THE BOARD'S STYLE - e.g., "Swiss-modernist editorial layout, zero 3D elements, pure typographic precision"]. Aspect ratio: [PANEL ASPECT RATIO].
```
### → Step 3: Composite in Figma (or equivalent)
After generating the replacement panel:
1. Import the original board into Figma (or Photoshop, Sketch, etc.)
2. Place the replacement panel over the weak panel, aligning edges to the grid
3. Adjust sizing if needed to match the grid cell dimensions
4. Export the final composite at full resolution
This manual compositing step is expected and normal - even professional studios composite final presentation decks from separately generated assets.
### ✓ Quality Gate: Panel Surgery
Before finalizing:
- Replacement panel matches the board's surface treatment and texture
- Replacement panel's color palette is identical to the board's palette (no rogue colors)
- Replacement panel's typography style matches the board's type hierarchy
- Replacement panel adds functional value (not filler)
- The composite reads as a single cohesive board with no visible seams
---
## Phase 7: Logo Originality Gate
When a reference image was provided in Phase 0, the generated logo mark will default to cloning the reference's symbol. This is the hardest problem in reference-based brand kit generation. Phase 7 is a mandatory post-generation audit that catches clones.
### → When to trigger the Logo Originality Gate
This phase is MANDATORY when:
- A reference image was provided in Phase 0
- The reference image contained a visible logo mark or symbol
Skip this phase when:
- No reference image was used
- The user is in Asset mode (they provided their OWN logo to preserve)
### → Step 1: Geometry-Difference Audit
Describe both marks in one sentence each:
| Mark | One-Sentence Geometry Description |
|---|---|
| **Reference mark** | e.g., "Eight overlapping diamond petals arranged radially to form a symmetrical flower blossom with a hollow center" |
| **Generated mark** | e.g., "???" |
Now run the **vocabulary overlap test:**
1. List the primary shape words from the reference description (e.g., "petals", "flower", "radial", "blossom", "hollow center")
2. List the primary shape words from the generated description
3. If **3 or more shape words match**, the generated mark is a clone → **FAIL**
4. If **2 or fewer shape words match**, the generated mark is sufficiently distinct → **PASS**
### → Step 2: Visual Similarity Check
Beyond geometry, check for these cloning signals:
| Signal | Clone Indicator |
|---|---|
| **Symmetry type** | Same symmetry (e.g., both 8-fold radial) → likely clone |
| **Shape count** | Same number of sub-shapes (e.g., both have 8 petals) → likely clone |
| **Negative space** | Same negative-space structure (e.g., both have a hollow center eye) → likely clone |
| **Rendering style** | Mark shown in the same style as reference (e.g., both use halftone stencil, both use chromatic gradient fill) → acceptable if geometry differs |
### → Step 3: Force Divergence (if clone detected)
If the generated mark fails the audit, do NOT try to "tweak" the mark - the AI will produce a minor variant that is still recognizably the same symbol. Instead:
1. **Choose a completely different logo method** from Phase 2 (e.g., if reference used Construction Geometry, switch to Negative Space Letterform or Monogram + Meaning)
2. **Choose a different primary shape vocabulary** (e.g., if reference used radial petals, use angular prisms or stacked bars)
3. **Explicitly ban the reference geometry in the prompt** - add to the REFERENCE INSTRUCTION block: `"The logo mark must NOT use [reference shape vocabulary]. Use [your chosen alternative] instead."`
4. **Regenerate the entire board** with the new logo (do not try to swap just the logo - it must thread through all panels consistently)
### → The Nuclear Option: User-Designed Logo
If after 2 regeneration attempts the logo still clones the reference, recommend the user:
1. Design their own logo mark externally (in Figma, Illustrator, or by hand)
2. Export as PNG at 1024px+
3. Switch to **Asset mode** (§ Reference Usage Protocol → Mode: Asset) and rebuild the board around their custom mark
This is not a failure of the skill - it is an honest acknowledgment that generating a truly original, memorable logo mark that rivals a reference image's symbol is the hardest unsolved problem in AI image generation.
### ✓ Quality Gate: Logo Originality
Before finalizing the board:
- Geometry-difference audit has been run (if reference provided)
- Generated mark uses different primary shape vocabulary than the reference
- Generated mark uses a different logo method than the reference
- If the mark failed the audit, the prompt was corrected and the board was regenerated
- The final mark is sufficiently distinct that a designer familiar with the reference would NOT identify it as a derivative
---
## Anti-Slop Rules
These are the patterns AI image generation defaults to when generating brand boards. Fight every single one.
### Layout slop
- Random floating icons on a gradient (the AI's default "brand board")
- Messy collage layout with no clear grid, no gutters, panels overlapping
- Canva template energy - generic rounded rectangles with stock imagery
- Corporate PowerPoint slide energy - bulleted feature lists in panels
- No clear visual hierarchy - everything at the same scale and weight
### Logo slop
- Overdesigned logo with too many elements, 4+ colors, ornate detail
- Generic lightning bolt, brain icon, or shield with no strategic connection
- **Logo morphing across panels** - the mark changes shape, gains/loses elements, or shifts proportions between the anchor panel and mockup panels. This is the #1 brand-board quality failure. The mark must be IDENTICAL everywhere.
- Clipart-style icons pretending to be identity marks
- Random animals with no metaphor connection
- Meaningless sparkles or starbursts added for "premium" feel
- Logo only shown once at large scale - must appear at MULTIPLE scales to prove it works
### Palette slop
- Default AI purple-blue gradient glow (unless strategy demands it)
- Random rainbow colors with no system
- More than 3 distinct hues across the entire board
- Neon accents with no restraint
- Pure black (#000000) or pure white (#FFFFFF) as base colors
### Typography slop
- Tiny illegible paragraphs or fake body copy filling panels
- Dense menu items, navigation lists, or lorem ipsum
- Text that exists to fill space rather than communicate
- Inconsistent type families across panels
- Gradient text as a lazy "premium" shortcut
### Content slop
- Em-dashes in any visible copy
- AI copywriting cliches: "Elevate," "Seamless," "Unleash," "Next-Gen," "Revolutionize," "Empower," "Transformative"
- Generic taglines: "Elevate your workflow," "Seamless solutions for modern teams"
- Stock photography energy: handshakes, laptops on desks, aerial city views
- Fake brand names: Acme, Nexus, NovaCore, Quantumly, FlowBit
### Mockup slop
- Full fake dashboards with dense data visualizations
- Cheap glossy 3D device renders
- Multiple devices showing different screens
- Busy app interfaces with many features visible
- Excessive icon grids
### Atmosphere slop
- Meaningless abstract blobs floating in space
- Over-rendered noise that hides the layout
- Cliche robot/AI imagery (glowing circuits, digital brains)
- Stock-template brand board energy
- Overbusy scenes with too many subjects
---
## Text Rules
Use very little text in the generated board. Text is expensive in AI-generated images - it competes with the visual system for attention and is prone to rendering errors.
**Good text to include:**
- Brand name (wordmark)
- One tagline (under 8 words)
- One URL (brandname.com)
- One terminal command or install line
- 2-5 small panel labels
- Short UI element text (button labels, input placeholders)
**Bad text to avoid:**
- Paragraphs of any length
- Fake body copy or lorem ipsum
- Dense menu items or navigation lists
- Tiny text that exists to fill space
- Long marketing descriptions
- Unreadable labels below 8pt equivalent
Text should be large enough to read at the generated resolution and sparse enough that removing any piece would be noticed.
---
## Photographic Direction
When a panel requires photography or atmospheric imagery, it must be art-directed to match the brand strategy. Do not use generic visual filler.
**Good image direction:**
- Cinematic landscapes color-graded to the brand palette
- Product closeups with controlled lighting and brand-colored surfaces
- Architectural scenes matching the brand's spatial energy
- Material textures (paper, metal, stone, fabric) in palette-matched tones
- Halftone or duotone treated photographs
- Abstract but controlled compositions with brand geometry
- Nature imagery (fields, forests, skies, water) tonally matched to the brand palette
- Macro crops of organic textures (grass, leaves, stone, fabric) as atmospheric fills
**Bad image direction:**
- Generic stock photography (handshakes, laptops, city aerials)
- Random nature imagery unconnected to the brand's palette or metaphor
- Cliche robot/AI imagery (glowing circuits, digital brains)
- Overbusy scenes with too many subjects
- Images that could belong to any brand
The image must feel like it was shot for this specific brand, even though it was generated.
### → Visual World Threading
The brand's visual world - its atmospheric imagery, textures, and environmental photography - must thread through MULTIPLE panels, not appear in just one "World" panel. This is what separates studio-grade boards from generic AI output.
- The Anchor panel can use the brand's visual world as a background behind the logo
- Proof panels (mockups) should show the visual world through device screens or as wallpaper
- The logo mark itself can contain the visual world (if using Method 6: Image-Filled Letterform)
- Color system panels can reference the visual world as the source of the palette
- The World panel gets the purest, most atmospheric expression of the imagery
The visual world is not decoration - it is the brand's PLACE. It answers: "Where does this brand live?" A nature-tech brand lives in sunlit meadows. A security brand lives in dark control rooms. A luxury brand lives in stone and leather. Thread that world through every panel where it fits naturally.
---
## Mockup Direction
When panels show the brand applied to digital or physical surfaces, the mockups must be minimal and believable. Mockups are identity applications - they prove the system works at scale. They are not feature demos.
One mockup per panel. One surface per mockup. Simple enough to believe.
### → Website Hero Mockup (not just browser chrome)
When including a digital application panel, do NOT just show an empty browser bar with navigation dots. Show an actual website hero section with real content:
- Navigation bar with logo mark on the left + 3-4 nav items (Research, Products, About, etc.) + CTA button
- Hero headline: 5-10 words, brand-specific, in the display typeface at large scale
- Supporting subhead: 1 line of context
- Primary CTA button in the brand accent color
- Optional: trust badges, "Trusted by" logos, or a small product visual
This must look like a real landing page someone would visit, not a wireframe. The hero composition itself should vary - not always left-text / right-image. Centered-over-background, bottom-left overlay, stacked-center are all valid.
### → Social Media Profile Mockup
This touchpoint is missing from most AI brand kits and immediately makes the output feel more real. Include a social media profile card (Twitter/X style) showing:
- **Avatar**: the brand logo mark in a circle
- **Display name**: brand name in bold
- **Handle**: @brandname
- **Bio line**: brand tagline or one-line description
- **Stats**: "X posts" · "X following" · "X followers" with plausible numbers
- **Join date**: "Joined [month] [year]"
- **Optional**: header image in brand style (brand-world image, gradient, or pattern)
- **Optional**: "Edit profile" button or "Follow" button depending on perspective
The card should use a dark or light background matching the board's canvas tone.
### → App Icon Mockup
Show the brand logo mark as an app icon on a realistic home screen dock:
- Rounded-rectangle icon (iOS style) with the logo mark centered
- Background color from brand palette (not always dark - match the mode)
- Appropriate padding so the mark doesn't touch the icon edges
- Shown alongside 3-4 other recognizable app shapes in the dock (Messages, Camera, Music, Settings)
- Optional: notification badge with a small number
The icon must be recognizable at actual app-icon size - this is the favicon test in action.
### → Physical Mockup Specifications
Physical objects must look tangible and believable, not like flat vector illustrations:
**Business card:**
- Show front face: logo, person's name, title, email, phone
- Optionally show back face with just the logo mark centered
- Multiple color variants prove the system's flexibility (dark/light/brand-color)
- Card proportions: standard 3.5" × 2" ratio
**Product packaging:**
- Box at 3/4 angle showing two faces
- Logo + tagline visible on the primary face
- Brand color as box surface or as accent detail
- The box should look like something you'd actually unbox
**Branded merchandise:**
- Hoodie or tee with logo placement on chest (left chest small, or center large)
- Clean garment - dark or light fabric, no busy pattern
- The logo must read clearly on the fabric
**Membership/ID card:**
- Credit-card proportions (3.375" × 2.125" ratio)
- Chip detail (gold or silver rectangle, top-left)
- Member number (realistic format: 0017 8200 5731)
- Logo mark and brand name
- Brand color as card background or accent strip
**Circular badge/stamp:**
- Logo mark centered in a circle
- Brand name or tagline running around the perimeter as border text
- Works as a seal, authentication mark, or brand stamp
### → Bad Mockups (Hard Bans)
- ❌ Full fake dashboards with dense data visualizations
- ❌ Cheap glossy 3D device renders with unrealistic reflections
- ❌ Multiple devices showing different screens in the same panel
- ❌ Busy app interfaces with many features visible
- ❌ Excessive icon grids
- ❌ Generic device frames with no branded content inside them
- ❌ Browser chrome with just navigation dots and nothing inside
### → Color System Panel Guidance
The color system panel is not just swatches - it is a designed artifact that shows the palette as a system.
**Default approach (use unless the mode specifies otherwise):**
Named color chips with hex codes - each swatch is a rounded rectangle or circle with the color name in small caps above and the hex code below. Example: "Deep Navy" above, "#1A2744" below. ALL palette colors shown together.
**Alternative approaches:**
- Full gradient tint-to-shade strips - each brand color shown from its lightest 5% tint to its darkest 95% shade as a horizontal bar (Thesis reference style)
- Material chips or paint swatches arranged as a stepped cascade
- Stacked horizontal bars showing proportional color usage (primary = widest)
- Color-on-color combinations showing accessible text/background pairings
The color panel MUST include actual hex values or clear color names. An unlabeled row of colored squares is not a system - it is a decoration.
### → Typography Specimen Panel Guidance
The typography panel is NOT optional filler. It is a system artifact.
**Required elements (include at minimum):**
- Large "Aa" in the display typeface
- Weight scale showing at least: Light, Regular, Medium, Bold (listed vertically with the corresponding weight rendering)
- Number row: 0 1 2 3 4 5 6 7 8 9
- Typeface name (e.g., "NORI Display" or "Inter")
**Optional elements:**
- Full alphabet row (A B C D ... X Y Z)
- Primary/secondary pairing demonstration (display + body side by side)
- Large pull-quote set in the display typeface
- Special characters or ligatures if the typeface has them
The specimen must prove the typeface was chosen deliberately, not defaulted to. If you can't name the typeface family, the typography direction isn't specific enough.
---
## Reference Usage Protocol
When the user provides reference images, first determine the **reference mode** before proceeding.
### → Step 0: Determine Reference Mode
| Mode | User signal | What it means |
|---|---|---|
| **Inspiration** | "like this", "this style", "this quality", "inspired by", reference shows someone else's brand | The user admires this work and wants the same STANDARD. Do not copy the logo or content. |
| **Asset** | "this is my logo", "use this logo", "build around this", "here's our mark", "convert this to a brand kit", reference shows the user's OWN logo/mark | The user designed or owns this logo and wants a full brand system built around it. PRESERVE the logo exactly. |
If ambiguous, ask: "Should I build a new logo inspired by this reference, or preserve the exact logo from this image?"
---
### → Mode: Inspiration (default)
Extract quality signals but do not copy content.
**Extract from references:**
- Grid structure and gutter proportions
- Canvas color and texture treatment
- Typography scale (ratio of heading to label)
- Visual density (how much of each panel is filled)
- Logo placement and sizing relative to panel
- Amount and type of text present
- Image treatment (color grading, halftone, overlay style)
- Accent color logic (how many, where used)
- Panel role distribution (which panels serve which purpose)
**Do not copy from references:**
- The exact logo or brand mark
- The exact brand name or tagline
- The exact panel composition or arrangement
- The exact color values
- Any unique visual asset or illustration
Use references as quality calibration, not as templates. The generated board should match the reference's STANDARD, not its CONTENT.
**Logo Anti-Cloning Protocol (Inspiration mode only):**
The AI model will default to reproducing the reference logo's geometry with minor tweaks. This is not a new logo - it is plagiarism.
**The geometry-difference test:** Describe the reference logo's geometry in one sentence, then describe YOUR logo's geometry in one sentence. If both sentences use the same primary shape vocabulary (e.g., both say "crossed bars" or "overlapping diamonds"), your mark is a clone. Start over with a DIFFERENT logo method.
**Rules:**
1. If the reference has a geometric/abstract mark → your mark MUST use a different logo method entirely
2. If the reference has a monogram → your monogram MUST use a different letter AND different construction technique
3. If you catch yourself describing a mark that "echoes" or "is inspired by" the reference logo - that is a clone. Stop. Pick a different method.
4. The prompt must explicitly state: "The logo must NOT resemble [describe reference logo geometry]. Use [your chosen different method] instead."
5. Never describe the reference logo in positive terms in the prompt ("similar to", "inspired by"). Only describe it in negative terms ("NOT like", "avoid", "different from").
---
### → Mode: Asset (user's own logo)
The user has provided THEIR logo. The goal is to build a complete brand system around this existing mark. The logo is sacred - preserve it exactly.
**Step 1: Format Check**
The image model cannot visually interpret vector or document formats. If the user provides any of these, render to PNG FIRST before proceeding:
| Format | Action |
|---|---|
| `.svg` | Render to PNG at 1024px wide (use a browser, Inkscape CLI, or ImageMagick). The model CANNOT see SVG path data. |
| `.pdf`, `.ai`, `.eps` | Export/rasterize to PNG. |
| `.png`, `.jpg`, `.webp` | Ready to use directly. |
If you cannot render the file, tell the user: "I can't visually read SVG/vector files. Can you export it as a PNG so I can see the actual mark?"
**Step 2: Analyze and describe the mark**
1. **Analyze the mark.** Describe its geometry precisely: shape count, arrangement, colors, proportions. This becomes the frozen logo description (§ Logo Consistency Protocol).
2. **Do NOT redesign, simplify, or "improve" the mark.** The user designed it or paid for it. Respect it. Even if it violates the 3-primitive cap or other logo constraints - those constraints are for logos the skill GENERATES, not logos the user PROVIDES.
3. **Write the frozen description from the reference image.** Study the mark and produce the most precise geometric sentence possible. Include exact shape count, spatial arrangement, color placement, and proportions.
4. **Build the brand strategy AROUND the mark.** Extract the logo's visual DNA - is it geometric? organic? monogram? - and let that inform the mode selection, palette, typography, and image-world direction.
5. **Paste the frozen description into every panel assignment.** The mark must appear identical across the board - anchor, mockups, app icon, social, physical. Use the same anti-morphing protocol as for generated logos.
6. **Skip the Logo Concept Method and Reduction Ladder.** Those phases are for designing new logos. When the user provides the logo, jump from Phase 1 (Strategy) directly to Phase 2's non-logo categories (mode, layout, canvas, typography, palette, tagline).
7. **Skip logo anti-cloning checks** in the Visual Diff and Pre-Flight. The cloning checks exist to prevent copying SOMEONE ELSE'S logo. When the user provides their own, faithful reproduction is the goal.
8. **Existing product mockups.** If the user's brief mentions specific features (e.g., "smart briefings", "shredder", "analytics dashboard"), the application mockup panels must reference those REAL features - not invent generic UI. Pull feature names, navigation labels, and UI patterns from the brief. If the user has provided screenshots or the product is accessible, match the actual UI style (sidebar layout, color scheme, component style). A brand kit for a real product with fake generic screenshots undermines the entire board.
---
## Active Baseline Configuration
These dials calibrate the engine's output. They are defaults. Adapt dynamically from the brief.
```
BRAND_DEPTH: 9 (1=surface decoration, 10=deep strategic identity)
LOGO_SIMPLICITY: 8 (1=complex illustration, 10=extreme reduction)
VISUAL_RESTRAINT: 8 (1=loud and busy, 10=sparse and quiet)
GRID_DISCIPLINE: 9 (1=loose organic, 10=strict presentation grid)
SYMBOL_MEANING: 9 (1=arbitrary decoration, 10=every element justified)
PALETTE_CONTROL: 9 (1=many colors, 10=tight monochrome + one accent)
TEXT_SPARSITY: 8 (1=lots of copy, 10=almost no text)
DETAIL_SUBTLETY: 7 (1=no craft details, 10=many hidden details)
```
Adapt from the brief:
- "Playful" or "fun" → reduce VISUAL_RESTRAINT to 5-6, allow brighter palette
- "Corporate" or "enterprise" → increase GRID_DISCIPLINE to 10
- "Creative studio" or "agency" → reduce GRID_DISCIPLINE to 6-7, increase detail
- "Luxury" → maximize VISUAL_RESTRAINT and PALETTE_CONTROL
- "Gaming" or "competitive" → reduce VISUAL_RESTRAINT to 4-5, increase PALETTE_CONTROL accents
- The user's brief always overrides defaults
- Mode 11 (Warm Editorial) → reduce VISUAL_RESTRAINT to 6, increase DETAIL_SUBTLETY to 8
- Mode 12 (Saturated Studio) → reduce VISUAL_RESTRAINT to 4-5, reduce PALETTE_CONTROL to 5-6
- Mode 13 (Soft Gradient) → increase VISUAL_RESTRAINT to 9, increase PALETTE_CONTROL to 8
- Mode 14 (Bold Neon) → reduce VISUAL_RESTRAINT to 3-4, reduce PALETTE_CONTROL to 4-5, increase DETAIL_SUBTLETY to 9
---
## Pre-Flight Checklist (25 Points)
Run this BEFORE rendering the final board. Walk every item. Any failure means correcting the prompt and re-rendering.
### Logo Quality (6 checks)
- [ ] 1. Is the logo describable in one sentence of geometry? ("It's a [shape] [operation] a [shape]")
- [ ] 2. Does the logo use ≤3 geometric primitives?
- [ ] 3. Would the logo be recognizable at 16×16 pixels (favicon test)?
- [ ] 4. Does the logo work in both black-on-white and white-on-black (inversion test)?
- [ ] 5. Is the logo free of ALL items in the Logo Anti-Patterns list?
- [ ] 6. Can the construction be shown as ≤3 guide shapes?
### Board Composition (6 checks)
- [ ] 7. Does every panel serve a DIFFERENT function? (no two panels doing the same job)
- [ ] 8. Is there visual rhythm - quiet panels alternating with loud panels?
- [ ] 9. Is at least one panel image-dominant (80%+ image)?
- [ ] 10. Is at least one panel type-dominant (tagline/specimen)?
- [ ] 11. Is there at least one panel showing the logo genuinely SMALL (favicon, app icon, social avatar)?
- [ ] 12. Are at least 3 different composition anchors used across panels?
### Brand System Coherence (5 checks)
- [ ] 13. Does the accent color repeat across ≥3 panels?
- [ ] 14. Is the image-world conceptually connected to the brand thesis / core metaphor?
- [ ] 15. Is the color system shown as a designed object with hex values or color names (not random unlabeled swatches)?
- [ ] 16. Is there a typography specimen with at least 2 weights shown?
- [ ] 17. Does the tagline pass the transplant test? (Would it sound wrong on a competitor's board?)
### Anti-Slop (5 checks)
- [ ] 18. Is the board free of purple-blue AI gradient glow (unless strategy justifies it)?
- [ ] 19. Is the board free of floating 3D objects in empty space?
- [ ] 20. Is the board free of generic stock imagery or cliché AI visuals?
- [ ] 21. Is the board free of lorem ipsum, gibberish text, or paragraphs of fake copy?
- [ ] 22. Is the board free of overcomplicated logo marks with >3 elements?
### Physical Reality (3 checks)
- [ ] 23. Is there at least one physical touchpoint (card, box, badge, merch, seal)?
- [ ] 24. If a website mockup exists, does it show an actual hero section with content (not just browser chrome with dots)?
- [ ] 25. If a social media mockup exists, does it have avatar, handle, bio, and stats (not just a logo in a circle)?
### Reference Cloning (3 checks - only when user provided reference images)
- [ ] 26. Does the logo use a DIFFERENT geometric construction than the reference logo? (Run the geometry-difference test)
- [ ] 27. Does the logo use a DIFFERENT logo method than the reference? (e.g., if reference used Construction Geometry, you used Negative Space)
- [ ] 28. Did the prompt explicitly include a negative constraint stating what the logo must NOT look like?
**If any checkbox fails, the board is not ready. Fix and re-check before generating.**
---
## Example Interpretations
### Example 1: AI Developer Tool
User: "Generate a brand kit for Kuro, an AI coding agent for senior engineers."
Interpretation:
- **Strategy Brief:** Dark developer-tool identity. Audience: senior engineers. Core metaphor: the scaffold. Emotional promise: quiet confidence.
- **Visual Mode:** Dark Developer / Builder
- **Layout:** 3 × 3 Full Identity System
- **Canvas:** Pure field, near-black `#0a0a0a`
- **Logo Method:** Monogram + Meaning - "K" with a scaffold/frame negative space cut
- **Typography:** Monospace technical + compressed display sans heading
- **Palette:** `#0a0a0a` base / `#1a1a1a` surface / `#f0ede8` text / `#00d4aa` teal accent
- **Tagline:** "What will you build today?" (Interrogative energy)
- **Premium details:** page number '01', construction grid at 15% opacity, terminal command `npm install kuro`, browser chrome with `app.kuro.dev`
### Example 2: Luxury Compliance Platform
User: "Brand kit for TrustPaw, a compliance monitoring tool with a friendly-but-serious tone."
Interpretation:
- **Strategy Brief:** Light editorial identity for compliance. Audience: legal/ops teams. Core metaphor: the watchdog. Emotional promise: trustworthy guardian.
- **Visual Mode:** Light Editorial / Compliance
- **Layout:** 2 × 3 Cinematic Deck Overview
- **Canvas:** Textured paper, warm ivory `#fdfbf7`
- **Logo Method:** Metaphor Fusion - dog silhouette + shield form, reduced to a geometric seal
- **Typography:** Editorial serif + clean sans pairing
- **Palette:** `#fdfbf7` base / `#f5f0e8` surface / `#1a1a1a` text / `#1e40af` deep blue accent + `#b91c1c` crimson secondary
- **Tagline:** "On guard." (Imperative energy)
- **Premium details:** embossed seal texture, small serif labels, badge mockup, warm stationery application
### Example 3: Gaming / Betting App
User: "Brand board for LuckDrop, a mobile game with loot drops and competitive leagues."
Interpretation:
- **Strategy Brief:** Dark gaming identity. Audience: competitive mobile gamers. Core metaphor: the jackpot moment. Emotional promise: electric reward.
- **Visual Mode:** Gaming / Betting / Competition
- **Layout:** 3 × 3 Full Identity System
- **Canvas:** Gradient depth, deep black `#050505` to dark purple `#0d0015`
- **Logo Method:** Metaphor Fusion - dice face + drop shape, neon-outlined mark
- **Typography:** Expressive display, bold and angular
- **Palette:** `#050505` base / `#0d0015` surface / `#f0f0f0` text / `#22c55e` neon green accent + `#eab308` gold secondary
- **Tagline:** "Every drop counts." (Fragment energy)
- **Premium details:** reward chip UI, leaderboard fragment, app icon on dark home screen, gold trophy badge
### Example 4: AI Knowledge Platform (Mode 11 - Warm Editorial)
User: "Brand kit for Athena, an AI research assistant that synthesizes scientific papers."
Interpretation:
- **Strategy Brief:** Warm humanist identity for an AI knowledge tool. Audience: researchers and academics. Core metaphor: the librarian - centuries of human thought organized and accessible. Emotional promise: intellectual warmth and trust. Avoiding cold tech aesthetics and AI-purple.
- **Visual Mode:** Mode 11 - Warm Editorial / Humanist
- **Layout:** 3 × 3 Full Identity System
- **Canvas:** Textured paper, warm cream `#faf5ef`
- **Logo Method:** Construction Geometry - a simple rounded cross inside a circle (reference: Nexus), symbolizing the intersection of knowledge domains
- **Logo Constraints:** 2 primitives (cross + circle). One-sentence: "It's a rounded cross centered in a circle." Favicon-safe: yes.
- **Typography:** Editorial serif (for tagline emphasis) + clean geometric sans (for headings and labels)
- **Palette:** `#faf5ef` base / `#f0e8da` surface / `#1a1a1a` text / `#b8a472` muted gold accent / `#1a2744` deep navy secondary
- **Tagline:** "Every paper. Every connection. *Understood*." (Fragment energy, serif-italic on "Understood")
- **Image-world:** Classical painting panel (Renaissance scholars, botanical illustrations) treated with pixel-mosaic texture. Art IS the brand's intellectual depth argument.
- **Premium details:** serif-italic emphasis word in tagline, social media profile card with @athena_ai handle, editorial website hero mockup with "Try Athena" CTA
### Example 5: Creative Agency (Mode 12 - Saturated Studio)
User: "Brand kit for Lumora, a creative branding agency."
Interpretation:
- **Strategy Brief:** Vibrant studio identity for a branding agency that sells craft. Audience: brand managers and CMOs hiring external creative. Core metaphor: the brand factor - the intersection of strategy and humanistic design. Emotional promise: confidence in craft.
- **Visual Mode:** Mode 12 - Saturated Studio / Agency
- **Layout:** 3 × 3 Full Identity System
- **Canvas:** Branded color field - saturated orange `#ff4d00` as the board canvas
- **Logo Method:** Construction Geometry - overlapping circles forming a flower/petal mark. Construction panel shows the Venn-diagram with labeled concept intersections ("Strategic Vision" + "Humanistic Touch" = "Brand Factor")
- **Logo Constraints:** 3 primitives (3 overlapping circles). One-sentence: "It's three circles overlapping to form a six-petal flower." Favicon-safe: yes.
- **Typography:** Modern geometric sans, strong scale contrast (very large display + very small labels), white text on saturated backgrounds
- **Palette:** `#ff4d00` primary canvas / `#6f2dbd` secondary / `#1a1a4e` dark surface / `#fafafa` text
- **Tagline:** "Design that builds brands that last." (Declarative energy)
- **Image-world:** Noise-gradient textures (mesh gradients with grain), radial gradient burst backgrounds. Zero photography. The brand IS the material.
- **Premium details:** business card mockups in 3 color variants (orange, purple, dark), geometric construction labels, gradient arc color system
### Example 6: Design Feedback Tool (Mode 13 - Soft Gradient)
User: "Brand kit for Thesis, a design feedback tool. Calm, soft gradients, minimal."
Interpretation:
- **Strategy Brief:** Calm tech identity for a design review tool. Audience: product designers and design managers. Core metaphor: the clear thought - feedback without noise. Emotional promise: clarity and quiet confidence.
- **Visual Mode:** Mode 13 - Soft Gradient / Calm Tech
- **Layout:** 3 × 3 Full Identity System
- **Canvas:** Pure field, white `#fafafa` to pale lavender `#f0ecf5`
- **Logo Method:** Construction Geometry - a triangle resting against a rectangle, forming an abstract play/forward shape
- **Logo Constraints:** 2 primitives (triangle + rectangle). One-sentence: "It's a triangle resting against a rectangle." Favicon-safe: yes.
- **Typography:** Clean geometric sans, medium weight, generous letter-spacing
- **Palette:** `#fafafa` base / `#f0ecf5` surface / `#1a1a2e` text / `#3366ff` electric blue accent / `#f08080` soft coral secondary
- **Tagline:** "The clear thought." (Fragment energy)
- **Image-world:** Soft organic gradient blobs (peach-to-blue, lavender-to-periwinkle) as brand atmosphere. Gradients are the visual weather, not decoration.
- **Color system:** Gradient tint-to-shade strips showing the full palette range from 5% tint to 95% shade
- **Premium details:** dark-mode UI variant panel, gradient blob flowing across panel borders, named color chips with hex codes
### Example 7: Creative OS Platform (Mode 14 - Bold Neon)
User: "Full brand system for NORI, a creative design OS for professional designers."
Interpretation:
- **Strategy Brief:** Bold creative-OS identity covering every touchpoint. Audience: professional designers and creative studios. Core metaphor: creative momentum - the OS that moves as fast as the ideas. Emotional promise: boundless creative energy. The brand exists in physical space as much as on screen.
- **Visual Mode:** Mode 14 - Bold Neon / Creative OS
- **Layout:** 6 × 3 Mega System (18 panels)
- **Canvas:** Pure field, true black `#000000`
- **Logo Method:** Construction Geometry - two rounded bars crossing into an X-knot ribbon shape
- **Logo Constraints:** 2 primitives (2 rounded bars). One-sentence: "It's two rounded bars crossing into a knot." Favicon-safe: yes. Shown at 5 scales across the board.
- **Typography:** Full Aa specimen with weight scale (Light / Regular / Medium / Bold) + number row (0-9) + custom display face name
- **Palette:** `#000000` base / `#0a0a0a` surface / `#F5F3EE` text / `#7A5CFF` Electric Purple / `#CCFF00` Neon Lime / `#FF6A4D` Coral Burst / `#4SD6FF` Sky Blue
- **Tagline:** "Focus. Create. Ship." (Imperative energy)
- **Image-world:** Iridescent gradient glass panels + dark product photography (box on dark surface, hoodie flat-lay) + lifestyle shots (card in hand, box on desk)
- **Mega touchpoints:** Logo cover (black bg) + logo on neon lime bg + construction proof + logo pattern tile + website hero + app icon dock + social media profile + notification card + business card + product box + hoodie + membership card + color system (named chips) + typography specimen (Aa + weights + numbers) + process icons (Capture → Organize → Create → Share) + circular badge + campaign tagline + brand-world image
- **Premium details:** ALL color swatches labeled with hex, member number on card (0017 8200 5731), chip detail on card, notification toast with real message
---
## Response Behavior
When the user asks for a brand-kit image, follow this execution flow:
**Phase 0: Visual Reference Acquisition**
1. Ask the user for a reference/inspiration image (if not already provided)
2. If reference provided: analyze for 8 DNA strands (surface, layout, cards, color, type, illustration, logo presentation, signature moves)
3. Generate the REFERENCE INSTRUCTION block (EXTRACT half + BLOCK half)
4. If reference is low-res (<512px), warn but proceed
**Phase 1-2: Strategy & Architecture**
5. Read the brief carefully - extract every signal
6. Write the Brand Strategy Brief (3-5 lines, committed direction)
7. Narrow the symbol pool to 2-3 candidates
8. Pick ONE visual mode from the 14 options
9. Pick ONE option from every remaining Phase 2 category (layout, canvas, logo method, typography, color discipline, tagline energy)
10. Walk the Logo Reduction Ladder - describe the mark's construction
11. Verify logo passes ALL Hard Constraints (§ Logo Hard Constraints) - 3-primitive cap, favicon test, one-sentence geometry, inversion test
**Phase 3-4: Composition & Prompt**
12. Assign panel roles using the Argument Structure
13. Assign composition anchors and energy levels to each panel
14. Plan 3-5 premium details
15. Build the complete Prompt Blueprint - fill in every field
16. If Phase 0 produced a REFERENCE INSTRUCTION block, prepend it to the prompt
17. Include the WHAT THIS IS NOT section with 4+ anti-patterns
18. Run the Anti-Slop check against your prompt
19. Run the 25-Point Pre-Flight Checklist - all must pass before generating
**Phase 5: Generate & Audit**
20. Generate the board image
21. Run the Visual Diff (Phase 5) - every check must pass
22. If any check fails, identify the failure, correct the prompt, and regenerate
**Phase 6: Panel Surgery (if needed)**
23. If 1-2 specific panels fail while the rest pass, diagnose the failure type
24. Generate replacement panels as standalone cards using the Single-Panel Prompt Template
25. Guide the user to composite in Figma (import board → overlay replacement → export)
**Phase 7: Logo Originality Gate (if reference was used)**
26. Run the geometry-difference audit: describe both marks, run vocabulary overlap test
27. Run the visual similarity check: symmetry, shape count, negative space
28. If clone detected: choose a different logo method and shape vocabulary, regenerate
29. If 2 attempts still clone: recommend the Nuclear Option (user designs logo externally, switch to Asset mode)
**Deliver**
30. Deliver the final board with a 2-3 line summary of the identity direction
Do not ask unnecessary follow-up questions if a strong interpretation is possible.
Do not generate without completing Phases 0-4 first.
Do not skip the Pre-Flight Checklist, the Visual Diff, or the Logo Originality Gate (when applicable).
---
## The Core Principles
These are the non-negotiable fundamentals. They apply regardless of which combinatorial picks you make. When any decision conflicts with these principles, the principles win.
> **Strategy before aesthetics.** The brand strategy dictates every visual decision. A board without a clear brand idea is just arranged rectangles, no matter how beautiful they are. If you cannot state the core metaphor in one sentence, you are not ready to generate.
> **The logo must be earned.** The logo is not the first thing you design - it is the last thing the strategy produces. It emerges from the intersection of the brand's action, metaphor, and cultural position. A logo designed before the strategy is a random icon.
> **One board, one idea, one system.** Every panel contributes to a single brand direction. The palette threads through every panel. The logo appears identically wherever it shows. The typography hierarchy is consistent across applications. If you swap the logo for another brand's mark and nothing else feels wrong, the system has no identity.
> **Sparse over busy. Quiet over loud. Intentional over decorative.** Remove until it hurts. Then remove one more element. The board should feel like it has generous space, not cramped density. Premium identity work whispers. Generic AI output shouts.
> **The grid is sacred.** Gutters must be consistent. Edges must align. Panels must relate to each other through proportion, not random sizing. The grid is not a constraint - it is the presentation system that makes the identity feel professional. Break the grid only with a panel bleed, and only once per board.
> **Reward closer inspection.** The board should have 3-5 details that a viewer discovers on second look: a construction line, a page number, a highlighted word, a subtle texture. These details signal craft. But they must not compete with the primary read. Detail is dessert, not the main course.Elite frontend image-direction skill for generating premium, conversion-aware website design reference images via ChatGPT image generation. Fires when th
---
name: imagegen-frontend-web
description: Elite frontend image-direction skill for generating premium, conversion-aware website design reference images via ChatGPT image generation. Fires when the user asks to generate website mockups, landing page concepts, section design references, or UI comp images. Enforces ONE separate horizontal image PER section, composition variety (bans the default left-text/right-image on every section), background-image freedom, varied CTAs, varied hero scales, narrative concept spine, second-read moments, and a single consistent palette across all images. Outputs structured prompt blueprints that produce Awwwards-tier visual references a developer or coding model can accurately recreate. Image generation only - does not write code.
---
# Elite Frontend Image Art Direction
> This skill fires when the user asks to generate website design reference images, landing page mockups, section comp images, UI concept visuals, or any image that will serve as a frontend design reference. You are an art director, not an illustrator. Every image you generate must be a structured, premium, implementation-friendly website section that a developer could look at and code. This skill does NOT write code - it produces the visual references that feed into the pixel-perfect, hero, and motion skills.
---
## The Hard Output Rule - Read First
**Generate ONE separate horizontal image PER section. Always. No exceptions.**
```
1 section requested → 1 image
4 sections requested → 4 images
8 sections requested → 8 images
12 sections requested → 12 images
"landing page" (no count) → default 6 sections → 6 images
"full website template" → default 8 sections → 8 images
```
Each image is one section, generated as its own image call. Never combine multiple sections into one tall frame. Never return a single image containing the whole page.
If you can only render one image at a time, output them sequentially - announce each one: *"Section 1 of 8: Hero"*, *"Section 2 of 8: Trust bar"*, etc.
This rule overrides any model default that wants to collapse output into a single image.
---
## The Pipeline
```
┌──────────────────────────────────────────────────────────────────────────┐
│ │
│ BRIEF IN ──→ Phase 1: Read the Brief │
│ (extract brand signals, classify style, │
│ map brief to direction dials) │
│ │
│ ──→ Phase 2: Art Direction │
│ (commit to combinatorial picks: │
│ theme, typography, hero, sections, │
│ composition anchors, backgrounds, │
│ CTAs, narrative spine, second-read) │
│ │
│ ──→ Phase 3: Prompt Engineering │
│ (build structured prompt per section │
│ using the blueprint templates) │
│ │
│ ──→ Phase 4: Generate │
│ (one image per section, announce each) │
│ │
│ ──→ Phase 5: Visual Diff │
│ (verify against brief, check for │
│ AI default drift, composition variety) │
│ │
│ Each phase has a ✓ Quality Gate. Failing a gate blocks the next. │
│ │
└──────────────────────────────────────────────────────────────────────────┘
```
---
## The Core Doctrine
Before generating any image, internalize these. They override every aesthetic preference. The quality bar is **Awwwards SOTD winners, Apple product pages, Linear marketing, Stripe homepage, Vercel brand.** If your generated image would look generic next to these, it is not good enough.
> **You are an art director, not a prompt monkey.** Standard AI image generation collapses into the same 5 defaults: centered dark hero, purple/blue AI glow, floating meaningless blobs, generic dashboard cards, and weak typography hierarchy. Your job is to aggressively break these defaults with intentional, structured, premium compositions.
> **Every image is a frontend reference.** The output must communicate layout, section hierarchy, spacing, typography scale, and color palette clearly enough that a developer can look at it and code it. Random mood art is not acceptable unless the user explicitly asks for it.
> **Composition variety is mandatory.** The left-text / right-image split is the most overused AI layout pattern. It is allowed, but never as the default, and never twice in a row. Across a multi-section page, at least 3 different composition anchors must appear.
> **One palette, threaded consistently.** All sections of a page share the same palette. The palette is chosen once in Phase 2 and applied to every section. Sections can vary in background mode (solid, image, gradient) but the hues must be consistent. A page where the hero is warm cream and the features section is cool blue-gray is a broken design system.
> **Whitespace is a design material.** Sections must breathe. The default AI instinct is to pack every pixel with content. Fight it. Generous negative space between elements is what separates premium from busy. Bias toward slightly more whitespace than you think is necessary.
> **Conversion awareness.** Every section has a job - hook, prove, educate, or convert. The page must flow as a persuasion sequence, not a random collection of pretty sections. Even purely visual references should imply where the user's eye goes and what action they should take.
---
## Phase 1: Read the Brief
Before generating anything, extract design signals from the user's request. Do not project your own aesthetic onto the brief. Read what is actually there.
### → Extract these signals
| Signal | What to look for |
|---|---|
| **Brand type** | SaaS / Agency / E-commerce / Portfolio / Editorial / Fintech / Health / AI / Crypto / Personal brand / Nonprofit |
| **Mood keywords** | Clean, bold, cinematic, minimal, editorial, premium, luxury, playful, dark, light, warm, cold, technical, organic |
| **Density preference** | Airy / balanced / packed - infer from "minimal" vs "feature-rich" vs "content-heavy" |
| **Image preference** | Photography-led / illustration-led / typography-led / product-focused / abstract |
| **Target audience** | Developer tools / Consumer / Enterprise / Creative professional / Luxury consumer |
| **Explicit constraints** | Specific colors mentioned, specific fonts mentioned, dark/light mode specified, specific section requests |
| **Reference links** | Any URLs, screenshots, or brand names the user mentions as inspiration |
| **Section count** | Explicit count or inferred from "landing page" (6), "full site" (8), "one-pager" (5-7) |
### → Output the Direction Brief
State in 2-3 lines the art direction you are committing to:
> *"Direction Brief: Dark cinematic SaaS landing page for an AI infrastructure product. 7 sections. Palette: deep charcoal base + warm off-white text + single amber accent. Typography: compressed display grotesk (Monument Extended energy). Giant statement hero with product screenshot as focal. Photography-led backgrounds with tonal color grading. Conversion-driven AIDA flow. Feels like: Linear meets Vercel with a warmer accent."*
### → Brief-to-Direction Mapping
Read the brief. Then bias your picks:
| If the user says... | Bias toward... |
|---|---|
| **"minimalist" / "clean" / "swiss" / "ultra simple"** | Mini Minimalist hero, solid surfaces, stacked center compositions, generous negative space, skip full-bleed images |
| **"editorial" / "magazine" / "art-directed" / "fashion"** | Mid Editorial or Giant Statement hero, editorial side-image backgrounds, off-grid compositions, strong typography contrast, duotone image treatments |
| **"cinematic" / "atmospheric" / "premium" / "luxury" / "bold"** | Giant Statement hero, full-bleed image backgrounds with tonal overlay, soft radial vignettes, bottom-left/centered-low text placement |
| **"SaaS" / "product" / "dashboard" / "fintech" / "infra"** | Mid Editorial hero, solid + inline asset backgrounds, clear product framing, trust-driven anchors, higher implementation clarity |
| **"agency" / "creative studio" / "portfolio"** | Giant Statement OR Mini Minimalist hero (commit to one), bold background variety, off-grid poster-like compositions |
| **"e-commerce" / "shop" / "store" / "product page"** | Mid Editorial hero with strong product focus, full-bleed product photography, product-led compositions, unmistakable CTAs |
| *Brief is silent on style* | Use defaults from the Configuration Baseline, pick decisively, do not split the difference |
### → If the brief is vague
Ask exactly ONE question: *"What's the brand name, one-line value prop, and preferred mood - closer to [dark cinematic] or [light editorial]?"*
If you can infer from context (e.g., user said "AI startup" or "luxury agency"), skip the question and declare your Direction Brief.
### ✓ Quality Gate: Brief
Before moving to Phase 2, confirm:
- All 8 signals are extracted (or inferred)
- Direction Brief is written
- You know the mood, palette direction, hero scale, and section count
- You have NOT started generating any images yet
---
## Phase 2: Art Direction (The Combinatorial Variation Engine)
This is the engine that prevents repetitive AI output. For each category below, commit to ONE option based on the brief. Do not blend. Do not hedge. Pick and commit.
The picks must be internally consistent - a "Quiet Premium Neutral" theme with "Monument-like compressed statement typography" is a valid pairing. A "Pristine Light Mode" theme with a "Deep Dark Mode" background character is not.
---
### → Theme Paradigm (pick 1)
| # | Theme | When to use |
|---|---|---|
| 1 | **Pristine Light Mode** - Off-white / cream / paper tones, sharp dark text, editorial confidence | Clean SaaS, editorial, health, lifestyle |
| 2 | **Deep Dark Mode** - Charcoal / graphite / zinc, elegant glow only when justified | Dev tools, AI/ML, gaming, cinematic |
| 3 | **Bold Studio Solid** - Strong controlled color fields (oxblood, royal blue, forest, vermilion, emerald) with crisp contrasting UI | Agency, creative studio, brand-forward |
| 4 | **Quiet Premium Neutral** - Bone, sand, taupe, stone, smoke, muted contrast, restrained luxury | Luxury, finance, architecture, fashion |
### → Background Character (pick 1 global default)
| # | Background | Character |
|---|---|---|
| 1 | Subtle technical grid / dotted field | Precise, engineered, dev-tool feel |
| 2 | Pure solid field with soft ambient gradient depth | Clean, modern, lets content breathe |
| 3 | Full-bleed cinematic imagery with proper contrast control | Atmospheric, editorial, immersive |
| 4 | Quiet textured paper / material / tactile surface feel | Warm, craft-oriented, luxury print |
### → Typography Character (pick 1)
| # | Type | Energy |
|---|---|---|
| 1 | **Satoshi-like clean grotesk** | Modern, approachable, startup-friendly |
| 2 | **Neue-Montreal-like refined grotesk** | Polished, agency, premium tech |
| 3 | **Cabinet/Clash-like expressive display** | Bold, statement, creative |
| 4 | **Monument-like compressed statement** | Industrial, dramatic, high-impact |
| 5 | **Elegant editorial serif + sans pairing** | Editorial, luxury, magazine |
| 6 | **Swiss rational sans with very strong hierarchy** | Structured, systematic, enterprise |
⚠ **Drift Warning:** Never drift into default web typography energy. The heading must feel like an architectural element, not "big text." If the generated image shows a heading that could be from any WordPress template, the typography pick was wrong.
### → Hero Architecture (pick 1)
| # | Architecture | Best for |
|---|---|---|
| 1 | **Cinematic Centered Minimalist** - Heading centered, cinematic visual fills background or floats behind text | Dark cinematic, immersive product launches |
| 2 | **Asymmetric Split** - Massive heading one side, supporting content other side, deliberate vertical tension | Bold agency, AI/tech launches |
| 3 | **Full-Bleed Subject** - Full-viewport photograph IS the hero, typography overlaid directly | Athlete/personal brand, fashion, lifestyle |
| 4 | **Typographic Poster** - Typography IS the visual, no hero image, viewport-bleeding scale | Creative studio, personal brand, editorial |
| 5 | **Editorial Offset** - Off-grid composition, asymmetric pulls, text and image not conventionally aligned | Magazine, editorial, art-directed brand |
| 6 | **Massive Image-First** - Photograph dominates, restrained text anchors a corner or edge | Product photography, luxury, e-commerce |
⚠ **Drift Warning:** The left-text / right-image hero is the most overused AI image generation pattern. It is allowed but should NOT be your first instinct. Before reaching for it, consider: centered over background image, bottom-left over image, top-left lead, stacked center, image-as-canvas, off-grid editorial. Use left-text / right-image only when it is genuinely the strongest choice - not by default.
### → Hero Scale (pick 1)
| Scale | Character |
|---|---|
| **Giant Statement** - Massive type, large image, dominant first viewport | Cinematic, atmospheric, brand-forward |
| **Mid Editorial** - Balanced type/image, cinematic but not screen-filling | SaaS, product, professional |
| **Mini Minimalist** - Tiny logo + short statement + thin CTA, lots of negative space | Confident restraint, luxury, swiss |
Mini does not mean weak - it means confident restraint.
### → Section System (pick 1 dominant structure)
| # | System | Character |
|---|---|---|
| 1 | **Strict modular bento rhythm** | Dense, organized, data-rich |
| 2 | **Alternating editorial blocks** | Narrative, story-driven |
| 3 | **Poster-like stacked storytelling** | Cinematic, chapter-based |
| 4 | **Gallery-led visual cadence** | Image-forward, portfolio |
| 5 | **Swiss grid discipline** | Rational, structured, systematic |
| 6 | **Asymmetric premium marketing flow** | Dynamic, agency, conversion-led |
### → Composition Anchor (assign 1 per section)
Each section picks 1 anchor. Across the site, **at least 3 different anchors must appear.** Never use the same anchor twice in a row.
| Anchor | Description |
|---|---|
| **Centered statement** | All content centered, symmetrical, authoritative |
| **Top-left lead, support bottom-right** | Reading-order diagonal flow |
| **Bottom-left text over background image** | Cinematic, editorial overlap |
| **Bottom-right CTA cluster** | Conversion-focused terminal anchor |
| **Left-third caption + right-two-thirds visual** | Classic split - use sparingly, never twice in a row |
| **Right-third caption + left-two-thirds visual** | Inverted classic - same rules |
| **Centered low** | Text in lower 40% over hero image, dramatic negative space above |
| **Off-grid editorial offset** | Asymmetric pull, text and image deliberately misaligned |
| **Stacked center** | Label / headline / sub / CTA all centered, ultra minimalist |
| **Image-as-canvas with text in safe area** | Image IS the section, text sits in a clear zone |
### → Background Mode (assign 1 per section)
Pick 1 per section. Vary across the page - never all the same mode. Backgrounds are a primary design tool, not a risk.
| Mode | Description |
|---|---|
| **Solid surface + inline asset** | Clean, safe, product-forward |
| **Subtle texture / paper / grid** | Tactile depth without imagery |
| **Full-bleed image + tonal overlay** | Cinematic, atmospheric, text must remain readable |
| **Editorial side-image (50/50, 60/40)** | Split composition, invertible |
| **Image-as-canvas + text overlay** | Image IS the background, text in safe area |
| **Flat color block + product crop accent** | Modernist, product-focused |
| **Cinematic tonal gradient** | Palette-matched, low chroma, professional |
| **Atmospheric photo with color grade** | Single-tone graded for brand mood |
| **Duotone treated image** | Two-color photo treatment, palette-locked |
| **Soft radial vignette + product crop** | Luxury / editorial feel |
| **Micro-noise gradient over solid** | Premium tactile depth, subtle not flashy |
| **Color-blocked diptych** | Two flat fields meeting, modernist |
### → CTA Variation (assign 1 per section)
Pick the CTA style that fits each section. Not a default pill every time. Across the site, vary CTA style at least once. The primary action stays unmistakable.
| CTA Style | When |
|---|---|
| **Classic primary pill** | Hero, pricing, final CTA |
| **Outline / ghost** | Secondary actions, subtle sections |
| **Underlined inline link with arrow** | Editorial, content sections |
| **Banner-style full-width CTA** | Conversion sections, urgency |
| **Oversized headline + tiny CTA hint** | Statement sections, confidence plays |
| **CTA as caption under a strong visual** | Image-led sections, galleries |
### → Signature Components (pick exactly 4)
| Component | Character |
|---|---|
| Diagonal Staggered Square Masonry | Dynamic, gallery-forward |
| 3D Cascading Card Deck | Depth, perspective, showcase |
| Hover-Accordion Slice Layout | Interactive, content-dense |
| Pristine Gapless Bento Grid | Organized, data-rich, modern |
| Infinite Brand Marquee Strip | Social proof, trust, motion |
| Turning Polaroid Arc | Playful, portfolio, scattered |
| Vertical Rhythm Lines | Editorial, structured, swiss |
| Off-Grid Editorial Layout | Magazine, art-directed |
| Product UI Panel Stack | SaaS, product demo, feature |
| Split Testimonial Quote Wall | Social proof, long-form |
| Oversized Metrics Strip | Authority, data-driven |
| Layered Image Crop Frames | Depth, editorial, cinematic |
### → Motion-Implied Language (pick exactly 2)
These are NOT code instructions. They are visual-direction cues that the generated image should visually imply through composition, blur, positioning, and element arrangement.
| Motion Language | What it implies visually |
|---|---|
| **Scrubbing text reveal energy** | Text elements at varying opacities, some faded, some sharp |
| **Pinned narrative section energy** | Sticky sidebar feel, content scrolling against a fixed element |
| **Staggered float-up energy** | Elements at slightly different vertical positions, cascade feel |
| **Parallax image drift energy** | Background and foreground at different scales, depth layers |
| **Smooth accordion expansion energy** | Horizontal or vertical slices, one expanded, others compressed |
| **Cinematic fade-through energy** | Overlapping transparency, elements dissolving into each other |
### → Narrative / Concept Spine (pick 1)
One conceptual thread that runs through the visual language of the entire page.
| Spine | Character |
|---|---|
| **Artifact / collectible** | Proof, specimen, treasured object framing |
| **Journey / pilgrimage** | Directional flow, waypoint sections, roadmap feeling |
| **Tool / precision instrument** | Machined detail, calibrated UI, tactile controls |
| **Living system / garden** | Organic growth, branching layout, nurtured tone |
| **Stage / spotlight** | Theatrical contrast, performer + audience framing |
| **Archive / dossier** | Indexed rows, captions, understated authority |
### → Second-Read Moment (pick exactly 1)
One unobvious but legible motif, placed deliberately once across the page. It rewards closer inspection without disrupting scan order.
| Moment | Description |
|---|---|
| **Asymmetric bleed** | One element deliberately breaks the grid but respects hierarchy |
| **Oversized punctuation/numeral** | A single massive character serves structural purpose |
| **Unexpected material switch** | Paper vs gloss vs metal accent - one section shifts texture |
| **Narrow vertical side-rail** | Editorial note style, a column of secondary info |
| **Macro crop** | A detail crop carries brand color naturally, not a full image |
Avoid gimmick-for-gimmick. The moment must aid scan order or brand recall.
### ✓ Quality Gate: Art Direction
Before moving to Phase 3, confirm:
- ONE option selected from each category (no blending, no hedging)
- Picks are internally consistent (theme + typography + hero make sense together)
- At least 3 different composition anchors assigned across sections
- Background modes vary across sections (not all the same)
- CTA style varies at least once across sections
- Exactly 4 signature components selected
- Exactly 2 motion languages selected
- Exactly 1 narrative spine selected
- Exactly 1 second-read moment selected
- No left-text / right-image used as the default hero composition
---
## Phase 3: Prompt Engineering
Each section gets its own structured prompt built from the Phase 2 picks. This is where art direction becomes generation-ready instructions.
### → The Prompt Blueprint
Every section prompt follows this structure. Fill in every field - skipping fields produces generic output.
```
PROMPT BLUEPRINT - Section [N] of [Total]: [Section Name]
─────────────────────────────────────────────────────────
FRAME:
Format: horizontal website section, 16:9 aspect ratio
Viewport: 1440×900 desktop browser frame
Render style: [photorealistic UI mockup / flat design comp / editorial layout]
COMPOSITION:
Anchor: [from Phase 2 - e.g., "centered statement" or "bottom-left over background"]
Visual weight: [where the eye lands first - e.g., "center-left, massive heading"]
Reading flow: [how the eye moves - e.g., "heading → subtext → CTA → background visual"]
TYPOGRAPHY:
Heading: [exact description - e.g., "massive compressed sans-serif, all-caps,
approximately 80pt equivalent, tight letter-spacing, 2 lines max"]
Subtext: [e.g., "16pt equivalent, regular weight, muted color, max 20 words,
1.5 line-height"]
Eyebrow: [e.g., "11pt monospace, uppercase, wide letter-spacing, muted opacity"]
CTA text: [e.g., "14pt, medium weight, uppercase, inside pill button"]
PALETTE:
Background: [exact description - e.g., "#0a0a0a deep charcoal with subtle
radial glow from center"]
Text primary: [e.g., "#f5f5f5 warm off-white"]
Text secondary: [e.g., "rgba(255,255,255,0.5) muted"]
Accent: [e.g., "#E8A04A warm amber - used on CTA only"]
BACKGROUND MODE:
[from Phase 2 - e.g., "full-bleed cinematic photograph of server rack room,
cool blue-teal color grade, 40% dark overlay for text readability"]
CTA:
Style: [from Phase 2 - e.g., "solid pill, amber background, dark text"]
Placement: [e.g., "centered below subtext, 32px gap"]
Count: [1 - never more in a hero]
ATMOSPHERE:
[e.g., "subtle film grain overlay at 3% opacity, soft radial ambient glow
from top-center, no hard shadows"]
CONTENT (placeholder text):
Eyebrow: [e.g., "INFRASTRUCTURE"]
Heading: [e.g., "Build without limits."]
Subtext: [e.g., "The platform for teams who ship fast."]
CTA: [e.g., "Get Started →"]
WHAT THIS IS NOT:
[Explicit anti-patterns - e.g., "NOT a generic dark hero with purple AI glow.
NOT a dashboard screenshot. NOT centered text over a gradient blob."]
MOTION IMPLIED:
[from Phase 2 - e.g., "staggered float-up energy: the heading, subtext, and
CTA appear at slightly different vertical offsets as if mid-cascade"]
```
### → Prompt Anti-Patterns (The Banned Defaults)
These are the patterns AI image generation collapses into. Every prompt must explicitly state what the image is NOT to counteract model defaults.
| Banned Pattern | Why it's banned | What to say instead |
|---|---|---|
| **Purple/blue AI gradient hero** | Every AI-generated "tech" image defaults to this. It screams "generated." | Specify the exact palette from Phase 2. Add "no purple, no blue gradient backgrounds." |
| **Floating translucent blobs** | The AI's version of "atmosphere" - meaningless glass orbs floating in space | Specify concrete atmosphere: grain, radial glow, tonal gradient, or photographic background |
| **Generic dashboard card grid** | AI loves generating 6-8 identical cards with line charts | Specify the exact component from Phase 2's signature set. Describe its unique geometry |
| **Centered text over gradient** | Safe, generic, says nothing about the brand | Specify the exact composition anchor from Phase 2. Force an asymmetric or editorial layout |
| **"Luxury" = beige serif on cream** | The AI's entire luxury vocabulary | Specify the actual luxury signals: restrained spacing, tactile texture, considered typography weight |
| **"Creative" = messy and unreadable** | Chaos ≠ creativity | Specify structured asymmetry: deliberate off-grid placement with clear reading order |
| **Tiny illegible text** | AI generates decorative text that no one can read | Specify minimum type scale: "heading must be legible and dominant, minimum 60pt equivalent" |
| **Identical section layouts** | Every section looks the same - same split, same proportion | Use the composition anchor assignments from Phase 2 - each section has a different anchor |
| **Stock photo energy** | Generic business people shaking hands, laptop on desk | Specify the exact photographic direction: subject, color grade, mood, crop style |
⚠ **Drift Warning:** The single most impactful thing you can add to any prompt is the "WHAT THIS IS NOT" section. AI models are as responsive to negative constraints as positive ones. Telling the model "NOT a purple gradient hero, NOT floating blobs, NOT a generic dashboard" eliminates 80% of default AI output.
### → Section-Specific Prompt Guidance
Different sections have different jobs. Use these section blueprints to ensure each section serves its purpose in the conversion flow.
**Section: Hero**
```
PURPOSE: Hook - the first thing the user sees. Must create an instant
emotional response and communicate the brand's energy in < 3 seconds.
MUST HAVE:
- ONE dominant focal point (massive heading OR cinematic image, not both competing)
- Brand name or product name visible
- Single CTA (never two)
- Breathing room - the hero must NOT feel packed
MUST NOT HAVE:
- Trust logos / "used by" badges (save for trust bar)
- Feature lists or bullet points
- Multiple competing CTAs
- Scroll indicators / bouncing chevrons
- Version labels (v2.0, BETA) unless the brief is literally a product launch
PROMPT ADDITION:
"This is a website hero section - the first viewport a user sees.
It must feel premium, confident, and immediately communicate the brand.
One focal point dominates. Generous whitespace. No clutter."
```
**Section: Trust Bar**
```
PURPOSE: Proof - immediately after the hero, establish credibility.
MUST HAVE:
- Logo strip OR metric strip OR testimonial quote
- Muted, understated styling (this section supports, not competes with hero)
- Visually lighter than surrounding sections
PROMPT ADDITION:
"This is a trust/social-proof bar. It should be visually quiet and
supportive - a thin horizontal strip of logos or a single powerful
metric. Not a full section, more like a divider with authority."
```
**Section: Features / Benefits**
```
PURPOSE: Interest - show what the product does and why it matters.
MUST HAVE:
- Clear visual hierarchy (section heading → feature items)
- Distinct feature blocks (cards, columns, or bento cells)
- Icons or micro-illustrations per feature (not just text)
MUST NOT HAVE:
- More than 6 feature items visible (3-4 is stronger)
- Identical card layouts without visual variation
- "FEATURE 01", "FEATURE 02" meta-labels
PROMPT ADDITION:
"This is a features/benefits section. Each feature should be
visually distinct with an icon or illustration. Cards should
NOT all look identical. Hierarchy: section heading first, then
feature grid below."
```
**Section: Social Proof / Testimonials**
```
PURPOSE: Desire - make the user want what others already have.
MUST HAVE:
- Real-looking names and avatar-style photos
- Quote text that feels authentic (not marketing copy)
- Company/role attribution
PROMPT ADDITION:
"This is a testimonial section. Show 1-3 quotes with avatar photos,
names, and company roles. The quotes should feel human and authentic.
Layout should feel editorial, not like a review aggregator."
```
**Section: CTA / Conversion**
```
PURPOSE: Action - the final push. High contrast, unmistakable action.
MUST HAVE:
- High-contrast background (inverted from the page's dominant mode)
- Single, dominant CTA button
- Short, punchy heading (3-7 words)
- Minimal supporting text
PROMPT ADDITION:
"This is the final conversion section. It should feel like a
decisive endpoint - high contrast, bold heading, unmistakable
CTA button. If the page is light, this section goes dark (or
uses the accent color as background). Maximum confidence."
```
**Section: Footer**
```
PURPOSE: Navigation + trust - the page's foundation.
MUST HAVE:
- Logo
- Link columns (Product, Company, Resources, Legal)
- Muted, structured, visually quiet
- Copyright line
PROMPT ADDITION:
"This is a website footer. Clean, organized link columns with
a logo. Visually understated - it anchors the page without
competing for attention. Dark or muted background."
```
### ✓ Quality Gate: Prompts
Before moving to Phase 4, confirm:
- Every section has a complete prompt following the blueprint structure
- Every prompt includes a WHAT THIS IS NOT section
- Palette is consistent across all section prompts
- Typography direction is consistent across all section prompts
- Composition anchors vary across sections (cross-reference Phase 2 assignments)
- Background modes vary across sections
- CTA styles vary at least once
- No prompt defaults to left-text / right-image without deliberate justification
- Placeholder content uses realistic text (no "Lorem ipsum", no "Company Name")
---
## Phase 4: Generate
Execute the prompts sequentially. One image per section.
### → Generation Rules
| Rule | Why |
|---|---|
| **Announce each section** before generating | *"Section 3 of 7: Features - Pristine Gapless Bento Grid with staggered float-up energy"* |
| **Horizontal format, 16:9** | Website sections are landscape, not portrait |
| **One section per image** | The Hard Output Rule - no exceptions |
| **Include the full prompt blueprint** in the generation call | Do not summarize - the model needs every field |
| **Verify palette consistency** before each generation | The accent color from section 1 must appear in section 5 |
| **Adjust prompt if a generation drifts** | If image 3 comes back with a purple gradient, re-generate with stronger anti-pattern language |
### → Section Sequencing
For a default landing page (6 sections), generate in this order:
```
Section 1: Hero - [Hook]
Section 2: Trust Bar - [Proof]
Section 3: Features - [Interest]
Section 4: How It Works - [Education]
Section 5: Testimonials - [Desire]
Section 6: CTA + Footer - [Action]
```
For a full website template (8 sections):
```
Section 1: Hero - [Hook]
Section 2: Trust Bar - [Proof]
Section 3: Features - [Interest]
Section 4: How It Works - [Education]
Section 5: Showcase/Demo - [Demonstration]
Section 6: Testimonials - [Desire]
Section 7: Pricing - [Decision]
Section 8: CTA + Footer - [Action]
```
Each section maps to a conversion stage. This is not arbitrary - the sequence follows AIDA (Attention → Interest → Desire → Action) with proof and education layers inserted for credibility.
### ✓ Quality Gate: Generation
After generating all images, confirm:
- Total image count matches section count (no missing sections)
- Each image is a separate horizontal image (no combined frames)
- Palette is visually consistent across all images (same accent, same base tones)
- No two adjacent sections use the same composition anchor
- At least 3 different composition anchors appear across all sections
- The hero is NOT a default left-text / right-image split (unless deliberately chosen)
- No purple/blue AI gradient backgrounds appear (unless the palette specifically calls for it)
- Typography scale is consistent (headings feel the same weight/family across sections)
---
## Phase 5: Visual Diff
Compare the generated images against the Direction Brief from Phase 1 and the Art Direction picks from Phase 2. Walk through every check. Any FAIL means re-generating that section with a corrected prompt.
### Composition Diff
| Check | PASS/FAIL |
|---|---|
| At least 3 different composition anchors appear across all sections | |
| No two adjacent sections use the same anchor | |
| The hero uses the assigned hero architecture (not a generic split) | |
| No section feels "empty" or "packed" - whitespace is intentional | |
| Each section has a clear visual hierarchy (primary → secondary → tertiary) | |
| Reading flow within each section is intuitive (eye knows where to go) | |
### Palette Diff
| Check | PASS/FAIL |
|---|---|
| All sections share the same base palette | |
| Accent color is consistent (same hue) across all sections | |
| No rogue colors appear that were not in the Direction Brief | |
| No AI-default purple/blue gradients unless explicitly chosen | |
| Dark sections use off-black (#0a0a0a), not pure black (#000000) | |
| Light sections use warm cream/off-white, not pure white (#FFFFFF) | |
### Typography Diff
| Check | PASS/FAIL |
|---|---|
| Heading typography feels consistent across all sections (same weight/family vibe) | |
| Heading scale is viewport-dominant (not "big text" - architectural) | |
| No section has headings wrapping beyond 3 lines | |
| Subtext is visually secondary (smaller, muted, constrained width) | |
| No illegible text (everything is readable at the generated resolution) | |
| Eyebrow/label text is present where assigned and visually consistent | |
### Section Purpose Diff
| Check | PASS/FAIL |
|---|---|
| Hero hooks - creates immediate emotional response | |
| Trust bar proves - quiet authority, not competing with hero | |
| Features inform - clear hierarchy, distinct items | |
| Testimonials persuade - human, authentic, editorial | |
| CTA converts - high contrast, unmistakable action | |
| Footer grounds - structured, quiet, anchoring | |
| The page flows as a persuasion sequence, not random sections | |
### AI Default Drift Diff
| Check | PASS/FAIL |
|---|---|
| No purple/blue AI gradient backgrounds (unless palette specifies) | |
| No floating translucent blobs | |
| No generic dashboard card spam | |
| No "luxury = beige serif" cliché | |
| No "creative = messy chaos" cliché | |
| No identical section layouts repeating | |
| No stock photo energy (generic business imagery) | |
| No meta-labels ("SECTION 01", "FEATURE 03") | |
| No em-dashes in copy | |
| No AI copywriting clichés ("Elevate", "Seamless", "Unleash", "Next-Gen", "Revolutionize") | |
### Implementation Readiness Diff
| Check | PASS/FAIL |
|---|---|
| Each image clearly communicates layout structure (a developer could grid this) | |
| Spacing is visible and measurable (not ambiguous overlap) | |
| Component boundaries are clear (cards have edges, sections have gaps) | |
| CTA buttons are clearly delineated (not text that might be a button) | |
| Image areas are distinguishable from background (clear boundaries) | |
| The image could be handed to the pixel-perfect skill and coded accurately | |
---
## Active Baseline Configuration
These are the global default dials. They calibrate the engine's output toward premium, conversion-aware, implementation-friendly design references.
```
DESIGN_VARIANCE: 8 (1=rigid/symmetrical, 10=artsy/asymmetric)
VISUAL_DENSITY: 4 (1=airy/gallery-like, 10=packed/intense)
ART_DIRECTION: 8 (1=safe commercial, 10=bold creative statement)
IMPLEMENTATION_CLARITY: 9 (1=loose moodboard, 10=very codeable UI reference)
IMAGE_USAGE_PRIORITY: 9 (1=mostly typographic, 10=strongly image-led)
SPACING_GENEROSITY: 8 (1=compact/tight, 10=very spacious/breathable)
LAYOUT_VARIATION: 8 (1=same anchor repeats, 10=bold composition variety)
CONVERSION_DISCIPLINE: 8 (1=pure art moodboard, 10=clear funnel + design balance)
```
These are defaults. Adapt dynamically from the brief:
- "Clean" → reduce density, increase spacing generosity
- "Crazy creative" → increase variance and art direction
- "Premium SaaS" → keep clarity high, art direction controlled
- "Editorial" → allow stronger type and more asymmetry
- The user's brief always overrides defaults
---
## The Core Principles
These are the fundamentals that separate premium design references from generic AI images. They apply regardless of which combinatorial picks you make.
> **One focal point per section.** Every section has ONE dominant visual element. Count elements competing for attention at the same scale. If the count exceeds 2, reduce until one clearly dominates.
> **Viewport-scale typography.** Headings are architectural elements, not "big text." They should feel like they command the section. Minimum 60pt equivalent on desktop. For 1-3 word headings, go massive - 100pt+. Tight tracking. Compressed line-height.
> **Extreme whitespace.** The background is not wasted space - it IS the design. Content lives in considered islands surrounded by intentional breathing room. If a section feels cramped, the spacing is wrong.
> **Tight palette, threaded consistently.** Maximum 3 hues across the entire page. Dark pages: off-black + warm white + one accent. Light pages: warm cream + near-black + one accent. The accent appears in CTAs and active states. Everything else is the base palette. More than one saturated accent across a page destroys visual cohesion.
> **Every section has a job.** Hero hooks. Trust bar proves. Features inform. Testimonials persuade. CTA converts. No section exists for decoration. Every section advances the user toward action.
> **The image is the spec.** The generated image must be clear enough that a developer can look at it and code it using the pixel-perfect skill. If the layout, spacing, typography, or component boundaries are ambiguous in the image, it has failed as a reference.Image-to-code replication pipeline. When the user provides a screenshot or design reference, this skill runs a structured extraction across seven lay
---
name: pixel-perfect-replication
description: Image-to-code replication pipeline. When the user provides a screenshot or design reference, this skill runs a structured extraction across seven layers (grid, type, color, spacing, components, atmosphere, interaction), builds an Extraction Sheet before any code is written, implements with exact fidelity to the reference, and verifies through inline Quality Gates and a final Visual Diff. The reference image is the spec. The code is a translation, not an interpretation.
---
# Pixel-Perfect Design Replication
> This skill fires when the user provides a screenshot, mockup, Figma export, or any design image and asks you to replicate it in code. The reference image is the specification. Your role is translator, not designer. Every visual decision - font size, spacing, color, radius, shadow, layout proportion - comes from the image, not from your preferences.
---
## The Pipeline
Every replication job follows this flow. No phase can be skipped. No phase can start before the previous one completes.
```
┌─────────────────────────────────────────────────────────────────────┐
│ │
│ IMAGE IN ──→ Phase 1: Intake ──→ Phase 2: Deep Extraction │
│ (classify) (7 layers, fill sheets) │
│ │
│ ──→ Phase 3: Build │
│ (structure-first, exact CSS) │
│ │
│ ──→ Phase 4: Visual Diff │
│ (verify against reference) │
│ │
│ Each phase has a ✓ Quality Gate. Failing a gate blocks the next. │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
---
## Phase 1: Image Intake
Receive the reference image. Before doing anything else, classify what you are looking at.
### → Classify the image
Fill in this table for every reference image:
| Field | Your answer |
|---|---|
| **Image type** | Full-page screenshot / single section / component detail / mobile view / desktop view / Figma frame / design tool export / live site screenshot |
| **Sections visible** | List top-to-bottom, e.g. "Nav → Hero → Features → Testimonials → Footer" |
| **Target viewport** | Estimated width: 1440px (desktop), 1280px (laptop), 768px (tablet), 375px (mobile) |
| **Fidelity** | High-res export (sub-pixel details are intentional) / compressed screenshot (some lossy artifacts) |
| **Theme** | Light / Dark / Mixed |
### → Output the Extraction Summary
Before any code, state what you see in structured natural language. This anchors every decision that follows.
Example:
> *Light mode, 1440px desktop. Five sections: sticky frosted nav with logo left / links center / CTA right, hero with massive serif heading left-aligned over full-bleed photography, 3-col feature grid with icon-top cards, testimonial carousel with large quotation marks, minimal footer with 4-col link grid. Palette: warm cream base, near-black text, terracotta accent on CTAs. Typography: serif display heading (likely Playfair Display), geometric sans body (likely Outfit). Cards are sharp-cornered, buttons are pill-shaped. No visible shadows - flat design with subtle border separators.*
### → If the image is unclear
Do not guess. Ask specifically:
> *"The nav links are too compressed to read at this resolution. The body font could be Outfit or Satoshi - they share near-identical geometry at this size. Can you provide a closer crop of the nav, or confirm the font stack?"*
### ✓ Quality Gate: Intake
Before moving to Phase 2, confirm:
- You have classified the image type, section count, viewport, and fidelity
- You have written the Extraction Summary
- You have flagged any unclear areas and asked for clarification (or confirmed everything is readable)
---
## Phase 2: Deep Extraction
Run all seven extraction layers on the reference image. Each layer focuses on one dimension of the design. Fill in the Extraction Sheet for each. Skipping a layer causes drift - small errors here compound into "it looks off" in the final build.
---
### Layer 1: Layout Grid
Extract the spatial skeleton.
**Extraction Sheet:**
| Property | Measured value |
|---|---|
| Container max-width | e.g. `1280px`, `1440px` - measure by proportion against viewport edges |
| Column system | e.g. `grid-cols-[1.15fr_1fr]`, `grid-cols-3`, `single column centered` |
| Horizontal padding | e.g. `px-6 md:px-12 lg:px-20` - measure the gap between content edge and viewport edge |
| Section heights | `min-h-[100dvh]` for full-viewport, `auto` for content-driven |
| Section spacing | Vertical gap between sections, e.g. `py-24 lg:py-32` |
| Alignment | Per-section: left / center / right / mixed |
| Z-axis layering | Any overlaps? Elements stacked on top of others? |
**How to measure proportions from images:**
- If the hero heading occupies ~60% of viewport width, on a 1440px target that is roughly `max-w-[54rem]`
- If one column is visually 1.5x wider than the adjacent column, use `grid-cols-[1.5fr_1fr]`
- If empty space above a heading is roughly 2x the heading font size, the padding is approximately `2em` relative to the heading
⚠ **Drift Warning:** The most common layout error is getting the container max-width wrong. A design with `max-w-[1200px]` looks noticeably different from one with `max-w-[1440px]` - the whitespace proportions change completely. Measure carefully.
---
### Layer 2: Typography
This is the most critical extraction. Wrong typography is the #1 reason a replication "looks off."
**Extraction Sheet (fill for EVERY visible text element):**
| Element | Font family | Weight | Size | Line-height | Letter-spacing | Transform | Color |
|---|---|---|---|---|---|---|---|
| Nav links | | | | | | | |
| Eyebrow/label | | | | | | | |
| H1 (hero) | | | | | | | |
| H2 (section) | | | | | | | |
| H3 (card title) | | | | | | | |
| Body text | | | | | | | |
| Caption/meta | | | | | | | |
| CTA text | | | | | | | |
| Footer links | | | | | | | |
**Font identification - what to look for:**
Fonts reveal themselves through specific characters. Study these before guessing:
| Check this character | What it tells you |
|---|---|
| Lowercase `a` | Single-story (Geist, Helvetica) vs double-story (Outfit, Satoshi, DM Sans) |
| Lowercase `g` | Open-tail (most sans-serifs) vs closed-tail (Futura, some geometric) |
| Lowercase `t` | Curved crossbar (humanist: Manrope, Jakarta) vs straight (geometric: Outfit, Satoshi) |
| Capital `R` | Straight leg (Geist, Helvetica) vs curved leg (Outfit, Satoshi) |
| Capital `Q` | Tail style varies dramatically between fonts - strong identifier |
| Lowercase `e` | High crossbar (geometric) vs centered (humanist) |
| Numbers `1, 4, 6, 9` | Highly distinctive shapes across fonts |
**Common web font quick-reference:**
| Visual character | Strong candidates |
|---|---|
| Geometric, double-story `a`, round counters | Outfit, Satoshi, DM Sans, Plus Jakarta Sans |
| Grotesque, single-story `a`, flat terminals | Geist, Suisse Intl, Helvetica Neue |
| Humanist, open counters, calligraphic stress | Manrope, Plus Jakarta Sans, Nunito Sans |
| Condensed, tall x-height | Barlow Condensed, Oswald, Archivo Narrow |
| Modern serif, high contrast, sharp serifs | Playfair Display, Bodoni Moda |
| Transitional serif, moderate contrast | Lora, Merriweather, Source Serif Pro |
| Display sans, wide, heavy | Cabinet Grotesk, Clash Display, Monument Extended |
| Monospace | JetBrains Mono, Fira Code, IBM Plex Mono, Geist Mono, Space Mono |
If you cannot confidently identify the font, state your top 2-3 candidates with the distinguishing character that makes you lean one way. Example: *"The double-story 'a' and round 'o' suggest Outfit, but the slightly squared terminals could indicate Satoshi. Defaulting to Outfit - swap by changing `--font-display` if incorrect."*
⚠ **Drift Warning:** Never assume a heading is `font-weight: 700` because "headings are bold." Many premium designs use `500` or `600` for headings with a heavier font face. Look at stem thickness relative to the counter space.
---
### Layer 3: Color Palette
Extract every distinct color. Not "it uses blue" - extract the hex.
**Extraction Sheet:**
| Role | Hex value | Notes |
|---|---|---|
| Background (primary) | | e.g. `#F5F0EB` warm cream, not plain `#FFFFFF` |
| Background (secondary) | | Alternate section BG, card BG |
| Background (dark section) | | If any sections flip to dark |
| Text (primary) | | Heading + body text on primary BG |
| Text (secondary) | | Muted descriptions, metadata |
| Text (tertiary) | | Placeholders, disabled states |
| Accent | | CTAs, active indicators, links |
| Accent (hover) | | Darker/lighter variant on interaction |
| Border | | Card borders, dividers, input borders |
| Shadow | | If tinted, note the hue |
**Extracting colors from compressed screenshots:**
Screenshots compress colors. To get accurate values:
- Sample from the **largest flat area** of the color, not from edges or JPEG artifacts
- Cross-reference with common web values - if you measure `#0b0b0b`, it is almost certainly `#0a0a0a` (standard off-black). If you measure `#f4f3f1`, it is likely `#f5f4f2` (common warm cream)
- After extracting, verify WCAG AA contrast between text and background colors to confirm the values are reasonable
⚠ **Drift Warning:** The difference between `#FFFFFF` (pure white) and `#F5F0EB` (warm cream) completely changes the feel of a page. Do not default to `#FFFFFF` or `#000000` unless the reference genuinely shows pure values - most premium designs use off-white and off-black.
---
### Layer 4: Spacing System
Spacing is what separates "looks close" from "looks identical."
**Extraction Sheet:**
| Measurement | Value | How to verify |
|---|---|---|
| Base unit | `4px` or `8px` | Measure the smallest repeated gap |
| Button padding (H) | e.g. `24px` / `px-6` | Horizontal space between text edge and button edge |
| Button padding (V) | e.g. `12px` / `py-3` | Vertical space |
| Card internal padding | e.g. `32px` / `p-8` | Space from card edge to card content |
| Grid gap | e.g. `24px` / `gap-6` | Space between cards/columns |
| Heading → subtext | e.g. `16px` / `mt-4` | Gap between heading baseline and subtext top |
| Subtext → CTA | e.g. `32px` / `mt-8` | Gap between subtext and button |
| Section padding (top) | e.g. `96px` / `pt-24` | Space from section top to first element |
| Section padding (bottom) | e.g. `128px` / `pb-32` | Space from last element to section bottom |
| Nav height | e.g. `64px` / `h-16` | Total nav bar height |
| Nav link gap | e.g. `32px` / `gap-8` | Space between nav links |
⚠ **Drift Warning:** Top and bottom section padding are often **not** equal. Many designs use more bottom padding than top (or vice versa) for optical balance. Do not assume `py-24` when the reference shows `pt-20 pb-28`. Measure each side independently.
---
### Layer 5: Component Inventory
Catalog every distinct UI component visible in the image.
**For each component, fill in:**
| Component | Shape (radius) | Border | Shadow | Background | States visible | Icon style |
|---|---|---|---|---|---|---|
| Primary button | | | | | | |
| Secondary button | | | | | | |
| Card | | | | | | |
| Input field | | | | | | |
| Badge/pill | | | | | | |
| Avatar | | | | | | |
| Navigation | | | | | | |
| Divider | | | | | | |
**Border-radius consistency check:** Most designs commit to one radius language. Check whether the design uses:
- **Sharp** - `0px` everywhere (brutalist, editorial)
- **Subtle** - `4-8px` everywhere (SaaS, product)
- **Rounded** - `12-16px` everywhere (modern, friendly)
- **Pill** - `9999px` on buttons, rounded on cards (premium, polished)
- **Mixed** - different radii for different components (verify each one)
⚠ **Drift Warning:** If buttons are pill-shaped (`rounded-full`) in the reference, they cannot be `rounded-lg` in the code. Radius mismatches are immediately visible - the eye detects them faster than color or spacing errors.
---
### Layer 6: Atmosphere and Texture
Extract the subtle details that make a design feel alive vs flat.
**Extraction Sheet:**
| Property | Present? | Details |
|---|---|---|
| Noise/grain overlay | yes/no | Opacity level (typically `0.03-0.06`) |
| Radial ambient glow | yes/no | Position, color, spread |
| Frosted glass (backdrop-blur) | yes/no | On what elements, blur amount |
| Gradient backgrounds | yes/no | Direction, stops, colors |
| Tinted shadows | yes/no | Shadow hue, not just black |
| Image overlays/scrims | yes/no | Gradient direction, opacity |
| Background images/patterns | yes/no | Subtle texture, dots, lines |
| Depth/layering feel | flat / subtle / heavy | Overall shadow usage |
---
### Layer 7: Responsive Cues and Interaction Inference
Even from a static image, extract clues about behavior.
**Extraction Sheet:**
| Signal | Inference |
|---|---|
| Multi-column layout | Will collapse to single column below 768px |
| Horizontal nav bar | Will need mobile menu below 768px |
| Sticky-looking nav | `position: fixed; top: 0` with backdrop-blur likely |
| Elements positioned as if "just landed" | Entry animation implied (fade-up with stagger) |
| Buttons with visual depth | Lift on hover (`translateY(-1px)`, shadow increase) |
| Cards with borders | Border color change or subtle background shift on hover |
| Dot indicators near images | Carousel/slider component |
| Active/selected tab styling | Tab component with state management |
| Form inputs visible | Focus ring, validation states needed |
---
### ✓ Quality Gate: Extraction
Before moving to Phase 3, confirm:
- All seven Extraction Sheets are filled in
- Font candidates are identified with reasoning
- Every distinct color has a hex value
- Spacing values are measured, not assumed
- Component inventory is complete with radius, border, shadow noted per component
- Anything unclear has been flagged to the user
---
## Phase 3: Build
Implementation starts here. Follow this exact build order - each step depends on the one before it.
### → Step 1: Global Foundation
Set the design tokens first. Everything else references these.
```css
/* BLUEPRINT: Global tokens
WHY: Setting these first means every component inherits
the correct base values. Changing a token here updates
the entire page. */
@import url('https://fonts.googleapis.com/css2?family=FONT_NAME:wght@300;400;500;600;700&display=swap');
:root {
/* Colors - from Extraction Sheet Layer 3 */
--color-bg: #____;
--color-surface: #____;
--color-text: #____;
--color-text-2: #____;
--color-text-3: #____;
--color-accent: #____;
--color-accent-hover: #____;
--color-border: rgba(_, _, _, _);
/* Typography - from Extraction Sheet Layer 2 */
--font-display: 'FONT_NAME', Georgia, serif;
--font-body: 'FONT_NAME', system-ui, sans-serif;
--font-mono: 'FONT_NAME', monospace;
/* Spacing - from Extraction Sheet Layer 4 */
--space-section: clamp(5rem, 10vw, 8rem);
--space-component: 2rem;
--space-element: 1rem;
/* Radius - from Extraction Sheet Layer 5 */
--radius-card: __px;
--radius-button: __px;
--radius-input: __px;
}
*,
*::before,
*::after {
margin: 0;
padding: 0;
box-sizing: border-box;
}
body {
font-family: var(--font-body);
font-size: 1rem; /* Adjust if reference base is not 16px */
line-height: 1.6; /* From extraction */
color: var(--color-text);
background-color: var(--color-bg);
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
}
```
### → Step 2: Layout Skeleton
Build the section containers with correct dimensions. No content yet - just the boxes.
```css
/* BLUEPRINT: Section containers
WHY: Getting the spatial structure right first prevents
cascading spacing errors when content is added. */
.section {
width: 100%;
max-width: ____px; /* From Layer 1 extraction */
margin: 0 auto;
padding: var(--space-section) clamp(1.5rem, 5vw, 5rem);
}
/* Full-viewport section */
.section--full {
min-height: 100dvh;
/* WHY dvh not vh: vh causes a layout jump on iOS Safari
when the address bar collapses. dvh accounts for this. */
display: flex;
flex-direction: column;
justify-content: center;
}
/* Grid layouts - adjust columns to match reference */
.grid-2-asymmetric {
display: grid;
grid-template-columns: 1.15fr 1fr; /* From Layer 1 */
align-items: center;
gap: 4rem;
}
.grid-3-equal {
display: grid;
grid-template-columns: repeat(3, 1fr);
gap: 1.5rem; /* From Layer 4 */
}
@media (max-width: 768px) {
.grid-2-asymmetric,
.grid-3-equal {
grid-template-columns: 1fr;
gap: 2rem;
}
}
```
### → Step 3: Typography Pass
Apply all text styles from the Layer 2 Extraction Sheet.
```css
/* BLUEPRINT: Typography scale
WHY: Every property is explicitly set from the extraction.
Never rely on browser defaults - they will drift. */
.heading-display {
font-family: var(--font-display);
font-size: clamp(2.5rem, 6vw, 5rem); /* From extraction */
font-weight: 700; /* Verified from stem thickness, not assumed */
line-height: 0.95; /* Tight - measured from baseline gap */
letter-spacing: -0.03em; /* Negative - measured from character proximity */
color: var(--color-text);
text-wrap: balance;
max-width: 18ch; /* Prevents 4+ line wraps */
}
.heading-section {
font-family: var(--font-display);
font-size: clamp(1.75rem, 4vw, 3rem);
font-weight: 600;
line-height: 1.1;
letter-spacing: -0.02em;
color: var(--color-text);
}
.body-text {
font-family: var(--font-body);
font-size: clamp(0.9375rem, 1.1vw, 1.125rem);
font-weight: 400;
line-height: 1.65;
color: var(--color-text-2);
max-width: 55ch; /* Comfortable reading width */
}
.eyebrow {
font-family: var(--font-mono);
font-size: 0.6875rem;
font-weight: 500;
letter-spacing: 0.18em;
text-transform: uppercase;
color: var(--color-text-3);
}
.caption {
font-size: 0.8125rem;
line-height: 1.5;
color: var(--color-text-3);
}
```
⚠ **Drift Warning:** Do not round font sizes to convenient values. If the extraction shows `15px` body text, use `0.9375rem`, not `1rem`. If the heading looks like `72px`, use `4.5rem`, not `5rem`. Rounding accumulates across the page.
### → Step 4: Components Pass
Build each component from the Layer 5 Extraction Sheet.
```css
/* BLUEPRINT: Button - primary
WHY: Padding, radius, and font-size are from the extraction.
The transition easing (0.16, 1, 0.3, 1) gives a snappy
deceleration that feels physical. */
.btn-primary {
display: inline-flex;
align-items: center;
justify-content: center;
gap: 0.5rem;
padding: 0.75rem 1.5rem; /* From Layer 4 */
font-family: var(--font-body);
font-size: 0.875rem; /* From Layer 2 */
font-weight: 600;
letter-spacing: 0.04em; /* Only if extraction shows tracking */
text-transform: uppercase; /* Only if extraction shows uppercase */
border-radius: var(--radius-button);
background: var(--color-accent);
color: #FFFFFF;
border: none;
cursor: pointer;
text-decoration: none;
transition: all 0.3s cubic-bezier(0.16, 1, 0.3, 1);
}
.btn-primary:hover {
background: var(--color-accent-hover);
transform: translateY(-1px);
box-shadow: 0 4px 16px rgba(0, 0, 0, 0.12);
}
.btn-primary:active {
transform: translateY(0) scale(0.98);
}
.btn-primary:focus-visible {
outline: 2px solid var(--color-accent);
outline-offset: 2px;
}
/* BLUEPRINT: Button - ghost/outline */
.btn-ghost {
display: inline-flex;
align-items: center;
justify-content: center;
gap: 0.5rem;
padding: 0.75rem 1.5rem;
font-family: var(--font-body);
font-size: 0.875rem;
font-weight: 500;
border-radius: var(--radius-button);
background: transparent;
color: var(--color-text);
border: 1px solid var(--color-border);
cursor: pointer;
text-decoration: none;
transition: all 0.3s cubic-bezier(0.16, 1, 0.3, 1);
}
.btn-ghost:hover {
border-color: var(--color-text);
background: rgba(0, 0, 0, 0.03);
}
/* BLUEPRINT: Card */
.card {
background: var(--color-surface);
border-radius: var(--radius-card);
padding: var(--space-component);
border: 1px solid var(--color-border);
/* Shadow: only add if extraction shows shadow */
}
/* BLUEPRINT: Navigation */
.nav {
position: fixed;
top: 0;
left: 0;
right: 0;
z-index: 50;
height: 64px; /* From Layer 4 extraction */
display: flex;
align-items: center;
justify-content: space-between;
padding: 0 clamp(1.5rem, 5vw, 5rem);
background: rgba(255, 255, 255, 0.85); /* Adjust to match */
backdrop-filter: blur(16px);
-webkit-backdrop-filter: blur(16px);
border-bottom: 1px solid var(--color-border);
}
.nav-link {
font-size: 0.875rem;
font-weight: 500;
color: var(--color-text-2);
text-decoration: none;
transition: color 0.2s ease;
}
.nav-link:hover {
color: var(--color-text);
}
```
### → Step 5: Spacing Adjustments
Walk through every element gap and verify against the Layer 4 Extraction Sheet. This is where implementations most commonly drift.
### → Step 6: Atmosphere Pass
Add texture and depth from the Layer 6 Extraction Sheet. Only add what the reference shows.
```css
/* BLUEPRINT: Noise/grain overlay
WHY: Breaks digital flatness. Only add if the reference
shows subtle texture on the background.
Uses position:fixed so the grain doesn't scroll. */
.grain-overlay {
position: fixed;
inset: 0;
pointer-events: none;
z-index: 9999;
opacity: 0.04; /* Adjust to match reference intensity */
background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)' opacity='1'/%3E%3C/svg%3E");
}
/* BLUEPRINT: Ambient radial glow
WHY: Adds depth to flat dark backgrounds. Only use if the
reference shows a subtle light center. */
.ambient-glow {
position: absolute;
inset: 0;
background: radial-gradient(
ellipse 60% 50% at 50% 40%,
rgba(255, 255, 255, 0.035) 0%,
transparent 70%
);
pointer-events: none;
}
/* BLUEPRINT: Frosted glass surface
WHY: For navs or overlays that show content blurring through.
saturate(180%) makes colors pop through the blur layer. */
.surface-frosted {
background: rgba(255, 255, 255, 0.8);
backdrop-filter: blur(20px) saturate(180%);
-webkit-backdrop-filter: blur(20px) saturate(180%);
}
```
⚠ **Drift Warning:** Do not add grain, glow, or blur if the reference does not show them. These are atmosphere details, not defaults. Adding texture the reference does not have is interpretation, not replication.
### → Step 7: Responsive Pass
If the reference is desktop-only, infer mobile behavior from the layout structure. If both desktop and mobile references are provided, match both exactly.
```css
/* BLUEPRINT: Mobile collapse
WHY: Every multi-column layout must collapse to single-column.
Touch targets must be minimum 44px for accessibility. */
@media (max-width: 768px) {
.grid-2-asymmetric,
.grid-3-equal {
grid-template-columns: 1fr;
}
.heading-display {
/* clamp() already handles this, but verify the minimum */
max-width: 100%;
}
.nav {
/* May need a hamburger menu implementation */
}
/* Touch targets */
.btn-primary,
.btn-ghost,
.nav-link {
min-height: 44px;
}
}
```
### → Step 8: Interaction Pass
Add hover states and entry animations. Static images cannot show interaction, but every interactive element needs feedback.
```css
/* BLUEPRINT: Staggered entry animation
WHY: Elements that fade+slide in feel intentional.
The blur-to-sharp adds perceived quality.
prefers-reduced-motion disables for accessibility. */
@keyframes enter {
from {
opacity: 0;
transform: translateY(24px);
filter: blur(6px);
}
to {
opacity: 1;
transform: translateY(0);
filter: blur(0);
}
}
.animate-in {
animation: enter 0.7s cubic-bezier(0.16, 1, 0.3, 1) both;
}
.animate-in:nth-child(1) { animation-delay: 0.05s; }
.animate-in:nth-child(2) { animation-delay: 0.15s; }
.animate-in:nth-child(3) { animation-delay: 0.25s; }
.animate-in:nth-child(4) { animation-delay: 0.35s; }
@media (prefers-reduced-motion: reduce) {
.animate-in {
animation: none;
opacity: 1;
transform: none;
filter: none;
}
}
/* Universal interactive transition */
a, button, [role="button"], input, select, textarea {
transition: all 0.3s cubic-bezier(0.16, 1, 0.3, 1);
}
```
### ✓ Quality Gate: Build
Before moving to Phase 4, confirm:
- Global tokens are set from extraction values, not defaults
- Layout skeleton matches the reference section structure
- Typography uses explicit values for every property (no browser defaults)
- Components match extraction sheets for radius, border, shadow, and padding
- Spacing between elements is verified against the reference
- Atmosphere effects are only present if the reference shows them
- Responsive collapse is implemented
- Hover/focus states are present on all interactive elements
---
## Phase 4: Visual Diff
Compare your implementation against the reference image. This is the final verification. Walk through every category below. Mark each item PASS or FAIL. Any FAIL blocks delivery.
### Layout Diff
| Check | PASS/FAIL |
|---|---|
| Section count and order match | |
| Container max-width proportions match | |
| Horizontal padding matches | |
| Grid column counts and ratios match | |
| Section heights feel proportionally correct | |
| Vertical spacing between sections matches | |
| Element alignment (left/center/right) matches per section | |
| Z-axis layering matches (if present) | |
### Typography Diff
| Check | PASS/FAIL |
|---|---|
| Font family loaded and rendering correctly | |
| Heading size proportionally correct against viewport | |
| Heading weight matches (not too thin, not too heavy) | |
| Heading line-height matches (tight vs relaxed) | |
| Heading letter-spacing matches (tight vs wide) | |
| Body text size matches | |
| Body line-height and max-width match | |
| Eyebrow/label styling matches (size, case, tracking, font) | |
| Text colors match per element type | |
### Color Diff
| Check | PASS/FAIL |
|---|---|
| Primary background color matches (not #FFF when it should be #F5F0EB) | |
| Text colors match (primary and secondary) | |
| Accent color matches | |
| Border/divider colors match | |
| No unexpected color shifts between sections | |
### Component Diff
| Check | PASS/FAIL |
|---|---|
| Button radius matches (pill vs rounded vs sharp) | |
| Button padding matches | |
| Button text styling matches (size, weight, case, tracking) | |
| Card styling matches (radius, padding, border, shadow) | |
| Navigation matches (height, background treatment, link styling) | |
| Image treatment matches (radius, aspect ratio, object-fit) | |
### Spacing Diff
| Check | PASS/FAIL |
|---|---|
| Heading → subtext gap matches | |
| Subtext → CTA gap matches | |
| Card internal padding matches | |
| Grid gap between elements matches | |
| Section padding (top AND bottom independently) matches | |
| Overall breathing room / negative space feels correct | |
### Atmosphere Diff
| Check | PASS/FAIL |
|---|---|
| Background atmosphere matches (flat/grain/gradient/glow) | |
| Shadow presence and intensity match | |
| Frosted glass / blur effects present where reference shows them | |
| No atmosphere effects added that the reference does NOT show | |
### Technical Checks
| Check | PASS/FAIL |
|---|---|
| Zero console errors | |
| All fonts loaded (no FOUT/FOIT) | |
| All images loaded (no broken placeholders) | |
| No horizontal overflow at any viewport | |
| Hover states on all interactive elements | |
| Focus-visible states for keyboard navigation | |
| `min-h-[100dvh]` used, not `h-screen` | |
| `prefers-reduced-motion` respected | |
---
## Handling Artistic Assets (Photographs, Illustrations, Textures)
CSS can reproduce layout, typography, colors, and geometric shapes. It CANNOT reproduce photographs, hand-drawn illustrations, organic brush strokes, marble textures, or painterly effects. This is the #1 source of drift between reference and output.
### → Classify every visual element in the reference
Walk through the reference and tag each visual element:
| Element type | Can CSS reproduce it? | What to do instead |
|---|---|---|
| **Solid color blocks** | ✅ Yes | Use exact hex from extraction |
| **Linear/radial gradients** | ✅ Yes | Match direction, stops, and colors |
| **Geometric shapes** (circles, rectangles, lines) | ✅ Yes | Use CSS shapes or simple SVG |
| **Icons** (outlined/filled) | ✅ Yes | Use an icon library or inline SVG |
| **Photographs** | ❌ No | Generate a mood-matched image or use `picsum.photos/seed/{keyword}/{w}/{h}` |
| **Hand-drawn illustrations** | ❌ No | Generate a matching illustration with `generate_image` tool |
| **Organic brush strokes / paint textures** | ❌ No | Generate as an image asset - do NOT approximate with CSS gradients |
| **Marble / fluid / organic textures** | ❌ No | Generate as an image asset or use a high-quality stock match |
| **3D renders** | ❌ No | Generate a matching render or use a placeholder with similar lighting/angle |
| **Abstract art / mixed media** | ❌ No | Generate with `generate_image` describing the exact style, colors, and composition |
### → When the reference contains photographs
1. **First choice:** Use `generate_image` to create a photograph that matches the mood, color palette, subject, and composition of the reference
2. **Second choice:** Use `picsum.photos/seed/{descriptive-keyword}/{w}/{h}` with a keyword that matches the content (e.g., `picsum.photos/seed/ocean-waves/800/600` for ocean imagery)
3. **Never:** Use a CSS gradient, striped pattern, or solid color block as a stand-in for a photograph. This is the most visible form of drift
### → When the reference contains illustrations or brush strokes
1. **First choice:** Use `generate_image` with a detailed prompt describing the illustration style, colors, stroke quality, and composition. Include the mood: "organic hand-painted pink brush stroke with visible texture, diagonal across white background, coral/hot-pink color, similar to expressive abstract art"
2. **Second choice:** If `generate_image` is not available, find a stock illustration with matching style and color
3. **Never:** Approximate organic, hand-drawn artwork with CSS gradients or geometric shapes. A diagonal CSS gradient is NOT a brush stroke. A CSS `border-radius` blob is NOT an organic shape. The eye detects the difference instantly
### → When the reference contains textured surfaces
Marble, wood grain, concrete, fabric, water, clouds - these need real image assets:
1. Generate the texture with `generate_image` describing the specific surface
2. Apply as a `background-image` with appropriate `background-size`, `object-fit`, and positioning
3. Match the scale - a zoomed-in marble texture looks different from a zoomed-out one
### → Asset sizing and positioning
When placing generated image assets into the layout:
```css
/* BLUEPRINT: Image asset inside a card or container
WHY: object-fit:cover ensures the image fills the space
without distortion. object-position lets you align the
focal point of the image to match the reference. */
.asset-container {
position: relative;
overflow: hidden;
border-radius: var(--radius-card); /* match card radius */
}
.asset-image {
width: 100%;
height: 100%;
object-fit: cover;
object-position: center; /* adjust to match reference focal point */
}
```
⚠ **Drift Warning:** This is the most common replication failure. When the AI cannot reproduce an artistic element, it substitutes a CSS pattern (stripes, gradients, solid blocks). This ALWAYS looks wrong because geometric CSS patterns have a fundamentally different visual quality than photographs or hand-drawn art. Always generate an image asset instead - even an imperfect generated image is closer to the reference than a CSS approximation.
---
## Edge Cases
### When you cannot identify the font
1. State your top 2-3 candidates with the distinguishing character that makes you lean one way
2. Suggest the user inspect the live site via DevTools → Computed Styles → `font-family`
3. Default to the closest Google Font match
4. Structure your CSS so the font can be swapped by changing a single `--font-display` variable
### When the reference is low resolution
1. Extract what you can confidently determine (layout, palette, general typography)
2. Flag uncertain measurements explicitly
3. Ask for a higher-res image or a URL to the live site
4. Do not invent sub-pixel details from a blurry screenshot
### When the reference shows content you cannot reproduce
Some references show dynamic content (live chat, real user avatars, real-time data):
1. Reproduce the visual appearance with static placeholder data
2. Use realistic content - real-sounding names, organic numbers (not "John Doe" or "99.99%")
3. Note which elements are placeholder in your delivery
For artistic content (photographs, illustrations, textures), see the "Handling Artistic Assets" section above. Never approximate with CSS - always generate or source a real image.
### When multiple reference images are provided
1. Run the full extraction on each image independently
2. Confirm the design system is consistent across images (same fonts, colors, components)
3. If inconsistencies exist, ask the user which image is authoritative
4. Desktop + mobile pairs: use desktop for the design system, mobile for responsive breakpoints
### When the reference uses a recognizable component library
If you spot shadcn/ui, Radix, Material, or another library:
1. State which library you believe is in use
2. Ask if the user wants the library or manual reproduction
3. If using the library: install properly and theme to match
4. If reproducing manually: match the visual output without the dependency
---
## The Core Principle
> The reference image is the specification. The code is a translation. You are a translator, not a designer. Match the image, not your preferences. If the reference contradicts your aesthetic instincts, the reference wins. The only technical override allowed is `min-h-[100dvh]` over `h-screen`, because `h-screen` is a browser bug, not a design choice.Surgical aesthetic upgrade pipeline for existing React codebases. Takes ugly, functional code (Bootstrap defaults, generic Tailwind, amateur CSS) and transform
---
name: visual-redesign
description: Surgical aesthetic upgrade pipeline for existing React codebases. Takes ugly, functional code (Bootstrap defaults, generic Tailwind, amateur CSS) and transforms it to Awwwards-tier quality WITHOUT touching or breaking the underlying JavaScript logic - states, effects, API calls, event handlers, routing, and data flow are sacred and untouchable. Audits the existing code across 7 layers (tokens, typography, spacing, color, components, atmosphere, motion), classifies every element as Sacred (JS logic - do not touch) or Slop (visual cruft - upgrade), then executes precise CSS-only surgery layer by layer. The skill that turns a developer's "make this look better" into a controlled, non-destructive visual transformation.
---
# Visual Redesign: Surgical Aesthetic Upgrade
> This skill fires when the user provides existing React/HTML/CSS code and asks to make it look better, upgrade the design, improve the aesthetics, make it premium, give it an Awwwards feel, or any variation of "this works but looks terrible." The user's code is FUNCTIONAL - it has working state, API calls, event handlers, and business logic. Your job is to upgrade the visual layer without breaking any of it. You are a surgeon, not a demolition crew. Cut precisely. Leave the patient alive.
---
## The Sacred Rule - Read First
**JavaScript logic is sacred. You do not touch it. Ever.**
This is the non-negotiable, unbreakable rule that governs every line of this skill:
```
SACRED (never modify):
├── useState / useReducer declarations and updates
├── useEffect / useCallback / useMemo bodies
├── API calls (fetch, axios, SWR, React Query)
├── Event handler LOGIC (what happens onClick, not how the button looks)
├── Conditional rendering logic (ternaries, && chains, if blocks)
├── Router/navigation logic
├── Form validation logic
├── Context providers and consumers
├── Custom hook implementations
├── Data transformations (map, filter, reduce on data)
├── Error handling (try/catch, error boundaries)
├── Prop drilling / prop interfaces
└── Third-party library integration logic
SLOP (upgrade aggressively):
├── className strings and CSS classes
├── Inline styles (style={{...}})
├── CSS/SCSS files
├── Tailwind utility classes
├── Bootstrap classes
├── Color values (hex, rgb, hsl)
├── Font families and sizes
├── Spacing values (padding, margin, gap)
├── Border-radius values
├── Shadow values
├── Transition/animation declarations
├── z-index values
├── Layout structure (flex/grid configuration)
└── Wrapper div nesting (for layout, NOT for conditional logic)
```
⚠ **Drift Warning:** The #1 way AI "breaks the app" is by restructuring JSX to look cleaner and accidentally removing a conditional wrapper, moving a key prop, changing a ref assignment, or reordering children that depend on DOM position. NEVER restructure JSX for aesthetic reasons if the existing structure works. Add CSS to the existing structure. Do not reshape the structure to fit your CSS preferences.
### → The Gray Zone
Some elements are both logic and style. Handle them with extreme care:
| Element | Sacred or Slop? | Rule |
|---|---|---|
| `className={isActive ? 'active' : ''}` | **Both** - logic is sacred, class names are slop | Keep the ternary. Change only the class name values: `className={isActive ? 'nav-link--active' : 'nav-link'}` |
| `style={{ display: isOpen ? 'block' : 'none' }}` | **Sacred** - this is conditional visibility logic | Do NOT replace with CSS classes. The inline style is driven by state. Leave it. Add your styles alongside it |
| `{items.map((item) => <Card key={item.id} ... />)}` | **Sacred** - the map, key, and data flow are logic | Style the Card component's internals. Do not change the map structure or key assignment |
| `ref={containerRef}` | **Sacred** - ref assignments drive JS behavior | Never remove, move, or rename refs |
| `aria-*` attributes | **Sacred** - accessibility attributes are functional | Never remove. You may add missing ones |
| `data-*` attributes | **Probably sacred** - often used by JS/tests | Never remove unless confirmed unused |
| `id` attributes | **Probably sacred** - may be used by JS selectors | Never change unless confirmed unused |
| `onClick={() => setOpen(!open)}` | **Sacred** - the handler is logic | Style the element. Do not touch the handler |
| `<div>` that wraps conditional content | **Sacred** - the div may exist for rendering reasons | Do not remove "unnecessary" wrapper divs unless you've confirmed they're purely presentational |
**The Golden Rule of the Gray Zone:** If you're unsure whether something is logic or style, leave it alone and add your styles alongside it. A slightly less elegant CSS solution that doesn't break the app is infinitely better than an elegant refactor that introduces bugs.
---
## The Pipeline
```
┌──────────────────────────────────────────────────────────────────────────┐
│ │
│ CODE IN ──→ Phase 1: Audit │
│ (read every file, classify Sacred vs Slop, │
│ identify the aesthetic crimes) │
│ │
│ ──→ Phase 2: Extraction │
│ (extract current design decisions across │
│ 7 layers, build the Slop Sheet) │
│ │
│ ──→ Phase 3: Prescription │
│ (define target aesthetic, map every │
│ slop item to its gold replacement) │
│ │
│ ──→ Phase 4: Surgery │
│ (execute replacements layer by layer: │
│ tokens → typography → color → spacing → │
│ components → atmosphere → motion) │
│ │
│ ──→ Phase 5: Post-Op │
│ (verify nothing broke, visual diff, │
│ responsive check, motion check) │
│ │
│ Each phase has a ✓ Quality Gate. Failing a gate blocks the next. │
│ │
└──────────────────────────────────────────────────────────────────────────┘
```
---
## Phase 1: Audit
Before changing a single character, read the entire codebase. Understand what exists. Classify everything.
### → Read every file and fill the Audit Table
| File | Type | Sacred elements | Slop elements | Risk level |
|---|---|---|---|---|
| `App.tsx` | Root component | Router setup, providers, global state | Root className, global wrapper styles | Low |
| `Header.tsx` | UI component | Nav state (mobile menu toggle), auth state | All className strings, inline styles, layout | Medium |
| `Hero.tsx` | UI component | CTA click handlers, any analytics calls | Typography, colors, spacing, images, layout | Low |
| `Features.tsx` | UI component | Data arrays, map iterations | Card styles, grid layout, icons | Low |
| `Dashboard.tsx` | Complex component | All state, effects, API calls, data transforms | Table styles, card styles, chart wrapper styles | **High** |
| `Form.tsx` | Complex component | Validation, submission, error handling, refs | Input styles, button styles, layout | **High** |
| `index.css` | Stylesheet | None (but may contain critical resets) | Everything | Low |
**Risk levels:**
- **Low** - Mostly presentational. Safe to restyle aggressively.
- **Medium** - Mix of logic and presentation. Restyle carefully, test after.
- **High** - Heavy logic intertwined with presentation. Touch only CSS classes and styles. Test every change.
### → Identify the Aesthetic Crimes
Walk through the UI and catalog every visual problem. Be specific - "looks bad" is not a diagnosis.
| Crime | Where | Severity | Example |
|---|---|---|---|
| **Generic font stack** | Global/body | Critical | `font-family: Arial, sans-serif` or browser default |
| **Default shadows** | Cards, buttons | Major | `box-shadow: 0 2px 4px rgba(0,0,0,0.1)` - the Bootstrap default |
| **Pure black text on pure white** | Everywhere | Major | `color: #000; background: #fff` - zero warmth, harsh contrast |
| **Inconsistent spacing** | Between sections | Major | `margin-top: 20px` on one section, `margin-top: 50px` on the next |
| **Bootstrap blue accent** | Buttons, links | Critical | `#0d6efd` - the single most recognizable "I didn't design this" signal |
| **Generic border-radius** | Cards, buttons | Moderate | `border-radius: 4px` everywhere - no radius language |
| **No entry animations** | Page load | Moderate | Elements just appear - static, lifeless mount |
| **No hover states** | Buttons, cards, links | Major | Interactive elements give zero feedback |
| **Cramped padding** | Cards, sections | Major | `padding: 16px` on a card that needs `32px` to breathe |
| **No atmosphere** | Backgrounds | Moderate | Flat `background: white` or `background: #f5f5f5` - no depth |
| **Mixed radius languages** | Across components | Moderate | Buttons are `rounded-full` but cards are `rounded-sm` with no logic |
| **Body font as heading font** | H1-H3 | Critical | Inter/Roboto/Arial at `font-size: 24px` pretending to be a display heading |
| **No visual hierarchy** | Content sections | Major | Everything the same size, weight, and color |
| **No whitespace system** | Layout | Major | Random `mt-4`, `mt-6`, `mt-3` with no pattern |
### → Output the Audit Summary
State in 3-5 lines what you found:
> *"Audit Summary: React SPA with 8 components. Router, auth state, and 3 API calls are sacred - all in Dashboard.tsx and Header.tsx. The visual layer is Bootstrap 5 defaults across the board: #0d6efd blue accent, default shadows, Arial font stack, 4px radius on everything, no hover states, no entry animations, cramped 16px padding on cards, pure black-on-white text. No design system - spacing and colors are ad-hoc per component. Estimated crimes: 14 critical, 23 major. Risk: Medium overall, High on Dashboard.tsx (complex state + table rendering)."*
### ✓ Quality Gate: Audit
Before moving to Phase 2, confirm:
- Every file has been read and classified in the Audit Table
- Sacred elements are identified in every file
- Risk levels are assigned per file
- Aesthetic crimes are cataloged with specific examples
- Audit Summary is written
- You understand which files are High risk (heavy JS logic)
- You have NOT modified any code yet
---
## Phase 2: Extraction
Extract the current design decisions across 7 layers. This creates the "before" snapshot - the Slop Sheet.
### → Layer 1: Tokens (Colors, Fonts, Spacing Scale)
| Token | Current value (Slop) | Source |
|---|---|---|
| Primary background | `#ffffff` or `white` | index.css / inline |
| Secondary background | `#f5f5f5` or `#f8f9fa` | Bootstrap gray-100 |
| Primary text | `#000000` or `#212529` | Bootstrap default |
| Secondary text | `#6c757d` | Bootstrap gray-600 |
| Accent/primary action | `#0d6efd` | Bootstrap primary |
| Accent hover | `#0b5ed7` | Bootstrap primary hover |
| Danger/error | `#dc3545` | Bootstrap danger |
| Success | `#198754` | Bootstrap success |
| Border color | `#dee2e6` | Bootstrap gray-300 |
| Font display | `system-ui` or `Arial` | Browser default |
| Font body | Same as display | No differentiation |
| Font mono | None | Missing |
| Spacing base | No system (ad-hoc) | Random px values |
| Radius default | `4px` or `0.375rem` | Bootstrap default |
### → Layer 2: Typography
| Element | Current spec (Slop) |
|---|---|
| H1 | `font-size: 2rem; font-weight: bold; font-family: inherit` |
| H2 | `font-size: 1.5rem; font-weight: bold` |
| H3 | `font-size: 1.25rem; font-weight: bold` |
| Body | `font-size: 1rem; line-height: 1.5` |
| Small/caption | `font-size: 0.875rem` |
| Button text | `font-size: 1rem; font-weight: 400` |
| Letter-spacing | None set (browser default: normal) |
| Line-height on headings | 1.2 (Bootstrap default - too loose for display) |
| Text wrapping | No `text-wrap: balance` on headings |
| Max-width on body text | None (text runs edge to edge) |
### → Layer 3: Spacing
| Measurement | Current value (Slop) |
|---|---|
| Section padding | Inconsistent: `py-3`, `py-4`, `py-5`, random px values |
| Card padding | `p-3` (12px) or `p-4` (16px) - cramped |
| Grid gap | `gap-3` (12px) or `gap-4` (16px) - tight |
| Heading → body gap | `mb-2` or `mb-3` - too tight |
| Body → CTA gap | `mt-3` - too tight |
| Nav height | `py-2` (short and cramped) or default Bootstrap nav height |
| Component spacing | No consistent system - every component different |
### → Layer 4: Color Usage
| Usage | Current value (Slop) | Problem |
|---|---|---|
| Background | Pure `#fff` or `#f8f9fa` | Flat, cold, no warmth |
| Text | Pure `#000` or `#212529` | Harsh, no refinement |
| Accent | Bootstrap `#0d6efd` | Screams "undesigned" |
| Borders | `#dee2e6` | Generic gray |
| Shadows | `rgba(0,0,0,0.1)` | Default, undifferentiated |
| Hover states | Slightly darker shade | No personality |
| Active states | Even darker shade | Mechanical, not physical |
| Error | Bootstrap `#dc3545` | Generic red |
### → Layer 5: Components
| Component | Current state (Slop) |
|---|---|
| Buttons | Bootstrap `.btn.btn-primary` - `#0d6efd`, `4px` radius, generic padding, no hover physics |
| Cards | `.card` - `1px solid #dee2e6`, `4px` radius, default shadow or no shadow, cramped padding |
| Inputs | Bootstrap form controls - `#dee2e6` border, no focus glow, no float labels |
| Navigation | Bootstrap navbar - busy, cramped, default styling |
| Tables | Bootstrap `.table` - zebra stripes, cramped rows, no refinement |
| Modals | Bootstrap modal - generic overlay, no entry animation |
| Badges/pills | Bootstrap `.badge` - small, cramped, primary blue |
| Dropdowns | Bootstrap dropdown - generic shadow, no animation |
### → Layer 6: Atmosphere
| Property | Current state (Slop) |
|---|---|
| Background texture | None - flat solid color |
| Ambient glow/gradient | None - completely flat |
| Grain/noise | None |
| Frosted glass | None |
| Depth system | Default Bootstrap shadow or none |
| Visual warmth | Zero - cold and clinical |
### → Layer 7: Motion
| Property | Current state (Slop) |
|---|---|
| Page entry | None - static mount, everything appears instantly |
| Scroll reveals | None - everything visible immediately |
| Hover transitions | `transition: all 0.15s ease-in-out` (Bootstrap default) or none |
| Page transitions | None - instant swap |
| Micro-interactions | None |
| Loading states | Spinner or "Loading..." text |
| Easing curves | `ease-in-out` CSS keyword or none |
### ✓ Quality Gate: Extraction
Before moving to Phase 3, confirm:
- All 7 extraction layers are filled in with actual values from the codebase
- Values are specific (exact hex codes, exact rem/px values), not vague
- You can see the gap between current state and target quality
- You have NOT modified any code yet
---
## Phase 3: Prescription
For every slop item extracted in Phase 2, prescribe the gold replacement. This is the transformation map - the surgical plan.
### → Token Prescription
```css
/* PRESCRIPTION: Design tokens - Slop → Gold
WHY: Tokens are the foundation. Changing these first
means every component that references them upgrades
automatically. This is the highest-leverage change. */
:root {
/* ── Colors ────────────────────────────────────── */
/* Background: #ffffff → warm off-white
WHY: Pure white is harsh and clinical. Off-white
with a warm undertone feels premium and intentional.
The difference is subtle but the eye registers it
as "designed" vs "default." */
--color-bg: #FAFAF9; /* was: #ffffff */
--color-surface: #FFFFFF; /* was: #f8f9fa - cards sit ON the bg */
--color-surface-2: #F5F4F2; /* was: none - for alternating sections */
/* Text: #000000 → warm near-black
WHY: Pure black on warm off-white creates a jarring
temperature clash. Near-black (#1a1a1a) matches the
warmth of the background and reduces eye strain. */
--color-text: #1A1A1A; /* was: #000000 or #212529 */
--color-text-2: #6B7280; /* was: #6c757d - muted, for secondary */
--color-text-3: #9CA3AF; /* was: none - for captions, placeholders */
/* Accent: #0d6efd → considered, non-Bootstrap hue
WHY: Bootstrap blue is the single loudest "I didn't
design this" signal on the web. ANY other considered
hue immediately elevates the design. Pick based on
brand context from the user's brief. */
--color-accent: #____; /* MUST be chosen based on brand context */
--color-accent-hover: #____; /* 10-15% darker or more saturated */
/* Borders and shadows: warm, not gray
WHY: Cool gray borders (#dee2e6) clash with warm
backgrounds. Use warm gray or very low-opacity black. */
--color-border: rgba(0, 0, 0, 0.08); /* was: #dee2e6 */
--color-shadow: rgba(0, 0, 0, 0.04); /* was: rgba(0,0,0,0.1) */
/* ── Typography ────────────────────────────────── */
/* Display font: Arial → a real display font
WHY: Arial/system-ui as a heading font is the
typographic equivalent of serving fine dining
on paper plates. Display fonts have optical
refinements for large sizes that body fonts lack. */
--font-display: 'Outfit', system-ui, sans-serif; /* was: Arial/system-ui */
--font-body: 'Inter', system-ui, sans-serif; /* was: same as display */
--font-mono: 'JetBrains Mono', monospace; /* was: none */
/* ── Spacing ───────────────────────────────────── */
/* Section spacing: random values → consistent scale
WHY: A spacing system creates rhythm. Random spacing
creates visual noise - the eye detects inconsistency
even when the brain can't articulate it. */
--space-section: clamp(5rem, 10vw, 8rem); /* was: random py values */
--space-element: 1.5rem; /* was: 0.75rem–1rem */
--space-component: 2rem; /* was: 1rem–1.5rem */
/* ── Radius ────────────────────────────────────── */
/* Radius: 4px everywhere → considered radius language
WHY: A design system commits to a radius language.
Pick ONE and apply consistently. */
--radius-sm: 8px; /* was: 4px (Bootstrap) - inputs, badges */
--radius-md: 12px; /* was: 4px - cards, containers */
--radius-lg: 16px; /* was: 4px - modals, large cards */
--radius-full: 9999px; /* was: 50% - pills, avatars */
/* ── Easing ────────────────────────────────────── */
/* Easing: ease-in-out → custom curves
WHY: CSS keyword easings are the typographic
equivalent of Comic Sans. Zero character,
zero intentionality. Custom curves give
every animation a deliberate feel. */
--ease-out: cubic-bezier(0.16, 1, 0.3, 1);
--ease-snap: cubic-bezier(0.22, 1, 0.36, 1);
--ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
}
```
### → Typography Prescription
```css
/* PRESCRIPTION: Typography scale - Slop → Gold
WHY: The heading is the first thing the eye hits.
A display font with tight tracking and compressed
line-height immediately signals "designed." The body
font stays readable with comfortable line-height. */
/* Import the fonts - add to the top of your CSS or <head> */
@import url('https://fonts.googleapis.com/css2?family=Outfit:wght@300;400;500;600;700&family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500&display=swap');
h1, h2, h3, h4 {
font-family: var(--font-display);
letter-spacing: -0.03em; /* was: normal (too loose at display size) */
line-height: 1.1; /* was: 1.2 (Bootstrap) - tighten */
text-wrap: balance; /* prevents ugly orphan lines */
color: var(--color-text);
}
h1 {
font-size: clamp(2.25rem, 5vw, 3.75rem); /* was: 2rem fixed */
font-weight: 700;
letter-spacing: -0.04em;
line-height: 1.05;
}
h2 {
font-size: clamp(1.75rem, 3.5vw, 2.75rem); /* was: 1.5rem fixed */
font-weight: 600;
}
h3 {
font-size: clamp(1.25rem, 2vw, 1.5rem); /* was: 1.25rem fixed */
font-weight: 600;
}
body, p, span, li {
font-family: var(--font-body);
font-size: clamp(0.9375rem, 1.1vw, 1.0625rem); /* was: 1rem fixed */
line-height: 1.65; /* was: 1.5 - slightly more generous */
color: var(--color-text);
}
/* Body text max-width - prevent wall-to-wall text */
p {
max-width: 65ch; /* was: none - text ran edge to edge */
}
/* Muted secondary text */
.text-muted, .text-secondary {
color: var(--color-text-2) !important; /* override Bootstrap's gray */
}
/* Eyebrow / label style - add where appropriate */
.eyebrow {
font-family: var(--font-mono);
font-size: 0.75rem;
font-weight: 500;
letter-spacing: 0.12em;
text-transform: uppercase;
color: var(--color-text-3);
}
```
### → Component Prescription
```css
/* PRESCRIPTION: Button - Bootstrap → Premium
WHY: The button is the most interactive element on the page.
Its hover feel communicates the entire quality level of the site.
A snappy cubic-bezier with a physical lift-and-shadow creates
a tactile impression that Bootstrap's default cannot achieve. */
/* Strip Bootstrap button defaults */
.btn {
font-family: var(--font-body);
font-size: 0.875rem;
font-weight: 600;
letter-spacing: 0.02em;
padding: 0.75rem 1.75rem; /* was: py-2 px-3 - cramped */
border-radius: var(--radius-full); /* was: 4px - now pill */
border: none;
cursor: pointer;
transition:
transform 0.4s var(--ease-snap),
box-shadow 0.4s var(--ease-snap),
background-color 0.3s var(--ease-out);
}
.btn:hover {
transform: translateY(-2px);
box-shadow: 0 4px 16px var(--color-shadow);
}
.btn:active {
transform: translateY(0) scale(0.98);
transition-duration: 0.1s;
}
/* Primary button */
.btn-primary {
background: var(--color-accent);
color: #ffffff;
border: none;
box-shadow: 0 1px 3px var(--color-shadow);
}
.btn-primary:hover {
background: var(--color-accent-hover);
}
/* Ghost / outline button */
.btn-outline-primary,
.btn-secondary,
.btn-outline-secondary {
background: transparent;
color: var(--color-text);
border: 1px solid var(--color-border);
}
.btn-outline-primary:hover,
.btn-outline-secondary:hover {
border-color: var(--color-text);
background: rgba(0, 0, 0, 0.02);
}
/* PRESCRIPTION: Card - Bootstrap → Premium */
.card {
background: var(--color-surface);
border: 1px solid var(--color-border);
border-radius: var(--radius-md); /* was: 4px */
padding: var(--space-component); /* was: 1rem - cramped */
box-shadow: none; /* was: default Bootstrap shadow */
transition:
transform 0.4s var(--ease-snap),
box-shadow 0.4s var(--ease-snap),
border-color 0.3s var(--ease-snap);
}
.card:hover {
transform: translateY(-4px);
box-shadow:
0 8px 24px rgba(0, 0, 0, 0.04),
0 2px 8px rgba(0, 0, 0, 0.02);
border-color: rgba(0, 0, 0, 0.12);
}
/* Reset Bootstrap card internals */
.card-body {
padding: 0; /* parent .card already has padding */
}
.card-title {
font-family: var(--font-display);
font-size: 1.125rem;
font-weight: 600;
letter-spacing: -0.01em;
margin-bottom: var(--space-element);
}
/* PRESCRIPTION: Input - Bootstrap → Premium */
.form-control,
input[type="text"],
input[type="email"],
input[type="password"],
textarea,
select {
font-family: var(--font-body);
font-size: 0.9375rem;
padding: 0.75rem 1rem; /* was: py-1.5 px-3 - cramped */
border: 1px solid var(--color-border);
border-radius: var(--radius-sm);
background: var(--color-surface);
color: var(--color-text);
transition:
border-color 0.3s var(--ease-snap),
box-shadow 0.3s var(--ease-snap);
}
.form-control:focus,
input:focus,
textarea:focus,
select:focus {
outline: none;
border-color: var(--color-accent);
box-shadow: 0 0 0 3px rgba(var(--color-accent-rgb), 0.15);
}
/* PRESCRIPTION: Navigation - Bootstrap → Premium */
.navbar, nav {
backdrop-filter: blur(16px) saturate(180%);
-webkit-backdrop-filter: blur(16px) saturate(180%);
background: rgba(250, 250, 249, 0.85); /* semi-transparent for frost */
border-bottom: 1px solid var(--color-border);
padding: 0 clamp(1.5rem, 5vw, 5rem);
height: 64px;
display: flex;
align-items: center;
}
.nav-link, .navbar-nav .nav-link {
font-family: var(--font-body);
font-size: 0.875rem;
font-weight: 500;
color: var(--color-text-2);
transition: color 0.3s var(--ease-snap);
position: relative;
}
.nav-link:hover {
color: var(--color-text);
}
/* Sliding underline on nav links */
.nav-link::after {
content: '';
position: absolute;
bottom: -2px;
left: 0;
width: 100%;
height: 1.5px;
background: var(--color-text);
transform: scaleX(0);
transform-origin: right;
transition: transform 0.3s var(--ease-snap);
}
.nav-link:hover::after {
transform: scaleX(1);
transform-origin: left;
}
/* PRESCRIPTION: Table - Bootstrap → Premium */
.table, table {
border-collapse: separate;
border-spacing: 0;
width: 100%;
}
.table th, table th {
font-family: var(--font-mono);
font-size: 0.6875rem;
font-weight: 500;
letter-spacing: 0.1em;
text-transform: uppercase;
color: var(--color-text-3);
padding: 0.75rem 1rem;
border-bottom: 1px solid var(--color-border);
text-align: left;
}
.table td, table td {
font-size: 0.9375rem;
padding: 1rem;
border-bottom: 1px solid rgba(0, 0, 0, 0.04);
color: var(--color-text);
}
.table tbody tr:hover, table tbody tr:hover {
background: rgba(0, 0, 0, 0.015);
}
/* Kill Bootstrap zebra striping - it looks cheap */
.table-striped > tbody > tr:nth-of-type(odd) {
background-color: transparent;
}
```
### → Atmosphere Prescription
```css
/* PRESCRIPTION: Atmosphere - Flat → Alive
WHY: Flat backgrounds feel like nothing. A subtle
radial gradient, grain texture, or warm tint gives
the background depth without adding visual elements. */
/* Subtle warm radial on the body */
body {
background:
radial-gradient(ellipse at 30% 0%, rgba(250, 235, 215, 0.2) 0%, transparent 50%),
var(--color-bg);
}
/* Noise grain overlay - felt, not seen */
body::after {
content: '';
position: fixed;
inset: 0;
pointer-events: none;
z-index: 9999;
opacity: 0.025;
background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)' opacity='1'/%3E%3C/svg%3E");
}
/* Section dividers - subtle border instead of hard lines */
section + section {
border-top: 1px solid var(--color-border);
}
/* Alternating section backgrounds for rhythm */
section:nth-child(even) {
background-color: var(--color-surface-2);
}
```
### → Motion Prescription
```css
/* PRESCRIPTION: Motion - Static → Alive
WHY: Every element that appears without animation
feels like the page is broken. A staggered fade-up
with deblur signals that the page loaded intentionally. */
/* Entry animation keyframe */
@keyframes enter-up {
from {
opacity: 0;
transform: translateY(24px);
filter: blur(6px);
}
to {
opacity: 1;
transform: translateY(0);
filter: blur(0);
}
}
/* Apply to major elements - use inline style for stagger:
<h1 class="enter-up" style="--stagger: 0ms">
<p class="enter-up" style="--stagger: 120ms">
<button class="enter-up" style="--stagger: 240ms"> */
.enter-up {
animation: enter-up 0.7s var(--ease-out) both;
animation-delay: var(--stagger, 0ms);
}
/* Scroll reveal - elements below the fold */
[data-reveal] {
opacity: 0;
transform: translateY(30px);
transition:
opacity 0.8s var(--ease-out),
transform 0.8s var(--ease-out);
}
[data-reveal].is-visible {
opacity: 1;
transform: translateY(0);
}
/* Universal interactive transition - replaces Bootstrap's
transition: all 0.15s ease-in-out on EVERY interactive element */
a, button, [role="button"],
input, select, textarea,
.card, .nav-link, .badge {
transition: all 0.3s var(--ease-snap);
}
/* Respect reduced motion */
@media (prefers-reduced-motion: reduce) {
.enter-up {
animation: none;
opacity: 1;
transform: none;
filter: none;
}
[data-reveal] {
opacity: 1;
transform: none;
transition: none;
}
*, *::before, *::after {
animation-duration: 0.01ms !important;
transition-duration: 0.01ms !important;
}
}
```
### → Scroll Reveal JavaScript (Non-Destructive)
```javascript
/* PRESCRIPTION: Scroll reveal - add as a separate script
WHY: This script observes [data-reveal] elements and
adds .is-visible when they enter the viewport. It does
NOT modify any existing JS - it's a new, separate file
that runs independently.
Add to the end of the page or import in main entry. */
class ScrollReveal {
constructor() {
if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) return;
this.observer = new IntersectionObserver(
(entries) => {
entries.forEach((entry) => {
if (entry.isIntersecting) {
entry.target.classList.add('is-visible');
this.observer.unobserve(entry.target);
}
});
},
{ threshold: 0.15, rootMargin: '-50px 0px' }
);
document.querySelectorAll('[data-reveal]').forEach((el) => {
this.observer.observe(el);
});
}
}
// Initialize after DOM ready
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', () => new ScrollReveal());
} else {
new ScrollReveal();
}
```
### ✓ Quality Gate: Prescription
Before moving to Phase 4, confirm:
- Every slop item from Phase 2 has a gold replacement prescribed
- Token prescriptions are internally consistent (warm bg + warm text, not mixed temperatures)
- The accent color is chosen based on the user's brand context (not another generic blue)
- Typography prescription uses a display font for headings and a body font for body
- Component prescriptions maintain the same DOM structure (class changes only)
- Atmosphere additions are subtle (opacity < 0.05 for grain, < 0.3 for gradients)
- Motion additions are non-destructive (new CSS classes and a new script, no existing JS modified)
- The accent color `#____` placeholder is filled with an actual hex value
---
## Phase 4: Surgery
Execute the prescriptions. This is the operating room. Follow the exact order below - each layer builds on the previous one.
### → Surgical Order
```
Layer 1: Tokens (CSS custom properties - the foundation)
Layer 2: Typography (font imports + heading/body styles)
Layer 3: Color (replace all Bootstrap/generic color values)
Layer 4: Spacing (padding, margins, gaps - breathing room)
Layer 5: Components (buttons, cards, inputs, nav, tables)
Layer 6: Atmosphere (grain, glow, section alternation)
Layer 7: Motion (entry animations, hover states, scroll reveals)
```
### → Surgical Rules
| Rule | Why |
|---|---|
| **One layer at a time** | If you change tokens, typography, AND components simultaneously and something breaks, you cannot isolate the cause |
| **Test after each layer** | Run the app. Does it still work? Do all routes load? Do forms submit? Do API calls return? If yes, proceed to the next layer |
| **CSS overrides, not replacements** | Add a new stylesheet (e.g., `gold.css`) that overrides the existing styles. Do NOT delete the existing CSS files until the override is confirmed working |
| **className changes are surgical** | If replacing Bootstrap classes with custom ones, search the entire codebase for each class before removing it. A class used in JS logic (`document.querySelector('.btn-primary')`) is sacred |
| **Never rewrite JSX structure** | You may add/change `className` props and `style` props. You may NOT reorder children, remove wrapper divs, change component hierarchy, or modify props that aren't purely visual |
| **New files > modified files** | Prefer creating `gold.css` and importing it AFTER existing stylesheets (for override priority) over editing the existing stylesheets directly. This makes rollback trivial |
### → The Override Strategy
The safest approach is a single new stylesheet loaded AFTER all existing stylesheets:
```css
/* gold.css - loaded LAST in the cascade
WHY: By loading after Bootstrap/existing CSS, our rules
override the defaults without deleting any existing code.
If something breaks, the user can remove this one import
to revert entirely. This is the safest surgery method.
Import in main entry file:
import './gold.css' // AFTER all other CSS imports */
```
This file contains ALL prescriptions from Phase 3 - tokens, typography, components, atmosphere, motion - in one file that can be added or removed as a single unit.
⚠ **Drift Warning:** The temptation is to "clean up" the existing CSS by deleting Bootstrap imports or removing old stylesheets. Do NOT do this until the user has confirmed the gold override is working. The old CSS is a safety net. Remove it only after the patient is confirmed stable.
### → High-Risk File Surgery (Dashboard, Forms, Complex Components)
For files marked **High** risk in the Audit Table:
1. **Read the entire file first** - understand every state variable, effect, and handler
2. **Map every className and style prop** - note which ones are referenced in JS logic
3. **Change ONLY className string values** - the attribute stays, only the value changes
4. **Never touch inline styles that reference state** - `style={{ display: isOpen ? 'block' : 'none' }}` is sacred
5. **Test immediately after changes** - run the app, trigger every state change, submit every form, verify every API call
```tsx
/* EXAMPLE: Safe className surgery on a complex component
BEFORE (Bootstrap):
<div className={`card ${isSelected ? 'border-primary' : ''}`}>
AFTER (Gold):
<div className={`card ${isSelected ? 'card--selected' : ''}`}>
The ternary logic is IDENTICAL. Only the class name value changed.
Then in gold.css:
.card--selected {
border-color: var(--color-accent);
box-shadow: 0 0 0 2px rgba(var(--color-accent-rgb), 0.2);
}
*/
```
### → Adding data-reveal Attributes (Non-Destructive)
To add scroll reveal animations, add `data-reveal` attributes to existing JSX elements. This is safe because `data-*` attributes do not affect React's rendering logic:
```tsx
/* BEFORE: */
<section className="features">
<h2>Features</h2>
{features.map(f => <FeatureCard key={f.id} {...f} />)}
</section>
/* AFTER - added data-reveal, nothing else changed: */
<section className="features" data-reveal>
<h2>Features</h2>
{features.map(f => <FeatureCard key={f.id} {...f} />)}
</section>
/* The data-reveal attribute is inert until the ScrollReveal
script observes it. It does not interfere with React's
reconciliation, event handling, or state management. */
```
### → Adding Entry Animation Classes (Non-Destructive)
```tsx
/* BEFORE: */
<h1 className="hero-heading">Build faster.</h1>
<p className="hero-subtext">The platform for modern teams.</p>
<button className="btn btn-primary" onClick={handleSignup}>Get Started</button>
/* AFTER - added enter-up class and stagger variable: */
<h1 className="hero-heading enter-up" style={{ '--stagger': '0ms' } as React.CSSProperties}>Build faster.</h1>
<p className="hero-subtext enter-up" style={{ '--stagger': '120ms' } as React.CSSProperties}>The platform for modern teams.</p>
<button className="btn btn-primary enter-up" style={{ '--stagger': '240ms' } as React.CSSProperties} onClick={handleSignup}>Get Started</button>
/* onClick handler is UNTOUCHED. Only className and style were added.
The style prop uses a CSS custom property for stagger delay.
In TypeScript, cast as React.CSSProperties to avoid type errors. */
```
### ✓ Quality Gate: Surgery
After all 7 layers are applied, confirm:
- The app runs without errors (console is clean)
- All routes load correctly
- All forms submit and validate correctly
- All API calls return data and render correctly
- All state changes work (toggles, modals, dropdowns, selections)
- All event handlers fire correctly (clicks, submits, keypresses)
- No ref errors or "cannot read property of undefined" errors
- The new CSS imports load AFTER existing stylesheets
- The gold.css file can be removed to fully revert
---
## Phase 5: Post-Op
Verify the surgery was successful. Walk through every check. Any FAIL requires diagnosis and correction.
### Functionality Check (Sacred Integrity)
| Check | PASS/FAIL |
|---|---|
| All pages/routes load without error | |
| All forms submit correctly | |
| All API calls return and render data | |
| All state toggles work (open/close, show/hide, select/deselect) | |
| All event handlers fire (onClick, onSubmit, onChange, onKeyDown) | |
| Authentication flow works (login, logout, protected routes) | |
| No console errors | |
| No TypeScript errors (if TS project) | |
| No broken refs or undefined property errors | |
| All conditional rendering works (loading states, error states, empty states) | |
⚠ **If ANY functionality check fails, REVERT the last surgery layer and diagnose. Do NOT proceed to visual checks until all functionality passes.**
### Visual Upgrade Check
| Check | PASS/FAIL |
|---|---|
| No Bootstrap blue (#0d6efd) visible anywhere | |
| No pure black (#000) text on pure white (#fff) backgrounds | |
| Heading font is a display font (not Arial/system-ui) | |
| Heading letter-spacing is negative (tight, not loose) | |
| Heading line-height is compressed (< 1.15) | |
| Body text has comfortable max-width (not edge-to-edge) | |
| Cards have generous padding (not cramped 16px) | |
| Buttons are pill-shaped or use the prescribed radius | |
| Buttons have hover lift + shadow expansion | |
| Buttons have active press feedback | |
| Nav has frosted glass treatment | |
| Color palette is warm and consistent (no cold grays mixed with warm tones) | |
| Shadows are subtle and warm (not default Bootstrap) | |
| Border-radius is consistent across same component types | |
### Atmosphere Check
| Check | PASS/FAIL |
|---|---|
| Background has subtle warmth (not flat white/gray) | |
| Grain overlay is present and subtle (felt, not seen) | |
| Section alternation creates rhythm (not all same background) | |
| No flat, dead-feeling sections remain | |
### Motion Check
| Check | PASS/FAIL |
|---|---|
| Hero elements animate in on page load (staggered fade-up-deblur) | |
| Scroll reveals trigger on below-fold sections | |
| All buttons have hover transitions (not instant state change) | |
| All cards have hover lift | |
| Nav links have animated underlines | |
| Input focus has border glow transition | |
| No animation uses CSS keyword easing (ease, ease-in, ease-out, ease-in-out) | |
| `prefers-reduced-motion` is respected (no motion on reduce) | |
### Responsive Check
| Check | PASS/FAIL |
|---|---|
| Layout works at 1440px (desktop) | |
| Layout works at 768px (tablet) | |
| Layout works at 375px (mobile) | |
| No horizontal overflow at any viewport | |
| Touch targets minimum 44px on mobile | |
| Heading doesn't wrap beyond 3 lines at any viewport | |
| Cards stack properly on mobile (single column) | |
### Rollback Check
| Check | PASS/FAIL |
|---|---|
| Removing gold.css import reverts ALL visual changes cleanly | |
| No existing CSS files were deleted (they're intact as fallback) | |
| No JSX structural changes were made (only className and data-* additions) | |
| The user can accept or reject the entire upgrade as one unit | |
---
## The Slop Catalog - Common Patterns and Their Cures
Quick-reference for the most common aesthetic crimes. Look up the pattern, apply the cure.
| Slop Pattern | The Crime | The Cure |
|---|---|---|
| `font-family: Arial, Helvetica, sans-serif` | Body font as display font | Import Outfit/Satoshi/Cabinet Grotesk for headings |
| `color: #000; background: #fff` | Pure black-on-white | `color: #1a1a1a; background: #FAFAF9` |
| `background: #0d6efd` | Bootstrap primary blue | Choose a brand-appropriate accent color |
| `box-shadow: 0 2px 4px rgba(0,0,0,0.1)` | Generic default shadow | `box-shadow: 0 1px 3px rgba(0,0,0,0.04)` at rest, expand on hover |
| `border-radius: 4px` | Bootstrap default radius | Commit to a radius language: 8/12/16/9999 |
| `border: 1px solid #dee2e6` | Cool gray border | `border: 1px solid rgba(0,0,0,0.08)` - warm, subtle |
| `transition: all 0.15s ease-in-out` | Bootstrap default transition | `transition: all 0.3s cubic-bezier(0.22, 1, 0.36, 1)` |
| `padding: 1rem` on a card | Cramped card padding | `padding: 2rem` minimum - cards need to breathe |
| `margin-bottom: 0.5rem` heading→body | Cramped heading gap | `margin-bottom: 1.5rem` - let the heading land |
| `gap: 1rem` in a card grid | Tight grid gap | `gap: 1.5rem` minimum - cards need separation |
| No `:hover` on buttons | Dead, unresponsive buttons | `translateY(-2px) + shadow expansion + custom easing` |
| No `:hover` on cards | Static, lifeless cards | `translateY(-4px) + shadow expansion + border glow` |
| No entry animation | Instant static mount | Staggered fade-up-deblur on above-fold elements |
| `h1 { font-size: 2rem }` | Undersized heading | `font-size: clamp(2.25rem, 5vw, 3.75rem)` |
| `line-height: 1.2` on headings | Too loose for display | `line-height: 1.05` - tight, architectural |
| No letter-spacing on headings | Loose, amateur tracking | `letter-spacing: -0.03em` - tighten |
| `py-3` section padding | Cramped sections | `py-20 md:py-32` - sections are chapters, not paragraphs |
| Zebra-striped tables | 2010 Bootstrap energy | Kill stripes, add subtle hover row highlight |
| `.badge { font-size: 0.75em }` | Tiny, cramped badges | `padding: 0.25rem 0.75rem; font-size: 0.75rem; border-radius: 9999px` |
| No `::placeholder` styling on inputs | Default gray placeholder | `color: var(--color-text-3); opacity: 0.7` |
---
## Edge Cases
### When the code uses CSS-in-JS (styled-components, Emotion)
1. Apply token prescriptions as a CSS custom property layer (`:root` variables)
2. Override styled-component styles via a global `createGlobalStyle` that references the tokens
3. For component-level overrides, add a `gold-overrides.ts` file with styled-component overrides
4. Never modify the existing styled-component definitions inline - create override wrappers
### When the code uses Tailwind CSS
1. Override Tailwind's `theme` in `tailwind.config.js` with the gold tokens (colors, fonts, radii, shadows)
2. Use `@layer utilities` for atmosphere and motion additions
3. Replace Tailwind color classes systematically: `text-gray-900` → `text-[#1a1a1a]` or define custom colors in config
4. Replace `shadow-sm` / `shadow-md` → custom shadow values in config
5. Replace `rounded` / `rounded-md` → custom radii in config
6. This is the safest approach for Tailwind because it changes the design system at the config level, not in every component file
### When the code uses Material UI / Chakra / Ant Design
1. Override the theme provider configuration - these libraries are designed for theme customization
2. Focus on the theme object: colors, typography, spacing, radii, shadows
3. Add component-level `sx` overrides or `styled()` wrappers for atmosphere and motion
4. Never fight the component library's structure - work within its theming system
### When the code is vanilla HTML/CSS (no framework)
1. Add `gold.css` as the LAST stylesheet in the `<head>`
2. Use CSS specificity to override existing styles without editing them
3. If existing styles use `!important`, your overrides may need `!important` too (unfortunate but necessary)
4. Add the ScrollReveal script as a `<script>` before `</body>`
### When the user says "just make the hero look good"
Do NOT upgrade the entire site. Apply the pipeline to the hero section only:
1. Audit the hero component
2. Extract its current design decisions
3. Prescribe the gold replacements for that section
4. Execute surgery on that section's CSS
5. Verify nothing else broke
Respect the user's scope. Upgrading more than asked wastes time and introduces risk.
---
## The Core Principles
> **The patient must survive.** A beautiful app that no longer functions is worse than an ugly app that works. Test after every surgery layer. Functionality always trumps aesthetics.
> **CSS overrides, never JS rewrites.** Your tools are className changes, new CSS files, and data-attributes. You do not rewrite component logic, refactor state management, or restructure JSX hierarchies. If a visual upgrade requires changing JS logic, find a CSS-only alternative.
> **The gold.css is a single unit.** One file, loaded last, that contains the entire visual upgrade. The user can add it (upgrade) or remove it (revert) with a single import. This is the surgical philosophy: clean entry, clean exit.
> **Warmth over neutrality.** Every premium design uses warm tones - off-white backgrounds, warm near-black text, warm gray borders. Cold neutrals (pure gray, pure white, pure black) feel clinical and undesigned. The fastest single upgrade is replacing the color temperature.
> **Spacing is the secret.** The single change that has the most dramatic impact is increasing spacing - section padding, card padding, heading gaps, grid gaps. Cramped spacing is the hallmark of amateur design. Generous spacing is the hallmark of premium design. When in doubt, add more space.
> **Display fonts separate amateurs from professionals.** Swapping the heading font from Arial/system-ui to a proper display font (Outfit, Satoshi, Cabinet Grotesk, Clash Display) is the highest-impact single change. Everything else builds on this foundation.