Dev notes

Motion Components

Three motion-driven surfaces added to the shared design system, and the one rule that shaped all of them: the animation is the treat, the static version is the contract. Everything works without a single moving pixel, then gets richer if the browser and the user allow it.

What shipped

Three content-agnostic surfaces landed in @paul-portfolio/css and @paul-portfolio/react, plus a shared-hook refactor. Each one wraps arbitrary children and is stable on the server, so they behave like backgrounds you drop around any content.

TiltCard — a 3D surface that tilts toward the pointer with a cursor-tracking glare highlight. Props: maxTilt, glare.
GradientBackground — a flowing multi-stop gradient, animated entirely in CSS. Props: colors, angle, speed, animate; falls back to the brand token palette.
Spotlight — a soft radial glow that follows the cursor across a background. Props: size, color.

Reduced motion is the default, not a fallback

The rule for all three: the static version is the contract, and the motion is the enhancement layered on top. If the browser or the user says no to movement, what's left still works and still looks intentional.

TiltCard flattens to a plain static card — no rotation, no glare.
Spotlight pins its glow to the center and stops tracking the cursor, so it reads as a static vignette.
GradientBackground is the cleanest case: the animation is a CSS keyframe gated behind prefers-reduced-motion, so it goes static with no JavaScript running at all.

Pointer, not keyboard

TiltCard and Spotlight react to the pointer, and only the pointer. There's a real accessibility reason for that line: yanking a card's rotation or throwing a glow around on focus would be distracting noise for someone navigating by keyboard, and it'd fight assistive tech for attention.

Keyboard users are simply unaffected — the surfaces sit still and let the content take focus normally.
Every component ships with an axe a11y test alongside its unit tests, so the accessible-by-default promise is asserted, not assumed.

One hook, shared across every animation

The obvious trap was three copies of the same reduced-motion listener. Instead the check became a single exported hook, usePrefersReducedMotion, and the existing Ticker was refactored onto it too.

One source of truth for "should this move?" means a fix to the media-query handling lands everywhere at once.
It's exported from the package, so anything built on top of the design system gets the same behavior for free.

Verification and housekeeping

TDD per component: CSS and React tests written first, each cycle going red then green.
packages/react: 146 tests passing (unit + axe for all three). packages/css: 139 tests passing. The React build runs a clean tsc typecheck.
Storybook stories added for each component, and versions bumped: @paul-portfolio/css 0.4.5→0.4.6, @paul-portfolio/react 0.4.4→0.4.5, with a changelog entry.
Angular ports deferred — the same call made for Select, FilterBar, and Ticker. The React and CSS surfaces come first; Angular follows when there's demand.

The takeaway

Motion that can't be turned off isn't a feature, it's a liability. Designing the static state first makes reduced-motion trivial instead of an afterthought.
When three components need the same environmental check, that check wants to be one shared, tested hook — not three quietly-drifting copies.

Update — September 18, 2026

Twenty effects from ReactBits and OriginKit, rebuilt so the library still costs nothing to install

Three surfaces became twenty. I went through the components I liked on ReactBits and OriginKit and rebuilt the ones I wanted into the design system — sparks, blur reveals, star borders, a liquid-glass surface, a segmented control that rubber-bands, a lattice loader, a drifting 3D wall, galleries, hero compositions, particle text. The hard rule the whole batch had to obey: a consumer who imports a Button shouldn’t pay for any of it.

Reimplement, don’t install.

The originals reach for libraries; the point of putting them in the system is that mine don’t. Each effect is a small React component plus a token-driven stylesheet, and the animated parts are CSS the tokens already describe. The star border, for instance, is a conic gradient that takes its colour from currentColor, so a caller tints it by setting the text colour — no prop, no config, no dependency.

.star-border__ring {
  background: conic-gradient(from 0deg,
    transparent, currentColor, transparent, currentColor, transparent);
  animation: paul-star-spin 4s linear infinite;
}

The WebGL ones became CSS.

A few originals are fragment shaders or WebGL scenes — a light bloom, a circular gallery. Pulling a renderer into a design system to reproduce them exactly would break the rule above, so I reinterpreted them: the bloom is a breathing radial gradient whose origin chases the pointer, and the circular gallery is a preserve-3d cylinder you spin with a drag. Not pixel-identical to a shader, but the same idea with nothing to download.

// each card sits on the cylinder; the ring rotates in a rAF loop
transform: rotateY(i * angleStep) translateZ(radius);

Canvas without a dependency, and a guard for the corners.

Where an effect genuinely needs a canvas — particle text assembling out of a cloud — the browser’s built-in 2D canvas does it, so there’s still nothing to install. And once every surface had rounded corners, I wanted them to be the Apple squircle rather than a plain arc, everywhere and on purpose. A base rule sets corner-shape: squircle system-wide, and a test fails the build if any component ships a radius without a deliberate corner shape beside it.

// every rule with a border-radius must also declare a corner-shape;
// a full-round radius must stay round, not a squircle of a circle
if (!shape) missing.push(rule);
expect(missing).toEqual([]);

Update — September 18, 2026

The corner rule existed, but half the entry points missed it

I added a global squircle rule and tested that it existed. That proved the declaration was in a file, not that the components imported it. The components-only entry deliberately skips base.css, so buttons, inputs, and cards used through that entry kept ordinary rounded corners.

The failing test needed to follow the public entry point.

I replaced the base-file presence check with an AST audit of every radius in the exported component styles. It found 68 declarations without a corner shape. Each component now carries its own shape; circles and capsules explicitly stay round, while overlays inherit.

FAIL src/components/__tests__/squircle.test.ts
AssertionError: expected [ …(68) ] to deeply equal []

/* Components-only consumers now receive both declarations. */
.btn {
  border-radius: var(--paul-radius-md);
  corner-shape: squircle;
}

The liquid button keeps its velocity when the pointer reverses.

The unfinished button used a radial CSS mask and an always-running animation loop. I replaced it with a subtractive SVG mask and separate critically damped springs for position and radius. New input changes the target without discarding velocity. The loop stops at rest and cancels when the component unmounts, becomes disabled, or reduced motion is enabled. Keyboard activation stays native.

The hero is a composition, so the copy and actions stay in charge.

Hero06 arranges supplied images in a spiral; Hero13 uses CSS perspective to interpret the public OriginKit poster. Both accept copy, navigation, and action slots. The pointer moves only the decorative gallery by at most ten pixels, and reduced motion keeps it still. Missing imagery never removes the heading or actions. These are original token-based interpretations, not imports of the vendor runtime.

The implementation and verification live in paul-design-system PR 91. Native corner-shape support is still required for continuous corners; unsupported browsers retain border-radius. A green source test does not turn that into universal browser support, and an open PR is not a deployed update.

What I'd do now, and what I did

Reduced motion as the default rather than a fallback, so the accessible path is the one that runs unless something opts out.
Motion behind components rather than scattered animation calls, which is what makes a policy like that enforceable at all.
A batch of twenty effect components rebuilt from ReactBits and OriginKit onto the tokens — sparks, blur reveals, star borders, liquid glass, a rubber-band segmented control, a lattice loader, a drifting 3D wall, galleries, hero compositions, particle text — none of which add a runtime dependency.
Squircle corners system-wide via a base rule, with a guard test that fails the build if a component ships a radius without a deliberate corner shape.

Where it could go further

Adoption is incomplete, though less than I assumed. The 3D scenes animate in a render loop that never touches a motion component, so they answer the preference through their own hook instead — the world already did, the particle lab did not until it was fixed.
There is no test that a new animation went through the components rather than around them.

Next on this

Review the liquid button, portrait sections, and component corner fix in paul-design-system PR 91 before merging and releasing. Seven renderer/library-heavy effects remain deferred; no new WebGL, physics, or icon dependency was added.
A check that any new animated component answers prefers-reduced-motion somehow — through these components or its own hook — since the gap is not knowing, rather than any one page.

Dev notes

Motion Components

What shipped

TiltCard — a 3D surface that tilts toward the pointer with a cursor-tracking glare highlight. Props: maxTilt, glare.
GradientBackground — a flowing multi-stop gradient, animated entirely in CSS. Props: colors, angle, speed, animate; falls back to the brand token palette.
Spotlight — a soft radial glow that follows the cursor across a background. Props: size, color.

Reduced motion is the default, not a fallback

TiltCard flattens to a plain static card — no rotation, no glare.
Spotlight pins its glow to the center and stops tracking the cursor, so it reads as a static vignette.
GradientBackground is the cleanest case: the animation is a CSS keyframe gated behind prefers-reduced-motion, so it goes static with no JavaScript running at all.

Pointer, not keyboard

Keyboard users are simply unaffected — the surfaces sit still and let the content take focus normally.
Every component ships with an axe a11y test alongside its unit tests, so the accessible-by-default promise is asserted, not assumed.

One hook, shared across every animation

One source of truth for "should this move?" means a fix to the media-query handling lands everywhere at once.
It's exported from the package, so anything built on top of the design system gets the same behavior for free.

Verification and housekeeping

TDD per component: CSS and React tests written first, each cycle going red then green.
packages/react: 146 tests passing (unit + axe for all three). packages/css: 139 tests passing. The React build runs a clean tsc typecheck.
Storybook stories added for each component, and versions bumped: @paul-portfolio/css 0.4.5→0.4.6, @paul-portfolio/react 0.4.4→0.4.5, with a changelog entry.
Angular ports deferred — the same call made for Select, FilterBar, and Ticker. The React and CSS surfaces come first; Angular follows when there's demand.

The takeaway

Motion that can't be turned off isn't a feature, it's a liability. Designing the static state first makes reduced-motion trivial instead of an afterthought.
When three components need the same environmental check, that check wants to be one shared, tested hook — not three quietly-drifting copies.

Update — September 18, 2026

Twenty effects from ReactBits and OriginKit, rebuilt so the library still costs nothing to install

Reimplement, don’t install.

.star-border__ring {
  background: conic-gradient(from 0deg,
    transparent, currentColor, transparent, currentColor, transparent);
  animation: paul-star-spin 4s linear infinite;
}

The WebGL ones became CSS.

// each card sits on the cylinder; the ring rotates in a rAF loop
transform: rotateY(i * angleStep) translateZ(radius);

Canvas without a dependency, and a guard for the corners.

// every rule with a border-radius must also declare a corner-shape;
// a full-round radius must stay round, not a squircle of a circle
if (!shape) missing.push(rule);
expect(missing).toEqual([]);

Update — September 18, 2026

The corner rule existed, but half the entry points missed it

The failing test needed to follow the public entry point.

FAIL src/components/__tests__/squircle.test.ts
AssertionError: expected [ …(68) ] to deeply equal []

/* Components-only consumers now receive both declarations. */
.btn {
  border-radius: var(--paul-radius-md);
  corner-shape: squircle;
}

The liquid button keeps its velocity when the pointer reverses.

The hero is a composition, so the copy and actions stay in charge.

What I'd do now, and what I did

Reduced motion as the default rather than a fallback, so the accessible path is the one that runs unless something opts out.
Motion behind components rather than scattered animation calls, which is what makes a policy like that enforceable at all.
A batch of twenty effect components rebuilt from ReactBits and OriginKit onto the tokens — sparks, blur reveals, star borders, liquid glass, a rubber-band segmented control, a lattice loader, a drifting 3D wall, galleries, hero compositions, particle text — none of which add a runtime dependency.
Squircle corners system-wide via a base rule, with a guard test that fails the build if a component ships a radius without a deliberate corner shape.

Where it could go further

Adoption is incomplete, though less than I assumed. The 3D scenes animate in a render loop that never touches a motion component, so they answer the preference through their own hook instead — the world already did, the particle lab did not until it was fixed.
There is no test that a new animation went through the components rather than around them.

Next on this

Review the liquid button, portrait sections, and component corner fix in paul-design-system PR 91 before merging and releasing. Seven renderer/library-heavy effects remain deferred; no new WebGL, physics, or icon dependency was added.
A check that any new animated component answers prefers-reduced-motion somehow — through these components or its own hook — since the gap is not knowing, rather than any one page.