Skip to content

notque/vexjoy-agent / skills/frontend/frontend

frontend

Unverified

Frontend: UI design, distinctive visual styles, HTML artifacts, Three.js 3D, TypeScript/React/Next.js apps, e-commerce, portfolios, React Native, web performance.

FileKindSize
SKILL.mdskill md22.5 KB
SPEC.mdmarkdown4.3 KB
agents/html-builder.mdmarkdown5.9 KB
assets/base-template.htmlother495 B
references/design-refs/accessibility-review.mdmarkdown13.0 KB
references/design-refs/design-critique.mdmarkdown10.4 KB
references/design-refs/design-handoff.mdmarkdown9.9 KB
references/design-refs/design-systems.mdmarkdown9.3 KB
references/design-refs/llm-design-failure-modes.mdmarkdown9.1 KB
references/design-refs/ux-copy.mdmarkdown9.5 KB
references/distinctive-frontend-design-refs/animation-patterns.mdmarkdown10.5 KB
references/distinctive-frontend-design-refs/background-techniques.mdmarkdown10.5 KB
references/distinctive-frontend-design-refs/balatro-shader-breakdown.mdmarkdown14.9 KB
references/distinctive-frontend-design-refs/card-shader-patterns.mdmarkdown10.9 KB
references/distinctive-frontend-design-refs/color-inspirations.jsonconfig9.4 KB
references/distinctive-frontend-design-refs/css-audit-patterns.mdmarkdown4.7 KB
references/distinctive-frontend-design-refs/font-catalog.jsonconfig9.7 KB
references/distinctive-frontend-design-refs/game-ui-polish.mdmarkdown6.3 KB
references/distinctive-frontend-design-refs/honest-placeholders.mdmarkdown3.2 KB
references/distinctive-frontend-design-refs/implementation-examples.mdmarkdown7.7 KB
references/distinctive-frontend-design-refs/macrostructure-catalog.mdmarkdown9.3 KB
references/distinctive-frontend-design-refs/oklch-color-harmony.mdmarkdown7.3 KB
references/distinctive-frontend-design-refs/performance-budgets.mdmarkdown10.6 KB
references/distinctive-frontend-design-refs/phase-details.mdmarkdown4.8 KB
references/distinctive-frontend-design-refs/pptx-conversion.mdmarkdown9.7 KB
references/distinctive-frontend-design-refs/roll-text.mdmarkdown7.2 KB
references/distinctive-frontend-design-refs/shader-integration-react.mdmarkdown16.7 KB
references/distinctive-frontend-design-refs/slide-controller.mdmarkdown9.4 KB
references/distinctive-frontend-design-refs/text-animation-patterns.mdmarkdown4.3 KB
references/html-artifact-refs/design-system.mdmarkdown10.2 KB
references/html-artifact-refs/diagram-layering.mdmarkdown3.9 KB
references/html-artifact-refs/infographic-layouts.mdmarkdown4.9 KB
references/html-artifact-refs/pdf-export.mdmarkdown6.0 KB
references/html-artifact-refs/pptx-export.mdmarkdown10.2 KB
references/html-artifact-refs/shape-diagram-illustration.mdmarkdown4.3 KB
references/nextjs-ecommerce.mdmarkdown3.4 KB
references/nextjs-ecommerce/admin-dashboard.mdmarkdown9.8 KB
references/nextjs-ecommerce/error-catalog.mdmarkdown7.9 KB
references/nextjs-ecommerce/expertise.mdmarkdown5.1 KB
references/nextjs-ecommerce/patterns-and-errors.mdmarkdown4.6 KB
references/nextjs-ecommerce/preferred-patterns.mdmarkdown8.0 KB
references/nextjs-ecommerce/shopping-cart-patterns.mdmarkdown7.7 KB
references/nextjs-ecommerce/stripe-integration.mdmarkdown9.5 KB
references/performance-optimization.mdmarkdown9.9 KB
references/performance-optimization/browser-dom-optimizations.mdmarkdown6.0 KB
references/performance-optimization/bundle-optimization.mdmarkdown7.9 KB
references/performance-optimization/core-web-vitals.mdmarkdown9.6 KB
references/performance-optimization/js-algorithm-optimizations.mdmarkdown9.6 KB
references/performance-optimization/metrics-and-monitoring.mdmarkdown8.8 KB
references/performance-optimization/nextjs-optimization.mdmarkdown10.6 KB
references/performance-optimization/performance-testing.mdmarkdown9.6 KB
references/performance-optimization/preferred-patterns.mdmarkdown7.4 KB
references/performance-optimization/react-async-patterns.mdmarkdown7.0 KB
references/performance-optimization/react-bundle-optimization.mdmarkdown6.3 KB
references/performance-optimization/react-rendering-performance.mdmarkdown12.0 KB
references/react-native.mdmarkdown4.4 KB
references/react-native/animation-patterns.mdmarkdown3.9 KB
references/react-native/error-handling.mdmarkdown7.7 KB
references/react-native/list-performance.mdmarkdown5.4 KB
references/react-native/monorepo-config.mdmarkdown2.3 KB
references/react-native/navigation-patterns.mdmarkdown2.0 KB
references/react-native/rendering-patterns.mdmarkdown3.2 KB
references/react-native/state-management.mdmarkdown3.3 KB
references/react-native/testing.mdmarkdown6.2 KB
references/react-native/ui-patterns.mdmarkdown5.0 KB
references/react-portfolio.mdmarkdown7.7 KB
references/react-portfolio/gallery-patterns.mdmarkdown2.5 KB
references/react-portfolio/image-optimization.mdmarkdown3.4 KB
references/react-portfolio/lightbox-patterns.mdmarkdown6.1 KB
references/react-portfolio/nextjs-app-router.mdmarkdown4.9 KB
references/react-portfolio/performance.mdmarkdown3.9 KB
references/react-portfolio/portfolio-seo.mdmarkdown4.8 KB
references/react-portfolio/responsive-design.mdmarkdown3.3 KB
references/threejs-builder-refs/advanced-animation.mdmarkdown12.1 KB
references/threejs-builder-refs/advanced-topics.mdmarkdown11.0 KB
references/threejs-builder-refs/build-recipes.mdmarkdown7.4 KB
references/threejs-builder-refs/game-architecture.mdmarkdown10.4 KB
references/threejs-builder-refs/game-patterns.mdmarkdown12.5 KB
references/threejs-builder-refs/gltf-loading.mdmarkdown8.6 KB
references/threejs-builder-refs/performance-patterns.mdmarkdown11.8 KB
references/threejs-builder-refs/react-three-fiber.mdmarkdown17.8 KB
references/threejs-builder-refs/shader-patterns.mdmarkdown15.0 KB
references/threejs-builder-refs/visual-polish.mdmarkdown16.3 KB
references/threejs-builder-refs/webgpu.mdmarkdown20.4 KB
references/typescript-frontend.mdmarkdown5.3 KB
references/typescript-frontend/engineering-rules.mdmarkdown7.8 KB
references/typescript-frontend/nextjs-security.mdmarkdown2.6 KB
references/typescript-frontend/react-view-transitions.mdmarkdown5.4 KB
references/ui-design.mdmarkdown10.2 KB
references/ui-design/ai-slop-detection.mdmarkdown8.5 KB
references/ui-design/design-conventions.mdmarkdown2.8 KB
references/ui-design/motion-and-interaction.mdmarkdown5.6 KB
scripts-distinctive-frontend-design/css_slop_rules.pyscript15.3 KB
scripts-distinctive-frontend-design/tests/test_css_slop_rules.pyscript6.9 KB
scripts-distinctive-frontend-design/tests/test_validate_design_advisory.pyscript3.3 KB
scripts-distinctive-frontend-design/tests/test_validate_design_macro.pyscript4.3 KB
scripts-distinctive-frontend-design/validate_design.pyscript22.2 KB
scripts-html-artifact/assemble-template.pyscript7.5 KB
scripts-html-artifact/css_slop_rules.pyscript15.4 KB
scripts-html-artifact/detect-shape.pyscript7.0 KB
scripts-html-artifact/fill-template.pyscript5.5 KB
scripts-html-artifact/pptx-bridge/__init__.pyscript490 B
scripts-html-artifact/pptx-bridge/_pptx_engine.pyscript26.4 KB
scripts-html-artifact/pptx-bridge/extract_slides.pyscript13.5 KB
scripts-html-artifact/pptx-bridge/render_pptx.pyscript6.9 KB
scripts-html-artifact/pptx-bridge/run-unified.pyscript11.6 KB
scripts-html-artifact/render-github-issues.pyscript7.5 KB
scripts-html-artifact/tests/test_assemble_template.pyscript29.5 KB
scripts-html-artifact/tests/test_css_slop_emission.pyscript7.9 KB
scripts-html-artifact/tests/test_detect_shape.pyscript5.3 KB
scripts-html-artifact/tests/test_fill_template.pyscript5.2 KB
scripts-html-artifact/tests/test_to_pdf.pyscript13.3 KB
scripts-html-artifact/tests/test_validate_artifact.pyscript13.6 KB
scripts-html-artifact/to-pdf.pyscript12.5 KB
scripts-html-artifact/validate-artifact.pyscript11.0 KB
templates/base-reset.cssother1.2 KB
templates/components/collapsible.cssother1.1 KB
templates/components/collapsible.jsscript516 B
templates/components/copy-button.cssother534 B
templates/components/copy-button.jsscript334 B
templates/components/drag-drop.cssother612 B
templates/components/drag-drop.jsscript1.1 KB
templates/components/filter.cssother1.1 KB
templates/components/filter.jsscript987 B
templates/components/keyboard-nav.cssother249 B
templates/components/keyboard-nav.jsscript900 B
templates/components/scrollytelling.cssother1.5 KB
templates/components/scrollytelling.jsscript2.0 KB
templates/components/slider.cssother848 B
templates/components/tabs.cssother770 B
templates/components/tabs.jsscript508 B
templates/components/theme-toggle.cssother1.2 KB
templates/components/theme-toggle.jsscript178 B
templates/fonts/ArchivoBlack-OFL.txtmarkdown4.4 KB
templates/fonts/archivo-black.cssother13.7 KB
templates/print/code-review-print.cssother1.9 KB
templates/print/data-viz-print.cssother1.5 KB
templates/print/deck-print.cssother1.5 KB
templates/print/default-print.cssother1.6 KB
templates/print/diagram-print.cssother1.6 KB
templates/print/editor-print.cssother2.1 KB
templates/print/prototype-print.cssother1.4 KB
templates/print/report-print.cssother1.8 KB
templates/print/spec-print.cssother1.4 KB
templates/saved/README.mdmarkdown1.8 KB
templates/saved/business-review.htmlother17.1 KB
templates/saved/business-review.slots.jsonconfig1.5 KB
templates/saved/github-issues.htmlother34.0 KB
templates/saved/project-kickoff.htmlother17.3 KB
templates/saved/project-kickoff.slots.jsonconfig1.7 KB
templates/saved/system-design.htmlother16.9 KB
templates/saved/system-design.slots.jsonconfig1.6 KB
templates/shapes/code-review.cssother2.7 KB
templates/shapes/data-viz.cssother2.3 KB
templates/shapes/deck.cssother1.9 KB
templates/shapes/diagram.cssother2.7 KB
templates/shapes/editor.cssother2.8 KB
templates/shapes/prototype.cssother2.7 KB
templates/shapes/report.cssother2.9 KB
templates/shapes/spec.cssother3.0 KB
templates/themes/birchline.cssother2.4 KB
templates/themes/dark-focus.cssother2.6 KB
templates/themes/interactive-warm.cssother4.5 KB
templates/themes/minimal-document.cssother2.6 KB

references/threejs-builder-refs/shader-patterns.md

View on GitHub
---
description: Custom GLSL shaders in Three.js — ShaderMaterial, vertex displacement, fragment effects, and EffectComposer postprocessing pipeline
agent: threejs-builder
category: visual-techniques
version_range: "Three.js r150+"
---

# Shader Patterns Reference

> **Scope**: Writing custom GLSL for Three.js — ShaderMaterial vs RawShaderMaterial, vertex displacement, fragment effects, postprocessing with EffectComposer. Does NOT cover TSL/WebGPU node materials (see webgpu.md).
> **Version range**: Three.js r150+
> **Generated**: 2026-04-08

---

## ShaderMaterial vs RawShaderMaterial

| Class | Preprocessor Includes | Built-in Uniforms | Use When |
|-------|----------------------|-------------------|----------|
| `ShaderMaterial` | Yes — Three.js injects `#include <common>`, fog, lights | `projectionMatrix`, `modelViewMatrix`, `normalMatrix` auto-bound | Custom effects that still need Three.js lighting chunks |
| `RawShaderMaterial` | None — full GLSL control | Must declare ALL uniforms manually, including matrices | Full shader control, when Three.js chunks cause conflicts |

The most common mistake: using `RawShaderMaterial` and forgetting to declare `projectionMatrix` and `modelViewMatrix`, then wondering why geometry doesn't render.

```javascript
// ShaderMaterial — Three.js injects precision, matrices, and chunk definitions
const mat = new THREE.ShaderMaterial({
  uniforms: {
    uTime: { value: 0.0 },
    uColor: { value: new THREE.Color(0x00ffcc) },
  },
  vertexShader: /* glsl */`
    uniform float uTime;
    varying vec2 vUv;

    void main() {
      vUv = uv;
      // projectionMatrix and modelViewMatrix are injected by Three.js
      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
    }
  `,
  fragmentShader: /* glsl */`
    uniform vec3 uColor;
    varying vec2 vUv;

    void main() {
      gl_FragColor = vec4(uColor * vUv.x, 1.0);
    }
  `,
});

// In animation loop:
mat.uniforms.uTime.value = clock.getElapsedTime();
```

```javascript
// RawShaderMaterial — must declare ALL uniforms and precision
const mat = new THREE.RawShaderMaterial({
  uniforms: {
    uTime: { value: 0.0 },
  },
  vertexShader: /* glsl */`
    precision mediump float;

    uniform mat4 projectionMatrix;
    uniform mat4 modelViewMatrix;
    uniform float uTime;
    attribute vec3 position;
    attribute vec2 uv;
    varying vec2 vUv;

    void main() {
      vUv = uv;
      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
    }
  `,
  fragmentShader: /* glsl */`
    precision mediump float;
    varying vec2 vUv;

    void main() {
      gl_FragColor = vec4(vUv, 0.5, 1.0);
    }
  `,
});
```

---

## Vertex Displacement Shaders

### Noise-Based Terrain

```javascript
// Simplex noise via glsl-noise (CDN) or inline implementation
// Three.js r150+ includes ShaderChunk — use #include <common> for noise utilities

const terrainMat = new THREE.ShaderMaterial({
  uniforms: {
    uTime: { value: 0 },
    uStrength: { value: 2.0 },
    uFrequency: { value: 0.5 },
  },
  vertexShader: /* glsl */`
    #include <common>  // includes noise utilities in Three.js r150+

    uniform float uTime;
    uniform float uStrength;
    uniform float uFrequency;
    varying float vElevation;

    // Classic Perlin noise — available after #include <common>
    void main() {
      vec4 modelPosition = modelMatrix * vec4(position, 1.0);

      float elevation =
        sin(modelPosition.x * uFrequency + uTime) *
        sin(modelPosition.z * uFrequency + uTime) *
        uStrength;

      modelPosition.y += elevation;
      vElevation = elevation;

      gl_Position = projectionMatrix * viewMatrix * modelPosition;
    }
  `,
  fragmentShader: /* glsl */`
    varying float vElevation;

    void main() {
      // Map elevation to color gradient
      float t = (vElevation + 2.0) / 4.0; // normalize to 0-1
      vec3 low  = vec3(0.04, 0.08, 0.2);  // deep water
      vec3 high = vec3(0.8, 0.95, 0.9);   // snow cap
      gl_FragColor = vec4(mix(low, high, t), 1.0);
    }
  `,
  side: THREE.DoubleSide,
  wireframe: false,
});
```

### Water Wave Displacement

```javascript
// Key pattern: multi-octave wave displacement with layered cnoise ripples
const waterMat = new THREE.ShaderMaterial({
  uniforms: {
    uTime: { value: 0 },
    uBigWavesElevation: { value: 0.2 },
    uBigWavesFrequency: { value: new THREE.Vector2(4, 1.5) },
    uSmallWavesElevation: { value: 0.15 },
    uDepthColor: { value: new THREE.Color('#186691') },
    uSurfaceColor: { value: new THREE.Color('#9bd8ff') },
  },
  vertexShader: /* glsl */`
    #include <common>
    uniform float uTime;
    uniform vec2 uBigWavesFrequency;
    uniform float uBigWavesElevation;
    uniform float uSmallWavesElevation;
    varying float vElevation;
    void main() {
      vec4 modelPosition = modelMatrix * vec4(position, 1.0);
      float elevation =
        sin(modelPosition.x * uBigWavesFrequency.x + uTime) *
        sin(modelPosition.z * uBigWavesFrequency.y + uTime) *
        uBigWavesElevation;
      // Layer 3 octaves of cnoise for organic ripples
      for(float i = 1.0; i <= 3.0; i++) {
        elevation -= abs(cnoise(vec3(modelPosition.xz * 3.0 * i, uTime * 0.2))) * uSmallWavesElevation / i;
      }
      modelPosition.y += elevation;
      vElevation = elevation;
      gl_Position = projectionMatrix * viewMatrix * modelPosition;
    }
  `,
  fragmentShader: /* glsl */`
    uniform vec3 uDepthColor;
    uniform vec3 uSurfaceColor;
    varying float vElevation;
    void main() {
      gl_FragColor = vec4(mix(uDepthColor, uSurfaceColor, (vElevation + 0.1) * 5.0), 1.0);
    }
  `,
});
```

---

## Fragment Shader Effects

### Holographic Effect

```javascript
const holoMat = new THREE.ShaderMaterial({
  uniforms: {
    uTime: { value: 0 },
    uColor: { value: new THREE.Color(0x70c5e8) },
  },
  transparent: true,
  side: THREE.DoubleSide,
  depthWrite: false,
  blending: THREE.AdditiveBlending,
  vertexShader: /* glsl */`
    varying vec2 vUv;
    varying float vNormal;
    void main() {
      vUv = uv;
      vec4 normalModelView = normalMatrix * vec4(normal, 0.0);
      // Fresnel-like rim lighting
      vNormal = abs(dot(normalize(normalModelView.xyz), vec3(0,0,1)));
      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
    }
  `,
  fragmentShader: /* glsl */`
    uniform float uTime;
    uniform vec3 uColor;
    varying vec2 vUv;
    varying float vNormal;

    void main() {
      // Horizontal scan lines
      float scanLine = step(0.5, fract(vUv.y * 50.0 - uTime * 0.5));
      // Rim glow (edges = bright)
      float rim = 1.0 - vNormal;
      float alpha = (scanLine * 0.1 + rim * 0.5) * 0.85;
      gl_FragColor = vec4(uColor, alpha);
    }
  `,
});
```

### Dissolve Shader

```javascript
const dissolveMat = new THREE.ShaderMaterial({
  uniforms: {
    uTime: { value: 0 },
    uProgress: { value: 0 },   // 0 = solid, 1 = fully dissolved
    uEdgeColor: { value: new THREE.Color(0xff6600) },
    uNoiseScale: { value: 3.0 },
  },
  transparent: true,
  side: THREE.DoubleSide,
  vertexShader: /* glsl */`
    varying vec2 vUv;
    void main() {
      vUv = uv;
      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
    }
  `,
  fragmentShader: /* glsl */`
    #include <common>
    uniform float uProgress;
    uniform vec3 uEdgeColor;
    uniform float uNoiseScale;
    varying vec2 vUv;

    void main() {
      float noise = cnoise(vec3(vUv * uNoiseScale, 0.0)) * 0.5 + 0.5;
      float edge = 0.05; // edge band width

      if (noise < uProgress) discard; // dissolve away

      float edgeMix = smoothstep(uProgress, uProgress + edge, noise);
      vec3 color = mix(uEdgeColor, vec3(1.0), edgeMix);
      float alpha = step(uProgress + edge, noise) * 1.0 + (1.0 - edgeMix) * 0.8;

      gl_FragColor = vec4(color, alpha);
    }
  `,
});
```

### Chromatic Aberration (Postprocessing Shader)

```javascript
// Use as EffectComposer ShaderPass
const ChromaticAberrationShader = {
  uniforms: {
    tDiffuse: { value: null },
    uOffset: { value: new THREE.Vector2(0.003, 0.003) },
  },
  vertexShader: /* glsl */`
    varying vec2 vUv;
    void main() {
      vUv = uv;
      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
    }
  `,
  fragmentShader: /* glsl */`
    uniform sampler2D tDiffuse;
    uniform vec2 uOffset;
    varying vec2 vUv;
    void main() {
      float r = texture2D(tDiffuse, vUv + uOffset).r;
      float g = texture2D(tDiffuse, vUv).g;
      float b = texture2D(tDiffuse, vUv - uOffset).b;
      gl_FragColor = vec4(r, g, b, 1.0);
    }
  `,
};
```

---

## Postprocessing Pipeline with EffectComposer

```javascript
import { EffectComposer } from 'three/addons/postprocessing/EffectComposer.js';
import { RenderPass } from 'three/addons/postprocessing/RenderPass.js';
import { UnrealBloomPass } from 'three/addons/postprocessing/UnrealBloomPass.js';
import { ShaderPass } from 'three/addons/postprocessing/ShaderPass.js';
import { SSAOPass } from 'three/addons/postprocessing/SSAOPass.js';
import { OutputPass } from 'three/addons/postprocessing/OutputPass.js';

const composer = new EffectComposer(renderer);

// 1. Base render pass — always first
composer.addPass(new RenderPass(scene, camera));

// 2. SSAO — ambient occlusion adds depth (r150+)
const ssaoPass = new SSAOPass(scene, camera, width, height);
ssaoPass.kernelRadius = 16;
ssaoPass.minDistance = 0.005;
ssaoPass.maxDistance = 0.1;
composer.addPass(ssaoPass);

// 3. Bloom — selective bloom via layers (r150+)
const bloomPass = new UnrealBloomPass(
  new THREE.Vector2(width, height),
  1.5,   // strength: 0-3, start at 1.5
  0.4,   // radius: 0-1
  0.85   // threshold: 0-1 (luminance required to bloom)
);
composer.addPass(bloomPass);

// 4. Custom shader passes
composer.addPass(new ShaderPass(ChromaticAberrationShader));

// 5. Output — color space correction (required in r150+, replaces GammaCorrectionShader)
composer.addPass(new OutputPass());

// In animation loop — use composer.render() instead of renderer.render()
renderer.setAnimationLoop((time) => {
  controls.update();
  composer.render();  // NOT renderer.render(scene, camera)
});

// Resize handler
window.addEventListener('resize', () => {
  composer.setSize(window.innerWidth, window.innerHeight);
  bloomPass.resolution.set(window.innerWidth, window.innerHeight);
});
```

---

## Uniform Patterns and Texture Sampling

### Passing Textures as Uniforms

```javascript
const textureLoader = new THREE.TextureLoader();
const texture = textureLoader.load('/textures/diffuse.jpg');

const mat = new THREE.ShaderMaterial({
  uniforms: {
    uTexture: { value: texture },       // sampler2D
    uTime: { value: 0 },                // float
    uResolution: { value: new THREE.Vector2(width, height) }, // vec2
    uMouse: { value: new THREE.Vector2() },  // vec2
  },
  fragmentShader: /* glsl */`
    uniform sampler2D uTexture;
    uniform float uTime;
    uniform vec2 uResolution;
    varying vec2 vUv;

    void main() {
      // Animated UV distortion using texture
      vec2 distortedUv = vUv + vec2(
        sin(vUv.y * 10.0 + uTime) * 0.02,
        cos(vUv.x * 10.0 + uTime) * 0.02
      );
      vec4 texColor = texture2D(uTexture, distortedUv);
      gl_FragColor = texColor;
    }
  `,
});
```

---

## Pattern Catalog

### Create ShaderMaterial Once, Update Uniforms Per Frame

**Detection**:
```bash
grep -rn "new THREE.ShaderMaterial" --include="*.js" --include="*.ts"
rg "new THREE\.ShaderMaterial" --type js
```

**Signal**:
```javascript
renderer.setAnimationLoop((time) => {
  // BAD: creates new material every frame — leaks GPU memory
  mesh.material = new THREE.ShaderMaterial({
    uniforms: { uTime: { value: time } },
    ...
  });
  renderer.render(scene, camera);
});
```

**Why this matters**: GPU memory leak. Each new `ShaderMaterial` allocates shader programs on the GPU. After 60 seconds at 60fps, you've allocated 3600 programs that are never freed.

**Preferred action**:
```javascript
// Create once, update uniform
const mat = new THREE.ShaderMaterial({ uniforms: { uTime: { value: 0 } }, ... });
mesh.material = mat;

renderer.setAnimationLoop((time) => {
  mat.uniforms.uTime.value = time * 0.001; // update, don't recreate
  renderer.render(scene, camera);
});
```

---

### Add OutputPass as Final Composer Pass

**Detection**:
```bash
grep -rn "EffectComposer" --include="*.js" --include="*.ts" -l
rg "GammaCorrectionShader" --type js
```

**Signal**:
```javascript
// r150+ — GammaCorrectionShader is deprecated, OutputPass is required
import { GammaCorrectionShader } from 'three/addons/shaders/GammaCorrectionShader.js'; // deprecated r154+
```

**Why this matters**: In Three.js r150+, `renderer.outputColorSpace` defaults to `SRGBColorSpace`. Without `OutputPass` at the end of the composer chain, colors appear washed out or double-gamma-corrected.

**Preferred action**:
```javascript
import { OutputPass } from 'three/addons/postprocessing/OutputPass.js';
composer.addPass(new OutputPass()); // always last pass
```

**Version note**: `OutputPass` introduced in r152. For r148-r151, use `ShaderPass(GammaCorrectionShader)` as last pass.

---

### Prefer ShaderMaterial Over onBeforeCompile Patching

**Detection**:
```bash
grep -rn "onBeforeCompile" --include="*.js" --include="*.ts"
rg "shader\.vertexShader\.replace" --type js
```

**Signal**:
```javascript
material.onBeforeCompile = (shader) => {
  shader.vertexShader = shader.vertexShader.replace(
    '#include <begin_vertex>',
    `vec3 transformed = position + vec3(sin(uTime), 0.0, 0.0);`
  );
};
```

**Why this matters**: `#include` tokens change between Three.js versions. Replacing `<begin_vertex>` in r155 may not match the chunk in r160. The material silently renders incorrectly with no error.

**Preferred action**: Use `ShaderMaterial` for custom vertex displacement instead of patching `onBeforeCompile`. Reserve `onBeforeCompile` only for lightweight additions to standard materials (fog, lights) where a custom `ShaderMaterial` would be too verbose.

---

## Error-Fix Mappings

| Error | Root Cause | Fix |
|-------|-----------|-----|
| `WebGL: INVALID_OPERATION: uniform not set` | Uniform declared in GLSL but not in `uniforms: {}` object | Add missing uniform key with initial value |
| `THREE.WebGLProgram: Shader error — 'cnoise' undefined` | Using `cnoise` without `#include <common>` in ShaderMaterial | Add `#include <common>` at top of vertex shader |
| Black screen with EffectComposer | Missing `OutputPass` or `GammaCorrectionShader` | Add `composer.addPass(new OutputPass())` as final pass |
| `Cannot read 'value' of undefined` | Accessing `mat.uniforms.uTime` before material created | Create material before animation loop, guard `if (!mat.uniforms)` |
| Bloom affecting UI elements | No bloom layer separation | Set emissive objects to `mesh.layers.enable(BLOOM_LAYER)`, use selective bloom technique |

---

## See Also

- `references/threejs-builder-refs/visual-polish.md` — HDR environments, PBR material recipes, lighting setups
- `references/threejs-builder-refs/webgpu.md` — TSL node materials for WebGPU renderer (different system)
- `references/threejs-builder-refs/performance-patterns.md` — InstancedMesh, BufferGeometry optimization
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall