---
name: enhance-web-web3d
description: >
  Audit-first skill for elevating an existing website or web app with 3D and
  cinematic motion — Three.js / React Three Fiber for the scene, GSAP
  ScrollTrigger for scroll-driven choreography, and Motion / React Spring for
  UI and physics. Works with any web stack (Next.js, Vite, Astro, Remix,
  vanilla) and any styling system. Use when the user asks to "add 3D", "add a
  WebGL hero", "make it cinematic", "scroll-driven 3D", "three.js scene",
  "React Three Fiber", "GSAP scroll animation", "product configurator", "make
  the landing page feel immersive", "add a 3D model viewer", "parallax /
  pinned scroll storytelling", or wants to add a "wow factor" / hero effect to
  a real, existing repo. Scans the codebase, picks the right library
  combination, and ships the effect with performance budgets, mobile + no-WebGL
  fallbacks, reduced-motion support, and SSR/hydration safety baked in — no
  rewrites, no broken builds, no janky scroll.
license: MIT
---

> ### Which enhance skill? (surface router)
>
> | Your surface | Use |
> |:-------------|:----|
> | **Web** product page / dashboard — composition, hierarchy, spacing, motion | `enhance-web-ui` |
> | **Web** product page — UX heuristics, flows, data wiring | `enhance-web-ux` |
> | **Web** landing / marketing / portfolio (greenfield, anti-slop) | `enhance-web-landing` |
> | **Web** existing site upgrade (audit-first, preserve behavior) | `enhance-web-redesign` |
> | **Web** 3D / WebGL / cinematic scroll on an existing site (audit-first) | `enhance-web-web3d` |
> | **React Native** screen (Expo / bare) | `mobile-rn-screen` |
> | **Capacitor / hybrid** shell (one web app shipped to iOS + Android) | `enhance-capacitor-ui` (axis architecture first) → then the web or rn skill |
> | Repo **README** showcase | `enhance-readme` |
>
> **You are here: `enhance-web-web3d`.** Native iOS/Android (SwiftUI / Compose, no web layer) is out of scope for all of these — use Apple HIG / Material directly.

# Enhance Web with 3D & Cinematic Motion

Add Three.js / React Three Fiber scenes, GSAP scroll choreography, and physics
motion to an **existing** web project — without rewriting it, breaking the
build, blowing the performance budget, or shipping a blank canvas to users on
weak devices or with WebGL disabled.

This is **not** a "drop a spinning cube on the homepage" skill. It audits the
repo first, decides whether 3D actually serves the page, picks the smallest
library combination that fits the existing stack, and ships the effect with
fallbacks and reduced-motion support from the first commit.

> **For greenfield / from-scratch 3D library mechanics** (raw Three.js scene
> setup, R3F primitives, shader authoring), this skill points you at the
> deeper references but stays focused on *integrating into a live repo*. For
> pure visual composition (no 3D) use `enhance-web-ui`; for anti-slop landing
> pages use `enhance-web-landing`.

---

## How This Works

When applied to an existing project, follow this sequence. **Never skip the
audit and jump to code** — that is how 3D ends up as a 4 MB hero nobody on
mobile can load.

1. **Scan** — Read the codebase. Identify framework, rendering model (SSR /
 SSG / SPA), styling system, existing motion/3D libraries, build tool, and
 the current performance baseline.
2. **Fit check** — Decide *whether* 3D/cinematic motion belongs on this
 surface and *where*. Reject 3D-for-3D's-sake.
3. **Diagnose** — Map concrete opportunities (hero, product viewer,
 scroll-story, background ambience) and the constraints around each.
4. **Choose stack** — Use the Decision Matrix to pick the minimal library
 combination that fits the existing stack.
5. **Implement** — Build with the chosen pattern, wiring performance budget,
 fallbacks, reduced-motion, and SSR/hydration safety in the same change.
6. **Verify** — Profile on a mid-tier device, test the no-WebGL and
 reduced-motion paths, confirm Lighthouse / Web Vitals didn't regress.

---

## Phase 0: Fit Check (does 3D belong here?)

Before touching any library, answer these. If you can't justify the effect,
the right move is `enhance-web-ui` or `enhance-web-landing`, not WebGL.

- [ ] **Does the effect serve comprehension or brand, or is it decoration?**
 A product configurator, a data-driven globe, a hero that shows the actual
 product in 3D — these earn their cost. A generic floating-blob background
 usually does not.
- [ ] **What is the performance budget?** A marketing landing page can spend
 more than a dashboard a user opens 40× a day. Name the budget (KB, LCP, INP,
 target FPS) *before* designing.
- [ ] **Who is the audience / device mix?** Heavy mobile traffic → design the
 mobile fallback first, then enhance up. Desktop-only internal tool → you
 have more headroom.
- [ ] **Is there a non-3D alternative that's 90% as good for 10% of the cost?**
 A pre-rendered `<video>`, an animated SVG, a CSS scroll effect, or a
 high-quality image sequence often beats live WebGL. The DEV community lesson
 holds: a scripted DOM/GSAP walkthrough can be **under 40 KB gzip vs a
 multi-MB MP4/GIF** — reach for real WebGL only when interactivity or true 3D
 depth is the point.
- [ ] **Reduced-motion + no-WebGL story exists?** If you can't describe what a
 `prefers-reduced-motion` user and a no-WebGL user see, you're not ready to
 build.

> **Anti-slop guardrail.** A spinning torus knot, a particle field with no
> meaning, or a tilt-on-mouse card that fights scrolling are the 3D equivalent
> of the purple-gradient hero. Motion and depth must explain, demo, or brand —
> never just sparkle.

---

## Phase 1: Recon — Learn the Existing Stack

Read the entry point, layout, and any existing animated component. Then record:

```
FRAMEWORK: [Next.js (app/pages?) / Vite+React / Astro / Remix / SvelteKit / vanilla]
RENDER MODEL: [SSR / SSG / CSR — matters for hydration + dynamic import]
REACT?: [yes → R3F is on the table | no → vanilla three.js]
STYLING: [Tailwind v3/v4 / CSS modules / styled-components / vanilla]
BUILD TOOL: [Vite / Webpack / Turbopack / esbuild — affects code-split + worker setup]
EXISTING MOTION: [framer-motion/motion? GSAP? Lenis? CSS only?]
EXISTING 3D: [three? @react-three/fiber? drei? none?]
PERF BASELINE: [current LCP / bundle size / Lighthouse, if measurable]
ASSET PIPELINE: [is there a /public model dir? a CDN? Draco/KTX2 already set up?]
```

Check the dependency manifest **before importing anything** — reuse what's
installed, match the installed major version (three, @react-three/fiber, gsap,
motion vs framer-motion), and never hallucinate an import.

Search for prior art and guard comments:

```bash
rg -l "three|@react-three|gsap|ScrollTrigger|Lenis|framer-motion|\"motion\"" --type ts --type tsx package.json
rg -n "useGSAP|registerPlugin|<Canvas|useFrame|frameloop" src/
rg -n "prefers-reduced-motion|matchMedia|DO NOT|deprecated" src/
```

---

## Phase 2: Opportunity Audit — Where 3D Earns Its Place

Map the page to one (rarely more than two) of these archetypes. Each has a
different cost/benefit and a different stack.

| Opportunity | What it is | Earns its cost when | Default stack |
|-------------|-----------|---------------------|---------------|
| **Hero scene** | First-fold 3D centerpiece | The product *is* visual/physical | Three.js or R3F + a light entrance tween |
| **Product viewer / configurator** | Rotate/zoom/customize a model | Users decide based on the object | R3F + drei (`OrbitControls`, `Environment`) |
| **Scroll story (pinned)** | Camera/model animates as you scroll | There's a narrative or process to reveal | GSAP `ScrollTrigger` (pin + scrub) driving the scene |
| **Ambient background** | Subtle depth behind content | Brand texture, low-distraction | Cheap shader / instanced particles, `frameloop="demand"` |
| **Data viz in 3D** | Globe, graph, point cloud | The data is inherently spatial | R3F + instancing; or 2D if it reads better flat |
| **Micro-interaction** | Hover/drag physics on a card | Delight on a key CTA | Motion / React Spring (often no Three.js at all) |

> **Rule:** one focal 3D moment per page beats five. If everything moves,
> nothing is special — the same hierarchy logic as `enhance-web-ui` applies in
> three dimensions.

---

## Phase 3: Decision Matrix — Pick the Minimal Stack

GSAP is **100% free for all use since April 2025** (all former Club/bonus
plugins — ScrollTrigger, SplitText, MorphSVG, etc. — included), so plugin
licensing is no longer a reason to avoid it.

| Use case | Recommended stack | Rationale |
|----------|-------------------|-----------|
| Marketing page, scroll-driven 3D | Three.js (or R3F) + **GSAP ScrollTrigger** + HTML/Motion overlays | GSAP owns scroll orchestration; clean layer separation |
| React app, interactive 3D viewer | **R3F** + drei + Motion | Declarative, state-driven, component-based |
| Timeline-choreographed sequences | **R3F + GSAP** (timeline in `useGSAP`) | GSAP timeline control over R3F objects |
| Physics-y drag / momentum / gestures | **R3F + React Spring** (`@react-spring/three`) | Spring physics feel natural |
| High-count particles / instances | Three.js + GSAP, `InstancedMesh`/`BatchedMesh` | Imperative control, minimal overhead |
| Smooth-scroll feel under GSAP | add **Lenis** (`lenis` / `react-lenis`) | Inertia scroll that ScrollTrigger can drive |
| Pure UI delight (no real 3D) | **Motion** or **React Spring** only | Don't pull in WebGL for a hover effect |
| Non-React repo | **vanilla three.js + GSAP** | R3F requires React; don't add React for one scene |

**One animation system per property.** GSAP *or* React Spring *or* Motion
animating a given transform — never two on the same property. Coordinate by
timing or split properties (GSAP drives position, Spring drives scale).

---

## Phase 4: Integration Patterns

Pick the pattern that matches the stack from Phase 3. Full, current code lives
in the foundation references (see *Research & Foundation Skills*); below are the
load-bearing shapes and the integration glue.

### Pattern A — Layered Separation (vanilla three.js + GSAP + HTML)

Best for non-React repos and marketing sites. Three layers: a 3D layer
(scene/camera/render loop), an animation layer (GSAP ScrollTrigger), and an
HTML/UI overlay. The scene exposes refs (camera, key meshes); GSAP animates
those refs on scroll; HTML sits on top.

```js
// scroll.js — GSAP drives the scene's exposed refs
import gsap from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";
gsap.registerPlugin(ScrollTrigger);

export function initScrollAnimations({ camera, model }) {
 const tl = gsap.timeline({
 scrollTrigger: { trigger: "#stage", start: "top top", end: "+=3000", scrub: 1, pin: true },
 });
 tl.to(camera.position, { x: 5, z: 10, onUpdate: () => camera.lookAt(0, 0, 0) })
 .to(model.rotation, { y: Math.PI * 2 }, 0);
 return () => tl.scrollTrigger?.kill(); // always return teardown
}
```

### Pattern B — Unified React (R3F + Motion)

Best for React apps with interactive, state-driven 3D. `<Canvas>` holds the
scene; `motion.div` overlays carry HTML. Keep per-frame work in `useFrame`
mutating **refs**, never React state.

```tsx
// Lazy-load the canvas so WebGL never blocks first paint / SSR
const Scene = dynamic(() => import("./Scene"), { ssr: false, loading: () => <Poster /> });

<Canvas camera={{ position: [0, 2, 5], fov: 45 }} dpr={[1, 1.5]} frameloop="demand">
 <Suspense fallback={null}><Scene /></Suspense>
</Canvas>
```

### Pattern C — Hybrid (R3F + GSAP timelines)

R3F renders; GSAP choreographs. Create the timeline inside `useGSAP` (scoped,
auto-cleaned) and target the R3F object's `.current`.

```tsx
import { useGSAP } from "@gsap/react";
useGSAP(() => {
 const tl = gsap.timeline({ scrollTrigger: { trigger: ref.current, scrub: 1 } });
 tl.to(groupRef.current.position, { y: 2, ease: "power2.inOut" });
}, { scope: ref }); // useGSAP reverts on unmount — handles Strict Mode double-invoke
```

### Pattern D — Physics (R3F + React Spring)

`@react-spring/three` for drag/momentum/gesture feedback that should feel
weighty. Spring owns scale/position; nothing else touches those props.

---

## Phase 5: Performance Budget (bake in, don't bolt on)

WebGL is expensive and degrades hard on weak devices. Apply these from the
first commit, not after a complaint.

**Render loop**
- [ ] Cap DPR: `dpr={[1, 1.5]}` (R3F) / `renderer.setPixelRatio(Math.min(devicePixelRatio, 2))`.
- [ ] Render on demand where possible: R3F `frameloop="demand"` + `invalidate()` on change; vanilla → only render when something changed or controls are active.
- [ ] **Pause off-screen.** `IntersectionObserver` stops the loop when the canvas leaves the viewport.
- [ ] Never read/write React state in `useFrame` — mutate refs. State in the loop forces 60 fps re-renders.

**Draw calls & geometry**
- [ ] Aim for **< 100 draw calls/frame**. Use `InstancedMesh` / `BatchedMesh` for repeated objects; merge static geometry.
- [ ] Reuse geometries and materials; don't allocate inside the loop.
- [ ] LOD for large scenes; simpler shaders + reduced geometry on mobile.

**Assets**
- [ ] glTF + **Draco** for meshes (50–80% smaller); **KTX2/Basis** for textures (3–5× smaller, lower GPU memory).
- [ ] Power-of-two textures, mipmaps, correct `colorSpace` (`SRGBColorSpace`).
- [ ] **Lazy-load 3D below the fold**; code-split the Three.js/R3F bundle; preload only critical assets. Never lazy-load the LCP element itself.

**Modern renderer (optional, current)**
- [ ] WebGPU is production-ready since three r171: `import { WebGPURenderer } from "three/webgpu"` ships one renderer with **automatic WebGL2 fallback**. Use `forceWebGL: true` to test the fallback path. No urgent migration if a WebGL2 app already runs smoothly.

**Main thread (advanced)**
- [ ] For heavy scenes, consider `OffscreenCanvas` + Web Worker to keep the main thread free for UI/INP.

**Cleanup**
- [ ] `dispose()` every geometry / material / texture / render target on unmount; `renderer.dispose()`. Kill GSAP tweens/ScrollTriggers (`useGSAP` does this for you).

---

## Phase 6: Accessibility & Graceful Degradation

A 3D enhancement that breaks for some users is a regression, not an upgrade.

- [ ] **Reduced motion.** Respect `prefers-reduced-motion`: disable scroll
 scrub / auto-rotation / parallax, or swap to a static poster frame. Gate at
 the source so the whole scene honors it.

```ts
const reduce = typeof window !== "undefined"
 && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
// reduce ? render static poster / no scrub : full experience
```

- [ ] **No-WebGL fallback.** Feature-detect; if WebGL/WebGPU is unavailable,
 render a static image/`<video>`/SVG that preserves the visual language and the
 conversion path. Never a blank canvas.
- [ ] **Mobile fallback designed first**, then enhanced up — simpler scene,
 fewer particles, no heavy post-processing, fewer transparent layers.
- [ ] **Keep semantic HTML for anything interactive.** Buttons, links, and
 text content live in real DOM (overlay), not as click targets inside the
 canvas — screen readers and keyboard users need them, and it protects INP.
- [ ] **Don't trap scroll or focus.** Pinned scroll sections must release; the
 canvas must not steal keyboard focus or block tabbing.
- [ ] **Protect LCP.** The hero's largest contentful element should not wait on
 WebGL init — show a poster immediately, hydrate the scene after.

---

## Phase 7: SSR / Hydration Safety

The most common way 3D breaks an existing app is server rendering and React
Strict Mode.

- [ ] **Don't render WebGL on the server.** Next.js: `dynamic(() => import("./Scene"), { ssr: false })`. Guard any `window`/`document` access with a client check.
- [ ] **Use `useGSAP()` from `@gsap/react`**, not bare `useEffect` — it scopes
 selectors and auto-reverts animations on unmount, surviving route changes and
 Strict Mode's double-invoke. Never create tweens in the render body (a new
 animation per re-render).
- [ ] **Clean up everything on unmount** — ScrollTriggers, RAF loops, resize
 listeners, IntersectionObservers, disposables.
- [ ] **Lenis (if used):** integrate with ScrollTrigger via the recommended
 `lenis.on("scroll", ScrollTrigger.update)` + ticker wiring so scroll position
 stays in sync.

---

## Common Pitfalls

| Pitfall | Fix |
|---------|-----|
| Two libraries animate the same property | One system per property; split or sequence |
| React state mutated in `useFrame` | Mutate refs; lift state out of the loop |
| Scene renders every frame while idle/off-screen | `frameloop="demand"` + `IntersectionObserver` pause |
| GSAP tween created in render body | Wrap in `useGSAP` / `contextSafe` |
| Blank canvas on no-WebGL / slow device | Feature-detect + poster/video fallback |
| WebGL initialized on server | `ssr: false` dynamic import; window guards |
| Multi-MB model on the hero | Draco/KTX2 + lazy-load + poster + device-tier scene |
| Scroll jank under ScrollTrigger | `scrub` numeric (smoothing), Lenis, refs not state |
| Memory grows on route change | Dispose geometries/materials/textures + kill tweens |
| Parallax/tilt fights native scroll | Reduced-motion gate + clamp; don't hijack the wheel |

---

## Verification Checklist (run before declaring done)

- [ ] Builds and type-checks; no hallucinated imports; installed versions matched.
- [ ] Profiled on a **mid-tier / mobile** device or throttled DevTools — holds target FPS.
- [ ] Draw calls within budget (`renderer.info` / `stats-gl`); DPR capped.
- [ ] `prefers-reduced-motion` path verified (motion off / poster shown).
- [ ] No-WebGL path verified (DevTools disable WebGL, or `forceWebGL` + simulated failure) — graceful fallback, never blank.
- [ ] Mobile layout + fallback scene verified at a real narrow viewport.
- [ ] LCP/INP/CLS not regressed vs the Phase 1 baseline (Lighthouse before/after).
- [ ] SSR/hydration clean — no `window is not defined`, no hydration mismatch, no Strict Mode double-mount leak.
- [ ] Unmount is clean — disposables freed, tweens/observers killed (navigate away and back, watch memory).
- [ ] Interactive elements remain real DOM, keyboard-reachable; canvas doesn't trap focus/scroll.
- [ ] One focal 3D moment per page; the effect explains/demos/brands (passes the Phase 0 fit check).

---

## Rules

- Work with the **existing stack**. Don't add React for one scene; don't swap build tools or styling systems.
- Don't break existing functionality or the build. Lazy-load and feature-gate so the page still works if WebGL fails.
- Check the dependency manifest before importing; match installed major versions (`three`, `@react-three/fiber`, `@react-three/drei`, `gsap`, `@gsap/react`, `motion`/`framer-motion`, `@react-spring/three`, `lenis`).
- Keep changes reviewable and scoped to the surface being enhanced.
- Performance budget, fallbacks, reduced-motion, and SSR safety ship **in the same change** as the effect — not as a follow-up.
- Add comments only for non-obvious intent (why a DPR cap, why `ssr: false`), not narration.

---

## When Not To Use

- Pure visual composition / hierarchy / spacing, no 3D → `enhance-web-ui`.
- Greenfield anti-slop landing page → `enhance-web-landing`.
- Generic existing-site premium upgrade (no 3D) → `enhance-web-redesign`.
- UX heuristics / flows / data wiring → `enhance-web-ux`.
- A hover/drag delight that needs no WebGL → `design-motion` / `design-motion`.

---

## Research & Foundation Skills

**Foundation / deeper mechanics (in this repo):**
- `enhance-web-web3d` — Three.js, R3F, shaders, particle systems (greenfield mechanics).
- `design-motion` — Framer Motion / Motion, GSAP, CSS animation patterns.
- `design-motion` — physics-y micro-interactions and delight.
- `audit-performance` — Core Web Vitals (LCP/INP/CLS), bundle analysis.
- `audit-accessibility` — reduced-motion, keyboard, screen-reader compliance.

**Current external anchors:**
- **GSAP is 100% free since April 2025** (all plugins included). Use `useGSAP()` (`@gsap/react`) for React cleanup/Strict-Mode safety. <https://gsap.com/resources/React/>
- **R3F performance docs** — WebGL is expensive on weak devices; design for graceful degradation; mutate refs not state in `useFrame`. <https://r3f.docs.pmnd.rs/advanced/scaling-performance>
- **three.js WebGPURenderer** — production-ready since r171, automatic WebGL2 fallback, `forceWebGL` to test. <https://threejs.org/manual/en/webgpurenderer.html>
- **"100 Three.js Tips That Actually Improve Performance" (2026)** — <100 draw calls, Draco/KTX2, lazy-load below the fold, dispose everything, profile with stats-gl/renderer.info/Spector.js. <https://www.utsubo.com/blog/threejs-best-practices-100-tips>
- **Cinematic 3D scroll with GSAP + Next.js + R3F** — DPR cap, refs for camera values, mobile simplification, reduced-motion, `useGSAP` cleanup, hydration safety. <https://mirax.cc/articles/cinematic-3d-scroll-gsap-nextjs-react-three-fiber>
- **R3F mobile performance (2026)** — Draco + LOD + `OffscreenCanvas`/Web Worker + instancing for stable 60 FPS. <https://www.krapton.com/blog/boosting-react-three-fiber-mobile-performance-in-2026-a-deep-dive-d6105c>
- **Optimizing 3D website performance** — device-tier detection, IntersectionObserver pause, static fallback for no-WebGL. <https://svilenkovic.com/3d/how-to-optimize-3d-website>

> Adapted and generalized from the `web3d-integration-patterns` meta-skill in
> [freshtechbro/claudedesignskills](https://github.com/freshtechbro/claudedesignskills)
> (and its `threejs-webgl` / `gsap-scrolltrigger` / `react-three-fiber` /
> `motion-framer` / `react-spring-physics` foundation skills) into an
> audit-first, repo-elevation skill in the `enhance-web-*` family.