tsogjavklann/awwwards-3d

---

name: awwwards-3d description: Build production-grade Awwwards-style scroll-driven 3D websites in the visual language of Active Theory, Lusion, 14islands, Bonhomme, Resn, Studio Freight, Locomotive, and Igloo Inc. Use when the user asks for an "Awwwards-style", "scroll-driven 3D", "WebGL hero", "3D landing page", "interactive product showcase", "scroll storytelling site", "cinematic web experience", "creative dev portfolio", "premium 3D site", "Lusion-style", "Active Theory-style", "scroll 3D animation", or mentions Three.js + GSAP + Lenis together. Also triggers on Mongolian phrases like "3D вэб", "scroll-тэй 3D", "premium вэбсайт", "cinematic вэб", "Awwwards маягтай", "3D landing", "интерактив 3D". Locks tech stack to Three.js r170 + GSAP 3.12.5 + Lenis 1.1.0 with three's built-in EffectComposer for post-processing. Produces single-file HTML deliverables when possible. Do NOT use for: static marketing sites without 3D, plain React/Next.js apps, dashboards, admin UIs, or simple landing pages where 3D would be decorative noise. license: MIT

Awwwards-Style 3D Websites

You are building scroll-driven, cinematic 3D web experiences in the lineage of Active Theory, Lusion, 14islands, Bonhomme, Resn, Studio Freight, Locomotive, and Igloo Inc. The aesthetic target is premium, slow, lerped, glossy, atmospheric — never snappy, never busy, never default.

Core Philosophy

Read these before touching code. They are the difference between "Three.js demo" and "Awwwards Site of the Day".

1. Aesthetics > Geometry. A 6-poly cube with a good HDRI, ACESFilmic tone mapping, and bloom looks better than a 200k-poly model lit by a single DirectionalLight. Spend budget on lighting/post-processing first, geometry last.
2. Lerp everything. No value should ever change instantly. Camera position, rotation, scroll progress, mouse position, even raycaster targets — all run through a damping factor (0.06–0.1 is the sweet spot). The world feels alive because nothing snaps.
3. Single-file HTML when possible. Default deliverable is one .html file using ESM imports from unpkg (and esm.sh for GSAP). No build step unless the user explicitly asks for one. This is what makes the work portable, reviewable, and shareable.
4. Mobile first, performance always. Cap pixelRatio at Math.min(devicePixelRatio, 2). Frustum-cull. Halve post-processing on mobile. Test on a mid-tier Android in Chrome DevTools before declaring done.
5. ACESFilmic tone mapping is non-negotiable. renderer.toneMapping = THREE.ACESFilmicToneMapping and renderer.outputColorSpace = THREE.SRGBColorSpace. Without this, everything looks flat and "WebGL-ish".
6. metalness > 0 requires an environment map. A metallic material with no envMap is a black blob. Always load an HDRI (or use RoomEnvironment as a fallback) before introducing metals/glass.
7. 60fps target on desktop, 30fps floor on mobile. If you can't hit it, cut post-processing passes before cutting geometry — the eye notices noise more than triangles.

Locked Tech Stack

These versions are tested together. Do not upgrade without asking.

three                       0.170.0
gsap                        3.12.5  (with ScrollTrigger)
lenis                       1.1.0   (NOT @studio-freight/lenis — that scope was retired)

Post-processing uses three's built-in EffectComposer from three/addons/postprocessing/. The standalone postprocessing library (v6.36.0) was evaluated and dropped from this skill — its internals call Material.onBeforeRender(), which three r170 removed, producing a console warning per material per frame. Three's built-in passes (UnrealBloomPass, OutputPass, ShaderPass, LUTPass, etc.) cover every effect we need with zero version drift.

Glass uses three's built-in MeshPhysicalMaterial with transmission: 1.0 + dispersion: 1.2 (r166+ feature — chromatic refraction without external libs). The drei-vanilla MeshTransmissionMaterial is NOT in three core/addons; reach for it only when you need temporal distortion or per-object backbuffer sampling (then add drei-vanilla and [email protected] to your importmap). See PATTERNS.md #5 for both paths.

CDN imports use this importmap pattern (see assets/templates/minimal.html for the canonical example):

<script type="importmap">
{
  "imports": {
    "three": "https://unpkg.com/[email protected]/build/three.module.js",
    "three/addons/": "https://unpkg.com/[email protected]/examples/jsm/",
    "gsap": "https://esm.sh/[email protected]",
    "gsap/ScrollTrigger": "https://esm.sh/[email protected]/ScrollTrigger",
    "lenis": "https://unpkg.com/[email protected]/dist/lenis.mjs"
  }
}
</script>

Composer choice — settled: This skill uses three's built-in EffectComposer from three/addons/postprocessing/. The standalone postprocessing npm library was tested and rejected: [email protected] flags Material.onBeforeRender() removed in r170, flooding the console once per material per frame. Three built-in passes cover every effect this skill needs (bloom, vignette via ShaderPass, grain via ShaderPass, LUT via LUTPass, output tone-mapping via OutputPass). See references/POST_PROCESSING.md for the canonical pass chain.

CDN reliability: Default to unpkg.com for three and lenis — it mirrors the npm directory structure exactly so three/addons/... resolves cleanly. cdn.jsdelivr.net was tested and intermittently failed to serve [email protected]/examples/jsm/postprocessing/* files (ERR_CONNECTION_CLOSED) from some networks. Use esm.sh for GSAP because that's the cleanest ESM gateway for the GSAP UMD bundle. If unpkg is unreachable, fallback order: unpkg → esm.sh → cdn.skypack.dev. For production, vendor the files locally (download to /vendor/) — strict CDN dependency is acceptable for prototypes only.

Update policy: Versions are locked because they were tested together. To upgrade: (1) bump in assets/templates/minimal.html first, (2) run all four templates in a browser, (3) fix any breaks, (4) update SKILL.md and PATTERNS.md. Do not silently bump versions in a single template — drift between templates is the #1 source of "works on my machine".

The 5-Step Workflow

Follow this order. Skipping a step produces "tech demo" output instead of "premium site" output.

Step 1 — Identify the Experience Archetype

Every Awwwards 3D site fits one of these. Pick one and commit:

Archetype	Pattern	Reference
Object showcase	Single hero object, camera orbits/zooms on scroll	Bonhomme product pages, Apple AirPods Pro
Room walkthrough	Camera path through 3D interior	Igloo Inc., Bruno Simon portfolio
Tunnel	Camera flies forward through endless geometry	Active Theory experiments
Vertical descent	Scroll = falling/rising through layers	14islands case studies
Flyover	Camera traverses a landscape	Lusion case studies
Particle field	Thousands of points reacting to scroll/mouse	Resn experiments

Ask the user which archetype if they haven't said. Do not invent a new one — these are proven.

Step 2 — Plan Assets

Choose the cheapest source that meets the bar:

1. Three.js primitives (SphereGeometry, BoxGeometry, TorusKnotGeometry) — for abstract/showcase work. Most Awwwards sites use these. Don't overlook them.
2. Blender via MCP — when you need a custom shape. See references/BLENDER_PIPELINE.md for recipes (coin, glass orb, blob, low-poly room) and the GLB export config (Draco + KTX2).
3. Polyhaven — HDRIs and textures, free, CC0. The HDRI is more important than the model.
4. Sketchfab — last resort for ready-made models. Always check polycount.

Step 3 — Pick a Template

Start from assets/templates/:

• minimal.html — empty scene with HDRI, tone mapping, Lenis, post-processing wired up. Use as the foundation for anything custom.
• coin-scroll.html — coin rotates and falls on scroll (object showcase).
• room-walkthrough.html — camera moves along a spline through a room (room walkthrough).
• glass-product.html — single product with MeshPhysicalMaterial transmission + dispersion (r166+), HDRI, gentle bloom (object showcase, glass).

Templates are starting points, not final work. Strip what you don't need, layer what you do.

Step 4 — Layer the Polish (in this order)

The order matters. Each layer assumes the previous is in place.

1. HDRI loaded and applied as scene.environment
2. Tone mapping — ACESFilmicToneMapping, exposure 1.0–1.2
3. Lighting — even with HDRI, add one DirectionalLight for shadow direction
4. Post-processing — three built-in EffectComposer with HDR target → RenderPass → UnrealBloomPass (strength ~0.45, radius 0.4, threshold 0.82) → vignette ShaderPass → OutputPass (applies renderer.toneMapping = ACESFilmic) → grain ShaderPass last
5. Lenis smooth scroll wired to GSAP ScrollTrigger.update
6. Custom cursor (optional, but a Bonhomme/Lusion signature)
7. Scroll timeline — GSAP timeline driven by ScrollTrigger, lerping camera/object properties
8. Film grain as the final composite layer — custom ShaderPass with a time-driven noise fragment, intensity ~0.05 (see references/POST_PROCESSING.md § "Pass 5 — Film grain")

Step 5 — Performance Audit

Before declaring done:

• Lighthouse Performance ≥ 85 on desktop, ≥ 70 on mobile
• FCP < 1.8s, LCP < 2.5s
• 60fps on desktop, 30fps minimum on mid-tier Android
• pixelRatio capped at 2
• GLB files Draco-compressed, textures KTX2 where possible
• No console.log inside requestAnimationFrame loops (kills perf in DevTools)
• All animations driven by delta time, not frame count

Hard Rules — Never Do These

These ship broken work. See references/ANTI_PATTERNS.md for the long form.

1. No snap animations. Every property change goes through lerp or GSAP ease.
2. No metalness > 0 without an environment map. Result: black blobs.
3. No uncapped pixelRatio. A 4K monitor with devicePixelRatio = 2 will tank to 15fps.
4. No uncompressed GLB. Draco compression is mandatory (see BLENDER_PIPELINE.md).
5. No auto-play audio. Browsers block it; users hate it.
6. No console.log in the animation loop. Even one per frame destroys DevTools.
7. No mixing CSS-driven and JS-driven scroll. Lenis owns scroll. ScrollTrigger reads from Lenis. CSS scroll-behavior: smooth must be removed.
8. No OrbitControls in production. It's for prototyping. Real sites use scroll-driven cameras.
9. No ShaderMaterial without precision declaration. Mobile GPUs need precision mediump float;.
10. No raycasting against the whole scene every frame. Filter to a small array of interactable meshes.
11. No frame-count-based animation. All motion must be driven by delta from clock.getDelta() and multiplied by it. A 144Hz monitor and a 30Hz monitor must produce visually identical motion. For lerp, use a framerate-independent formula: factor = 1 - Math.pow(1 - ease, delta * 60) instead of raw ease.

Reference Files

Load these on demand — do not read all of them at start.

• references/ARCHITECTURE.md — scene structure, the lerp/scroll loop, render order
• references/PATTERNS.md — 33 copy-paste code snippets for common needs
• references/PROCEDURAL_GEOMETRY.md — code-only geometry generation; primitives, math-driven shapes, vertex displacement, hybrid Blender patterns. The default path before reaching for AI 3D generators.
• references/BLENDER_PIPELINE.md — Blender MCP recipes + GLB export config
• references/SHADERS.md — GLSL building blocks (noise, fresnel, dispersion, custom materials)
• references/POST_PROCESSING.md — bloom, DOF, grain, chromatic aberration recipes
• references/TRANSITIONS.md — Barba.js page transitions, View Transitions API
• references/ANTI_PATTERNS.md — long-form list of what kills the aesthetic and why

Inspiration Archive

When the user is undecided about direction, point them here. Open these in a browser, do not screenshot or scrape.

• Active Theory — https://activetheory.net — masters of WebGL flair, GLSL distortions, hand-crafted bloom and dispersion
• Lusion — https://lusion.co — surreal product showcases, transmissive materials, perfect color grading
• 14islands — https://14islands.com — playful 3D, signature page transitions, tasteful typography over scenes
• Bonhomme — https://bonhomme.lol — bold typography meets 3D, distinctive cursors, art-direction-led
• Resn — https://resn.co.nz — atmospheric particle work, dreamlike palettes, slow camera moves
• Studio Freight — https://studiofreight.com — authors of Lenis; minimalism + perfectly tuned smoothness
• Locomotive — https://locomotive.ca — original Locomotive Scroll authors; scroll choreography mastery
• Igloo Inc. — https://igloo.inc — landscape flyovers, narrative pacing, Pixar-grade lighting
• Awwwards Sites of the Day — https://www.awwwards.com/websites/sites_of_the_day/ — daily curated archive for current trends

Audio (Optional but Signature)

~70% of Awwwards 3D winners include subtle audio: ambient drones, hover ticks, scroll whooshes. Done well, audio is the difference between "site" and "experience". Done badly, it's the reason users close the tab in the first 2 seconds.

Rules:

• Use Howler.js (https://esm.sh/[email protected]) or the Web Audio API. No <audio> tag for ambient.
• Always gate playback behind a user gesture (button click, scroll-into-view past first viewport). Browsers block autoplay anyway, but the UX rule is stricter: never start sound the user didn't ask for.
• Provide a persistent mute toggle in the UI corner. Default: OFF on mobile, OFF on first visit (use localStorage to remember the user's choice on return).
• Loop ambient at -18 dB to -24 dB. UI sounds at -12 dB to -18 dB.
• Preload short SFX, lazy-load ambient (it's the bigger file).
• Pause audio on document.visibilitychange when the tab is hidden.

File format: Always include both .webm (Opus) and .mp3 for compatibility. Howler picks the best one automatically.

Output Format

Default deliverable: a single .html file that includes all CSS, JS, and importmap inline — portable, reviewable, fork-able by pasting one file.

Important — file:// limitation: these templates use ESM imports from CDNs via <script type="importmap">. Browsers block CDN fetches from file:// origins (treated as unique security origins). Double-clicking the .html will fail. The user must serve it over HTTP:

cd <folder containing the .html>
python -m http.server 8765
# then open: http://localhost:8765/<filename>.html

Always include this two-line instruction at the top of any template you ship to the user. Do not assume they know.

If the user asks for a multi-file build (Vite, Next.js), ask which framework before scaffolding. Then run scripts/init_project.py to generate the project skeleton — that path produces a package.json so npm run dev handles the server automatically.

When You Get Stuck

• Camera/object behavior wrong → re-read references/ARCHITECTURE.md (the lerp loop section).
• Material looks flat or black → HDRI not loaded, or tone mapping not set. Check Step 4 — Layer the Polish.
• Performance bad → cut post-processing passes first, geometry last. See references/POST_PROCESSING.md.
• Scroll feels janky → Lenis not wired to ScrollTrigger. See references/PATTERNS.md § "Lenis + ScrollTrigger".
• "It works but doesn't feel premium" → you skipped Step 4. Go back and layer in order.