Animation & Effects

Overview

Motion in Luminaux is deliberately centralized so the whole app animates with one consistent vocabulary — the same way styles/index.css owns color. Every duration, easing curve, spring and reusable variant lives in src/lib/motion.ts; components pull from there instead of hardcoding magic numbers. On top of the tokens sit two layers:

• Wrappers — thin, ergonomic components (PageTransition, Stagger, FadeIn, Collapse, AnimatedNumber, SheetModal) that apply the tokens for common cases.
• FX components — free-core reimplementations of effects that would otherwise require the paid Motion+ tier (Typewriter, ScrambleText, TiltCard, SwipeRow, CursorGlow, Parallax, HeroCanvas, and more).

The canonical live reference is /ui/motion (src/pages/ui/MotionShowcasePage.tsx) — a UI-kit page that demos every reusable motion export in the standard Panel-in-Stagger idiom, opened by a live HeroCanvas variant="lines" banner layered with RotatingWord + AnimatedNumber. Its sections: entrance/scroll (Reveal, Parallax, Stagger) · animated text (Typewriter, RotatingWord, ScrambleText, ScrollRevealLines) · interaction (TiltCard, SwipeRow, ImageRevealSlider) · numbers (AnimatedNumber variants) · overlays (WarpOverlay, SheetModal) · hero backgrounds (all five HeroCanvas variants) · decorative (ParticleField, DotGrid, WaveDivider) · a shell note. Several FX are also woven into sibling /ui/* pages: ImageRevealSlider on Lightbox (B&W→color over public/photos/), Typewriter/ScrambleText/RotatingWord/ScrollRevealLines on Typography, WarpOverlay on Modals, AnimatedNumber on Badges' count bubbles — and StatCard (src/components/ui/StatCard.tsx) wraps its surface in TiltCard for the pointer tilt.

The golden rules

These are authoritative and apply to every line of animation code you add:

1. Import only from motion/react. The npm package is motion. Never import from framer-motion.
2. No Motion+. We do not have the paid Motion+ tier. Never add motion-plus / motion-plus-react, use premium components (e.g. their <AnimateNumber>), or the AI Kit (npx motion-ai). Everything here is built from free core APIs — build equivalents the same way.
3. Reduced motion is global and non-negotiable. MotionProvider sets reducedMotion="user"; never override it. Any imperative animate() or scroll-linked value must also branch on useReducedMotion() (those bypass MotionConfig).
4. Tokens are the single source of truth. Pull durations/easings/springs/variants from src/lib/motion.ts — no inline magic numbers.
5. Memoize dynamic motion(as). Creating a motion component inline in render mints a new type each render and remounts (re-animates) the subtree. Use motion.create(as) wrapped in useMemo([as]) (as Stagger/StaggerItem do).

Architecture & files

src/lib/motion.ts                     # tokens: durations, easings, springs, variants,
                                      #         PAGE_TRANSITION_KINDS / PAGE_TRANSITIONS,
                                      #         PAGE_LOADER_KINDS, PARALLAX_DISTANCE
src/components/motion/
  index.ts                            # barrel — re-exports every wrapper + FX component
  MotionProvider.tsx                  # global MotionConfig (reducedMotion="user")
  PageTransition.tsx                  # route-change transition (driven by config.pageTransition)
  Stagger.tsx / StaggerItem.tsx       # orchestrated child entrance
  FadeIn.tsx                          # one-off fade + rise
  Collapse.tsx                        # height auto <-> 0
  AnimatedNumber.tsx                  # count-up (free AnimateNumber equivalent)
  SheetModal.tsx                      # responsive dialog / drag-to-dismiss bottom sheet
  Typewriter.tsx  ScrambleText.tsx    # text FX
  TiltCard.tsx  SwipeRow.tsx          # gesture FX
  CursorGlow.tsx  WarpOverlay.tsx     # ambient / overlay FX
  ImageRevealSlider.tsx               # before/after comparison
  ScrollRevealLines.tsx  Reveal.tsx   # scroll reveals
  Parallax.tsx  RotatingWord.tsx      # scroll drift / headline cycle
  ParticleField.tsx  DotGrid.tsx      # decorative backgrounds
  WaveDivider.tsx  HeroCanvas.tsx     # section decor / hero background
src/components/loading/
  AppSplash.tsx                       # full-screen branded splash (initial load + replay)
  PageLoader.tsx                      # Suspense fallback for lazy pages
  SplashMark.tsx                      # shared brand lockup used by both
src/pages/ui/MotionShowcasePage.tsx   # /ui/motion — the canonical demo of every export above

Where they mount:

• MotionProvider wraps the app near the root so reducedMotion="user" and the default spring transition apply everywhere.
• PageTransition wraps the routed subtree inside an AnimatePresence (keyed per route) in the layout, so navigating fades/wipes/slides the page per config.pageTransition.
• AppSplash is mounted at the root beside the routes, inside the providers so it can useLayout().
• PageLoader is the fallback shown while a code-split page loads.

The motion config flags (pageTransition, pageLoader, routeLoader, splashFrequency) live on LayoutContext alongside the rest of the shell config — see Layout System and Customizer & Layout Settings.

Usage

Import wrappers and FX from the barrel; import tokens from @/lib/motion:

import {FadeIn, Stagger, StaggerItem, AnimatedNumber, Reveal} from '@/components/motion'
import {DURATION, EASE_OUT, spring, fadeInUp} from '@/lib/motion'

Prefer the wrappers over raw motion.* for common cases (entrances, staggering, collapse, count-up, modals). Drop to raw motion.* (still from motion/react) only when a wrapper doesn't fit — and then still pull timing from the tokens.

import {motion} from 'motion/react'
import {DURATION, EASE_OUT} from '@/lib/motion'
 
    ;
 
<motion.div
    initial={{opacity: 0, y: 12}}
    animate={{opacity: 1, y: 0}}
    transition={{duration: DURATION.base, ease: EASE_OUT}}
/>

API / Props

Motion tokens

All from src/lib/motion.ts.

Easing & durations

Springs

Key variants (all are Variants with hidden / visible (+ often exit) states)

Other tokens

Motion wrappers & FX catalog

Every component below is exported from src/components/motion/index.ts. Props marked ? are optional; defaults are shown where the component sets one.

Loading components

From src/components/loading/ — driven by the config flags in the next section.

The three loader styles (branded / minimal / playful) render distinct visuals in both AppSplash and PageLoader: branded = brand mark + progress bar/shimmer, minimal = a slim indeterminate bar / spinner, playful = three bouncing dots.

Configuration & customization

The four motion config flags

Defined on LayoutContext (src/context/LayoutContext.tsx), persisted to localStorage, and editable from both the Layout Customizer panel and the Layout Settings page:

The pickers reuse customizer: i18n keys (src/locales/en/customizer.json):

pageTransition, pageTransitionNone/Fade/Slide/ClipWipe/Iris/Doors/Blinds
pageLoader, pageLoaderBranded/Minimal/Playful
routeLoader, routeLoaderDesc
loaderFrequency, loaderFreqAlways/loaderFreqOnce

How config.pageTransition drives PageTransition

PageTransition reads config.pageTransition via useLayout(), looks up the variant set in PAGE_TRANSITIONS[kind], and applies it as initial="hidden" animate="visible" exit="exit". Under reduced motion it forces PAGE_TRANSITIONS.none (clip-path isn't covered by MotionConfig's reduced-motion handling). The blinds kind additionally renders a BlindsOverlay (8 background-colored slats that retract top-to-bottom) on top of a plain fade.

Add a page-transition kind

1. Add the kind to PAGE_TRANSITION_KINDS in src/lib/motion.ts.
2. Add its Variants (clip-path / transform only — no Motion+) and register it in the PAGE_TRANSITIONS map.
3. Add a pageTransition<Cap> i18n key to customizer.json (e.g. pageTransitionZoom).

The Customizer + Layout Settings pickers map over PAGE_TRANSITION_KINDS automatically, so no picker edits are needed.

Add a page-loader style

1. Add the style to PAGE_LOADER_KINDS in src/lib/motion.ts.
2. Add a branch for it in both AppSplash.tsx and PageLoader.tsx.
3. Add a pageLoader<Cap> i18n key.

Replay the splash on demand

Dispatch the window event — used by the Page Loader preview to show the current style full-screen without a reload:

window.dispatchEvent(new Event('app:replay-splash'))

Examples

Staggered card grid

import {Stagger, StaggerItem} from '@/components/motion'
 
    ;
 
<Stagger className="grid gap-4 sm:grid-cols-3">
    {stats.map((s) => (
        <StaggerItem key={s.id}>
            <StatCard {...s} />
        </StaggerItem>
    ))}
</Stagger>

One-off entrance with a delay

import {FadeIn} from '@/components/motion'
 
    ;
 
<FadeIn delay={0.1}>
    <PageHeader title="Reports"/>
</FadeIn>

Count-up KPI (re-animates when the value changes, with a trend arrow)

import {AnimatedNumber} from '@/components/motion'
 
    ;
 
<AnimatedNumber value={revenue} prefix="$" decimals={2} trend="up" animateOnChange/>

Collapse / accordion body

import {Collapse} from '@/components/motion'
 
    ;
 
<Collapse open={isOpen}>
    <div className="p-4">{body}</div>
</Collapse>

Scroll-reveal a section

import {Reveal} from '@/components/motion'
 
    ;
 
<Reveal>
    <section className="…">…</section>
</Reveal>

Parallax drift with a named distance

import {Parallax} from '@/components/motion'
import {PARALLAX_DISTANCE} from '@/lib/motion'
 
    ;
 
<Parallax distance={PARALLAX_DISTANCE.hero}>
    <img src={asset('/photos/photo-1.jpg')} alt="" />
</Parallax>

Responsive dialog / bottom sheet

import {SheetModal} from '@/components/motion'
 
    ;
 
<SheetModal open={open} onClose={close} labelledBy="dlg-title">
    <h2 id="dlg-title">Confirm</h2>
    …
</SheetModal>

Text FX

import {Typewriter, ScrambleText, RotatingWord} from '@/components/motion'
 
    ;
 
<Typewriter words={['Fast', 'Themeable', 'Accessible']}/>
<ScrambleText text="demo content" trigger="hover"/>
<RotatingWord words={t('landing:heroWords', {returnObjects: true}) as string[]}/>

Custom animation from tokens (when no wrapper fits)

import {motion} from 'motion/react'
import {springSnappy} from '@/lib/motion'
 
    ;
 
<motion.button whileHover={{y: -4}} transition={springSnappy}>
    Hover me
</motion.button>

Best practices

• Reach for a wrapper first. FadeIn/Stagger/Collapse/AnimatedNumber cover most cases and already apply the tokens and reduced-motion handling.
• Never hardcode timing. Pull DURATION, EASE_OUT, spring* and variants from src/lib/motion.ts. If you need a new value, add it to the tokens file.
• Memoize any as-polymorphic motion component. motion.create(as) inline in render re-mounts and replays the subtree; wrap in useMemo([as]) (see Stagger/StaggerItem).
• Guard imperative + scroll-linked motion. animate(), useScroll/useTransform, and clip-path effects bypass MotionConfig, so branch on useReducedMotion() yourself (as AppSplash, Parallax, PageTransition do).
• Don't reproject layout on tab/panel switches. Wrapping switched content in a keyed motion/layout element re-measures sibling layout/layoutId nodes (Switch thumbs, tab indicators) and flickers the page. Use a plain keyed opacity fade instead.
• Stagger doesn't cascade through a sliding AnimatePresence overlay. Inside a slideInRight aside (customizer-style), a nested staggerContainer flips straight to visible. For a staggered reveal there, give each child an explicit per-index initial/animate + delay.
• Colors stay on tokens. FX that paint (ParticleField, DotGrid, WaveDivider, HeroCanvas) read semantic tokens (bg-primary, currentColor, --border) — don't hardcode hex.
• Demo every new FX on /ui/motion. When you add an FX component to the barrel, add it to MotionShowcasePage too — otherwise it becomes a dead export (four FX once sat unused in the barrel until the showcase page was added).

Troubleshooting

FAQ

Which package do we use — framer-motion or motion? motion — always import from motion/react. framer-motion is never used.

Can I use Motion+ components like <AnimateNumber>? No. We don't have the paid Motion+ tier. Use the free equivalents here — e.g. AnimatedNumber for count-up. Never add motion-plus / motion-plus-react.

How do I disable animations for accessibility? You don't need to — it's automatic. MotionProvider sets reducedMotion="user", so the OS "Reduce Motion" setting strips transforms globally. Just remember to add a useReducedMotion() branch to any imperative or scroll-linked motion you write.

Where do I change the default page transition or loader for everyone? The defaultLayout in src/context/LayoutContext.tsx (pageTransition, pageLoader, routeLoader, splashFrequency). Note that persisted localStorage overrides defaults for existing browsers.

How do I add a new bouncing/curtain effect? See Configuration & customization — add a kind to the relevant *_KINDS array, wire the variant/branch, add the i18n key.

Why is my motion component remounting? Almost always a fresh motion.create(as) type per render. Memoize with useMemo([as]).

Where can I see every effect running? /ui/motion (src/pages/ui/MotionShowcasePage.tsx) — the canonical showcase of every wrapper and FX export, including all five HeroCanvas variants.

Notes for designers & content editors

• Motion is subtle by default. The shipping default pageTransition is none and entrances are short (DURATION.base = 0.25s). Livelier "curtain" effects (clipWipe, iris, doors, blinds) are opt-in per user via the Customizer / Layout Settings.
• Everything respects "Reduce Motion." If a user has that OS setting on, animations simplify to fades or static states — there is no separate toggle to maintain.
• All motion colors come from theme tokens, so effects re-skin automatically across the design skins and light/dark. Nothing is hardcoded to a hex value.
• Text used in FX is content, not decoration. Typewriter / RotatingWord / ScrambleText take real strings (resolve them through i18n keys, never hardcode UI copy).
• The splash is branded via SplashMark, which reads the product name/tagline from src/config/brand.ts — update the brand there, not in the loaders.

Related