3D surfaces, scenes and backgrounds

CSS 3D or WebGL#

The kit builds depth in two ways. CSS 3D puts real content into space, your screens, cards and text stay HTML, sharp, selectable and clickable. WebGL paints a picture behind the content, light, particles or a sphere of dots, pixel by pixel with a small shader.

Pick CSS 3D when the content itself carries the depth, such as a product screen in a turned device or pricing cards that lean toward the pointer. The 3D surfaces stand in space for this, the 3D scenes move while the page scrolls.

Pick WebGL when the picture is the stage for a message, behind a hero, a band of numbers or the call to action at the end. The 3D backgrounds take your content as children and lay it over the picture.

• 3D surfacesDevices, cards and stages in real CSS perspective.
• 3D scenesRooms that move while the page scrolls.
• 3D backgroundsLiving WebGL pictures behind your content.

Install#

Install every 3D component like any other. aiw add brings the helpers along as a dependency, depth for the CSS surfaces and webgl for the backgrounds. That is all it needs, both helpers are written in house and work without three.js.

aiw add @ai-website/device-3d @ai-website/shader-gradient

import { ShaderGradient } from '@/components/ui/shader-gradient';
import { Device3D } from '@/components/ui/device-3d';

<ShaderGradient scrim="left" scrimStrength={0.7} className="min-h-[560px]">
  <div className="kit-container grid items-center gap-12 py-24 md:grid-cols-2">
    <div>
      <h1>Your account, in one hand</h1>
      <p>Send, save and split, with one look at the whole month.</p>
    </div>
    <Device3D device="phone" angle="hero" width={280} label="Banking app on a phone">
      <img src="/app-home.avif" alt="Home screen of the app" width={390} height={844} />
    </Device3D>
  </div>
</ShaderGradient>

In Astro a 3D component gets a client directive so it runs. client:visible fits almost always, the motion starts on screen anyway.

<!-- Without a directive the still picture shows, finished and calm -->
<ShaderGradient scrim="center">…</ShaderGradient>

<!-- With a directive the shader starts once the section comes into view -->
<ShaderGradient client:visible scrim="center">…</ShaderGradient>

The WebGL helper#

webgl is a slim helper without a library. One triangle covers the canvas, the fragment shader paints every pixel. The helper takes care of everything around it, sizing with a capped pixel ratio, starting on screen, pausing out of view and in hidden tabs, theme and accent changes, pointer and scroll, a lost and restored context and the clean up on unmount.

ShaderCanvas#

ShaderBackdrop#

Every background of the kit shares the same props intensity, speed, colors, interactive, fallback and the three scrim props. Every shader receives these uniforms by itself.

Helpers for CSS 3D#

The CSS surfaces and scenes share depth. Its helpers write CSS variables straight onto the element, so a surface moves without a React render.

Text on 3D#

Text on a moving picture needs calm underneath. The scrim lays a shade in the color of the page between picture and content and follows the shape of your text block. Center suits a centered headline, left a hero with text on the left, bottom text along the lower edge and soft text across the whole area. Strong covers the most, for long paragraphs or forms.

• Check the contrast at the brightest moment of the picture, at least 4.5 to 1 for body text and 3 to 1 for large headlines.
• Inside a card the scrim takes the card color, so scrimColor="var(--card)".
• On phones the center and left scrims cover the whole area, because the text takes almost the full width there.
• Buttons and links on the picture keep their full area and focus ring, the shader never takes clicks.

Still picture and reduced motion#

Every 3D component has a still picture. For the backgrounds it is a CSS picture in the same colors, shown without JavaScript, without WebGL, until the first real frame and after a lost context, with a soft crossfade. Pass fallback for a still picture of your own.

With reduced motion the shader draws one calm frame and then rests. The CSS surfaces rest in their finished pose, scenes show every layer in order and readable. On touch devices nothing leans toward the finger, the surface keeps its resting pose.

Performance#

• The pixel ratio is capped, 1.5 on desktop and 1 on phones. For soft pictures scale halves the resolution once more.
• Phones draw 30 frames per second with u_quality at 0.55, so fewer layers and particles. Desktop runs at the rate of the display.
• A shader starts only on screen, pauses out of view and in hidden tabs and frees everything on unmount.
• CSS 3D moves only transform and opacity. Pointer and scroll run through CSS variables, not through React state.
• Every shader component is built for under 8 KB gzip and 60 frames per second on desktop. Add it with client:visible, then its code loads only shortly before it comes into view.

Your own shader#

For a background of your own you write only the fragment shader. GLSL_NOISE brings hash, noise and fbm, ACCENT_PALETTE the accent with two neighbours and a pale tint. Output premultiplied alpha, so the page shows through and one shader fits background, surface and card.

import { ShaderCanvas, ShaderBackdrop, GLSL_NOISE, ACCENT_PALETTE } from '@/components/ui/webgl';

const FRAG = `${GLSL_NOISE}
void main(){
  vec2 p = gl_FragCoord.xy / u_res;
  float n = fbm(p * 3. + vec2(u_time * .05, 0.));
  vec3 c = mix(u_c0, u_c1, n);
  float a = smoothstep(.2, .9, n) * .6 * u_intensity;
  gl_FragColor = vec4(c * a, a);
}`;

export function Mist({ children }: { children: React.ReactNode }) {
  return (
    <ShaderBackdrop
      scrim="center"
      layer={<ShaderCanvas fragment={FRAG} colors={ACCENT_PALETTE} scale={0.5} fallback="radial-gradient(60% 60% at 50% 40%, color-mix(in oklab, var(--primary) 30%, transparent), transparent)" />}
    >
      {children}
    </ShaderBackdrop>
  );
}

• 3D in VisualsEvery surface, scene and background with a live preview.
• MotionThe ground rules for motion in the kit.
• Scroll storiesScenes that tell across several screens.
• AccessibilityContrast, focus and reduced motion across the kit.