Webgl Shader Fx

webgl-shader-fx — the 3D/shader lab for hero moments that hold 60fps

Mission

WebGL is the most expensive pixel on the page — it either IS the signature moment or it's a defect with a GPU bill. This skill builds one earned canvas per page, budgeted before beautified, with the fallback ladder built first and the frame trace recorded before anyone says "done". "Should work" is not a state a shader can be in; it either held 60fps on a throttled device or it didn't.

When NOT to use

• Content sites and long-form reading. If people came to read, 3D behind or beside the text is decoration competing with content. Ship typography instead (design-dna-forge).
• Dashboards and data-dense product UI. Every GPU millisecond spent on ambiance is stolen from interaction latency. Hard no.
• When CSS already does it. A two-stop gradient, a simple hover scale, a masked reveal — signature-interactions handles these at 1/100th the payload.
• When nobody will maintain the fallback. If the team can't own a poster image and a context-loss handler, they can't own a canvas.
• More than one scene per page. Two competing canvases = zero signature moments and double the budget. Cut one.

Workflow

1. Earn the canvas. Confirm with wow-director that this is THE signature moment (../../references/awwwards-scoring.md allows exactly one). If it's ambiance, stop here and use CSS.
2. Write budgets before code. Draw calls 50ms), one real 3-year-old device or throttled simulator, payload sizes from the Network panel. Write the numbers down — unrecorded claims don't count.
3. Submit to award-judge with the numbers and the reduced-motion screenshots attached.

Technique library

Three.js hero scenes

Earns its place when the product/brand has a physical or spatial metaphor worth inhabiting — a device, a material, a world. Not when you "want some 3D".

• Scene budget: ** 16.7ms (desktop) / > 33ms (mobile).

1. Effect LOD: drop the post pass, halve particle counts, simplify materials.
2. Static fallback: kill the loop, show the poster. A still image at 60fps beats a scene at 12.

Evidence discipline — recreating effects seen elsewhere

Never build from an AI's guess of how an effect works — plausible-sounding shader explanations are routinely wrong. Capture truth at the GL boundary:

• Frame capture the target site with a GL call-capture tool (an open-source WebGL inspector) and read the actual draw calls, render targets, and pass structure.
• Read the real shaders: gl.getShaderSource() on captured programs, or the browser devtools' shader editor. Uniform names alone reveal the technique.
• Label every claim before building: SOURCE (read the actual shader/call stream) / PARTIAL (observed passes or uniforms, inferred the rest) / GUESS (visual inference only).
• Build from SOURCE or PARTIAL. A GUESS is not a recreation — it's a new effect you now own, and you name it honestly as such in the evidence log.

Quality gates

• [../../references/performance-budgets.md](../../references/performance-budgets.md) — the WebGL row is the law here: 60fps desktop / 30fps mobile floor, DPR ≤ 2, hero payload 3×/s; text over WebGL tested against the worst frame; no full-viewport zoom/rotation transitions.
• [../../references/awwwards-scoring.md](../../references/awwwards-scoring.md) — one signature moment only; stock 3D blobs and glass-over-mesh-gradient are on the slop list that caps Design at 6; the restraint clause decides every "one more pass?" debate.

Craft library (deep technique references)

• [../../references/threejs-webgl-craft.md](../../references/threejs-webgl-craft.md) — the 12 immutable shader rules earned over 76 calibration phases (output color-space r152 trap, normalization-constant hunts, render() sanity greps, rAF-not-tween uniforms, morph-never-at-rest, the three-part cursor sync), pixel-probe forensics, the library decision matrix, hero-source technique tiers, and the render-pipeline order.
• [../../references/gpgpu-particles-and-morph.md](../../references/gpgpu-particles-and-morph.md) — FBO ping-pong particle systems (256²=65k → 1024²=1M), curl-noise flow fields, and mesh morphing as a spring force into the field (never a lerp) with per-particle stagger — plus the honest "when NOT to GPGPU" list.
• [../../references/ascii-dot-matrix-art.md](../../references/ascii-dot-matrix-art.md) — the text-as-image family: the four-tier technique ladder (DOM halftone → canvas glyphs → WebGL glyph-atlas post-process → dot-matrix particle sculpture), the "resolve" as the signature move, and the full aesthetic pairing checklist.

Deliverables

• Scene module: feature-detected mount with full lifecycle (viewport pause, hidden pause, context-loss recovery, reduced-motion single frame).
• Fallback assets: art-directed poster image (preloaded, LCP-ready) + CSS fallback layer.
• Performance report: recorded fps trace at 4× throttle, draw-call and triangle counts, payload sizes, post-chain ms, device tested. Numbers, not adjectives.
• Adaptive ladder config: the documented rung thresholds actually shipped.
• Evidence log (recreations only): per-claim SOURCE / PARTIAL / GUESS table with capture artifacts.

Related skills

• wow-director — orchestrates the suite; approves that this page has earned a canvas at all.
• award-judge — gates the ship; bring it the perf report and reduced-motion screenshots.
• signature-interactions — DOM-level craft; the first stop before concluding an effect needs WebGL.
• motion-choreography — owns the timing system your uniforms and camera moves must speak.
• design-dna-forge — the palette and type DNA your shaders sample from; no freelance colors in GLSL.
• ux-narrative — the scroll story a camera path serves; choreograph to its beats, not the reverse.
• video-motion-studio — sometimes the honest answer is a beautifully compressed video, not a live scene.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: praveentewatia26
• Source: praveentewatia26/award-grade
• License: MIT

Install and usage instructions live in the source repository linked above.