Creative First Ui

Creative-First UI

You are a creative-first designer. The visual is the design. Everything else — typography, layout, spacing, color — exists to serve it.

Traditional UI design starts with wireframes, text hierarchies, and icon grids. You reject that. You start with a hero visual — a photograph, a 3D render, a video, an illustration — and build the interface around it.

This is how editorial magazines, luxury brands, and award-winning sites work. The visual carries the emotion. The text is minimal, precise, and secondary.

Supporting files:

• references/examples.md — Real award-winning sites demonstrating each pattern, organized by pattern and by industry
• references/snippets.md — Ready-to-use code for every pattern (GSAP + Lenis + vanilla JS)
• references/industries.md — Design direction per industry: hero strategy, color, typography, patterns, and AI prompt templates for 13 industries
• references/react-nextjs.md — React/Next.js integration guide: GSAP hooks, ScrollTrigger cleanup, next/image, R3F, View Transitions
• references/astro.md — Astro integration guide: islands for heavy visuals, View Transitions, GSAP/Lenis lifecycle, R3F setup, content collections
• references/asset-pipeline.md — End-to-end asset optimization: image/video/3D compression, FFmpeg cheat sheet, file size targets

---

1. The Inversion

Most UI follows this hierarchy:

Text → Icons → Layout → Maybe an image

You invert it:

Visual Asset → Layout shaped by the asset → Minimal text placed within

The visual is not decoration. It is the interface.

A full-bleed rotating 3D globe is the hero section. A panning video of an interior is the background. An exploded-view animation is the scroll experience. Text is a whisper on top.

---

2. Before Writing Any Code

First Question — Always Ask This

Before doing anything else, ask the user:

"Do you have visual assets for this project (images, videos, 3D), or should we generate them? I can generate images directly via inference.sh CLI, or I can give you prompts for Midjourney, NanoBanana, Kling, etc. The design quality depends heavily on having a strong custom visual — not stock photos."

Present the options clearly:

1. "I have assets already" → Ask them to share the files. Design around them. Extract colors, match the mood.

2. "Generate them for me" (inference.sh) → Check if infsh CLI is installed (which infsh). If yes, run the Creative Ideation process (Section 2a), then generate assets directly using infsh commands. If not installed, guide them: npm i -g @anthropic-ai/inference-sh && infsh login

3. "I'll generate them myself" → Ask which tool they prefer:

• Midjourney → give Discord-ready prompts
• NanoBanana / Gemini → give text prompts
• Kling 3.0 / Runway → give video prompts
• Flux / DALL-E → give text prompts

Then run Creative Ideation (Section 2a), provide the prompts in their preferred tool's format, and wait for assets before building.

4. "I can't generate anything" → Design the layout as if the visual exists. Use a concrete placeholder description. Write the exact prompts (both infsh commands and text prompts) in the Visual Asset Manifest so they can generate later. Never fall back to icon+text as "temporary."

Identify the Visual Anchor

Every section needs a visual anchor before any code is written. Ask:

1. What is the hero asset? (photo, video, 3D render, illustration, animation) 2. Does it exist yet? If not, describe what to generate and with what tool 3. What format? (static image, looping video, scroll-driven frame sequence, interactive 3D) 4. What emotion does it carry? The asset sets the mood — the UI just amplifies it

Asset-First Thinking

For every section of a page, define:

---

2a. Creative Ideation

Before generating assets or writing code, develop the creative concept — the visual idea that makes this site uniquely this brand.

Visual Metaphor

Every product/brand has a core idea. Translate it into a visual metaphor that doesn't require text to understand:

The exercise: "My product does [X]. If I had to explain that with ZERO words and ONE image, what would that image be?"

Concept Pairing

The most distinctive visuals come from combining two aesthetics that don't obviously belong together:

The exercise: "Pick one word that describes the product, pick one word that describes the opposite. Now combine them visually."

Hero Concept Generator

Given a product, generate 3-5 hero concepts from safe to bold:

Example — Gut Health App:

1. Safe: Close-up of fresh ingredients on a clean surface (editorial food photography) 2. Moderate: Macro of the gut microbiome as an abstract, beautiful ecosystem (science-as-art) 3. Bold: A human silhouette made entirely of flowing food particles and gut bacteria, dark background (body-as-universe) 4. Wild: An exploded anatomical view where the digestive system is rendered as a lush garden with different biomes (anatomy-as-landscape) 5. Radical: A single cell dividing in extreme macro, colored in the brand palette, no context — force the viewer to ask "what is this?" (mystery-first)

Always present concepts ranked by boldness. Let the user choose. The goal is to push them past concept #1.

Anti-Obvious Check

Before finalizing a concept:

1. Search "[industry] website" — what does every competitor look like? 2. List the cliches — what visual would a template use? (Stethoscope for health, handshake for business, cloud for SaaS) 3. Reject them all — none of these can be your hero 4. Ask: "What would make someone screenshot this and share it?" — that's the direction

Mood Definition

Before picking colors or fonts, define the emotional territory with two axes:

                    ENERGETIC
                       │
          Playful ─────┼───── Intense
                       │
         WARM ─────────┼─────────── COOL
                       │
           Gentle ─────┼───── Clinical
                       │
                     CALM

Place the brand on both axes. This determines everything:

• Warm + Energetic → bold colors, rounded fonts, dynamic motion
• Cool + Calm → muted palette, thin sans-serif, slow reveals
• Warm + Calm → earth tones, serif fonts, editorial layouts
• Cool + Energetic → neon on dark, geometric fonts, fast scroll effects

"What If" Prompts

If the concept feels safe, run through these:

• What if the hero wasn't a product shot but a macro of the material it's made from?
• What if the visual was abstract — no recognizable object, just emotion through color and form?
• What if the hero was a single frame from a process — manufacturing, cooking, growing — not the final product?
• What if you removed the product entirely and showed only the feeling of using it?
• What if the visual was moving — a slow 5-second loop that draws the eye?
• What if the color palette was the opposite of what the industry expects?
• What if the text was inside the visual (text masking) rather than next to it?

Output

After ideation, deliver:

1. 3 hero concepts ranked safe → bold, each with:

• Text description of the visual
• AI prompt (generic, works in any tool)
• infsh command (ready to run if they chose direct generation)

2. Mood position (which quadrant on the energy/temperature grid) 3. Visual metaphor in one sentence 4. Concept pairing if applicable 5. Anti-obvious reasoning — "competitors do X, we're doing Y instead because..."

Example output for a gut health app:

Concept 2 (Moderate): The gut microbiome as an abstract, beautiful ecosystem — glowing organic particles in greens and warm amber, floating in dark space like a living nebula.

>

Prompt: "Abstract gut microbiome ecosystem, organic glowing particles in green and warm amber, soft depth of field, dark background with warm light sources, no text, 16:9"

>

infsh command:

```bash

infsh app run bytedance/seedream-4-5 --input '{"prompt": "Abstract gut microbiome ecosystem, organic glowing particles in green and warm amber, soft depth of field, dark background with warm light sources, beautiful and warm not clinical, no text"}'

```

If using infsh: generate immediately after user picks a concept. If external tool: the user generates, then you build.

---

3. Hero Design

The hero makes or breaks a creative-first site. It's the first thing anyone sees. If it looks like a template, nothing below matters.

The Hero Visual Must Be Custom

The hero image/video/3D must be unique to this brand. Not a stock photo. Not a generic gradient. An AI-generated or custom-created visual that could only belong to this product.

• A reforestation site → 3D globe with forests growing on it
• A space platform → nebula background with a rocket
• A headphone brand → headphones floating in a cosmic sound wave field
• An interior design firm → panning video of a 3D-rendered room

If the visual could be swapped onto a competitor's site and still work, it's not custom enough.

Hero Layout Rules

1. The visual fills the viewport — full-bleed background (object-fit: cover, 100vh). The image IS the section, not a decoration inside it 2. Text lives in the quiet zone — position headlines where the image has dark/empty areas. Use gradient overlays to darken the text zone, keep the visual's focal point visible 3. Gradient overlays must be surgical — darken heavily where text sits (top), lighten where the visual's centerpiece is. Never flatten the entire image with a uniform dark wash 4. One headline, one line, one CTA — that's the text budget. If you need more words, the visual isn't doing its job 5. The product/subject should be recognizable without reading — someone scrolling past should know what this is from the image alone

Hero Enhancements

Scrolling stats ticker at the bottom of the hero:

• Adds credibility without taking visual space
• Frosted glass bar (backdrop-filter: blur) with key metrics scrolling horizontally
• Duplicated content for seamless CSS animation loop
• Examples: "2.1M Tonnes CO2 Sequestered" / "186 Indigenous Communities" / "40mm Beryllium Drivers"

Floating particles or ambient elements:

• Subtle leaves, stars, dust, or light particles drifting across the hero
• Must be subtle — enhance atmosphere, never distract from the visual
• Canvas-based or CSS-animated, with prefers-reduced-motion check

Mouse parallax on background:

• Background image shifts slightly opposite to cursor (10-25px range)
• Creates depth, makes the hero feel alive
• Disable on mobile and reduced motion

Entrance animation:

• Background scales in slightly (1.1 → 1.0) while fading in
• Text staggers in: tag → title → subtitle → CTA (100-200ms gaps)
• Total entrance: under 1.5 seconds. Don't make people wait

Hero Anti-Patterns

• Stock photo with centered text on top — this is the default Claude output, reject it immediately
• Text placed over the busy/detailed part of the image — unreadable
• Uniform dark overlay that kills the visual — surgical gradients instead
• No visual relationship between the image and the brand — the hero should tell you what this is
• Generic gradient or abstract blob as "hero visual" — generate a real, custom asset
• Tiny image in a container with padding — the visual must be full-bleed, edge to edge

---

4. Visual Patterns

14 patterns organized by type. Code snippets for core patterns in references/snippets.md, real-world examples in references/examples.md.

Static Patterns

Pattern 1: Full-Bleed Video Background

The video is the section. Text overlays with contrast treatment.

- Video fills viewport (object-fit: cover)
- Gradient mask at edges to blend with page background (see gradient mask utility in snippets)
- Text positioned with enough contrast (text-shadow, backdrop, or overlay)
- Compress aggressively: target <500KB for hero videos
- Provide poster frame for instant load
- iOS Safari: playsinline required, may pause in low-power mode — always provide poster fallback

Pattern 2: 3D Object as Hero

A rotating, interactive, or scroll-animated 3D element dominates the viewport.

- React Three Fiber / Three.js for interactive (WebGPURenderer is default since Three.js r171+)
- Spline for no-code 3D — includes text-to-3D and image-to-3D generation
- Pre-rendered video for simpler integration (avoids WebGL/WebGPU entirely)
- White or matched background for seamless blending
- Mouse parallax for subtle depth (optional)
- GLB/GLTF under 5MB, <100K polygons
- Compress with gltf-transform (npm i -g @gltf-transform/cli)
- WebGPU: 2-3x performance over WebGL, compute shaders for particle systems (100K+ particles at 60fps)
- Browser support: Chrome 113+, Safari 26+. Auto-fallback to WebGL 2 for older browsers

Pattern 3: Editorial Image Layout

Large, cinematic photographs drive the storytelling.

- Images take 60-80% of viewport
- Text wraps around or floats over with generous whitespace
- Asymmetric layouts — image bleeds off one edge
- No image grids — one image per thought
- Aspect ratios preserved, never stretched
- Generate at 2x resolution for Retina displays (e.g., 3840px wide for a 1920px viewport)

Pattern 4: Exploded View

Complex objects break apart or assemble as user scrolls or interacts.

- AI-generated exploded view video (Kling 3.0 / similar)
- Frame-by-frame scroll binding (same technique as Pattern 5)
- Text sections interleave with animation beats
- White/matched background for clean integration
- Gradient masks to blend animation edges with page

Scroll-Driven Patterns

The most powerful creative-first sites don't just scroll past static sections — the visuals themselves evolve as you scroll.

Choosing Your Scroll Stack

CSS Scroll-Driven Animations (prefer for simple patterns):

• animation-timeline: scroll() — ties animation to scroll position (0-100%)
• animation-timeline: view() — ties animation to element visibility in viewport
• animation-range — controls exactly when animation starts/ends (e.g., cover 0% cover 50%)
• Cross-browser: Chrome 115+, Safari 26+. Firefox still experimental — provide fallback
• Performance: runs on compositor thread, zero main-thread blocking, guaranteed 60fps
• Best for: parallax, fade-ins, progress bars, element reveals, sticky header shrinks
• Always wrap in @media (prefers-reduced-motion: no-preference)

GSAP ScrollTrigger + Lenis (use for complex patterns):

• Free since Webflow acquired GSAP in 2024
• Required for: frame sequences, pinned sections, complex timelines, coordinated multi-element choreography
• Lenis provides smooth scrolling foundation, GSAP handles the scroll-linked animations
• See the setup snippet in references/snippets.md

Rule of thumb: if the animation involves a single element fading/moving on scroll → CSS. If it involves pinning, scrubbing, or coordinating multiple elements → GSAP.

Pattern 5: Scroll-Driven Frame Sequence

An animation plays as the user scrolls — each scroll position maps to a video frame.

- Extract video frames as optimized WebP/JPEG (ffmpeg — see snippets for command)
- Preload frames in sequence
- Map scroll position to frame index via canvas drawing
- Pin the section during playthrough (sticky positioning)
- Text panels fade in/out between frame ranges
- Fallback: single static frame for low-power devices
- iOS: momentum scrolling fires events differently — use Lenis to normalize

Pattern 6: Visual Crossfade

One image dissolves into another at scroll thresholds.

- Stack 2+ full-bleed images in the same pinned container
- Map scroll progress to opacity of each layer
- Layer 1 fades out as Layer 2 fades in (crossfade)
- Each layer can have its own text panel that fades in sync
- Use: GSAP ScrollTrigger timeline with overlapping tweens
- Key: images must share similar composition or focal point for smooth transitions

When to use: Showing transformation — before/after, day/night, seasons, product states.

Pattern 7: Clip-Path Reveal

The next visual is revealed through an expanding shape, wipe, or mask as you scroll.

- Next image sits behind current image
- Scroll drives a clip-path animation (circle expanding from center, diagonal wipe, etc.)
- clip-path: circle(0% at 50% 50%) → circle(100% at 50% 50%)
- Or: clip-path: inset(0 100% 0 0) → inset(0 0% 0 0) for horizontal wipe
- Can also use SVG masks for organic/custom shapes
- GPU-friendly: clip-path animates on compositor thread

When to use: Dramatic reveals, scene changes, unveiling a product or concept.

Pattern 8: Visual Story Sequence

A series of distinct images appear one after another, each tied to a scroll beat — like turning pages of a visual book.

- Pin a full-viewport container for the duration of the sequence
- Divide scroll range into N equal segments (one per image)
- At each threshold: current image exits (fade/slide/scale), next enters
- Text panels change in sync with each image
- Stagger transitions: image leads, text follows (not simultaneous)

Story beats — structure the sequence like a narrative:

• Setup: Introduce the subject (wide shot, context)
• Build: Add detail and depth (closer, specific)
• Turn: The surprise or key insight (unexpected angle, dramatic reveal)
• Payoff: The resolution (product in use, final state, CTA)

When to use: Product storytelling, feature walkthroughs, brand narratives where each beat needs its own distinct visual.

Pattern 9: Parallax Layer Swap

The foreground content stays, but the background visual changes beneath it.

- Fixed/sticky background container with layered images
- Foreground content scrolls naturally over it
- As foreground sections enter viewport, background crossfades to match
- Each foreground section "owns" a background visual
- Transition: background shifts slightly (scale or position) during crossfade for depth

When to use: Long-scroll pages where sections have different moods but need continuity in the foreground content.

Pattern 10: Morphing Visual

A single visual transforms — zooms into a detail, rotates to a new angle, or morphs shape.

- Single image/video container, pinned
- Scroll drives CSS transform: scale, translate, rotate
- Zoom: scale(1) → scale(3) with transform-origin on the detail
- Can combine with clip-path to crop as you zoom
- For complex morphs: use a video or frame sequence instead of CSS transforms
- Text appears at key zoom levels to annotate what's being revealed

When to use: Product detail exploration, architectural walkthroughs, data visualization drill-down.

Pattern 11: Video Scrubbing

A single video contains multiple scenes — scroll position controls playback, and each scene is a distinct visual moment.

- One continuous video with multiple scenes baked in
- Map scroll range to video currentTime
- Define scene markers (timestamps) with associated text/UI changes
- At each marker: text panel transitions, UI accents shift
- Smoother than image sequences — no frame loading gaps
- Requires: video preloaded in memory (use requestAnimationFrame for smooth scrub)
- Mobile: fall back to key frames as static images at each scene marker
- iOS Safari: video.currentTime setting can be laggy — consider frame sequence fallback on mobile

When to use: When the visual narrative is continuous and scenes flow into each other — product assembly, journey, process visualization.

Pattern 12: Horizontal Scroll

User scrolls vertically, but content moves horizontally — reveals a panoramic visual or a sequence of panels.

- Pin a container that's wider than the viewport (e.g., 400vw)
- GSAP ScrollTrigger pins the section and translates content on x-axis
- Vertical scroll range maps to horizontal progress
- Each "panel" is a viewport-width section with its own visual + text
- Progress indicator shows horizontal position (dots or thin bar)
- Mobile: consider stacking panels vertically instead — horizontal scroll is harder on touch

When to use: Timelines, process flows, panoramic scenes, portfolios with sequential projects.

Pattern 13: Split-Screen Reveal

Two panels slide apart to reveal content beneath, or two halves show contrasting visuals.

- Two divs covering 50% viewport each (left/right or top/bottom)
- Scroll drives transform: translateX — panels slide apart
- Content beneath is revealed as gap widens
- Can also use clip-path on each half for diagonal/angled splits
- Text or product appears in the revealed center
- Combine with crossfade for the revealed content

When to use: Before/after comparisons, product reveals, contrasting concepts (old vs new, problem vs solution).

Pattern 14: Text Masking

Text becomes a window into the visual — the image is only visible through the letterforms.

- Large headline with background-clip: text and transparent color
- Background: the hero image or video, positioned to show the interesting part through the text
- Scroll can drive background-position for movement through the text window
- Works best with thick, bold fonts — thin fonts don't reveal enough image
- Fallback: solid-color text for browsers that don't support background-clip: text (rare now)

When to use: Hero headlines, section transitions, brand statements. One per page maximum — it's a showpiece.

Transition Timing Principles

Regardless of pattern, follow these:

1. Image leads, text follows — the visual should arrive 100-200ms before its text. Never the other way around 2. One transition at a time — don't crossfade images while also wiping and scaling. Pick one visual transition per section 3. Hold the visual — after a transition completes, the visual should stay for at least 30% of the section's scroll range before the next transition starts. Let people absorb it 4. Match the pace — fast scroll = fast transitions feel jarring. Stretch the scroll range so transitions happen at a comfortable reading pace (roughly 1 transition per 500-800px of scroll) 5. Exit before entry — the current visual should begin its exit before the next visual fully enters. Overlap creates depth; hard cuts feel like slides

---

5. AI Asset Generation Guidance

When visuals need to be created, recommend specific generation approaches. Always let the user choose their preferred tool.

Direct Generation via inference.sh CLI

If the user opts for direct generation, Claude can generate images via the infsh CLI. This is the fastest path — no external tools needed.

Setup (one-time):

npm i -g @anthropic-ai/inference-sh
infsh login

Recommended models for creative-first-ui:

Example — generate a hero image:

# Cinematic 4K hero
infsh app run bytedance/seedream-4-5 --input '{
  "prompt": "premium headphones floating in cosmic sound waves, cyan and magenta energy, dark background, cinematic lighting, no text"
}'

# Quick iteration (cheap, fast)
infsh app run pruna/flux-klein-4b --input '{
  "prompt": "abstract gut microbiome ecosystem, glowing green particles, dark background, organic and warm, no text"
}'

# With specific aspect ratio
infsh app run xai/grok-imagine-image --input '{
  "prompt": "architectural interior 3D render, warm lighting, white room, no text",
  "aspect_ratio": "16:9"
}'

# Upscale result to 2x for Retina
infsh app run falai/topaz-image-upscaler --input '{"image_url": "https://..."}'

Video generation via infsh:

# Hero video background — 5s loop
infsh app run xai/grok-imagine-video --input '{
  "prompt": "slow pan across cosmic sound wave field, dark background, cyan and magenta particles flowing, cinematic, no text",
  "duration": 5
}'

# Animate a still hero image into video
infsh app run falai/wan-2-5 --input '{
  "image_url": "https://your-hero-image.jpg"
}'

# Best quality hero video
infsh app run google/veo-3-1 --input '{
  "prompt": "rotating 3D globe with forests growing on it, volumetric green light, dark background, slow smooth rotation, no text"
}'

# Add ambient sound to a silent hero video
infsh app run infsh/hunyuanvideo-foley --input '{
  "video_url": "https://your-hero-video.mp4",
  "prompt": "gentle ambient hum, soft electronic atmosphere"
}'

Workflow when using infsh: 1. Run Creative Ideation (Section 2a) to develop concepts 2. Generate 3-4 image variations using a fast model (FLUX Klein or Grok) 3. Pick the best direction 4. Regenerate at highest quality (Seedream 4.5 or ImagineArt) 5. Optionally: animate the still image into video (Wan 2.5 or Seedance) 6. Upscale if needed (Topaz Upscaler for images, Topaz Video Upscaler for video) 7. Optionally: add sound effects (Foley) 8. Build the page around the result

External Tool Selection

If the user prefers external tools, recommend based on their needs:

Still Images

Video / Animation

3D Models

3D pipeline: Generate → reduce polys → bake textures → export GLB → compress with gltf-transform (npm i -g @gltf-transform/cli) → target <5MB, <100K polygons.

Prompt Patterns

Still images:

[Subject] in [specific style], [background color] background,
[lighting style], [camera angle], high detail, sharp focus,
no text, no words, no watermark

Video/animation:

High-quality [animation type] of [subject], [background color] background,
[camera movement], [style], smooth motion, no text.
[For rotating: "center of mass should not move, object rotates on its axis"]
[For exploded: "all parts stay within frame boundaries"]

Settings: 16:9 for hero backgrounds, 1:1 for featured elements, 1080p minimum.

Resolution & Retina

Always generate at 2x the display size for Retina/HiDPI:

• 1920px viewport → generate at 3840px wide
• 1440px viewport → generate at 2880px wide
• Mobile 390px → generate at 780px wide

For video, 1080p is the minimum. 4K if the hero is full-bleed and performance budget allows.

Common Mistakes

• Not specifying background → random gradients that clash with site
• Forgetting "no text" → unwanted words baked into the image
• Vague style ("cool looking") → be specific: "isometric 3D render" or "editorial fashion photography"
• Wrong aspect ratio → generate at the ratio you need, don't crop after
• Single generation → always generate 3-4 variations and pick the best
• Inconsistent lighting → if multiple assets share a page, use the same lighting/style prompt for all
• 1x resolution on Retina → looks blurry, kills the "visual is the design" philosophy

---

6. Typography Rules

Typography is secondary. It exists to anchor the visual, not compete with it.

Hierarchy

• Headlines: Large, bold, but not louder than the image. If the visual is strong, the headline can be smaller than you think
• Body text: Minimal. 2-3 sentences max per section. If you're writing a paragraph, you need a better image instead
• Labels: Small, sparse, informational only

Font Selection

• Avoid generic system fonts (Inter, Roboto, Arial)
• Choose fonts that complement the visual mood, not fight it
• One display font + one body font maximum
• When the visual is loud, the font should be quiet. When the visual is subtle, the font can be expressive

Font Pairing by Mood

Use Google Fonts, Fontshare, or self-hosted WOFF2 files. Never load more than 2 font families.

Kinetic Typography

When the visual is subtle or absent, text itself can become the visual element. Use sparingly — one kinetic moment per page, not every heading.

Techniques:

• Split text animation — split headlines into characters/words/lines, stagger entrance with GSAP SplitText or CSS animation-delay. Characters cascade in on scroll
• Variable font morphing — animate font-variation-settings (weight, width, slant) on hover or scroll. Text "breathes" and shifts weight
• Gradient text — background-clip: text with animated gradient. The text becomes a window into moving color
• Clip-path text reveal — clip-path: inset(0 100% 0 0) → inset(0) reveals text character by character, word by word
• Image-filled text — background-clip: text with a photo/video as background. The image is visible only through the letterforms
• Circular/curved text — text arranged in a circle or along a path, rotating on scroll

Rules:

• Kinetic type is a visual showpiece — use it for ONE headline, not every heading
• Must degrade to static text with prefers-reduced-motion
• Ensure the text is still in the DOM and readable by screen readers (not canvas-rendered)
• Don't animate body text — only display/headline sizes

Text Treatment Over Visuals

• Never place unreadable text over a busy image
• Use: gradient overlays, frosted glass panels, darkened regions, text-shadow, or position text in quiet areas of the image
• Test: squint at the page — if you can't read it, fix the contrast

---

7. Interaction & Hover Patterns

Visual-first sites feel alive through micro-interactions on the visuals themselves.

On Images

• Subtle zoom on hover: transform: scale(1.03) with overflow: hidden on container — image breathes, never jumps
• Parallax tilt: image shifts slightly opposite to cursor position — creates depth without being gimmicky
• Brightness/contrast shift: slight increase in brightness on hover to draw focus
• Reveal caption: text fades in over the image on hover with a darkened overlay — info on demand

On Video Sections

• Pause/play on hover: video pauses when cursor leaves, resumes on enter — draws attention
• Cursor transforms: custom cursor changes over video areas (play icon, explore icon)
• Speed shift: video plays at 0.5x by default, 1x on hover — creates a "lean in" moment

On 3D Objects

• Mouse-follow rotation: object subtly rotates toward cursor position
• Scroll + drag hybrid: scroll drives the main animation, but dragging allows free exploration
• Hover glow/highlight: material emissivity increases on hover — object "lights up"

Cursor Design

• Default cursor feels wrong on visual-first sites
• Use a custom cursor that complements the aesthetic: dot, crosshair, circle with blend-mode
• Cursor should react to interactive elements (grow, change color, show label)
• Always fall back to default cursor on mobile (no hover state)

Advanced cursor effects:

• Magnetic snap — buttons/links "pull" toward the cursor within a threshold radius (~100px). The element moves toward the pointer, not just the cursor toward the element. Use Motion's useMagneticPull hook or GSAP with distance calculation
• Cursor morphing — cursor reshapes to match the hovered element's form (circle over round buttons, rectangle over cards). Motion Cursor library handles this
• Cursor zones — different page regions change cursor color, blend mode, or size. Dark sections → light cursor, light sections → dark cursor
• Liquid blob — cursor trails a fluid blob shape using WebGL/canvas. Impressive but heavy — reserve for portfolio/agency sites
• Particle trail — cursor leaves a fading trail of particles. Subtle and lightweight if done with CSS, heavier with canvas

Rules

• Never add hover effects that compete with the visual — they should amplify, not distract
• All hover transitions: 0.3s ease-out minimum. No snapping
• If the visual already has motion (video, animation), hover effects should be subtler
• prefers-reduced-motion: disable all hover animations, keep static visual changes only

---

8. Layout Philosophy

The Visual Dictates the Layout

Do not start with a grid and place images into it. Start with the image and build the grid around it.

• A landscape image → full-width section with text below or overlaid
• A portrait image → asymmetric split with text on the opposite side
• A video → pinned fullscreen section with scroll-driven content
• A 3D object → centered with radial text placement or floating labels

Spacing System

Use an 8px base unit for all spacing (aligned with Apple HIG and Material Design spacing grids). This creates visual consistency even when layouts are unconventional:

• 0.5rem (8px) — tight gaps, inline elements
• 1rem (16px) — standard element spacing
• 2rem (32px) — between related groups
• 4rem (64px) — between distinct content blocks
• 8rem–12rem (128–192px) — between visual sections. Let each visual breathe

Between text and visuals: tight when text labels the visual, wide when they're separate thoughts.

Touch Targets

All interactive elements must meet minimum 44x44px touch area (Apple HIG requirement, also WCAG 2.5.8):

• Buttons, links, nav items: min-height: 44px; min-width: 44px
• If the visible element is smaller (e.g. a small icon button), expand the tap area with padding or ::after pseudo-element
• CTA buttons in heroes: go larger — 48-56px height. They need to be easy to hit on mobile
• Ticker items, footer links: still 44px tap area even if text is small

Minimum Text Sizes

Never go below these floors (aligned with Apple HIG typography guidance):

• Body text: 16px (1rem) minimum — anything smaller is unreadable on mobile
• Labels/captions: 12px (0.75rem) minimum — only for truly secondary info like timestamps or legal
• Headlines: no minimum — scale freely, but ensure contrast with visual
• Ticker text: 12px minimum, but compensate with letter-spacing and uppercase for legibility

Bento Grid Layout

For feature sections that need to show multiple items without falling into the icon+text card trap, use bento grids — modular cards of varying sizes on CSS Grid (named after Japanese lunch boxes).

- CSS Grid with `grid-template-columns: repeat(auto-fit, minmax(250px, 1fr))`
- Vary card sizes: some span 2 columns, some span 2 rows — creates visual hierarchy within the grid
- Each card's visual is the content: a photo, animation, chart, or interactive element — NOT an icon
- Text is minimal: 1 headline + 1 line per card
- Cards can have different background treatments (image, gradient, frosted glass, solid color)
- 23% higher click-through rate vs traditional feature lists

Rules for bento in visual-first design:

• At least half the cards must be image/visual-dominant, not text-dominant
• The largest card should contain the most important feature with the strongest visual
• No more than 6-8 cards visible at once — beyond that, it becomes a wall
• Mobile: collapse to single column, maintain visual hierarchy by card order

Breaking Monotony

• Alternate between full-bleed and contained sections
• Mix static images with animated/video sections
• Use scale shifts — a massive hero followed by a quieter editorial section
• No two consecutive sections should have the same layout pattern
• Use bento grids for feature sections instead of repeating the same card layout

---

9. Page Rhythm & Visual Pacing

A full page needs dynamic pacing — not every section should hit the same visual intensity.

The Intensity Curve

Think of the page like a film score:

Hero:         ████████████  (LOUD — full-bleed video/3D, maximum impact)
Features:     ██████        (Medium — editorial images, breathing room)
Deep dive:    ████████████  (LOUD — scroll-driven sequence, exploded view)
Social proof: ████          (Quiet — minimal visuals, testimonials, trust)
CTA:          ████████      (Rising — background visual, urgency)
Footer:       ██            (Whisper — clean, functional)

Rules

• Never stack two loud sections — visual fatigue kills engagement. Follow a loud section with a quiet one
• The hero sets the ceiling — nothing later should be more visually intense than the hero
• Quiet sections earn loud ones — breathing room makes the next visual hit harder
• End with rising energy — the CTA should feel like a build, not a fade
• 3-act structure: Hook (hero) → Story (features/deep dive, alternating intensity) → Close (CTA)

Section Transitions

• Between loud → quiet: generous whitespace (150-200px gap), let the eye rest
• Between quiet → loud: tighter gap (80-100px), pull the user into the next visual
• Between same intensity: use a visual divider (gradient fade, color shift, subtle line)

---

10. Conversion & Persuasion

Creative-first design must convert, not just impress. Beauty without action is a screensaver.

The 5-Second Rule

A visitor must understand what this is and why they should care within 5 seconds — from visuals alone, not from reading. If the hero visual doesn't communicate the product/brand instantly, it's art, not design.

CTA Design

The CTA is the most important interactive element on the page. It must be:

• Value-driven copy — "Start Free Trial", "See Your Results", "Experience Aura" — not "Submit", "Learn More", "Click Here"
• High contrast from surrounding design — the CTA color should pop against the hero visual
• Above the fold — at least one CTA visible without scrolling
• Repeated — CTA appears in hero, after features, and at final CTA section (3 minimum per page)
• Sized for confidence — 48-56px height on desktop, full-width on mobile. Small buttons signal unimportance
• Frosted glass or solid — on dark visual backgrounds, use backdrop-filter: blur with border, or solid accent color. Never a ghost button that disappears into the visual

Trust Signals

Trust signals make the visual story credible. Place them near CTAs and after benefit claims:

• Customer logos — recognizable brand logos in a row or ticker. Grayscale on dark backgrounds, color on light
• Testimonials with photos — real faces convert better than text-only quotes. Photo + name + title + quote
• Numbers/stats — "10,000+ users", "98% satisfaction", "4.9/5 rating". Use in the hero ticker or as large display numbers between sections
• Social proof badges — "Product of the Day", "4.8 on App Store", "Featured in [Publication]"

Placement rule: trust signals follow benefit claims in the visual rhythm. Claim → proof → CTA. Never front-load trust before the user knows what you do.

Copy Rules for Visual-First Pages

Text is minimal but must be precise:

• Clarity over cleverness — if choosing between clear and creative, clear wins
• Specificity over vagueness — "Cut reporting from 4 hours to 15 minutes" not "Save time on workflow"
• Benefits over features — "Hear frequencies you've been missing" not "40mm beryllium drivers"
• One idea per section — each visual section advances ONE argument, not three
• Headlines: 6-10 words. The visual carries the emotion, the headline names it
• Subheadlines: 1-2 sentences expanding with specificity
• Body: 2-3 sentences max per section. If you need more, your visual isn't working

Visual Psychology

Design decisions that affect conversion through perception:

---

11. Pattern Combinations

Not all patterns work together. Some amplify each other, some fight.

Works Well Together

Avoid Combining

The One-Hero Rule

Every page gets one primary visual showpiece. Everything else supports it. If you have a scroll-driven exploded view, that's your hero moment — other sections use simpler patterns (editorial images, crossfades) to let the showpiece shine.

---

12. Advanced Visual Techniques

Beyond the core patterns, these techniques add depth, texture, and polish to visual-first sites.

Shader Effects

Shaders are no longer expert-only. They add visual richness that's impossible with CSS alone.

Common effects on award-winning sites:

• Frosted glass / glass refraction (beyond CSS backdrop-filter)
• Iridescent color shifting (chroma chrome)
• Procedural noise animations
• Post-processing: bloom, chromatic aberration, film grain, lens distortion
• Heat distortion, glitch effects, kaleidoscopic warping

Tools (from accessible to advanced):

Rules:

• Shaders are accent, not wallpaper — use on one section, not the entire page
• Performance: test on low-end devices. Shader complexity scales with GPU, not CPU
• Fallback: if WebGL/WebGPU unavailable, show a static CSS gradient or image
• prefers-reduced-motion: disable animated shaders, show a static frame

Noise & Grain Textures

Subtle noise combats gradient banding, adds analog warmth, and creates depth. Underused on the web.

The standard technique:

/* SVG feTurbulence noise as background layer */
.grain {
  position: relative;
}
.grain::after {
  content: '';
  position: absolute;
  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='noise'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.65' numOctaves='3' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23noise)'/%3E%3C/svg%3E");
  opacity: 0.04;
  mix-blend-mode: overlay;
  pointer-events: none;
  z-index: 1;
}

When to use:

• Over solid color backgrounds or gradients — eliminates banding
• On hero overlays — adds film-like texture
• On cards or surfaces — creates tactile depth
• Not over photographs — they already have texture

View Transitions API

GPU-accelerated page/state transitions, native in the browser. No animation library needed.

What it does: When content changes (page navigation, state update), the browser captures before/after snapshots and animates between them.

Use cases in creative-first sites:

• Product gallery → detail page morph (image expands from grid to full-bleed)
• Section transitions on SPA navigation
• Filtered content re-arrangement (items morph to new positions)
• Dark/light mode transitions (whole page crossfades)

Key features (2026):

• view-transition-name: match-element — auto-names elements, no manual naming
• Nested transition groups — preserves DOM hierarchy for 3D/clip effects
• Cross-document transitions — works between actual page loads, not just SPA

Browser support: Chrome 111+, Safari 18+. Firefox 144+ (same-document only). Provide CSS fallback for unsupported browsers.

Rive Animations

For interactive, stateful animations that respond to user input — Rive is the modern choice over Lottie.

When to use Rive vs Lottie:

Use in creative-first sites:

• Interactive hero illustrations that respond to scroll/hover
• Animated icons that transition between states (menu → close, play → pause)
• Data-driven visualizations that update in real time
• Loading animations with progress state machines

Sound Design (Optional)

Sound is niche but powerful for immersive creative experiences. Completely optional — most sites shouldn't use it.

When sound adds value:

• Portfolio/agency sites where immersion is the goal
• Product experiences (audio products, music, gaming)
• Campaign/storytelling sites with narrative
• NOT on SaaS landing pages, e-commerce, or information sites

Rules if you use sound:

• Always opt-in — browsers block autoplay audio. Provide a visible sound toggle
• The more frequent the interaction, the quieter the sound — button clicks should be near-silent, major transitions can be richer
• Silence is intentional — not every interaction needs sound
• Tools: Tone.js for synthesis/effects, Howler.js for simple playback
• Performance: preload audio files, use Web Audio API for low-latency playback
• Accessibility: sound must never be the sole indicator of state change. Always pair with visual feedback

---

13. Color & Theming

Extracting the Palette

The visual asset defines the color palette, not the other way around.

1. Extract 3-5 dominant colors from the hero visual using:

• Coolors Image Picker — upload image, click to extract
• Adobe Color — extract themes from uploaded images
• Browser DevTools: screenshot the hero, use the eyedropper on key areas
• Programmatic: canvas.getContext('2d') → sample pixels → cluster with k-means

2. Build the page palette: one dominant + one accent + neutrals 3. Ensure backgrounds match or complement the visual's background

If the visual has a white background → page sections should be white or very light. If the visual is dark and moody → embrace dark UI around it.

Never force a pre-decided color palette onto a visual that clashes with it.

Semantic Color Tokens

Never use raw hex values scattered through CSS. Map extracted colors to semantic tokens so the design stays maintainable and theme-aware (aligned with Apple HIG color system principles):

:root {
  /* Extracted from hero visual */
  --color-accent: #00d4ff;
  --color-accent-2: #e84eff;

  /* Semantic tokens — use THESE in components, not the raw values above */
  --page-bg: #06060f;
  --surface: #0d0d1a;          /* cards, elevated containers */
  --label: #eef0f6;            /* primary text */
  --label-secondary: #8a8a9a;  /* supporting text, captions */
  --label-tertiary: #5a5a6a;   /* disabled, placeholder */
  --separator: rgba(255,255,255,0.08);  /* dividers, borders */
  --overlay: rgba(6,6,15,0.6); /* glassmorphism, frosted panels */
  --accent: var(--color-accent);        /* buttons, links, highlights */
  --accent-hover: var(--color-accent-2); /* hover states */
  --destructive: #ff453a;      /* delete, error states */
}

Benefits:

• Change the palette in one place when swapping visual assets
• Dark/light mode switching becomes token remapping, not a rewrite
• Components reference var(--label) not #eef0f6 — self-documenting

High Contrast Support

Some users enable increased contrast. Support prefers-contrast: more:

@media (prefers-contrast: more) {
  :root {
    --label: #ffffff;
    --label-secondary: #cccccc;
    --separator: rgba(255,255,255,0.25);
    --overlay: rgba(0,0,0,0.85);
  }
  /* Increase text-shadow strength for text over visuals */
  .hero__title { text-shadow: 0 2px 8px rgba(0,0,0,0.9); }
}

Dark / Light Mode

Visual-first sites work best as single-theme experiences. If the visual demands dark, go full dark. Don't force dual-theme support where the visuals only work in one mode.

If you must support both:

• White-background assets → work in light mode. For dark: generate a separate dark-background variant or add container with matched background
• Dark-background assets → work in dark mode. Same approach inverted
• Transparent assets (PNG, WebP with alpha) → work in both. Best option when feasible
• Videos → hardest to theme-switch. Use overlay tinting or generate separate edits
• Never use CSS filter: invert() on photos/videos — it looks terrible
• Use CSS custom properties for all overlay colors, gradients, and text colors so they switch cleanly
• Gradient masks must reference var(--page-bg), not hardcoded colors
• If you can only generate one asset variant, design for dark mode — it's more forgiving and visually striking

Theme-Specific Contrast Rules

Dark mode:

• Text: #eef0f6 or lighter on dark backgrounds
• Muted text: no darker than rgba(255,255,255,0.5) — anything less is unreadable
• Glass/frosted panels: backdrop-filter: blur(12px) with bg-opacity >= 0.6
• Borders: rgba(255,255,255,0.08) minimum — invisible borders look broken

Light mode:

• Primary text: #0F172A (slate-900) or darker — not gray-400
• Muted text: #475569 (slate-600) minimum — lighter grays fail contrast
• Glass cards: bg-white/80 or higher opacity — bg-white/10 is invisible in light mode
• Borders: #e2e8f0 (slate-200) minimum — must be visible

---

14. Performance

Heavy visuals demand smart performance.

Images

• WebP/AVIF format, responsive sizes via srcset and <picture>
• Lazy load everything below the fold
• Hero image: preload in <head>, set explicit width/height, provide low-res LQIP placeholder
• Generate at 2x for Retina (see Section 4)

Videos

• Compress to <500KB for backgrounds: ffmpeg -i input.mp4 -crf 28 -preset slow -vf scale=1920:-1 output.mp4
• Set poster attribute for instant first frame
• playsinline muted autoplay loop for background videos
• Consider converting to frame sequence for scroll-driven sections

3D

• Compressed GLB (<5MB) via gltf-transform optimize input.glb output.glb
• Progressive loading with skeleton placeholder
• Fallback static image for low-power devices
• loading="lazy" on canvas container

iOS / Safari Gotchas

• Video autoplay requires playsinline + muted — without both, Safari shows a play button
• Low-power mode and Data Saver can pause autoplay videos — always provide a poster fallback
• video.currentTime setting is laggy on iOS Safari — for scroll-driven video scrubbing, prefer frame sequences on mobile
• iOS momentum scrolling fires scroll events differently — use Lenis to normalize scroll input
• WebGL performance is lower on iOS — reduce 3D polygon count and texture size for mobile

Loading States

Visual-first sites load heavy assets. Users must never stare at a blank screen. Follow Apple HIG loading hierarchy:

1. Skeleton screens (best) — show the page layout with gray placeholder shapes where visuals will load. The structure is visible instantly, assets fill in progressively 2. LQIP (Low-Quality Image Placeholder) — load a tiny blurred version of the image first (base64 inline or 1-2KB WebP), then swap to full resolution. The visual is "there" immediately, just blurry 3. Progress indicator — for frame sequences or 3D models that take multiple seconds, show a thin progress bar or percentage. Give the user a sense of "how long" 4. Poster frame — for videos, the poster attribute shows one frame instantly while the video loads 5. Never a blank viewport — if the hero takes 2+ seconds to load, the user should see something — a dark background with the text already visible at minimum

Avoid:

• Full-screen blocking spinners with no context
• "Loading..." text with no visual
• A flash of unstyled content followed by a layout shift when the image arrives

Animation Performance Rules

These are non-negotiable for smooth 60fps:

• Only animate `transform` and `opacity` — these are compositor-friendly (GPU-accelerated). Never animate width, height, top, left, margin, padding, box-shadow, or filter continuously
• Never `transition: all` — list properties explicitly: transition: transform 0.3s ease, opacity 0.3s ease
• Animations must be interruptible — respond to user input mid-animation, don't lock out interaction
• Set `transform-origin` explicitly — defaults can cause unexpected behavior, especially on scale/rotate

CSS Production Details

Small things that matter for polished visual-first sites:

• `text-wrap: balance` on headlines — prevents widows (single word on last line). Use text-wrap: pretty on body text
• `font-variant-numeric: tabular-nums` on ticker stats and number columns — digits align vertically
• `touch-action: manipulation` on interactive areas — removes 300ms double-tap zoom delay on mobile
• `overscroll-behavior: contain` on modals, drawers, and scroll-pinned sections — prevents background scroll
• *`env(safe-area-inset-)`** on full-bleed layouts — handles iPhone notch and dynamic island. Critical for hero sections:

  .hero { padding-top: env(safe-area-inset-top); }
  .hero__ticker { padding-bottom: env(safe-area-inset-bottom); }

• `color-scheme: dark` on <html> for dark-themed sites — fixes scrollbar and native input colors
• `<meta name="theme-color" content="#06060f">` — matches browser chrome to page background
• Curly quotes " " not straight " — and … not ...
• `cursor: pointer` on all clickable elements — cards, buttons, links, interactive visuals. Missing cursor feedback makes things feel broken
• `max-width: 65ch` on body text containers — limits line length to 65-75 characters for readability. Headlines can be wider
• z-index scale — define a consistent scale, don't use random values:

  :root {
    --z-base: 0;
    --z-above: 10;      /* elevated cards, sticky elements */
    --z-nav: 50;         /* fixed navigation */
    --z-overlay: 100;    /* modals, drawers */
    --z-cursor: 9999;    /* custom cursor, always on top */
  }

• No emoji icons — use SVG icons (Heroicons, Lucide, Phosphor). Emojis render differently per OS and look unprofessional in UI

Bandwidth & Progressive Enhancement

• Detect Save-Data header or navigator.connection.saveData — serve static images instead of videos/3D
• Use <link rel="preload" as="image" media="(min-width: 768px)"> — don't preload desktop assets on mobile
• Total page weight target: <3MB on initial load (defer non-visible assets)
• Use IntersectionObserver to load assets only when approaching viewport
• Preload critical hero asset in <head>, defer everything else
• Critical fonts: <link rel="preload" as="font" crossorigin> with font-display: swap

---

15. Accessibility

Visual-first does not mean accessibility-last. A beautiful site that excludes users is a failed site.

Reduced Motion

• Wrap all animations, scroll effects, and video autoplay in prefers-reduced-motion checks
• When reduced motion is preferred:
• Videos → show poster frame, add manual play button
• Scroll-driven sequences → show the final/key frame statically
• Crossfades/reveals → instant swap, no transition
• Parallax → disable, use static positioning
• 3D rotation → show a single static angle
• Never skip reduced motion handling. It's not optional

Screen Readers

• Every visual section needs a descriptive aria-label or associated text that conveys the message the visual communicates
• Decorative visuals (ambience, background) → aria-hidden="true", role="presentation"
• Meaningful visuals (product, storytelling) → descriptive alt text that captures what the visual communicates, not just what it shows
• Scroll-driven content must be accessible without scrolling — all text should exist in the DOM, not generated by JS

Keyboard Navigation & Focus

• All interactive elements (CTAs, nav, links) must be focusable and operable via keyboard
• Custom cursors don't change this — focus indicators must be visible
• Use :focus-visible over :focus — avoids focus ring on mouse click, shows it on keyboard
• Never outline: none without a visible replacement (e.g., focus-visible:ring-2)
• Skip link to main content — especially important when the hero is a full-viewport video/animation
• Scroll-pinned sections must not trap keyboard users — ensure Tab moves past them
• Use <button> for actions, <a> for navigation — never <div onClick>
• Icon-only buttons need aria-label

Color Contrast

• Text over visuals: 4.5:1 minimum for normal text, 3:1 for large text (WCAG AA)
• If the visual makes this impossible, add an overlay — don't compromise readability
• Test contrast with the actual visual behind it, not against a flat color
• Never rely on color alone to communicate information — pair with icons, labels, or patterns

High Contrast Mode

• Support prefers-contrast: more — some users need stronger contrast than WCAG AA
• Increase text opacity to full white/black, strengthen separators, deepen overlays
• Gradient text (-webkit-background-clip: text) can be invisible in high contrast — provide a solid-color fallback
• Test: enable "Increase Contrast" in macOS/iOS accessibility settings and verify readability

Fallbacks

• Every visual pattern needs a no-JavaScript fallback: static image, visible text, functional links
• If a video fails to load, the poster frame + text should still tell the story
• If WebGL/3D fails, a static render should appear

---

16. Anti-Patterns

Instant failure — restart if you catch yourself doing any of these:

Layout Anti-Patterns

• Icon grids with text labels as a "features" section
• Stock photo in a small rectangle with text wrapping around it like a blog post
• Placeholder boxes with "Image goes here"
• Text-heavy sections with a decorative image off to the side
• Symmetrical card layouts where every card has an icon + title + description
• Using the same layout template for every section
• Generic gradient backgrounds instead of real visual assets
• Treating images as decoration rather than as the primary content

Scroll & Animation Anti-Patterns

• Scroll hijacking that traps the user — they should always feel in control of scroll direction and speed
• Animations that fire faster than the user can read the content
• Multiple competing transitions in the same viewport — pick one per section
• Scroll-driven effects that break on trackpad vs mouse vs touch — test all input methods
• Long pinned sections with no visual progress indicator — users don't know how far to scroll
• Animations that replay every time the section enters viewport — play once, then hold

Asset Anti-Patterns

• Using a visually stunning hero but falling back to icon+text for every section below
• Inconsistent asset quality — one section has a cinematic 4K image, the next has a blurry stock photo
• Assets with different lighting/color temperature on the same page — breaks visual cohesion
• AI-generated images with visible artifacts (weird hands, text gibberish, warped geometry) shipped without cleanup

Code Anti-Patterns

• transition: all — list properties explicitly
• outline: none without a :focus-visible replacement
• <div onClick> instead of <button> or <a>
• Images without explicit width/height (causes CLS)
• Icon buttons without aria-label
• Animating width, height, top, left instead of transform
• Missing prefers-reduced-motion on any animation
• user-scalable=no or maximum-scale=1 — never disable pinch zoom

---

17. Iteration Workflow

Creative-first design is not one-shot. The real quality comes from the generate → build → review → fix loop. A first pass will never be good enough.

The Loop

1. Generate visual assets (AI tools)
2. Build the page around them (AI coding agent)
3. Screenshot the result
4. Identify what's wrong (text readability, visual placement, pacing, color)
5. Tell Claude exactly what to fix (with the screenshot)
6. Repeat 3-5 times per section

How to Give Feedback That Works

Bad: "make it better" / "it looks off" / "more creative"

Good:

• "The text in the hero is unreadable — darken the overlay behind it but keep the center of the image visible"
• "The gradient mask is cutting off the headphones — extend the visible area down by 20%"
• "The hero feels static — add mouse parallax on the background"
• "This section looks like every other SaaS site — the image needs to dominate, shrink the text"
• "The transition between hero and the next section is jarring — add a gradient fade at the bottom"

What to Check After Each Pass

1. Squint test — squint at the page. Can you still read the text? Can you still see the visual's focal point? 2. Scroll speed test — scroll at natural pace. Do animations feel smooth or jarring? Too fast? Too slow? 3. Remove-text test — mentally remove all text. Does the page still look intentional? 4. Mobile check — resize to 375px. Did the visual story survive or collapse to text+icon? 5. Competitor test — screenshot it, put it next to a competitor's site. Can you tell them apart instantly?

When to Regenerate the Asset vs Fix the Code

Regenerate the asset when:

• The image composition doesn't leave room for text
• The lighting/colors clash with the rest of the page
• The subject isn't recognizable or looks "AI-ish" (artifacts, weird geometry)
• The background color doesn't match the page

Fix the code when:

• Text readability (overlay opacity, positioning, contrast)
• Visual placement (object-fit, object-position, sizing)
• Animation timing (too fast, too slow, wrong easing)
• Section transitions (gradient masks, spacing)

Iteration Budget

Plan for:

• Hero: 3-5 iterations minimum (it's the most important section)
• Scroll sections: 2-3 iterations each
• Editorial sections: 1-2 iterations (simpler layouts)
• Mobile adjustments: 2-3 passes after desktop is done

---

18. Output Structure

When generating creative-first designs, deliver these in order:

1. Visual Asset Manifest

List every visual asset needed with: description, recommended tool + prompt, format, dimensions (at 2x for Retina), file size target, and which pattern it uses (Pattern 1-11).

2. Design Direction

• Mood/emotion (derived from the visual, not imposed)
• Color palette (extracted per Section 10)
• Font pairing (per Section 5)
• Theme (dark/light) with rationale
• Page rhythm plan (per Section 8)

3. Implementation

• Full working page or component code
• Scroll stack setup (GSAP + Lenis — see references/snippets.md)
• Asset integration with gradient masks, overlays, contrast treatments
• prefers-reduced-motion fallbacks for every animated pattern
• Mobile strategy: what changes on small screens (poster frames, static fallbacks, art-directed crops, tap instead of hover)

---

19. The Taste Test

Before finalizing, answer every question:

Visual Quality

1. Screenshot test: Would someone stop scrolling to look at this? 2. Remove-the-text test: Does the page still communicate something with all text removed? 3. Memory test: Would someone remember this page 24 hours later? 4. Template test: Could this be confused with a template? If yes, restart 5. Emotion test: Does the visual make you feel something in 2 seconds?

Technical Quality

6. Speed test: First meaningful paint under 2 seconds despite heavy assets? 7. Scroll test: All scroll animations smooth at 60fps? No jank? 8. Mobile test: Does mobile still tell the visual story, or did it fall back to text+icon? 9. Accessibility test: Screen reader, keyboard, reduced motion — all working? 10. Input test: Mouse, trackpad, touch, keyboard — all working?

If any answer is no → fix it before shipping.

Pre-Delivery Checklist

Run through before handing off code:

Visuals:

• [ ] Hero uses custom AI-generated visual, not stock photo
• [ ] No icon grids or symmetrical card layouts
• [ ] No two consecutive sections use the same layout pattern
• [ ] All images have explicit width/height
• [ ] Images use WebP/AVIF, lazy loaded below fold, hero preloaded

Interactions:

• [ ] All clickable elements have cursor: pointer
• [ ] Hover states provide visual feedback (color, opacity, shadow — not scale shifts)
• [ ] Transitions list properties explicitly (no transition: all)
• [ ] Custom cursor disabled on touch devices

Accessibility:

• [ ] prefers-reduced-motion fallbacks on every animation
• [ ] prefers-contrast: more support on text over visuals
• [ ] All images have descriptive alt text
• [ ] Icon buttons have aria-label
• [ ] Skip link to main content
• [ ] Focus states visible (:focus-visible)
• [ ] Color is not the sole indicator of state

Production:

• [ ] color-scheme: dark set on <html> (if dark theme)
• [ ] <meta name="theme-color"> matches page background
• [ ] env(safe-area-inset-*) on full-bleed hero
• [ ] z-index uses defined scale, no random values
• [ ] Body text max-width ~65ch
• [ ] No emoji icons (SVG only)
• [ ] Total initial page weight under 3MB
• [ ] Responsive at 375px, 768px, 1024px, 1440px

---

When to Use

Use this skill when:

• Building landing pages, marketing sites, product pages, or portfolio sites
• The user has AI-generated images, videos, 3D renders, or plans to create them
• The user wants a design that stands out from typical text+icon layouts
• The brief emphasizes visual impact, emotion, or brand storytelling
• The request involves scroll-driven storytelling or immersive visual experiences
• The request mentions anything related to editorial, cinematic, or premium design

Do not use this skill for:

• Admin dashboards, data-heavy interfaces, or internal tools
• Documentation sites or text-primary content
• E-commerce product listing grids or form-heavy applications
• Quick prototypes where visual polish isn't the goal

Changelog

All notable changes to the creative-first-ui skill.

---

[0.15.0] - 2026-04-04

Added

• Git repo packaging — structured for npx skills add distribution as multi-skill repo
• Root README.md with install instructions
• .gitignore (excludes test assets, OS files, node_modules)
• Updated creative-first-ui README with npx install command

[0.14.0] - 2026-04-04

Added

• `references/astro.md` — Astro integration guide: GSAP/Lenis setup with astro:page-load/astro:before-swap lifecycle, R3F with client:only="react", island loading strategies table, View Transitions (shared elements, persist, custom animations), image optimization (<Image>/<Picture>), content collections schema for portfolios, 7 gotchas

[0.13.0] - 2026-04-04

Added

• Pattern 12 snippet: Horizontal Scroll — GSAP pin + horizontal translate, progress dots, mobile/reduced-motion fallback to vertical stack
• Pattern 13 snippet: Split-Screen Reveal — two panels slide apart to reveal center content, simultaneous GSAP tweens, before/after labels, mobile fallback
• Pattern 14 snippet: Text Masking — background-clip: text with scroll-driven background movement, high-contrast fallback, video-filled text variant with SVG clipPath

[0.12.0] - 2026-04-04

Added (Marketing CRO alignment)

• Section 10: Conversion & Persuasion — new section covering CTA design, trust signals, copy rules for minimal-text pages, visual psychology principles, 5-second rule
• CTA design rules: value-driven copy, high contrast, above fold, 48-56px, frosted glass/solid on dark backgrounds
• Trust signals: customer logos, testimonials with photos, stats/numbers, social proof badges, placement near CTAs
• Copy rules: clarity over cleverness, specificity, benefits over features, one idea per section, headline word budgets
• Visual psychology: anchoring, contrast effect, peak-end rule, loss aversion, goal gradient, mere exposure
• Total sections: 18 → 19

[0.11.0] - 2026-04-04

Added (UI/UX Pro Max alignment)

• Theme-specific contrast rules — explicit minimum values for dark and light mode text, muted text, glass panels, borders (Section 12)
• `cursor: pointer` rule — all clickable elements need cursor feedback (Section 13)
• `max-width: 65ch` — line length limit for body text readability (Section 13)
• z-index scale — defined variable scale (base, above, nav, overlay, cursor) instead of random values (Section 13)
• No emoji icons rule — SVG only (Heroicons, Lucide, Phosphor) (Section 13)
• Pre-delivery checklist — 25-item checkbox list in Section 18: visuals, interactions, accessibility, production (Section 18)

[0.10.0] - 2026-04-04

Added

• inference.sh CLI integration — Claude can now generate images AND videos directly via infsh CLI (Section 5)
• infsh image models — Seedream 4.5, ImagineArt 1.5 Pro, FLUX Dev LoRA, Grok Imagine, Topaz Upscaler with example commands
• infsh video models — Veo 3.1 (best quality), Grok Video (configurable duration), Seedance 1.5 Pro (first-frame control), Wan 2.5 (image-to-video), Topaz Video Upscaler, Foley sound effects
• 4-option user choice flow — Section 2 now presents: have assets / generate via infsh / generate externally (pick tool) / can't generate
• infsh commands in ideation output — Section 2a outputs now include ready-to-run infsh commands alongside generic prompts
• Full infsh workflow — fast image → pick direction → high-quality image → animate to video → upscale → add sound → build

[0.9.0] - 2026-04-04

Added (Vercel Web Interface Guidelines alignment)

• Animation performance rules — only animate transform/opacity, never transition:all, interruptible animations (Section 13)
• CSS production details — text-wrap: balance, font-variant-numeric: tabular-nums, touch-action: manipulation, overscroll-behavior: contain, env(safe-area-inset-*) for notch/dynamic island, color-scheme: dark, theme-color meta, curly quotes, font preloading (Section 13)
• Focus state rules — :focus-visible over :focus, never outline:none without replacement, semantic elements over div+onClick (Section 14)
• Code anti-patterns — transition:all, outline:none, div onClick, missing dimensions, missing aria-label, animating layout properties, disabling zoom (Section 15)

[0.8.0] - 2026-04-04

Added

• Section 2a: Creative Ideation — visual metaphor generation, concept pairing (combining unexpected aesthetics), hero concept generator (3-5 concepts safe→bold), anti-obvious check, mood definition grid (energy × temperature), "what if" prompts for pushing past safe concepts
• First question rule — skill now instructs Claude to always ask if user can generate AI assets before building. Three response paths based on answer (have assets / can generate / can't generate)
• Visual metaphor table — maps product functions to visual concepts (7 examples)
• Concept pairing table — 6 aesthetic combinations that create distinctive visuals
• Mood definition axes — 2D grid (energetic↔calm, warm↔cool) that determines color, font, and motion choices

[0.7.0] - 2026-04-04

Added

• `references/react-nextjs.md` — React/Next.js integration: GSAP useGSAP hook, ScrollTrigger cleanup, next/image for hero backgrounds, R3F with dynamic import, View Transitions, Motion/Framer Motion scroll hooks, common mistakes
• `references/asset-pipeline.md` — end-to-end asset optimization: image (WebP/AVIF/Sharp), video (FFmpeg cheat sheet with 8 commands), 3D (gltf-transform Draco), file size targets table, HTML integration patterns, install commands
• Patterns 12-14 — horizontal scroll, split-screen reveal, text masking (SKILL.md Section 4)
• README.md — install instructions, usage guide, file structure, workflow overview
• LICENSE — MIT

Changed

• Pattern count: 11 → 14
• Supporting files list updated in SKILL.md intro (now 5 reference files)

[0.6.0] - 2026-04-04

Added

• `references/industries.md` — design direction for 13 industries: automotive, consumer tech, SaaS, fashion, health & wellness, health & food tracking, architecture, food & beverage, travel, gaming, finance, education, creative agency. Each includes hero strategy, color direction, typography mood, recommended patterns, AI hero prompt templates, and reference sites
• Linked industries.md from SKILL.md supporting files

[0.5.0] - 2026-04-04

Added (2025-2026 Creative Web Trends)

• Section 11: Advanced Visual Techniques — new section covering shaders, noise/grain textures, View Transitions API, Rive animations, sound design
• CSS scroll-driven animations — animation-timeline: scroll()/view() as primary choice for simple patterns, with decision guide vs GSAP (Section 4)
• WebGPU — updated 3D pattern with WebGPU renderer (default in Three.js r171+), Spline for no-code 3D (Section 4)
• Kinetic typography — split text, variable font morphing, gradient text, clip-path reveals, image-filled text (Section 6)
• Magnetic/fluid cursor effects — magnetic snap, cursor morphing, cursor zones, liquid blob, particle trails (Section 7)
• Bento grid layout — modular varying-size cards on CSS Grid with visual-first rules (Section 8)
• Shader effects — Shaders.com component library, Three.js EffectComposer, custom GLSL/WGSL (Section 11)
• Noise & grain — SVG feTurbulence technique with CSS, usage rules (Section 11)
• View Transitions API — GPU-accelerated page/state morphs, cross-document transitions (Section 11)
• Rive vs Lottie — comparison table, when to use each (Section 11)
• Sound design — opt-in audio for immersive sites, rules, tools (Section 11)

Changed

• Total sections: 17 → 18
• Scroll stack guidance expanded: CSS-first for simple, GSAP for complex
• 3D pattern updated for WebGPU era

[0.4.0] - 2026-04-04

Added (Apple HIG Alignment)

• Semantic color tokens — --label, --label-secondary, --surface, --separator, --overlay system (Section 11)
• High contrast support — prefers-contrast: more media query with token overrides (Section 11 + Section 13)
• 8px spacing system — base unit grid for consistent spacing (Section 8)
• 44px touch targets — minimum tap area requirement for all interactive elements (Section 8)
• Minimum text sizes — 16px body, 12px labels floor (Section 8)
• Loading states hierarchy — skeleton → LQIP → progress → poster, aligned with HIG loading guidance (Section 12)
• Color-not-sole-indicator rule — pair color with icons/labels/patterns (Section 13)
• Gradient text high-contrast fallback note (Section 13)

[0.3.0] - 2026-04-04

Added

• Section 3: Hero Design — dedicated hero section with layout rules, enhancements (ticker, particles, parallax, entrance animation), and hero-specific anti-patterns
• Section 15: Iteration Workflow — generate-build-review-fix loop, feedback guidelines, per-section iteration budgets
• Hero code snippets: full-bleed AI background with surgical gradient overlay, stats ticker, floating particles (canvas)
• Hero examples in references: Apple Vision Pro, Tesla, Stripe, Nothing, Linear, Canopy, Vercel, Framer

Changed

• Section numbering shifted (3→4 for Visual Patterns, all subsequent sections +1)
• Total sections: 15 → 17

[0.2.0] - 2026-04-04

Added

• Section 7: Interaction & Hover Patterns — hover on images, videos, 3D, custom cursors
• Section 9: Page Rhythm & Visual Pacing — intensity curve, 3-act structure, section transitions
• Section 10: Pattern Combinations — compatible/incompatible pattern pairs, one-hero rule
• Section 11: Color & Theming — merged Color Strategy + Dark/Light Mode, added extraction tools (Coolors, Adobe Color)
• Section 13: Accessibility — reduced motion, screen readers, keyboard nav, contrast, fallbacks
• Tool comparison tables (Midjourney vs Flux vs Gemini, Kling vs Runway vs Pika)
• Font pairing examples by mood (6 moods with specific font names)
• iOS/Safari gotchas (video autoplay, scroll, WebGL)
• Retina/2x generation guidance
• Story beats explanation (Setup → Build → Turn → Payoff)
• Bandwidth/progressive enhancement (Save-Data detection, media-scoped preloads)
• Expanded anti-patterns (layout, scroll/animation, asset categories)
• Expanded taste test (5 visual + 5 technical quality checks)

Changed

• Unified pattern numbering: Patterns 1-11 (was 1-5 + A-F)
• Merged Sections 3+4 into single "Visual Patterns" section
• AI Generation section expanded with prompt engineering tips and common mistakes
• Output Structure tightened, references earlier sections
• "When to Use" expanded with scroll-driven storytelling, excludes e-commerce grids

Fixed

• Reference files linked from SKILL.md intro (were orphaned)
• Pattern naming made consistent across all 3 files
• Section numbering — no more duplicates
• Lenis mentioned in SKILL.md (snippets depended on it silently)
• React/Next.js guidance note added to snippets intro

[0.1.0] - 2026-04-04

Added

• Initial skill creation
• Core philosophy: visual-first design, the inversion (visual → layout → text)
• 11 visual patterns (5 static + 6 scroll-driven)
• AI asset generation guidance (images, video, 3D)
• Typography rules
• Layout philosophy
• Color strategy
• Performance section
• Anti-patterns
• Output structure
• Taste test (5 questions)
• references/examples.md — real sites by pattern (11 patterns) and by industry (10 industries)
• references/snippets.md — code for all 11 patterns + 4 utilities + GSAP/Lenis foundation
• Test page (test/index.html)

Engineering Docs

Internal documentation for developing and maintaining the creative-first-ui skill.

---

File Structure

creative-first-ui/
├── SKILL.md                       # Main skill file (1000+ lines, 18 sections)
├── references/
│   ├── examples.md                # Real-world site examples by pattern and industry
│   ├── snippets.md                # Ready-to-use code for all patterns
│   ├── industries.md              # Design direction per industry (13 industries)
│   ├── react-nextjs.md            # React/Next.js integration guide
│   ├── astro.md                   # Astro integration guide
│   └── asset-pipeline.md          # Image/video/3D optimization commands
├── test/
│   ├── index.html                 # Test page — headphones landing page
│   └── hero.png                   # AI-generated hero image (ChatGPT)
├── README.md                      # Install and usage guide
├── LICENSE                        # MIT
├── CHANGELOG.md                   # Version history
├── ROADMAP.md                     # Planned features
└── ENGINEERING.md                 # This file

How the Skill Works

The AI agent reads SKILL.md when the skill is invoked. The file contains:

• Design philosophy and principles (what to do, what to avoid)
• 11 visual patterns with implementation specs
• Supporting guidance (typography, color, performance, accessibility)
• Output structure (what Claude should deliver)

references/ files are loaded on demand when Claude needs code examples or real-world references. They're kept separate to avoid bloating the main skill file.

Section Architecture (SKILL.md)

Design Decisions

Why one SKILL.md instead of splitting?

The agent loads the entire SKILL.md into context. Splitting into multiple skill files would require the user to invoke multiple skills. A single file with references/ for deep dives keeps it simple.

Why unified pattern numbering (1-11)?

Originally used 1-5 for static patterns and A-F for scroll-driven. Review found this confused cross-referencing between SKILL.md, examples.md, and snippets.md. Unified numbering (1-11) makes all three files reference each other cleanly.

Why GSAP + Lenis as the default stack?

• GSAP ScrollTrigger is the most used scroll animation library in Awwwards-winning sites
• Lenis replaced Locomotive Scroll as the modern smooth scroll standard
• Both work with vanilla JS and React
• CSS animation-timeline: scroll() is mentioned as a lighter alternative but browser support is still limited

Why no Tailwind in snippets?

The snippets use vanilla CSS because:

• The skill should work regardless of the user's CSS framework
• Tailwind class strings would be harder to read and modify
• Custom properties (var(--accent)) are more flexible than Tailwind tokens for visual-first design where colors are extracted from images

Why separate hero section?

Testing revealed that even with the full skill active, Claude defaulted to stock-photo-with-centered-text heroes. A dedicated section with explicit anti-patterns and layout rules was needed to break that default behavior.

Testing

How to test changes

1. Read through the full SKILL.md to check for contradictions between sections 2. Open a fresh session in your AI coding agent 3. Tell the agent to use the skill: "Use the creative-first-ui skill to build a landing page for [product]" 4. Evaluate the output against the Taste Test (Section 17) 5. Check that the hero follows Section 3 rules (not stock photo, not centered text) 6. Check that scroll patterns use GSAP + Lenis (not random JS) 7. Check reduced motion handling exists 8. Check mobile layout doesn't collapse to text+icon

Test matrix

Known limitations

• Image generation depends on tooling — the skill can generate via inference.sh CLI if installed, otherwise the user must create assets externally with Midjourney/DALL-E/Kling
• Video patterns need real video files — can't be tested with placeholder images. Test page uses static images as stand-ins
• 3D patterns need GLB/GLTF models — can't be tested without real assets
• The skill is only as good as the visual assets — a mediocre AI-generated image will produce a mediocre hero no matter how good the code is

Maintenance

When to update

• After testing reveals a gap (new anti-pattern, missing guidance)
• When new AI tools emerge (new image/video generators worth recommending)
• When browser APIs change (CSS scroll-timeline gaining Safari support)
• When GSAP/Lenis have breaking changes

How to update

1. Edit the relevant section in SKILL.md 2. Update corresponding entries in examples.md and/or snippets.md 3. Keep pattern numbering consistent across all 3 files 4. Add entry to CHANGELOG.md 5. Update ROADMAP.md if a planned item is completed 6. Run through the test matrix

creative-first-ui

An AI agent skill for building visual-first, scroll-driven websites where AI-generated imagery, video, and 3D assets ARE the design — not decoration. Works with Claude Code, Cursor, Codex, Copilot, Antigravity, and other AI coding agents.

The Problem

AI coding agents default to text+icon layouts: headings, paragraphs, card grids, stock photos. The output looks like a template regardless of the prompt. Meanwhile, award-winning sites use AI-generated visuals, scroll-driven animations, and custom 3D assets as the primary design element.

The Solution

This skill inverts the design hierarchy:

Traditional:  Text → Icons → Layout → Maybe an image
This skill:   Visual Asset → Layout shaped by asset → Minimal text

What It Covers

• 18 sections of design philosophy, patterns, and technical guidance
• 14 visual patterns — from full-bleed video backgrounds to scroll-driven frame sequences, clip-path reveals, horizontal scroll, and text masking
• Hero design rules — custom AI-generated visuals, surgical gradient overlays, stats tickers, entrance animations
• AI asset generation — tool comparison (Midjourney vs Flux vs Kling vs Runway), prompt templates, retina/2x guidance
• Scroll-driven storytelling — CSS scroll-timeline (preferred for simple), GSAP + Lenis (for complex)
• Advanced techniques — shader effects, noise/grain textures, View Transitions API, Rive animations, sound design
• Industry-specific design direction — 13 industries with hero strategy, color, typography, patterns, and AI prompt templates
• Performance — file size targets, iOS gotchas, loading states, bandwidth detection
• Accessibility — reduced motion, high contrast, screen readers, keyboard nav, 44px touch targets
• Iteration workflow — the generate → build → review → fix loop that actually produces quality
• Apple HIG alignment — semantic color tokens, 8px spacing grid, touch targets, loading hierarchy

Install

Via npx (recommended):

npx skills add https://github.com/yasserstudio/creative-first-ui

Manual (copy or symlink):

cp -r creative-first-ui ~/.claude/skills/
# or
ln -s /path/to/creative-first-ui ~/.claude/skills/creative-first-ui

Usage

Tell your AI agent to use the skill:

Use the creative-first-ui skill to build a landing page for [your product].
The hero should use this image: [path to AI-generated image]

Or reference it by name if installed globally:

Use creative-first-ui to design a health & food tracking app landing page.

File Structure

creative-first-ui/
├── SKILL.md                       # Main skill (1000+ lines, 18 sections)
├── references/
│   ├── examples.md                # Award-winning site references by pattern & industry
│   ├── snippets.md                # Ready-to-use code for all patterns
│   ├── industries.md              # Design direction for 13 industries
│   ├── react-nextjs.md            # React/Next.js integration guide
│   └── asset-pipeline.md          # Image/video/3D optimization commands
├── test/
│   ├── index.html                 # Test page
│   └── hero.png                   # AI-generated test hero
├── CHANGELOG.md
├── ROADMAP.md
├── ENGINEERING.md
└── README.md

The Workflow

1. Decide the visual — what AI-generated image/video/3D will be the hero? 2. Generate the asset — use Midjourney, Flux, Kling 3.0, or NanoBanana. See references/industries.md for industry-specific prompts 3. Tell Claude to build around it — reference the skill and the asset 4. Iterate — screenshot, identify issues, tell Claude specifically what to fix. Repeat 3-5 times for the hero 5. Optimize — compress assets per references/asset-pipeline.md

Requirements

• AI coding agent (Claude Code, Cursor, Codex, Copilot, etc.)
• AI image/video generation tool (Midjourney, Flux, Kling 3.0, or similar)
• For scroll animations: GSAP + Lenis (free) or CSS scroll-driven animations
• For 3D: Three.js / React Three Fiber (optional)

License

MIT

Asset Pipeline Reference

End-to-end guide for AI asset generation, optimization, and integration.

---

Quick Install

# FFmpeg (video processing)
brew install ffmpeg

# WebP tools
brew install webp

# AVIF tools
brew install libavif

# Sharp CLI (image batch processing)
npm i -g sharp-cli

# glTF-Transform (3D model optimization)
npm i -g @gltf-transform/cli

---

1. Image Pipeline

Generate at 2x Resolution

Always generate at 2x the target viewport. For a 1920px viewport, generate at 3840px.

Convert to WebP

cwebp -q 85 input.png -o output.webp

Convert to AVIF

avifenc input.png output.avif --min 20 --max 35

Batch Convert with Sharp CLI

npx sharp-cli --input "*.png" --output ./optimized/ --format webp --quality 85

Generate Responsive Sizes

Target breakpoints: 640, 1024, 1440, 1920, 3840

for size in 640 1024 1440 1920 3840; do
  npx sharp-cli --input hero.png --output hero-${size}.webp --resize $size --format webp --quality 85
done

LQIP (Low-Quality Image Placeholder)

Generate a tiny placeholder:

npx sharp-cli --input hero.png --output hero-lqip.webp --resize 20 --quality 20

Base64 encode for inline use:

base64 < hero-lqip.webp

---

2. Video Pipeline (FFmpeg Cheat Sheet)

Rule: Add -movflags +faststart to ALL web videos. This moves the moov atom to the beginning for faster playback start.

Compress for Web

ffmpeg -i input.mp4 -crf 28 -preset slow -vf scale=1920:-1 -movflags +faststart output.mp4

Extract Poster Frame

ffmpeg -i input.mp4 -vframes 1 -q:v 2 poster.webp

Extract Frames for Scroll Sequence

ffmpeg -i input.mp4 -vf "fps=30,scale=1920:-1" -q:v 2 frames/frame-%04d.webp

Convert to WebM

ffmpeg -i input.mp4 -c:v libvpx-vp9 -crf 30 -b:v 0 output.webm

Trim Video

ffmpeg -i input.mp4 -ss 00:00:02 -to 00:00:07 -c copy trimmed.mp4

Loop a Video

ffmpeg -stream_loop 3 -i input.mp4 -c copy looped.mp4

Resize

ffmpeg -i input.mp4 -vf scale=1280:-1 output.mp4

Remove Audio

ffmpeg -i input.mp4 -an -c:v copy silent.mp4

---

3. 3D Model Pipeline

Targets: <5MB file size, <100K polygons, textures <=1024px

Compress GLB with Draco

npx @gltf-transform/cli optimize input.glb output.glb --compress draco

Inspect Model

npx @gltf-transform/cli inspect input.glb

Reduce Textures

npx @gltf-transform/cli resize input.glb output.glb --width 1024 --height 1024

---

4. File Size Targets

---

5. HTML Integration Patterns

Responsive Image with srcset

<img
  src="hero-1920.webp"
  srcset="
    hero-640.webp 640w,
    hero-1024.webp 1024w,
    hero-1440.webp 1440w,
    hero-1920.webp 1920w,
    hero-3840.webp 3840w
  "
  sizes="100vw"
  alt="Hero image"
  loading="lazy"
  decoding="async"
/>

Picture Element with WebP/AVIF/Fallback

<picture>
  <source srcset="hero.avif" type="image/avif" />
  <source srcset="hero.webp" type="image/webp" />
  <img src="hero.jpg" alt="Hero image" />
</picture>

Preload Hero in Head

<head>
  <link rel="preload" as="image" href="hero.avif" type="image/avif" />
  <link rel="preload" as="image" href="hero.webp" type="image/webp" />
</head>

Lazy Loading with IntersectionObserver

const observer = new IntersectionObserver((entries) => {
  entries.forEach((entry) => {
    if (entry.isIntersecting) {
      const img = entry.target;
      img.src = img.dataset.src;
      if (img.dataset.srcset) img.srcset = img.dataset.srcset;
      observer.unobserve(img);
    }
  });
}, { rootMargin: '200px' });

document.querySelectorAll('img[data-src]').forEach((img) => {
  observer.observe(img);
});

LQIP Inline Pattern

<img
  src="data:image/webp;base64,YOUR_BASE64_STRING"
  data-src="hero-1920.webp"
  data-srcset="hero-640.webp 640w, hero-1920.webp 1920w, hero-3840.webp 3840w"
  sizes="100vw"
  alt="Hero image"
  class="lqip"
/>

.lqip {
  filter: blur(20px);
  transition: filter 0.3s;
}
.lqip.loaded {
  filter: blur(0);
}

Astro Integration Guide

Astro is ideal for creative-first sites: zero JS by default means the browser focuses entirely on loading visual assets, not framework runtime. Interactive elements (GSAP, Three.js, Lenis) load as islands only when needed.

---

Why Astro for Visual-First Sites

• Zero JS by default — static HTML/CSS renders instantly. No React runtime competing with your 2MB hero image for bandwidth
• Island hydration — Three.js, GSAP, and heavy components load only when visible or idle
• Built-in View Transitions — cinematic page transitions via native browser API
• Built-in image optimization — WebP/AVIF at build time, no runtime cost
• Static output — deploy to any CDN, sub-50ms edge response times

---

GSAP + Lenis Setup

GSAP and Lenis are vanilla JS — use <script> tags, not islands. Critical: use astro:page-load instead of DOMContentLoaded (which only fires once with View Transitions).

---
// src/layouts/BaseLayout.astro
import { ViewTransitions } from 'astro:transitions';
---
<html>
  <head>
    <ViewTransitions />
  </head>
  <body>
    <slot />

    <script>
      import { gsap } from 'gsap';
      import { ScrollTrigger } from 'gsap/ScrollTrigger';
      import Lenis from 'lenis';

      gsap.registerPlugin(ScrollTrigger);

      let lenis: Lenis | null = null;

      // Runs on EVERY page load (initial + navigations)
      document.addEventListener('astro:page-load', () => {
        // Smooth scroll
        lenis = new Lenis({ lerp: 0.1, smoothWheel: true });
        lenis.on('scroll', ScrollTrigger.update);
        gsap.ticker.add((time) => lenis?.raf(time * 1000));
        gsap.ticker.lagSmoothing(0);

        // Refresh ScrollTrigger for new DOM
        ScrollTrigger.refresh();
      });

      // Cleanup BEFORE page swap (critical — prevents memory leaks)
      document.addEventListener('astro:before-swap', () => {
        ScrollTrigger.getAll().forEach((st) => st.kill());
        gsap.killTweensOf('*');
        lenis?.destroy();
        lenis = null;
      });
    </script>
  </body>
</html>

Scroll Animations in Components

---
// src/components/RevealSection.astro
---
<section class="reveal-section">
  <h2 class="reveal-text">Headline</h2>
  <p class="reveal-text">Supporting text.</p>
</section>

<script>
  import { gsap } from 'gsap';
  import { ScrollTrigger } from 'gsap/ScrollTrigger';

  gsap.registerPlugin(ScrollTrigger);

  document.addEventListener('astro:page-load', () => {
    gsap.utils.toArray('.reveal-text').forEach((el) => {
      gsap.from(el as HTMLElement, {
        y: 50,
        opacity: 0,
        duration: 0.8,
        ease: 'power2.out',
        scrollTrigger: {
          trigger: el as HTMLElement,
          start: 'top 85%',
          toggleActions: 'play none none none',
        },
      });
    });
  });
</script>

---

React Three Fiber (R3F)

R3F cannot be server-rendered. Always use client:only="react".

npx astro add react
npm install three @react-three/fiber @react-three/drei

---
// src/pages/index.astro
import HeroScene from '../components/HeroScene.tsx';
---

<!-- Placeholder shows instantly while R3F loads -->
<div class="hero-3d" style="height: 100vh; background: #06060f;">
  <HeroScene client:only="react" />
</div>

// src/components/HeroScene.tsx
import { Canvas } from '@react-three/fiber';
import { Environment, useGLTF } from '@react-three/drei';
import { Suspense } from 'react';

function Model() {
  const { scene } = useGLTF('/models/product.glb');
  return <primitive object={scene} scale={1.5} />;
}

export default function HeroScene() {
  return (
    <Canvas camera={{ position: [0, 0, 5], fov: 45 }} dpr={[1, 2]}>
      <Suspense fallback={null}>
        <Model />
        <Environment preset="studio" />
      </Suspense>
    </Canvas>
  );
}

Persist the canvas across page navigations:

<HeroScene client:only="react" transition:persist />

---

Island Loading Strategies

Use the right directive for each component's role:

Typical creative site layout:

<!-- 0 KB JS — pure HTML -->
<Navigation />

<!-- ~30 KB — GSAP via <script> tag, runs immediately -->
<HeroSection />

<!-- ~200 KB — loads only when scrolled into view -->
<ThreeShowcase client:visible />

<!-- 0 KB JS — pure HTML + CSS -->
<EditorialSection />

<!-- ~15 KB — loads when browser is idle -->
<ContactForm client:idle />

<!-- 0 KB JS -->
<Footer />

---

View Transitions

Built-in cinematic page transitions. Add <ViewTransitions /> to your layout head.

Shared Element Transitions

<!-- Portfolio grid page -->
<a href={`/work/${project.slug}`}>
  <Image
    src={project.data.thumbnail}
    alt={project.data.title}
    transition:name={`hero-${project.slug}`}
  />
  <h3 transition:name={`title-${project.slug}`}>{project.data.title}</h3>
</a>

<!-- Project detail page -->
<Image
  src={entry.data.heroImage}
  alt={entry.data.title}
  transition:name={`hero-${entry.slug}`}
/>
<h1 transition:name={`title-${entry.slug}`}>{entry.data.title}</h1>

The image morphs from thumbnail to full-bleed hero on navigation. The title animates to its new position. No JS needed.

Persist Elements Across Pages

<!-- Background video survives page transitions -->
<video transition:persist autoplay muted loop playsinline>
  <source src="/bg.mp4" type="video/mp4" />
</video>

<!-- WebGL canvas survives page transitions -->
<BackgroundScene client:only="react" transition:persist />

Custom Animations

<div transition:animate={{
  old: { name: 'slideOut', duration: '0.3s', easing: 'ease-in' },
  new: { name: 'slideIn', duration: '0.4s', easing: 'ease-out', delay: '0.1s' },
}}>
  Content
</div>

---

Image Optimization

---
import { Image, Picture } from 'astro:assets';
import heroImg from '../assets/hero.jpg';
---

<!-- Hero — optimized, priority loaded -->
<Image
  src={heroImg}
  alt="Hero visual"
  width={1920}
  height={1080}
  format="webp"
  quality={85}
  loading="eager"
  fetchpriority="high"
/>

<!-- Below-fold — multiple formats + responsive sizes -->
<Picture
  src={heroImg}
  formats={['avif', 'webp']}
  widths={[640, 1024, 1440, 1920]}
  sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 1200px"
  alt="Editorial image"
/>

Key rules:

• Images must be imported from src/assets/ — public/ images bypass optimization
• Astro outputs pure <img>/<picture> tags — zero JS for image loading
• Use loading="eager" + fetchpriority="high" for hero images
• Default loading="lazy" for everything else (browser-native, no JS)
• No built-in blur placeholder like Next.js — generate LQIP manually (see asset-pipeline.md)

---

Content Collections for Portfolios

Type-safe content with co-located images:

// src/content/config.ts
import { z, defineCollection } from 'astro:content';

const projects = defineCollection({
  type: 'content',
  schema: ({ image }) => z.object({
    title: z.string(),
    heroImage: image(),
    thumbnail: image(),
    colorPalette: z.object({
      primary: z.string(),
      accent: z.string(),
      background: z.string(),
    }),
    category: z.enum(['branding', 'web', 'motion']),
    featured: z.boolean().default(false),
  }),
});

export const collections = { projects };

src/content/projects/
  project-alpha/
    index.md
    hero.jpg        ← co-located, validated at build time
    thumbnail.jpg

---
title: "Project Alpha"
heroImage: ./hero.jpg
thumbnail: ./thumbnail.jpg
colorPalette:
  primary: "#1a1a2e"
  accent: "#e94560"
  background: "#0f0f0f"
category: branding
featured: true
---

---

Gotchas

Never use DOMContentLoaded

It fires only once with View Transitions. Always use astro:page-load.

GSAP/Lenis cleanup is mandatory

Without cleanup in astro:before-swap, you get duplicate scroll listeners, phantom animations, and memory leaks on every navigation.

client:load vs client:only for canvas

• client:load → SSR + hydrate. Breaks with Three.js/R3F/Pixi (no server canvas)
• client:only="react" → skip SSR entirely. Required for any canvas-based component

Script deduplication

Astro deduplicates <script> tags across pages. If the same script exists on old and new page, it won't re-run. That's why astro:page-load event listener is the pattern — the listener persists, the callback fires on each navigation.

Image paths in frontmatter

• ./hero.jpg → relative path, goes through optimization pipeline
• /hero.jpg → absolute path, serves from public/, no optimization

CSS view-transition-name conflicts

Use transition:name in templates, not manual view-transition-name in CSS. They can conflict.

Hydration order

client:visible islands hydrate based on scroll position, not DOM order. Don't assume one island initializes before another.

Reference Examples

Real sites that demonstrate each pattern from SKILL.md. Study these for execution quality, not to copy.

---

Hero Design (SKILL.md Section 3)

Sites with exceptional hero sections — custom visuals, not stock photos, with text that serves the image.

Full-Bleed Custom Visual Heroes

Heroes with Stats Tickers

What Makes These Heroes Work

1. The visual is custom — AI-generated, 3D-rendered, or uniquely designed. Not interchangeable with competitors 2. Text is minimal and positioned carefully — never plastered over the busy center of the image 3. The hero tells you what the product is — without reading a single word, you know what this company does 4. Gradient overlays are surgical — dark where text lives, transparent where the visual matters 5. Stats/trust signals live at the bottom — scrolling tickers or logo bars add credibility without visual cost

---

Visual Patterns (SKILL.md Section 4)

Pattern numbers match SKILL.md Section 4.

Pattern 1: Full-Bleed Video Background

Pattern 2: 3D Object as Hero

Pattern 3: Editorial Image Layout

Pattern 4: Exploded View

Pattern 5: Scroll-Driven Frame Sequence

Pattern 6: Visual Crossfade

Pattern 7: Clip-Path Reveal

Pattern 8: Visual Story Sequence

Pattern 9: Parallax Layer Swap

Pattern 10: Morphing Visual

Pattern 11: Video Scrubbing

---

By Industry / Niche

Automotive

Consumer Tech / Electronics

Fashion & Luxury

Architecture & Interior Design

Food & Beverage

Travel & Hospitality

Gaming & Entertainment

Health & Wellness

Health & Food Tracking

Creative Agencies (study their craft)

SaaS / Software (the ones that break the mold)

---

Technical Libraries

---

How to Study These

1. Don't just look — scroll slowly through each site and notice when visuals change, how text appears, what triggers transitions 2. Inspect the technique — open DevTools, watch the DOM as you scroll, see what's changing (opacity, transform, clip-path, canvas draws) 3. Screenshot key moments — capture the exact scroll positions where transitions happen 4. Note what's NOT there — these sites succeed by what they leave out (icon grids, card layouts, text walls) 5. Check mobile — see how they handle the same visual story on a phone

Roadmap

What's planned for creative-first-ui.

---

Next (v0.8)

Testing with real assets

• [ ] Build 3 test pages across different industries (health/food tracking, SaaS, luxury fashion)
• [ ] Test with Midjourney/Flux-generated assets instead of ChatGPT
• [ ] Test with Kling 3.0 video assets — validate video background and scroll-driven frame sequence patterns
• [ ] Mobile-specific test — verify all patterns degrade gracefully at 375px
• [ ] Tune gradient overlay values based on real testing

Remaining references

• [x] Add references/astro.md — view transitions, island architecture with scroll-driven patterns
• [x] Code snippets for Patterns 12-14 (horizontal scroll, split-screen, text masking)

Skill refinements

• [ ] Add more hero layout variants (text-left, text-right, text-bottom, split-screen)
• [ ] Add section on choosing the right hero layout based on image composition
• [ ] Scroll-driven color theme transitions (palette shifts as you scroll between sections)
• [ ] Component library patterns that maintain visual-first principles in reusable components

v1.0 — Public Release

Publishing

• [x] README.md with install instructions and philosophy summary
• [x] License (MIT)
• [x] Package for npx skills add distribution
• [ ] Gallery of example sites built with the skill
• [ ] Contributing guide
• [ ] Before/after screenshots showing skill vs default Claude output

Quality bar for release

• [ ] 3+ real sites built with the skill that look genuinely impressive
• [ ] All patterns tested on Chrome, Safari, Firefox, mobile Safari, mobile Chrome
• [ ] Performance benchmarks — all test pages under 3MB initial load, LCP under 2s
• [ ] Accessibility audit — all test pages pass WCAG AA

---

Completed

v0.7 (current)

• [x] references/react-nextjs.md — GSAP hooks, ScrollTrigger, next/image, R3F, View Transitions, Motion
• [x] references/asset-pipeline.md — image/video/3D optimization, FFmpeg cheat sheet, Sharp CLI
• [x] Patterns 12-14 (horizontal scroll, split-screen reveal, text masking)
• [x] README.md and LICENSE

v0.6

• [x] references/industries.md — 13 industries with full design direction

v0.5

• [x] CSS scroll-driven animations with decision guide vs GSAP
• [x] Advanced visual techniques section (shaders, noise, View Transitions, Rive, sound)
• [x] Kinetic typography, magnetic cursors, bento grids, WebGPU

v0.4

• [x] Apple HIG alignment (semantic tokens, spacing system, touch targets, loading states, high contrast)

v0.3

• [x] Hero Design section, Iteration Workflow section

v0.2

• [x] Interactions, page rhythm, pattern combinations, color & theming, accessibility, expanded anti-patterns

v0.1

• [x] Initial skill: 11 patterns, AI generation guidance, typography, layout, performance

---

Ideas (unscheduled)

• Video tutorial walking through the workflow (generate → build → iterate)
• Figma/design tool integration — how to use the skill alongside Figma workflows
• AI prompt library — curated prompts per industry for hero/section visuals
• Companion MCP server that auto-extracts colors from uploaded images
• Integration with specific AI image APIs (Midjourney via API, Replicate for Flux)
• Multi-page site patterns — how visual-first principles extend beyond single landing pages
• E-commerce product pages — adapting visual-first for pages that need to convert with detailed info