Motion System · v1
Crisp.
Purposeful.
Fast.
Four primitives. One mental model. Ships near-zero JS until each island enters the viewport.
"Motion without discipline is noise.
Motion with discipline is product polish."
Most teams reach for a full animation library, ship 80 kb of JS, and get janky layout animations in return. This system is different — one dependency, four thin wrappers, no layout thrashing.
Architecture
Three layers, top to bottom
Start with Primitives — they cover 95% of the site.
Tokens and reduced-motion handling come for free.
Reveal · Stagger · Parallax · ScrollScene
Drop into .astro files as client:visible islands.
ease · duration · distance
One source of truth. Change a number, everything feels the same.
usePrefersReducedMotion()
Every primitive consults this. Choreography survives, movement doesn't.
Capabilities
Every primitive, live
Click a tab. Four primitives, plus the physics and tokens that tune them — six demos, one tab bar.
ScrollScene in the wild
Scroll to advance the signal lifecycle
Real scroll, not a loop — the sticky pin below exposes progress 0→1
straight from useScroll, the same primitive the "ScrollScene" tab
above only simulates on a timer.
Performance
The guardrails
Built-in constraints so you can't accidentally ship slow animations.
Never top/left/width/height. Composited by the GPU.
Applied per-element, not globally. Never promoted layers you don't need.
Prevents sticky sections triggering layout work elsewhere on the page.
Islands don't hydrate until they enter the viewport. First paint is pure HTML.
Motion ships ESM. Unused primitives never reach the bundle.
Integration
Three steps
Install
bun add motionImport a primitive
import Reveal from '@/components/motion/Reveal.astro'Drop it in your Astro file
<Reveal><HeroHeadline /></Reveal> That's it. No provider setup, no global config.
The motion tokens live in src/lib/motion.ts — edit the four numbers and
the whole site recalibrates.
One system.
Zero overhead.
Unused primitives tree-shake to nothing.
Islands defer until they're needed.