Bewegungsmuster

Bewegungsmuster (Motion Patterns)

Copy-paste-Muster für die häufigsten UI-Animationen. Jedes Muster hier basiert auf motion-foundations-Tokens und Springs. Definiere hier keine neuen Dauer- oder Easing-Werte – importiere sie.

Wann aktivieren

• Animation eines Buttons, einer Karte, eines Modals oder einer Toast-Benachrichtigung
• Aufbau von Listeneingängen mit Staffelung (Stagger)
• Einrichtung von Seitenübergängen im Next.js App Router
• Hinzufügen von Ein- oder Ausgangsanimationen zu bedingten Inhalten
• Implementierung von Scroll-Reveal, Scroll-verknüpftem Fortschritt oder klebrigen Story-Abschnitten
• Bau von expandierenden Karten, Akkordeons oder Shared-Element-Übergängen

Ausgaben

Dieses Skill produziert:

• Barrierefreie, SSR-sichere Animation für alle standardmäßigen UI-Komponenten
• Mit AnimatePresence umschlossene bedingte Renderings mit korrektem Exit-Verhalten
• Eine Page-Transition-Wrapper-Komponente für den Next.js App Router
• Scroll-Reveal- und Scroll-verknüpfte Muster mittels useScroll + useTransform
• Layout-Animationen (layout, layoutId) für expandierende und überblendende Elemente

Prinzipien

• Jedes Muster importiert aus motion-foundations. Keine rohen Zahlen.
• Jedes bedingte Rendering wird mit AnimatePresence und einem key umschlossen.
• Exit-Animationen werden immer zusammen mit Enter-Animationen definiert – nie als nachträglicher Gedanke.
• layout wird nur für kleine, isolierte Verschiebungen verwendet. Große Teilbäume erhalten explizite Transformationen.

Regeln

1. Umschließe bedingte Renderings immer mit AnimatePresence und einem key auf dem direkten Kind. Ohne einen Schlüssel werden Exit-Animationen nie ausgelöst.
2. Definiere immer exit, wenn du initial + animate definierst. Eine Animation ohne Exit ist unvollständig.
3. Verwende mode="wait" für Seitenübergänge. Der Enter darf erst starten, wenn der Exit abgeschlossen ist.
4. Verwende niemals layout auf Teilbäumen mit mehr als ~5 Kindern oder tief verschachteltem DOM. Verwende stattdessen explizite x-/y-Transformationen.
5. Das Staffelungsintervall 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-Lock, role="dialog", aria-modal="true".
7. Scroll-Reveals verwenden viewport={{ once: true }}. Wiederholungen beim Rausscrollen sind ablenkend, nicht informativ.
8. Alle Token-Werte werden aus motion-foundations importiert. Keine inline-Zahlen.

Entscheidungshilfe

Das richtige Muster wählen

Situation	Muster
Element erscheint / verschwindet	AnimatePresence
Liste von Elementen, die nacheinander geladen werden	Stagger-Varianten
Navigation zwischen Routen	Page-Transition-Wrapper
Element ändert seine Größe an Ort und Stelle	layout-Prop
Selbes Element bewegt sich über Seitenkontexte hinweg	layoutId
Element erscheint beim Hineinscrollen	whileInView
Wert an die Scrollposition gebunden	useScroll + useTransform

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

Modus	Verwendung
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 wahr sein:

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

Fehlt eines dieser Elemente, 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 zwischen ihnen bei erneuten Renderings über

Verwende layout="position" für Text in einem expandierenden Container, um zu verhindern, dass der Textfluss animiert.

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"

// Umschließen an der Aufrufstelle:
// <AnimatePresence>{isOpen && <Modal key="modal" />}</AnimatePresence>

export function Modal({ onClose }: { onClose: () => void }) {
  return (
    <>
      {/* Overlay */}
      <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-Lock, 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-Stack

"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-Reveal

"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 }}
    />
  )
}

Expandierende 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, dass Textfluss animiert */}
      <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, bedingte Anwesenheit behandelt und reduzierte Bewegungen respektiert – kombiniert Tokens, Springs, AnimatePresence und den Barrierefreiheits-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

Dieses Skill deckt nicht ab:

• Token- und Spring-Definitionen → siehe motion-foundations
• Drag-Interaktionen, Wischgesten, neu anordenbare Listen → siehe motion-advanced
• Text-Animationen (Wort-/Zeichen-Enthüllung, Zähler) → siehe motion-advanced
• SVG-Pfadzeichnen oder Morphing → siehe motion-advanced
• Benutzerdefinierte Animations-Hooks → siehe motion-advanced
• CSS-only-Übergänge, die nicht motion/react verwenden

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 Liste mit 50 Elementen	Regel 4	mode="popLayout" oder explizite Transformationen verwenden
staggerChildren: 0.2 auf einer Liste mit 10 Elementen	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 Eingänge lenken ab, informieren nicht
transition={{ duration: 0.3 }} inline	Regel 8	motionTokens.duration.normal verwenden

Verwandte Skills

• motion-foundations – definiert alle Tokens, Springs, 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 Sequenzierung. Definiert keine Muster aus diesem Skill neu.