Conventions
Learn one component, know them all
The same prop names, the same units and the same escape hatches on all 25 components, so neither you nor your agent has to guess.
Units
| Prop | Type and unit | Rule |
|---|---|---|
duration | number (ms) | Always milliseconds: duration={1200} is 1.2 seconds. |
speed | number (multiplier) | 1 is the component's normal speed; 0.5 is half, 2 is double. |
pixelsPerSecond | number (px/s) | Drift in pixels per second (Marquee). |
strength | number (0 to 1) | How strong an effect is, clamped between 0 and 1. |
pullDistance | number (px) | The farthest a MagneticButton moves, in pixels. |
paused | boolean | Stops the component; present on all 25. |
What paused does
Motion that runs longer than five seconds needs a way to stop it (WCAG 2.2.2). While paused is true a component asks for no animation frames at all; this is checked in a real browser for every component.
- mesh-gradient, noise-field, particle-field: the frame loop stops; the last frame stays on screen and the WebGL context is kept.
- distortion-image: gives its WebGL context back and shows the plain image.
- smooth-scroll: removes the smooth scroll; the browser's own scrolling takes over.
- marquee: stops the strip where it is (
animation-play-state: paused). - text-reveal: shows the whole text at once.
- scroll-reveal: shows the content in its final state.
- the twelve canvas components (flame-switch, ember-badge, lantern-sky and the rest): the effect stops drawing and the last frame stays; the control itself (switch, tabs, slider, button) keeps working.
A component's paused stops that component only. To stop everything at once (a site-wide “Pause motion” button), call pauseAll() from @frictionborn/runtime; it stops the shared frame loop.
Refs, props and imports
Every component forwards ref to its root element and spreads the HTML attributes you pass onto it. Your handlers (onPointerMove, onFocus and so on) run alongside the component's own. Named and default exports both work:
import { AmbientHero } from "@/components/ui/ambient-hero";
// or
import AmbientHero from "@/components/ui/ambient-hero";What next
See the units in action in any component playground, or read the performance budget each component is measured against.