r3f-scene-polish git:20260726.b67ae30A

Immutable. This exact content is served forever at /api/v1/blob/35e343e9bc7548b9.

---
name: r3f-scene-polish
description: "Art-directs an existing three.js or React Three Fiber scene to cinematic quality with postprocessing, HDRI and PBR lighting, contact shadows, transmission materials, and camera choreography. Use for look-development once the scene renders, not for scene setup or lifecycle."
license: MIT
---

# R3F Scene Polish — Cinematic Look-Dev

Take an **already-working** three.js / React Three Fiber scene and art-direct it
to a premium, cinematic result. This skill owns the *aesthetic* layer:
postprocessing, physically-based lighting, shadows, materials, tone mapping, and
camera choreography.

## Boundary (read first)

This skill is the **second half** of a 3D scene — the look-dev pass after it
renders correctly. It does **not** own setup or correctness:

- Canvas/createRoot lifecycle, loaders, GLTF, disposal, SSR/client boundaries,
  DPR, "blank canvas" and resize bugs → **`web-three-r3f`**.
- Native (Expo / React Native) motion → **`expo-motion`**.
- Cross-stack motion-system direction / tokens / repo-wide upgrades →
  **`design-motion-audit`**.

If the scene doesn't render yet, start in `web-three-r3f`, then return here.

## Before implementing

- Read `references/art-direction.md` — the current-API (2026) look-dev recipes:
  the `@react-three/postprocessing` quality ladder, `drei` `Environment` /
  `ContactShadows` / `AccumulativeShadows` / `MeshTransmissionMaterial`, tone
  mapping (AgX vs ACES), selective bloom, and the WebGPU/TSL caveat. **Verify
  every API against the repo's installed versions before editing** — the
  reference pins the versions it was written against.
- Read `references/motion-vocabulary.md` for named camera/lighting decisions.
- Read `references/performance-accessibility.md` before final QA.

## Look-dev rules

1. **Light for form.** HDRI (`Environment`) for image-based lighting; add
   key/fill/rim intentionally; ground the subject with `ContactShadows` or
   `AccumulativeShadows` (or float it deliberately).
2. **Tone-map deliberately.** three-core defaults to `NoToneMapping`; the R3F
   `<Canvas>` defaults to `ACESFilmicToneMapping`. Prefer `AgX` / `Neutral` for
   accurate highlight rolloff; don't double-tonemap (renderer *or* the
   postprocessing `ToneMapping` effect, not both).
3. **Build a postprocessing quality ladder**, not a pile-up: order effects
   intentionally, gate expensive ones (N8AO, DoF) behind a device/DPR quality
   tier, and give reduced-motion / low-power a lighter branch.
4. **Prefer PBR material values, HDRI, and physically-plausible lighting** over
   fake tricks; use `MeshTransmissionMaterial` for glass, sharing one FBO for
   many transmissive objects.
5. **Choreograph the camera** with intent (dolly/truck/orbit + easing), not large
   spins for basic feedback; keep text legible through the motion.
6. **Animate hot paths cheaply** (refs + delta-time in `useFrame`); this skill
   assumes `web-three-r3f`'s correctness rules (no `setState` in the frame loop,
   reuse math objects, dispose) — see that skill, don't re-derive them here.
7. **Always add a reduced-motion / low-power alternative** for camera travel,
   parallax, heavy postprocessing, and idle loops.

Return complete code changes or a complete look-dev plan, depending on the
request.

## Optional power tool: art-direction audit

This skill ships `scripts/audit.mjs`, a static auditor for R3F/three.js
**art-direction** quality — tone mapping (double-tonemap, legacy API), color
management (deprecated `outputEncoding`/`sRGBEncoding`), lighting (unlit scenes),
postprocessing quality (missing quality ladder, legacy `SSAO`, WebGPU mismatch), and
material color-space. This is the visual layer `web-three-r3f`'s lifecycle audit does
**not** cover; run both. Optional — findings are leads.

```bash
node scripts/audit.mjs doctor                    # list every rule
node scripts/audit.mjs scan --root . --format json
```

Verify each finding against the repo's installed package versions before changing behavior.