GPU surface
A shader or a 3D scene is the loudest thing a page can carry. It costs a
second WebGL context, a JavaScript chunk, battery on a phone, and attention.
This skill decides whether the page earns it, then builds it so the still
version is as considered as the moving one.
1. Earn it — before any install
- Read the repo's rules. In
taste.md, design.md, and TASTE.md/DESIGN.md,
search for gradient, glass, 3D, WebGL, canvas, motion, and set-piece. When
a line refuses the effect, stop and quote it. A tutorial recommending the
effect does not outrank the repo.
- One GPU surface per page. Count what the route already renders:
grep -rnE "<Canvas|ShaderMount|@paper-design/shaders|@react-three/fiber" app components,
then follow the imports into the route. When one exists, the new surface
replaces it or does not ship. When the repo caps scroll set-pieces at one
per page, a GPU hero counts toward that cap too.
- Name its job in one sentence. For example, it frames the product, carries the
brand mark, or shows a state change. "Makes it look premium" is not a job.
- Try the static version first. A token-coloured CSS gradient, an
optimised image, or an exported SVG noise texture costs no JavaScript and no
GPU. When the static version does the job, ship that and stop here.
2. Pick the engine
| Need |
Use |
Why |
| Moving gradient, grain, noise, god rays, liquid metal on a logo, glass distortion over an image |
@paper-design/shaders-react |
One fragment shader on one canvas, no three.js. It pauses itself when off-screen and when the tab is hidden. Static* variants exist. |
| Real geometry, camera, lights, models, or 3D interaction |
@react-three/fiber + @react-three/drei |
A full scene graph, and the heaviest option. Only when the job needs depth. |
| Frosted glass panels over DOM content |
CSS backdrop-filter first |
A refraction library only when the brand file asks for refraction. The npm package named liquid-glass-js is not the dashersw/liquid-glass-js repository. |
| ShaderGradient |
Prefer Paper's MeshGradient or GrainGradient |
As of 2026-10-20, @shadergradient/react was last published 2025-12-08 and runs on the three.js stack for what Paper does in a single shader. |
Before installing:
- Check peers. Run
node .claude/skills/web-steward/peer-check.mjs --root ..
R3F 9 and drei 10 declare React 19 peers. On React 18, either move to R3F 8
or upgrade React first (a web-steward job). Do not install over an unmet peer.
- Pin
0.x packages exactly (pnpm add -E / npm i -E). Paper Shaders is
0.0.x, where any release may change behaviour.
3. Build — the wrapper contract
Every surface goes through one wrapper under components/effects/, so there is
one place to audit, budget, and swap engines. The contract:
- Client-only and late. Load it with
next/dynamic and { ssr: false }.
Use a static named import inside a leaf module, so the package tree-shakes to
the one shader in use.
- A poster underneath. The container paints a token colour or a CSS
gradient, so the page looks intentional at first paint, before WebGL, and
without WebGL. The canvas is
aria-hidden.
- Check for WebGL2 first. Without WebGL2, Paper throws inside an effect,
which leaves a console error. Check and skip, so the poster stays and the
console stays clean.
- An art-directed still. Under
prefers-reduced-motion: reduce, render
speed={0} at a chosen frame. Pick the frame by looking at it; it is the
version a reduced-motion reader gets, so design it instead of accepting frame 0.
- Token colours only. Read them from
design.md or the Tailwind config,
never from the library's demo presets.
- Slow and readable. Start at
speed 0.1–0.3. Text over the surface must
pass contrast on its brightest frame, not its average one.
- A pixel ceiling. Set
maxPixelCount (Paper's default allows 1920×1080×4).
For R3F, pass dpr={[1, 1.5]} and frameloop="demand" unless the scene must
animate continuously. R3F does not pause off-screen on its own.
Reference implementation for Paper. LiquidMetal, GrainGradient, and FlutedGlass
follow the same shape:
// components/effects/MeshGradientLayer.tsx — the only file that imports the shader package
'use client'
import { MeshGradient, type MeshGradientProps } from '@paper-design/shaders-react'
export default function MeshGradientLayer(props: MeshGradientProps) {
return <MeshGradient {...props} />
}
// components/effects/ShaderSurface.tsx
'use client'
import dynamic from 'next/dynamic'
import { useEffect, useState, useSyncExternalStore, type ReactNode } from 'react'
import type { MeshGradientProps } from '@paper-design/shaders-react'
// Never rendered on the server and loaded after hydration, so it cannot hold up first paint.
const MeshGradientLayer = dynamic(() => import('./MeshGradientLayer'), { ssr: false })
const REDUCED = '(prefers-reduced-motion: reduce)'
function subscribeReduced(onChange: () => void) {
const query = window.matchMedia(REDUCED)
query.addEventListener('change', onChange)
return () => query.removeEventListener('change', onChange)
}
// Paper throws inside an effect when WebGL2 is missing; checking first keeps the poster and a clean console.
function hasWebGL2() {
const gl = document.createElement('canvas').getContext('webgl2')
gl?.getExtension('WEBGL_lose_context')?.loseContext()
return Boolean(gl)
}
type ShaderSurfaceProps = {
/** Token values only. */
colors: string[]
/** Shown under reduced motion, and the frame the animation starts from. */
stillFrame: number
/** Painted before and without WebGL: a token colour or a CSS gradient. */
poster: string
speed?: number
className?: string
children?: ReactNode
} & Pick<MeshGradientProps, 'distortion' | 'swirl' | 'grainMixer' | 'grainOverlay'>
export function ShaderSurface({
colors,
stillFrame,
poster,
speed = 0.2,
className = '',
children,
...look
}: ShaderSurfaceProps) {
const reduced = useSyncExternalStore(subscribeReduced, () => window.matchMedia(REDUCED).matches, () => true)
const [gpu, setGpu] = useState(false)
useEffect(() => setGpu(hasWebGL2()), [])
// Inline, not utility classes: the canvas sits at z-index -1 and must stay inside this stacking context.
return (
<div className={className} style={{ position: 'relative', isolation: 'isolate', overflow: 'hidden', background: poster }}>
{gpu && (
<MeshGradientLayer
aria-hidden
colors={colors}
{...look}
speed={reduced ? 0 : speed}
frame={stillFrame}
maxPixelCount={1920 * 1080}
style={{ position: 'absolute', inset: 0, zIndex: -1 }}
/>
)}
{children}
</div>
)
}
className carries size and placement only. Keep the inline positioning and
the behaviour. This shape was type-checked against Next 16 and
@paper-design/shaders-react@0.0.81 and rendered in headless Chromium in three
states: animated (canvas moving), reduced motion (canvas still at the chosen
frame), and WebGL disabled (no canvas, poster shown). All three left zero
console errors.
4. Prove
Run inside web-release-gate phases 4 and 5, plus:
visual-proof after-shots at 375 / 768 / 1440, light and dark, then again
with --reduced-motion --label after-reduced. Open the reduced shots; the
still must tell the same story.
core-web-vitals: the route's first-load JS before and after, read from the
build output. The canvas must not be the LCP element; the headline stays it.
- Contrast of text over the brightest frame.
- A real phone if one is available; otherwise write "not tested on a device".
Add this line to the gate's "Done means" block:
GPU: <engine>@<exact version> on <route> — job: <one sentence>; still frame <n>;
first-load JS <before> → <after>; reduced-motion shots <path>; device: <tested | not tested>
Refusals
- A second GPU surface on the same page.
- A moving surface behind body copy. Headlines and short labels only, at
passing contrast.
- An effect the repo's taste file refuses, whoever recommends it.
- A library's demo palette instead of the repo's tokens.
- A WebGL dependency for something a CSS gradient, an image, or an SVG already does.
1---2name: gpu-surface3description: Decide on, build, and prove one GPU-rendered surface on a web page — a WebGL shader background (mesh gradient, grain, liquid metal on a logo, fluted glass) or a React Three Fiber scene. Use when a task adds, changes, or reviews a canvas, shader, or 3D element; when someone shares a ShaderGradient, Paper Shaders, Liquid Logo, Liquid Glass, three.js, or react-three-fiber link and asks for the effect; or before installing @paper-design/shaders-react, @react-three/fiber, three, or a similar package. Checks the repo's taste rules first, picks the lightest engine, and defines the wrapper, the reduced-motion still, the budget, and the proof. Runs inside web-release-gate phase 3.4metadata:5 source: https://skillmd.com/skills/frankxai/gpu-surface6---78# GPU surface910A shader or a 3D scene is the loudest thing a page can carry. It costs a11second WebGL context, a JavaScript chunk, battery on a phone, and attention.12This skill decides whether the page earns it, then builds it so the still13version is as considered as the moving one.1415## 1. Earn it — before any install16171. **Read the repo's rules.** In `taste.md`, `design.md`, and `TASTE.md`/`DESIGN.md`,18 search for gradient, glass, 3D, WebGL, canvas, motion, and set-piece. When19 a line refuses the effect, stop and quote it. A tutorial recommending the20 effect does not outrank the repo.212. **One GPU surface per page.** Count what the route already renders:22 `grep -rnE "<Canvas|ShaderMount|@paper-design/shaders|@react-three/fiber" app components`,23 then follow the imports into the route. When one exists, the new surface24 replaces it or does not ship. When the repo caps scroll set-pieces at one25 per page, a GPU hero counts toward that cap too.263. **Name its job in one sentence.** For example, it frames the product, carries the27 brand mark, or shows a state change. "Makes it look premium" is not a job.284. **Try the static version first.** A token-coloured CSS gradient, an29 optimised image, or an exported SVG noise texture costs no JavaScript and no30 GPU. When the static version does the job, ship that and stop here.3132## 2. Pick the engine3334| Need | Use | Why |35|---|---|---|36| Moving gradient, grain, noise, god rays, liquid metal on a logo, glass distortion over an image | `@paper-design/shaders-react` | One fragment shader on one canvas, no three.js. It pauses itself when off-screen and when the tab is hidden. `Static*` variants exist. |37| Real geometry, camera, lights, models, or 3D interaction | `@react-three/fiber` + `@react-three/drei` | A full scene graph, and the heaviest option. Only when the job needs depth. |38| Frosted glass panels over DOM content | CSS `backdrop-filter` first | A refraction library only when the brand file asks for refraction. The npm package named `liquid-glass-js` is not the `dashersw/liquid-glass-js` repository. |39| ShaderGradient | Prefer Paper's `MeshGradient` or `GrainGradient` | As of 2026-10-20, `@shadergradient/react` was last published 2025-12-08 and runs on the three.js stack for what Paper does in a single shader. |4041Before installing:4243- **Check peers.** Run `node .claude/skills/web-steward/peer-check.mjs --root .`.44 R3F 9 and drei 10 declare React 19 peers. On React 18, either move to R3F 845 or upgrade React first (a `web-steward` job). Do not install over an unmet peer.46- **Pin `0.x` packages exactly** (`pnpm add -E` / `npm i -E`). Paper Shaders is47 0.0.x, where any release may change behaviour.4849## 3. Build — the wrapper contract5051Every surface goes through one wrapper under `components/effects/`, so there is52one place to audit, budget, and swap engines. The contract:5354- **Client-only and late.** Load it with `next/dynamic` and `{ ssr: false }`.55 Use a static named import inside a leaf module, so the package tree-shakes to56 the one shader in use.57- **A poster underneath.** The container paints a token colour or a CSS58 gradient, so the page looks intentional at first paint, before WebGL, and59 without WebGL. The canvas is `aria-hidden`.60- **Check for WebGL2 first.** Without WebGL2, Paper throws inside an effect,61 which leaves a console error. Check and skip, so the poster stays and the62 console stays clean.63- **An art-directed still.** Under `prefers-reduced-motion: reduce`, render64 `speed={0}` at a chosen `frame`. Pick the frame by looking at it; it is the65 version a reduced-motion reader gets, so design it instead of accepting frame 0.66- **Token colours only.** Read them from `design.md` or the Tailwind config,67 never from the library's demo presets.68- **Slow and readable.** Start at `speed` 0.1–0.3. Text over the surface must69 pass contrast on its brightest frame, not its average one.70- **A pixel ceiling.** Set `maxPixelCount` (Paper's default allows 1920×1080×4).71 For R3F, pass `dpr={[1, 1.5]}` and `frameloop="demand"` unless the scene must72 animate continuously. R3F does not pause off-screen on its own.7374Reference implementation for Paper. LiquidMetal, GrainGradient, and FlutedGlass75follow the same shape:7677```tsx78// components/effects/MeshGradientLayer.tsx — the only file that imports the shader package79'use client'8081import { MeshGradient, type MeshGradientProps } from '@paper-design/shaders-react'8283export default function MeshGradientLayer(props: MeshGradientProps) {84 return <MeshGradient {...props} />85}86```8788```tsx89// components/effects/ShaderSurface.tsx90'use client'9192import dynamic from 'next/dynamic'93import { useEffect, useState, useSyncExternalStore, type ReactNode } from 'react'94import type { MeshGradientProps } from '@paper-design/shaders-react'9596// Never rendered on the server and loaded after hydration, so it cannot hold up first paint.97const MeshGradientLayer = dynamic(() => import('./MeshGradientLayer'), { ssr: false })9899const REDUCED = '(prefers-reduced-motion: reduce)'100101function subscribeReduced(onChange: () => void) {102 const query = window.matchMedia(REDUCED)103 query.addEventListener('change', onChange)104 return () => query.removeEventListener('change', onChange)105}106107// Paper throws inside an effect when WebGL2 is missing; checking first keeps the poster and a clean console.108function hasWebGL2() {109 const gl = document.createElement('canvas').getContext('webgl2')110 gl?.getExtension('WEBGL_lose_context')?.loseContext()111 return Boolean(gl)112}113114type ShaderSurfaceProps = {115 /** Token values only. */116 colors: string[]117 /** Shown under reduced motion, and the frame the animation starts from. */118 stillFrame: number119 /** Painted before and without WebGL: a token colour or a CSS gradient. */120 poster: string121 speed?: number122 className?: string123 children?: ReactNode124} & Pick<MeshGradientProps, 'distortion' | 'swirl' | 'grainMixer' | 'grainOverlay'>125126export function ShaderSurface({127 colors,128 stillFrame,129 poster,130 speed = 0.2,131 className = '',132 children,133 ...look134}: ShaderSurfaceProps) {135 const reduced = useSyncExternalStore(subscribeReduced, () => window.matchMedia(REDUCED).matches, () => true)136 const [gpu, setGpu] = useState(false)137 useEffect(() => setGpu(hasWebGL2()), [])138139 // Inline, not utility classes: the canvas sits at z-index -1 and must stay inside this stacking context.140 return (141 <div className={className} style={{ position: 'relative', isolation: 'isolate', overflow: 'hidden', background: poster }}>142 {gpu && (143 <MeshGradientLayer144 aria-hidden145 colors={colors}146 {...look}147 speed={reduced ? 0 : speed}148 frame={stillFrame}149 maxPixelCount={1920 * 1080}150 style={{ position: 'absolute', inset: 0, zIndex: -1 }}151 />152 )}153 {children}154 </div>155 )156}157```158159`className` carries size and placement only. Keep the inline positioning and160the behaviour. This shape was type-checked against Next 16 and161`@paper-design/shaders-react@0.0.81` and rendered in headless Chromium in three162states: animated (canvas moving), reduced motion (canvas still at the chosen163frame), and WebGL disabled (no canvas, poster shown). All three left zero164console errors.165166## 4. Prove167168Run inside `web-release-gate` phases 4 and 5, plus:169170- `visual-proof` after-shots at 375 / 768 / 1440, light and dark, then again171 with `--reduced-motion --label after-reduced`. Open the reduced shots; the172 still must tell the same story.173- `core-web-vitals`: the route's first-load JS before and after, read from the174 build output. The canvas must not be the LCP element; the headline stays it.175- Contrast of text over the brightest frame.176- A real phone if one is available; otherwise write "not tested on a device".177178Add this line to the gate's "Done means" block:179180```181GPU: <engine>@<exact version> on <route> — job: <one sentence>; still frame <n>;182 first-load JS <before> → <after>; reduced-motion shots <path>; device: <tested | not tested>183```184185## Refusals186187- A second GPU surface on the same page.188- A moving surface behind body copy. Headlines and short labels only, at189 passing contrast.190- An effect the repo's taste file refuses, whoever recommends it.191- A library's demo palette instead of the repo's tokens.192- A WebGL dependency for something a CSS gradient, an image, or an SVG already does.