shaders

---
name: "shaders"
description: "Design, implement, adapt, and verify production-ready shader-powered website sections, primarily for React and Next.js. Use for WebGL, WebGPU, GLSL, Three.js, React Three Fiber, html-in-canvas, procedural visuals, interactive backgrounds, hero sections, product showcases, feature lists, CTAs, image or video distortion, particles, portals, scroll transitions, or DOM effects where a shader should support real website content rather than become a standalone graphics demo."
license: "MIT"
---

# Shaders

Create a section with one clear visual idea, a small client-side rendering island, real DOM content, and an intentional fallback. Treat the shader as art direction and interaction support—not decoration pasted behind a layout.

## Workflow

1. Inspect before choosing a renderer.
   - Read the repository `README.md` and applicable `AGENTS.md`.
   - Inspect `package.json`, routes, styling, motion libraries, design tokens, browser targets, and nearby section implementations.
   - Preserve the existing stack. Do not introduce React Three Fiber, Three.js, GSAP, Tailwind, Shaders, or another package merely because it is familiar.
   - If the request includes a visual reference, inspect both the rendered reference and any available source. Recreate the mechanics and composition; do not copy branding, content, or proprietary assets.

2. Write a five-line section brief before coding.
   - **Role:** hero, product showcase, feature narrative, transition, CTA, background, or DOM treatment.
   - **Focal subject:** the one object, field, image, or action the eye should follow.
   - **Input:** idle time, pointer, scroll, drag, route state, or none.
   - **Restraint:** what remains static, monochrome, or quiet.
   - **Fallback:** still image, CSS atmosphere, poster frame, plain DOM, or simplified WebGL.

3. Select the smallest appropriate rendering path.
   - Read [architecture-and-recipes.md](references/architecture-and-recipes.md).
   - Prefer an installed project primitive or a single fullscreen pass before adopting a scene graph.
   - For a fullscreen or bounded pass with no project primitive, start from this skill's [assets](assets/README.md): a zero-dependency WebGL2 engine, pointer tracker, particle field, six original fragments (mist, silk wind, chromatic flow, portal, dither gradient, media distortion), and React recipes for hero, feature-card, and notification-pill sections. Copy into the project and adapt; do not import across repositories.
   - Use Three.js or React Three Fiber when the section actually needs 3D geometry, cameras, raycasting, instancing, PBR materials, or model interaction.
   - Use an html-in-canvas component only when distorting live DOM is the concept and its experimental-browser fallback is acceptable.
   - Recreate mechanics from references instead of copying their source. Verify the license of any pen, repo, or library before adapting its code; several popular shader demos (for example the Sabo Sugi CodePens) are non-commercial by default.

4. Keep ownership boundaries explicit.
   - Let the DOM own headings, copy, links, forms, prices, and primary controls.
   - Let the renderer own pixels, textures, geometry, uniforms, hit testing, and its animation loop.
   - Let React own coarse state such as selected product or active feature. Keep frame-by-frame values in refs, uniforms, or the rendering engine—not React state.
   - Use one normalized driver for coordinated scroll sequences rather than several timelines fighting over the same section.

5. Implement the section as a contained client island.
   - Read [react-nextjs.md](references/react-nextjs.md) before editing React or Next.js code.
   - Keep the Server Component boundary around static content when possible.
   - Dynamically load a browser-only renderer when its module touches `window`, WebGL, or WebGPU at import time.
   - Size the canvas from its section container. Do not assume the full viewport unless the section is explicitly full-bleed.
   - Expose a small, typed art-direction surface: colors, intensity, speed, seed, interaction strength, and class names. Avoid leaking low-level uniforms into page code.

6. Design all interaction states, not only desktop hover.
   - Define idle, active, leaving, touch, keyboard, reduced-motion, off-screen, and renderer-failure behavior.
   - Smooth pointer position, direction, and velocity before uploading them. Decay momentum instead of snapping values to zero.
   - Give touch an explicit tap or drag model; never rely on hover as the only way to understand or activate content.
   - Mirror meaningful canvas selection in semantic DOM controls and focus states.

7. Tune in this order.
   - Composition and crop.
   - Text contrast across representative frames.
   - Motion timing and input response.
   - Color and material response.
   - Detail, particles, grain, bloom, or chromatic separation last.
   - Remove effects that compete with the section's message.

8. Match the look, not just the mechanism.
   - When the brief includes a visual reference, read [look-development.md](references/look-development.md) and decompose the reference (ground, structure, softness, anisotropy, palette, compositing, motion, composition) before writing GLSL.
   - Run the render–critique loop: harness mirroring the real composition, screenshot, critique in the failure-mode vocabulary, change the owning mechanism variable, re-render. Iterate at least twice; verify a second frame at a later time.
   - Do not present a reference-driven shader whose renders you have not looked at.

9. Verify the result.
   - Read [quality-and-qa.md](references/quality-and-qa.md).
   - Run the repository's relevant typecheck, lint, tests, and production build.
   - Exercise desktop, narrow mobile, touch, keyboard, reduced motion, route remount, and unsupported-renderer fallback.
   - Inspect for duplicate canvases, leaked animation frames, layout shift, unreadable frames, console errors, and resources that survive unmount.

## Core defaults

- Preserve the project's design system, components, easing curves, typography, CSS strategy, and dependency policy.
- Keep one dominant shader gesture per viewport. Use calmer editorial space around it.
- Keep chromatic effects in the media layer unless the established brand system says otherwise.
- Render decorative canvases with `aria-hidden="true"` and no pointer interception.
- Use `dvh`/`svh` and safe-area insets for full-height sections.
- Respect `prefers-reduced-motion`; a static shader frame can be a valid reduced-motion treatment.
- Pause loops when off-screen or hidden, cap device pixel ratio, resize from the container, and dispose GPU resources on unmount.
- Feature-detect WebGPU/WebGL. Never make core content depend on successful GPU initialization.
- Prefer deterministic seeds so visual QA and screenshots are reproducible.
- Avoid full-screen blur, gratuitous glow, random neon palettes, and constant cursor pursuit unless the brief requires them.
- Preserve Korean line breaking with `word-break: keep-all`; never justify Korean body copy.

## Reference routing

- Read [architecture-and-recipes.md](references/architecture-and-recipes.md) to choose a renderer or adapt a shader to a hero, product, feature, transition, or DOM effect.
- Read [look-development.md](references/look-development.md) whenever the request includes a visual reference or the result must reach taste-level quality: reference decomposition, the soft-field grammar (anisotropy, OKLab compositing, dither), and the mandatory render–critique loop.
- Read [assets/README.md](assets/README.md) before implementing a fullscreen or bounded pass; copy and adapt the engine, fragments, and React recipes there instead of writing a new engine from scratch.
- Read [react-nextjs.md](references/react-nextjs.md) before writing React/Next.js integration, lifecycle, props, or SSR code.
- Read [quality-and-qa.md](references/quality-and-qa.md) for art direction, accessibility, performance, fallbacks, and the verification matrix.
- Read [research-notes.md](references/research-notes.md) when the user asks for inspiration provenance, one of the researched examples (Canvas UI, Shaders, the Sabo Sugi demos, "mist.and.memory", Soal Labs, the casebook master prompt, Codrops case studies), or before reusing any referenced source, to check its recorded license status.

## Completion contract

Do not call a shader section complete until:

- the semantic section works with the renderer disabled;
- the visual has a documented purpose and bounded region;
- pointer, touch, keyboard, and reduced-motion behavior are defined;
- the renderer pauses and cleans up correctly;
- fallback output is intentional rather than a blank canvas;
- reference-driven visuals passed the render–critique loop (screenshots actually reviewed);
- relevant source checks pass; and
- the user can tune the major visual decisions without editing shader internals.