motion-patterns

Motion Patterns

Kopier- und einfügbereite Muster für die häufigsten UI-Animationen. Jedes Muster basiert auf den Tokens und Federn von motion-foundations. Definiere hier keine neuen Dauer- oder Easing-Werte – importiere sie.

Wann aktivieren

• Animieren eines Buttons, einer Karte, eines Modals oder einer Toast-Benachrichtigung
• Erstellen von Listeneingängen mit Staffelung
• Einrichten von Seitenübergängen im Next.js App Router
• Hinzufügen von Ein- oder Ausgangsanimationen zu bedingten Inhalten
• Implementieren von Scroll-Enthüllungen, scrollverknüpften Fortschrittsbalken oder klebrigen Story-Abschnitten
• Erstellen von aufklappbaren Karten, Akkordeons oder Shared-Element-Übergängen

Ausgaben

Diese Skill produziert:

• Barrierefreie, SSR-sichere Animationen für alle gängigen UI-Komponenten
• Mit AnimatePresence umschlossene bedingte Renderings mit korrektem Exit-Verhalten
• Page-Transition-Wrapper-Komponente für den Next.js App Router
• Scroll-Enthüllungs- und Scroll-verknüpfte Muster mit useScroll + useTransform
• Layout-Animationsmuster (layout, layoutId) für aufklappbare und überblendende Elemente

Prinzipien

• Jedes Muster importiert aus motion-foundations. Keine rohen Zahlenwerte.
• Jedes bedingte Rendern wird in AnimatePresence mit einem key verpackt.
• Exit-Animationen werden immer zusammen mit Enter-Animationen definiert – niemals als nachträglicher Gedanke.
• layout wird nur für kleine, isolierte Verschiebungen verwendet. Bei großen Teilbäumen werden explizite Transformationen verwendet.

Regeln

1. Bedingte Renderings immer in AnimatePresence mit einem key auf dem direkten Kind umschließen. Ohne Key werden Exit-Animationen niemals ausgelöst.
2. exit immer zusammen mit initial + animate definieren. Eine Animation ohne Exit ist unvollständig.
3. mode="wait" bei Seitenübergängen verwenden. Enter darf erst beginnen, wenn Exit abgeschlossen ist.
4. layout niemals auf Teilbäumen mit mehr als ~5 Kindern oder tief verschachteltem DOM verwenden. Stattdessen explizite x/y-Transformationen verwenden.
5. Das Stagger-Intervall muss zwischen 0.05s und 0.10s liegen. Darunter wirkt es mechanisch; darüber träge.
6. Modals müssen immer enthalten: Focus Trap, Escape-Taste zum Schließen, Scroll-Sperre, role="dialog", aria-modal="true".
7. Scroll-Enthüllungen verwenden viewport={{ once: true }}. Wiederholungen beim Rausscrollen sind ablenkend, nicht informativ.
8. Alle Token-Werte werden aus motion-foundations importiert. Keine Inline-Zahlen.

Entscheidungshilfen

Das richtige Muster auswählen

Situation	Muster
Element erscheint / verschwindet	AnimatePresence
Liste von Elementen, die nacheinander erscheinen	Stagger-Varianten
Navigation zwischen Routen	Page-Transition-Wrapper
Element ändert seine Größe an Ort und Stelle	layout-Prop
Gleiches Element bewegt sich über Seitenkontexte hinweg	layoutId
Element erscheint, wenn es in den sichtbaren Bereich gescrollt wird	whileInView
Wert, der an die Scrollposition gebunden ist	useScroll + useTransform

Wann mode="wait" vs. mode="sync" verwenden

Modus	Verwendung wenn
wait	Seitenübergänge, Inhaltswechsel (eines nach dem anderen)
sync	Gestapelte Benachrichtigungen, Listenelemente (Überlappung ist in Ordnung)
popLayout	Elemente, die aus einer umfließenden Liste entfernt werden

Kernkonzepte

AnimatePresence-Vertrag

Drei Dinge müssen immer zutreffen:

1. AnimatePresence umschließt das Bedingte
2. Das direkte Kind hat einen key
3. Das Kind hat eine exit-Prop

Fehlt eines davon, schlägt die Exit-Animation still fehl.

layout vs. layoutId

• layout – animiert die eigene Größen-/Positionsänderung des Elements an Ort und Stelle
• layoutId – verknüpft zwei separate Elemente und blendet sie über mehrere Renderings hinweg ineinander über

Verwende layout="position" für Text innerhalb eines sich ausdehnenden Containers, um zu verhindern, dass der Text-Umbruch animiert wird.

Code-Beispiele

Button-Feedback

"use client"
import { motion } from "motion/react"
import { springs, motionTokens } from "@/lib/motion-tokens"

<motion.button
  whileHover={{ scale: motionTokens.scale.pop }}
  whileTap={{ scale: motionTokens.scale.press }}
  transition={springs.snappy}
/>

Gestaffelte Liste

"use client"
import { motion } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"

const container = {
  hidden: {},
  visible: {
    transition: {
      staggerChildren: 0.08,   // innerhalb der 0.05–0.10 Regel
      delayChildren: 0.1,
    },
  },
}

const item = {
  hidden:  { opacity: 0, y: motionTokens.distance.md },
  visible: { opacity: 1, y: 0, transition: springs.gentle },
}

<motion.ul variants={container} initial="hidden" animate="visible">
  {items.map((i) => (
    <motion.li key={i.id} variants={item} />
  ))}
</motion.ul>

Modal

"use client"
import { motion, AnimatePresence } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"

// Am Aufrufort umschließen:
// <AnimatePresence>{isOpen && <Modal key="modal" />}</AnimatePresence>

export function Modal({ onClose }: { onClose: () => void }) {
  return (
    <>
      {/* Überlagerung */}
      <motion.div
        className="fixed inset-0 bg-black/50"
        initial={{ opacity: 0 }}
        animate={{ opacity: 1 }}
        exit={{ opacity: 0 }}
        onClick={onClose}
      />

      {/* Panel – Barrierefreiheitsanforderungen: Focus Trap, Escape zum Schließen,
          Scroll-Sperre, role="dialog", aria-modal="true" */}
      <motion.div
        role="dialog"
        aria-modal="true"
        className="fixed inset-x-4 top-1/2 -translate-y-1/2 rounded-xl bg-white p-6"
        initial={{
          opacity: 0,
          scale: motionTokens.scale.press,
          y: motionTokens.distance.sm,
        }}
        animate={{ opacity: 1, scale: 1, y: 0 }}
        exit={{
          opacity: 0,
          scale: motionTokens.scale.press,
          y: motionTokens.distance.sm,
        }}
        transition={springs.gentle}
      />
    </>
  )
}

Toast-Stapel

"use client"
import { motion, AnimatePresence } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"

<AnimatePresence mode="sync">
  {toasts.map((t) => (
    <motion.div
      key={t.id}
      layout
      initial={{
        opacity: 0,
        x: motionTokens.distance.xl,
        scale: motionTokens.scale.subtle,
      }}
      animate={{ opacity: 1, x: 0, scale: 1 }}
      exit={{
        opacity: 0,
        x: motionTokens.distance.xl,
        scale: motionTokens.scale.subtle,
      }}
      transition={springs.snappy}
    />
  )}
</AnimatePresence>

Seitenübergang (Next.js App Router)

// components/page-transition.tsx
"use client"
import { motion, AnimatePresence } from "motion/react"
import { usePathname } from "next/navigation"
import { motionTokens } from "@/lib/motion-tokens"

const variants = {
  initial: { opacity: 0, y: motionTokens.distance.sm },
  enter:   { opacity: 1, y: 0 },
  exit:    { opacity: 0, y: -motionTokens.distance.sm },
}

export function PageTransition({ children }: { children: React.ReactNode }) {
  const pathname = usePathname()
  return (
    <AnimatePresence mode="wait">
      <motion.div
        key={pathname}
        variants={variants}
        initial="initial"
        animate="enter"
        exit="exit"
        transition={{
          duration: motionTokens.duration.normal,
          ease: motionTokens.easing.smooth,
        }}
      >
        {children}
      </motion.div>
    </AnimatePresence>
  )
}

Scroll-Enthüllung

"use client"
import { motion } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"

<motion.div
  initial={{ opacity: 0, y: motionTokens.distance.lg }}
  whileInView={{ opacity: 1, y: 0 }}
  viewport={{ once: true, margin: "-80px" }}   // once: true – Regel 7
  transition={{ duration: motionTokens.duration.slow, ease: motionTokens.easing.smooth }}
/>

Scroll-Fortschrittsbalken

"use client"
import { motion, useScroll } from "motion/react"

export function ScrollProgress() {
  const { scrollYProgress } = useScroll()
  return (
    <motion.div
      className="fixed top-0 left-0 h-1 bg-indigo-500 origin-left w-full"
      style={{ scaleX: scrollYProgress }}
    />
  )
}

Aufklappbare Karte

"use client"
import { useState } from "react"
import { motion, AnimatePresence } from "motion/react"
import { springs, motionTokens } from "@/lib/motion-tokens"

export function ExpandingCard({ title, body }: { title: string; body: string }) {
  const [expanded, setExpanded] = useState(false)

  return (
    <motion.div layout onClick={() => setExpanded(!expanded)} className="cursor-pointer">
      {/* layout="position" verhindert das Animieren des Text-Umbruchs */}
      <motion.h2 layout="position" className="font-semibold">
        {title}
      </motion.h2>

      <AnimatePresence>
        {expanded && (
          <motion.p
            key="body"
            initial={{ opacity: 0 }}
            animate={{ opacity: 1 }}
            exit={{ opacity: 0 }}
            transition={{ duration: motionTokens.duration.fast }}
          >
            {body}
          </motion.p>
        )}
      </AnimatePresence>
    </motion.div>
  )
}

Shared-Element-Überblendung

// Quellkontext
<motion.img layoutId="hero-image" src={src} className="w-16 h-16 rounded" />

// Zielkontext (gleiches layoutId – motion übernimmt den Übergang)
<motion.img layoutId="hero-image" src={src} className="w-full rounded-xl" />

Akkordeon

<motion.div
  initial={false}
  animate={{ opacity: open ? 1 : 0, scaleY: open ? 1 : 0 }}
  style={{ transformOrigin: "top", overflow: "hidden" }}
  transition={{
    duration: motionTokens.duration.normal,
    ease: motionTokens.easing.smooth,
  }}
> {children}
</motion.div>

End-to-End-Beispiel

Eine gestaffelte Liste, die beim Mounten erscheint, bedingtes Vorhandensein behandelt und reduzierte Bewegung respektiert – Kombination von Tokens, Federn, AnimatePresence und dem Accessibility-Hook aus motion-foundations:

"use client"
import { useState } from "react"
import { motion, AnimatePresence } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"
import { useSafeMotion } from "@/hooks/use-reduced-motion"

const containerVariants = {
  hidden: {},
  visible: {
    transition: { staggerChildren: 0.08, delayChildren: 0.1 },
  },
}

function ListItem({ label, onRemove }: { label: string; onRemove: () => void }) {
  const safe = useSafeMotion(motionTokens.distance.sm)
  return (
    <motion.li
      variants={{
        hidden:  safe.initial,
        visible: safe.animate,
      }}
      exit={safe.exit}
      transition={springs.gentle}
      className="flex items-center justify-between p-3 rounded-lg bg-white shadow-sm"
    >
      <span>{label}</span>
      <button onClick={onRemove}>Entfernen</button>
    </motion.li>
  )
}

export function AnimatedList({ items, onRemove }: {
  items: { id: string; label: string }[]
  onRemove: (id: string) => void
}) {
  return (
    <motion.ul
      variants={containerVariants}
      initial="hidden"
      animate="visible"
      className="space-y-2"
    >
      <AnimatePresence mode="popLayout">
        {items.map((item) => (
          <ListItem
            key={item.id}
            label={item.label}
            onRemove={() => onRemove(item.id)}
          />
        ))}
      </AnimatePresence>
    </motion.ul>
  )
}

Einschränkungen / Nicht-Ziele

Diese Skill behandelt nicht:

• Token- und Feder-Definitionen → siehe motion-foundations
• Drag-Interaktionen, Wischgesten, neu anordenbare Listen → siehe motion-advanced
• Textanimationen (Wort-/Zeichen-Enthüllung, Zähler) → siehe motion-advanced
• SVG-Pfadzeichnen oder -Morphing → siehe motion-advanced
• Benutzerdefinierte Animations-Hooks → siehe motion-advanced
• CSS-only-Transitionen ohne motion/react

Anti-Patterns

Anti-Pattern	Verletzte Regel	Behebung
AnimatePresence-Kind ohne key	Regel 1	Stabilen key zum direkten Kind hinzufügen
initial + animate ohne exit	Regel 2	Immer alle drei zusammen definieren
Seitenübergang ohne mode="wait"	Regel 3	mode="wait" zu AnimatePresence hinzufügen
layout auf einer 50-Elemente-Liste	Regel 4	mode="popLayout" oder explizite Transformationen verwenden
staggerChildren: 0.2 auf einer 10-Elemente-Liste	Regel 5	Auf 0.08–0.10 begrenzen
Modal ohne Focus Trap	Regel 6	focus-trap-react oder Radix Dialog hinzufügen
whileInView ohne viewport={{ once: true }}	Regel 7	Wiederholte Eintritte lenken ab, informieren nicht
transition={{ duration: 0.3 }} inline	Regel 8	motionTokens.duration.normal verwenden

Verwandte Skills

• motion-foundations – definiert alle Tokens, Federn, den useSafeMotion-Hook und SSR-Guards, die jedes Muster hier importiert. Muss zuerst eingerichtet werden.
• motion-advanced – erweitert diese Muster um Drag, Gesten, SVG, Text, benutzerdefinierte Hooks und imperative Ablaufsteuerung. Definiert keine Muster aus dieser Skill neu.