Scroll choreography
Usage
Scroll-driven presets — this repo had only Reveal (motion.doc.tsx) before this pass. Follows reference/MECHANISMS.md's scroll-choreography rule: IntersectionObserver or a throttled/rAF-batched scroll read, transform/opacity only, never a per-frame scroll handler doing layout reads. A route-level "top loading bar" preset also exists (RouteProgressBar) but lives in apps/dashboard/app/(docs)/_chrome/ rather than this package, since it needs next/navigation's usePathname and packages/ui is deliberately framework-agnostic — not wired into the live site chrome by default, available to mount if the product wants it.import { ProgressLine, ParallaxDrift, CountUp, ScrollScale, PinFade } from '@summonware/ui';Best practices
DoUse ProgressLine on a genuinely long scrollable page (a long article, a settings page with many sections) — on a short page it never visibly changes, which reads as broken, not calm.
DoKeep ParallaxDrift subtle (a low speed, 0.1–0.3) and reserve it for decorative/background elements — parallaxing real content the user needs to read is disorienting, not premium.
Don'tUse CountUp for a number that updates live/streams (e.g. a live ticker) — it is a one-shot reveal-on-scroll animation, not a data-bound counter.
Anatomy
ProgressLineA fixed top bar filling with page scroll progress.
ParallaxDriftTranslates its child at a fraction of scroll speed.
CountUpAnimates a number from 0 to a target once scrolled into view.
ScrollScaleReveal's sibling — scales in from 96% instead of translating.
PinFadeStays sticky-pinned, fading out as it's about to scroll past.
Examples
Common configurations, variations and states.CountUp, scroll-triggered stat
Active seats
0
Scroll this into view — the number animates from 0.
ScrollScale
Scales in on scroll
Scroll this into view — scales up from 96% while fading in.
ParallaxDrift
Drifts slower
A decorative badge drifting slower than the page as you scroll past it.