material-motion

name	material-motion
description	Apply Material Design 3 motion transitions using GSAP and shared project motion tokens. Triggers on "add a page transition", "animate this section", "material motion", or invoke with /material-motion.

Material Motion (M3 transitions)

Source: github.com/kevzlou7979/material-motion — adapted here for Next.js + React + GSAP.

Core principle

"Material 3 motion is not 'add a fade.' It is: identify the relationship between the two UI states, pick the transition pattern that expresses that relationship, then build it with GSAP."

Pattern selection by relationship

Relationship	Pattern	Use case
Sequential siblings (wizard steps, tabs)	Shared axis X	Horizontal slide + fade
Hierarchy up/down (list → detail)	Shared axis Y	Scroll reveals, drill-in
Parent into child / depth	Shared axis Z	Scale 0.92→1 + opacity
Element morphs into another	Container transform	GSAP Flip
Unrelated content swap	Fade through	Sequential, no cross-dissolve
Enter/exit screen bounds	Fade	Dialogs, menus, toasts

Token vocabulary

Import from @/lib/motion:

• Easing: GSAP_EASE ("power2.out") for entry; GSAP_EASE_IN ("power2.in") for exit.
• Durations (seconds): MOTION_S.fast (0.15), MOTION_S.base (0.22), MOTION_S.slow (0.32).
• Slide offset: SLIDE_OFFSET (~28px) for spatial relationships.
• Helpers: gsapStagger(), prefersReducedMotion().

Critical rules

• Reduced motion is mandatory: wrap with prefersReducedMotion(); snap to final state and return early.
• Never invent durations/eases — reuse the tokens.
• No bouncy / elastic eases.
• Build timelines on mount, kill/revert on unmount (use gsap.context()).
• No GSAP at module top level (SSR incompatible) — import GSAP and register plugins inside useEffect.

React/Next adaptation

onMount→useEffect, onDestroy→the effect cleanup. Register ScrollTrigger/Flip inside the effect after a dynamic import("gsap"). See components/blocks/reveal.tsx for the canonical scroll-reveal implementation and lib/motion.ts for all token definitions.