agentleFS
tsogjavklanntsogjavklann/awwwards-3d/SKILL.md

awwwards-3d

Skill16 starsChanged 6 months agoMITView on GitHub

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.

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 1

    1. Eliart-tech/Claude-skills★ 0100% same

    Edited · 0

    None found.

    Wrote their own version · 0

    None found.

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. About 0 are common, 6 are distinctive, and 8 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read these before touching code.

    line 13
  2. Distinctive:

    Lerp everything: No value should ever change instantly.

    line 16
  3. Very specific:

    Single-file HTML when possible: Default deliverable is one .html file using ESM imports from unpkg (and esm.sh for GSAP).

    line 17
  4. Distinctive:

    60fps target on desktop, 30fps floor on mobile: If you can't hit it, cut post-processing passes before cutting geometry — the eye notices …

    line 21
  5. Distinctive:

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

    line 61
  6. Distinctive:

    Every Awwwards 3D site fits one of these.

    line 65
  7. Distinctive:

    Ask the user which archetype if they haven't said.

    line 76
  8. Very specific:

    No snap animations: Every property change goes through lerp or GSAP ease.

    line 127
  9. Very specific:

    No frame-count-based animation: All motion must be driven by delta from clock.getDelta() and multiplied by it.

    line 137
  10. Distinctive:

    When the user is undecided about direction, point them here.

    line 154
  11. Very specific:

    Use Howler.js (https://esm.sh/howler@2.2.4) or the Web Audio API.

    line 171
  12. Very specific:

    File format: Always include both .webm (Opus) and .mp3 for compatibility.

    line 178
  13. Very specific:

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

    line 182
  14. Very specific:

    If the user asks for a multi-file build (Vite, Next.js), ask which framework before scaffolding.

    line 194

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 three-mesh-bvh@0.7.8 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/three@0.170.0/build/three.module.js",
    "three/addons/": "https://unpkg.com/three@0.170.0/examples/jsm/",
    "gsap": "https://esm.sh/gsap@3.12.5",
    "gsap/ScrollTrigger": "https://esm.sh/gsap@3.12.5/ScrollTrigger",
    "lenis": "https://unpkg.com/lenis@1.1.0/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: postprocessing@6.36.0 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 three@0.170.0/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:

ArchetypePatternReference
Object showcaseSingle hero object, camera orbits/zooms on scrollBonhomme product pages, Apple AirPods Pro
Room walkthroughCamera path through 3D interiorIgloo Inc., Bruno Simon portfolio
TunnelCamera flies forward through endless geometryActive Theory experiments
Vertical descentScroll = falling/rising through layers14islands case studies
FlyoverCamera traverses a landscapeLusion case studies
Particle fieldThousands of points reacting to scroll/mouseResn 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.

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/howler@2.2.4) 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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.