` wrapping a `

elements. Logos: next/image with width/height + alt, equal visual weight. */ children: ReactNode; /** Accessible name for the region, e.g. "Companies using Acme". */ label: string; /** Seconds per loop. ≈ 40s per 1600px of content; never faster than ~60px/s. */ duration?: number; reverse?: boolean; /** Content that moves > 5s and carries information (testimonials) needs a pause control (WCAG 2.2.2). */ pausable?: boolean; className?: string; }; /** Server Component. Two tracks; the duplicate is aria-hidden + inert (no double reading, no double tab stops). */ export function Marquee({ children, label, duration = 40, reverse = false, pausable = false, className }: MarqueeProps) { return (
{pausable ? ( Pause scrolling ) : null}
); } ``` ```css /* ── 1. Marquee (T1) ──────────────────────────────────────────────────────────────────── */ @layer components { .fx-marquee { --fx-gap: 3rem; display: flex; gap: var(--fx-gap); overflow: hidden; padding-block: 0.25rem; /* room for focus rings */ mask-image: linear-gradient(to right, transparent, black 8%, black 92%, transparent); } .fx-marquee__track { display: flex; flex-shrink: 0; align-items: center; justify-content: space-around; gap: var(--fx-gap); min-width: 100%; margin: 0; padding: 0; list-style: none; animation: fx-marquee var(--fx-marquee-duration, 40s) linear infinite; } .fx-marquee[data-reverse] .fx-marquee__track { animation-direction: reverse; } .fx-marquee:focus-within .fx-marquee__track, .fx-marquee-wrap:has(.fx-marquee__pause:checked) .fx-marquee__track { animation-play-state: paused; } @media (hover: hover) and (pointer: fine) { .fx-marquee:hover .fx-marquee__track { animation-play-state: paused; } } @media (prefers-reduced-motion: reduce) { .fx-marquee { overflow-x: auto; mask-image: none; } .fx-marquee__track { animation: none; } .fx-marquee__track[aria-hidden] { display: none; } .fx-marquee-wrap label:has(.fx-marquee__pause) { display: none; } } } @keyframes fx-marquee { to { transform: translateX(calc(-100% - var(--fx-gap))); } } ``` ```tsx {logos.map((l) => (

))} ``` Each track has `min-width: 100%`, so the loop is seamless with any item count. For fewer than about 6 logos, use a static row instead. ## 2. SpotlightCard (pointer glow on a feature grid) - **Inspired by:** React Bits `SpotlightCard` (https://reactbits.dev), Magic UI `magic-card`. - **Upstream bugs fixed:** `setState` on every mousemove, which re-renders children and repaints a full-card `radial-gradient`; a conditional `useMotionTemplate` hook (magic-card); hardcoded neutral palette. - **Technique:** a pre-rasterised radial blob moved through the `translate` property. Pointer events are coalesced into one rAF, with one `getBoundingClientRect` per frame and zero React renders. A 120ms `translate` transition retargets every frame, which reads as a light spring without motion. - **Tier:** T2, ~0.5 KB. - **Reduced motion / touch / pen:** the effect never attaches, leaving a static `surface-card`. - **A11y:** the glow is `aria-hidden`. Keyboard parity comes from `:focus-within`, which raises the border to `--brand-line`. Put a real link or button inside the card. - **SSR:** a client component, but children render on the server (pass Server Components as `children`). ```tsx "use client"; import { useEffect, useRef, type ComponentProps } from "react"; import { cn } from "@/lib/cn"; /** Pointer-following glow. Zero React renders per move: one rAF-coalesced `translate` write on a * pre-rasterised blob. Touch, pen, keyboard and reduced motion get the static card (+ focus border). */ export function SpotlightCard({ className, children, ...rest }: ComponentProps<"div">) { const cardRef = useRef(null); const glowRef = useRef(null); useEffect(() => { const card = cardRef.current; const glow = glowRef.current; if (!card || !glow) return; if (!matchMedia("(hover: hover) and (pointer: fine) and (prefers-reduced-motion: no-preference)").matches) return; let raf = 0; let px = 0; let py = 0; const write = () => { raf = 0; const r = card.getBoundingClientRect(); // one read per frame, not per event glow.style.translate = `${px - r.left}px ${py - r.top}px`; }; const onMove = (e: PointerEvent) => { if (e.pointerType !== "mouse") return; px = e.clientX; py = e.clientY; if (!raf) raf = requestAnimationFrame(write); }; card.addEventListener("pointermove", onMove, { passive: true }); return () => { card.removeEventListener("pointermove", onMove); if (raf) cancelAnimationFrame(raf); }; }, []); return (

); } ``` ```css /* ── 2. Spotlight card (T2, ~0.5 KB) ──────────────────────────────────────────────────── */ @layer components { .fx-spot { position: relative; isolation: isolate; overflow: hidden; } .fx-spot__glow { position: absolute; top: 0; left: 0; z-index: -1; width: var(--fx-spot-size, 22rem); aspect-ratio: 1; border-radius: 50%; pointer-events: none; background: radial-gradient(closest-side, color-mix(in oklab, var(--brand) 22%, transparent), transparent); transform: translate(-50%, -50%); /* centres on the pointer; JS writes the `translate` property */ opacity: 0; transition: opacity var(--duration-slow) ease, translate 120ms var(--ease-out); } @media (hover: hover) and (pointer: fine) and (prefers-reduced-motion: no-preference) { .fx-spot:hover .fx-spot__glow { opacity: 1; } } .fx-spot:focus-within { border-color: var(--brand-line); } /* keyboard parity */ } ``` Use one spotlight grid per page (it is the "secondary" effect). Each card owns its own listener, so there are no window listeners. ## 3. RevealText (per-word headline reveal) - **Inspired by:** React Bits `SplitText` / `BlurText` (https://reactbits.dev), Aceternity `text-generate-effect`, Magic UI `text-animate`. - **Upstream bugs fixed:** GSAP + SplitText (45–70 KB); SSR text at `opacity:0` (invisible without JS, LCP delayed to the end of the stagger); hydration flash; per-character nodes; duplicate `aria-label` + `sr-only` copies. - **Tier:** T1, 0 KB JS. - **`trigger="load"`** (hero h1): words rise 0.3em via `@starting-style` with a 40ms stagger capped at 400ms. **Opacity stays 1**, so the LCP is the first paint. This also works on client navigations, since new elements get a starting style too. - **`trigger="scroll"`** (below the fold only): each word fades and rises, scrubbed by `animation-timeline: view()`. Browsers without scroll timelines show static text. - **Reduced motion:** static text, and `--duration-slower` is 0 in base.css. - **A11y:** one copy of the text with real spaces between inline-block words, so screen readers read it normally. - **SSR:** full text in the server HTML (verified with JS disabled). ```tsx import type { CSSProperties, ElementType } from "react"; import { cn } from "@/lib/cn"; type RevealTextProps = { text: string; as?: ElementType; /** "load": hero/LCP-safe rise on first paint (opacity never 0). * "scroll": scrubbed by a CSS view() timeline where supported, static elsewhere. Below the fold only. */ trigger?: "load" | "scroll"; className?: string; }; /** Server Component. Splits per word (never per character); real spaces keep one readable copy for AT. */ export function RevealText({ text, as: Tag = "h2", trigger = "scroll", className }: RevealTextProps) { const words = text.trim().split(/\s+/); return ( {words.map((word, i) => ( {word} {i < words.length - 1 ? " " : null} ))} ); } ``` ```css /* ── 3. Text reveal (T1) ──────────────────────────────────────────────────────────────── */ @layer components { .fx-reveal { --fx-stagger: 40ms; } .fx-reveal__word { display: inline-block; } @media (prefers-reduced-motion: no-preference) { /* load: movement only, opacity stays 1 → LCP is the first paint */ .fx-reveal[data-trigger="load"] .fx-reveal__word { transition: translate var(--duration-slower) var(--ease-out-expo); transition-delay: min(calc(var(--i) * var(--fx-stagger)), 400ms); @starting-style { translate: 0 0.3em; } } /* scroll: scrubbed by the view timeline; unsupported browsers show static text */ @supports (animation-timeline: view()) { .fx-reveal[data-trigger="scroll"] .fx-reveal__word { animation: fx-rise linear both; animation-timeline: view(); animation-range: entry calc(5% + var(--i) * 1.5%) cover calc(25% + var(--i) * 1.5%); } } } } @keyframes fx-rise { from { opacity: 0; translate: 0 0.5em; } to { opacity: 1; translate: 0 0; } } ``` ```tsx ``` Keep it to 1–2 headings per page. For block-level section reveals use base.css `reveal`; for masked line rises use `motion` → `references/recipes.md` §10. Don't add `clip-path` or `opacity:0` to the load variant: whether a fully clipped first frame counts as painted for LCP is unverified. ## 4. BeamBorder (a light travelling around one card) - **Inspired by:** Magic UI `border-beam` (https://magicui.design/docs/components/border-beam), React Bits `StarBorder`, motion-primitives `border-trail`. - **Upstream bugs fixed:** motion animating `offset-distance` on the JS main thread forever (border-beam); keyframes that exist only in a commented `tailwind.config.js`, so the effect is dead on v4 (StarBorder); ` ``` ## 8. ShinyText (a sweep of light across a label) - **Inspired by:** React Bits `ShinyText` (https://reactbits.dev), Magic UI `animated-shiny-text`, motion-primitives `text-shimmer`. - **Upstream bugs fixed:** a perpetual `useAnimationFrame` JS loop per instance writing `background-position` (it keeps ticking even when `disabled`); no offscreen or reduced-motion handling. - **Tier:** T1-paint, 0 KB. `background-clip: text` can't be moved by transform, so this is a **paint** animation. It gets its own layer (`will-change: transform`) so each frame repaints only the label. - **Measured:** without its own layer, a shiny eyebrow on top of `AuroraBackdrop` dropped 14–46% of frames while scrolling (headless, software raster); without the shine, 0–4%. **Don't put ShinyText over an animated backdrop** even with the fix. They count as two effects in one viewport anyway. - **Reduced motion:** plain `--fg-muted` text. - **A11y:** real text, and contrast stays within the fg scale. **Never on h1/h2** (that is `design/gradient-text`), never on body copy, never in brand colour. - **SSR:** a Server Component. ```tsx import type { ComponentProps } from "react"; import { cn } from "@/lib/cn"; /** Server Component. A light sweep across one short muted string (eyebrow, badge). Paint animation: * one per viewport, never on h1/body copy, never on top of another animated layer. */ export function ShinyText({ className, ...rest }: ComponentProps<"span">) { return ; } ``` ```css /* ── 8. Shiny text (T1-paint: one short string per viewport) ─────────────────────────── */ @layer components { .fx-shine { color: var(--fg-muted); /* fallback */ background-image: linear-gradient(100deg, var(--fg-muted) 40%, var(--fg) 50%, var(--fg-muted) 60%); background-size: 250% 100%; background-position: 100% 0; -webkit-background-clip: text; background-clip: text; -webkit-text-fill-color: transparent; animation: fx-shine 3.2s var(--ease-in-out) infinite; /* own layer: otherwise each frame's repaint invalidates whatever big layer it shares (e.g. text over an animated backdrop repaints the whole hero: measured 15% → 1.4% dropped frames) */ will-change: transform; } @media (prefers-reduced-motion: reduce) { .fx-shine { animation: none; background: none; -webkit-text-fill-color: currentColor; will-change: auto; } } } @keyframes fx-shine { 0% { background-position: 100% 0; } 55%, 100% { background-position: 0% 0; } } ``` ```tsx
Now with agent skills
``` ## 9. AuroraBackdrop (WebGL aurora → CSS) - **Inspired by:** React Bits `Aurora` / `Silk` / `SoftAurora` (https://reactbits.dev), Aceternity `aurora-background`. - **Upstream bugs fixed:** three + R3F (~150 KB) or ogl for one full-screen quad; `new Color()` ×3 per frame; effect deps that rebuild the GL context; no DPR cap, offscreen pause or reduced motion. - **Technique:** three large radial gradients with the softness baked in (**no `filter: blur`**), each drifting 27–41s via `transform`. That is 3 composited layers and zero repaints while idle. It gives about 80% of the shader mood at 0 KB. Single hue by construction (`--brand`): multi-hue meshes are a banned trope (`design/purple-gradient`). - **Measured fix:** fading toward the fold with `mask-image` on the container forced a re-rendered surface every frame (10% dropped frames). A static gradient overlay (`::after` to `--bg`) measured 0%. If the section background isn't `--bg`, set `--fx-aurora-fade`. - **Tier:** T1, 0 KB. This is the page's **signature**, so nothing else animates in the hero. - **Reduced motion:** the blobs hold still (static glow). - **A11y / SSR:** `aria-hidden`, Server Component. ```tsx import type { CSSProperties } from "react"; /** Server Component. Three pre-softened brand blobs drifting on the compositor (no filter: blur, no WebGL). * Parent needs `relative isolate`. Masked toward the fold so it never sits behind body copy. */ export function AuroraBackdrop({ intensity = 0.2 }: { intensity?: number }) { return ( ); } ``` ```css /* ── 9. CSS aurora (T1, replaces WebGL Aurora/Silk) ──────────────────────────────────── */ @layer components { .fx-aurora { position: absolute; inset: 0; z-index: -1; overflow: hidden; pointer-events: none; contain: strict; } /* fade toward the fold so it never sits behind body copy. A static overlay, not mask-image: a mask over animated children forces a re-rendered surface every frame (measured 10% dropped frames). */ .fx-aurora::after { content: ""; position: absolute; inset: 0; background: linear-gradient(to bottom, transparent 35%, var(--fx-aurora-fade, var(--bg)) 92%); } .fx-aurora > span { position: absolute; width: 55vmax; aspect-ratio: 1; border-radius: 50%; opacity: var(--fx-aurora-opacity, 0.2); animation: fx-drift 32s var(--ease-in-out) infinite alternate; } .fx-aurora > span:nth-child(1) { top: -30vmax; left: -12vmax; background: radial-gradient(closest-side, var(--brand), color-mix(in oklab, var(--brand) 35%, transparent) 45%, transparent); } .fx-aurora > span:nth-child(2) { top: -26vmax; right: -20vmax; background: radial-gradient(closest-side, color-mix(in oklab, var(--brand) 55%, var(--fg)), transparent); animation-duration: 41s; animation-direction: alternate-reverse; } .fx-aurora > span:nth-child(3) { top: -10vmax; left: 30%; width: 40vmax; background: radial-gradient(closest-side, color-mix(in oklab, var(--brand) 45%, transparent), transparent); animation-duration: 27s; opacity: calc(var(--fx-aurora-opacity, 0.2) * 0.65); } @media (prefers-reduced-motion: reduce) { .fx-aurora > span { animation: none; } } } @keyframes fx-drift { from { transform: translate3d(0, 0, 0) scale(1); } to { transform: translate3d(8vmax, 5vmax, 0) scale(1.12); } } ``` ```tsx
…hero…
``` Keep `intensity` ≤ 0.25 on dark directions, and check gutters stay near the canvas colour. If the brief truly needs a shader, follow `speed` → `references/rendering-smoothness.md` §8 (WebGL2 hook) and `motion` → `references/webgl-canvas.md`, with this component as the CSS fallback underneath. ## 10. HeroSpotlight (angled light behind the hero) - **Inspired by:** Aceternity `spotlight` (https://ui.aceternity.com/components/spotlight). - **Upstream bugs fixed:** `animate-spotlight` ships with no CSS in the registry item, so the SVG stays at `opacity-0` forever on Tailwind v4 (silently dead); hardcoded `id="filter"` collides across instances; a 151px `feGaussianBlur`; `z-[1]` sits over content. `spotlight-new` loops forever. - **Technique:** one rotated elliptical radial gradient that fades in once (1.4s `--ease-out-expo`, 0.2s delay). `light-dark()` tints it with `--brand` in light schemes and `--fg` in dark ones. - **Tier:** T1 one-shot, 0 KB. Starting at opacity 0 is safe because gradients are never LCP candidates. - **Reduced motion:** shown immediately. - **A11y / SSR:** `aria-hidden`, Server Component. ```tsx import { cn } from "@/lib/cn"; /** Server Component, zero JS. A soft angled light (brand-tinted in light mode, fg-tinted in dark) that * fades in once on load. No SVG filter, no ids, no infinite loop. Parent needs `relative isolate`. */ export function HeroSpotlight({ className }: { className?: string }) { return (

); } ``` ```css /* ── 10. Hero spotlight (T1 one-shot) ─────────────────────────────────────────────────── */ @layer components { .fx-spotlight { position: absolute; top: -45%; left: -25%; width: 110%; height: 130%; background: radial-gradient( ellipse 38% 14% at 50% 50%, light-dark(color-mix(in oklab, var(--brand) 16%, transparent), color-mix(in oklab, var(--fg) 16%, transparent)), transparent 70% ); transform: rotate(32deg); animation: fx-spotlight-in 1.4s var(--ease-out-expo) 0.2s both; /* decorative, never LCP */ } @media (prefers-reduced-motion: reduce) { .fx-spotlight { animation: none; } } } @keyframes fx-spotlight-in { from { opacity: 0; transform: translate(-6%, -5%) rotate(32deg) scale(0.96); } to { opacity: 1; transform: translate(0, 0) rotate(32deg) scale(1); } } ``` --- ## Verification log (2026-09-16) - `next build` passed (TypeScript strict); every demo route is static (`○`). `void lint` reported 0 errors, and no findings in `src/components/fx` or `fx.css`. - Server HTML with JavaScript disabled: the h1 text is complete, the ticker shows `12,400`, the marquee duplicate has `aria-hidden="true" inert`, and no inline `opacity:0`. - Playwright (Chromium 149): SpotlightCard glow `translate: 120px 60px`, opacity 1 on hover; Magnetic `translate: 14.8px 5.5px` while tracking; the below-fold ticker counts 0 → 65.8 → 98.6 once, with the `sr-only` copy stable at 98.6; FxGate set `data-fx-paused` on the offscreen shine only; no console errors from fx code. - Screenshots at 1440px (dark, light, `--force-prefers-reduced-motion`) and 390px: all effects visible and on-token. Reduced motion showed the static marquee (no mask), a static brand beam border, and still blobs. - `void smooth` (desktop, scroll, headless software raster): each effect alone dropped 0–5% of frames. The full ten-effect page dropped 22–39% before the two fixes above (the shine's own layer and the aurora overlay instead of a mask) and 0% in two runs after them. The machine load average was 10–22, so repeat measurements varied by ±15 points; re-measure on your own route. - `void a11y`: a marquee logo contrast failure with `text-fg-subtle` in the light theme, measured before `--fg-subtle` was raised to AA (fixed by using `text-fg-muted`, noted in §1).