Ziel
Erlins Methodik für Animationen auf seiner persönlichen Website: Einführung der motion-Bibliothek für Next.js/React-Seiten, Migration von framer-motion, Implementierung von Scroll-Enthüllungen / Stagger-Grids / Seitenübergängen / Navigationseffekten, wobei niemals Inhalte durch Animationen verdeckt werden dürfen. Wichtige Lektion: whileInView führte dazu, dass Projektkarten auf der Startseite bei opacity:0 hängen blieben („Projektkarten verschwunden“). Daher ist eine Ausfallsicherung für die Sichtbarkeit erforderlich; bestehende, zuverlässige Implementierungen können beibehalten werden. Reveal ist eine optionale Referenz, kein vollständiges Verbot von whileInView.
Ausführungsschritte
-
Projektumgebung zuerst prüfen (30 Sekunden vor dem Handeln aufwenden, um falsche Vorlagen zu vermeiden):
- Paketmanager: Erkenne nur eine Lockfile:
pnpm-lock.yaml→ pnpm,package-lock.json→ npm,yarn.lock→ yarn,bun.lockoderbun.lockb→ bun. Bei mehreren Lockfiles anhalten und den Benutzer fragen; bei keiner Lockfile denpackageManagerin derpackage.jsonlesen. Wenn immer noch unklar, anhalten und nicht raten. Nachfolgende Installations-, Migrations-, Lint- und Build-Befehle folgen dem bestätigten Manager. - Next/React-Version: Überprüfe die tatsächlichen Versionen von Next/React und der Animationsbibliothek, deren Peer-Abhängigkeiten und offizielle Kompatibilitätshinweise. Keine fest codierten Versionen oder Behauptungen einer vollständigen API-Kompatibilität zwischen Versionen.
- Router-Struktur (vor der Auswahl einer Vorlage erkennen, nicht standardmäßig App Router annehmen): Vorhandensein von
app/Verzeichnis → App Router, die folgende Regeln für die Vorlage anwenden; nurpages/→ Pages Router, keintemplate.tsxMechanismus, stattdessen inpages/_app.tsxoder auf Komponentenebene der Zielseite Übergänge implementieren und den Unterschied erklären; keines von beiden → kein Next-Projekt, äquivalente Implementierung am Einstiegspunkt des Frameworks. App Router: Bei locale-prefixed Routen (app/[locale]/Verzeichnis) die Vorlage inapp/[locale]/template.tsxablegen; ohne locale-Routen (z. B. clientseitiger Sprachwechsel) inapp/template.tsx. Next mountet die Vorlage bei jeder Navigation neu, Fade-In funktioniert trotzdem. - Ist die Komponente aktuell eine Serverkomponente: Interaktive motion-Elemente in die kleinste mögliche Clientkomponente isolieren; nicht die gesamte Komponente mit Serverlogik in eine Clientkomponente umwandeln.
- Paketmanager: Erkenne nur eine Lockfile:
-
Bestehende Abhängigkeiten beibehalten: Wenn
framer-motionbereits vorhanden ist und die Anforderungen erfüllt, weiterhin verwenden. Nicht standardmäßig aufgrund neuer Animationen migrieren. Nur wenn der Benutzer eine Migration verlangt oder die Kompatibilität es erfordert, die Versionen prüfen,motionmit dem Projekt-Paketmanager installieren, jede Importanweisung (motion/react) und API überprüfen, und nach Bestätigung keine verbleibenden Abhängigkeiten das alte Paket entfernen. Keine unnötigen Kommentare oder Dokumentationen ändern. -
Animationen einrichten: Nach Bedarf auf Reveal verweisen: Die Vorlage befindet sich in
assets/reveal.tsx, nachcomponents/motion/reveal.tsxkopieren und Pfad-Aliase anpassen. Gestaltungsprinzipien (an das Projekt anpassen):- Sichtbarkeits-Ausfallsicherung: Die Vorlage verwendet IntersectionObserver + 2,5 s Timeout; 2,5 s ist nur ein Referenzparameter, je nach Seite und Ladeverhalten anpassen. Alternativ kann ein validiertes
whileInViewoder ein anderer Mechanismus verwendet werden, um sicherzustellen, dass Inhalte auch bei Observer-, JS- oder Hydrationsfehlern zugänglich sind. - Reduced Motion und Observer-Fehler gemäß SSR/Hydration und Projekt-Lint-Regeln behandeln; Inkonsistenzen bei der Hydration und unnötige synchrone Effekt-Updates vermeiden. Einmalige Lint-Erfahrung nicht als Verbot aller APIs interpretieren.
- Reduced Motion rendert direkt den Endzustand.
- Reine CSS-Transition (
cubic-bezier(0.22,1,0.36,1)), keinmotion.div, null Animations-Laufzeit-Overhead. Revealhat eine eigene className-Prop: Karten, die ursprünglich<div>sind (z. B.glass-Karten), übergeben die Klasse direkt anReveal, spart eine Verschachtelungsebene; semantische Elemente wie<article>/<section>werden mitRevealumschlossen, um ihre Semantik zu bewahren.
- Sichtbarkeits-Ausfallsicherung: Die Vorlage verwendet IntersectionObserver + 2,5 s Timeout; 2,5 s ist nur ein Referenzparameter, je nach Seite und Ladeverhalten anpassen. Alternativ kann ein validiertes
-
Anwendungspositionen und Stagger-Formel:
Position Vorgehen delay Kartengitter (mehrere Blöcke auf der Startseite) Jedes Element mit RevealumschließenMath.min(i * 0.08, 0.4), gedeckelt, um lange Grids nicht träge zu machenArtikellisten (writing, latest-writing) Jede Zeile mit Revealumschließeni * 0.05~0.07, gedeckelt mitMath.min(i*0.05, 0.3), um lange Listen nicht träge zu machenTextzeilen bei großen Projekt-Bildern RevealFest 0.15, um mit dem Bild-Versatz zu variierenText-/Kontaktkarten (about) Große Blöcke mit RevealZweiter Block 0.1Navigationsleiste motion.headerinitialy:"-100%"einfliegen lassen, beim Scrollen Ausblenden unter Verwendung derselben Transform— Mobiles Menü AnimatePresence+opacity/yÜbergang, ersetztblock/hiddenUmschaltung— Routenwechsel Neue app/template.tsx(ohne locale-Routen) oderapp/[locale]/template.tsx(locale-prefixed; Next mountet template bei jeder Navigation neu) mitopacity+yFade-In, 0.35s— -
Verifizieren und Ausliefern: Nach dem in Schritt 1 bestätigten Paketmanager:
pnpm lint && pnpm build # pnpm-Projekt; build muss erfolgreich sein (SSG-Projekt mit SSG-Export) npm run lint && npm run build # npm-ProjektNur mit Benutzerfreigabe committen, nach Projekt-Konvention, z. B.:
feat(motion): migrate motion library and add site-wide animations. Nur die für diese Aufgabe relevanten Dateien hinzufügen – falls das Repository nicht zusammenhängende uncommittete Änderungen enthält, diese nicht in diesen Commit aufnehmen.
Entscheidungsregeln
- Wann verwenden: Neue Animationen für Next.js-Seiten hinzufügen; Migration von
framer-motionzumotion(vor der Migration aktuelle API-Version prüfen); Benutzer wünscht „Scroll-Enthüllungen“, „Stagger“, „Seitenübergänge“, „mehr Animationen“. - Nicht zuständig für: SwiftUI, CSS-only oder Remotion Videoanimationen.
- Gestaltungsregeln für Animationen (aus Fehlern gelernt):
- LCP-Elemente (H1, Hero) erhalten keine Eingangsanimation:
SkewRevealhat eineinstant-Prop, oder der Anfangszustand ist direkt der Endzustand, sonst flackert SSR-Text. - Alle Animationen respektieren
prefers-reduced-motion:useReducedMotion()verwenden, bei reduced den Endzustand rendern / keine Listener registrieren. - Einheitliche Beschleunigung
[0.22, 1, 0.36, 1](easeOutQuint-Stil), Dauer 0.3–0.8s, Zurückhaltung priorisieren. - Hover-Animationen können mit CSS-Transition umgesetzt werden (z. B.
hover:-translate-y-1,group-hover:scale-105), kein motion nötig. - Bei clientseitigem Filtern (z. B. Tag-Filter) werden Listenelemente mit unverändertem Key nicht erneut animiert – das ist erwartetes Verhalten, neu erscheinende Elemente werden automatisch ausgelöst.
- LCP-Elemente (H1, Hero) erhalten keine Eingangsanimation:
- Bestehende Komponenten-Zugehörigkeit: SkewReveal (Eingang), Parallax, Magnetic, MouseParallax beibehalten, neue Effekte im selben Verzeichnis hinzufügen; wenn das Projekt bereits ein
.zcode/.agentsAnimationskomponenten-Verzeichnis (z. B.components/motion/) hat, neue Komponenten dort ablegen. - Server/Client-Grenze: Serverkomponenten können
Revealdirekt rendern (es ist eine Clientkomponente, aber als Kindkomponente problemlos verwendbar).
Visuelle, Zugänglichkeits- und Inhalts-Sichtbarkeit vor Abschluss der Animationen prüfen; diese Fähigkeit regelt die motion-Implementierung für Next.js/React; RN/Expo oder andere Stacks werden nach denselben Prinzipien direkt implementiert, ohne auf dieses Skript angewiesen zu sein.
Ausgabeformat
Reveal-Komponente platzieren: ausassets/reveal.tsxnachcomponents/motion/reveal.tsxkopieren und Pfad-Aliase anpassen.- Routenübergang:
app/template.tsx(ohne locale-Routen) oderapp/[locale]/template.tsx(locale-prefixed),opacity+yFade-In 0.35s. - Commit-Nachricht: Conventional Commits + deutsche Beschreibung, z. B.:
feat(motion): migrate motion library and add site-wide animations(englisch bleibt, da etablierte Konvention).
Beispiele
Benutzerfrage
„Seite mit Scroll-Enthüllungen versehen und gleichzeitig framer-motion durch motion ersetzen.“
Werkzeugausgabe
pnpm
pnpm add motion && pnpm remove framer-motion erfolgreich, in package.json erscheint eine kompatible Version von motion; pnpm lint && pnpm build für die SSG-Seite bleibt erfolgreich.
sed
sed -i '' 's/from "framer-motion"/from "motion\/react"/g' <files> ausgeführt, alle Importe zeigen auf motion/react; nur für diese Migration relevante und tatsächlich veraltete Kommentare aktualisiert.
Endausgabe
components/motion/reveal.tsx (manueller IntersectionObserver + 2,5s Sicherung) + Karten/Liste Stagger + app/template.tsx Routen-FadeIn; Lint, Build bestanden; tatsächliche Überprüfung berichten; nur bei vorhandener Commit-Erlaubnis die relevanten Dateien committen.
Zugangskontrolle
- Inhalts-Richtlinie: Niemals Inhalte durch Animationen verstecken – SSR, reduced-motion, Observer/Skriptfehler auf Zugänglichkeit prüfen; Reveal und Timeout-Parameter sind Referenzimplementierungen, keine mechanischen API-Verbote.
- Barrierefreiheits-Richtlinie: Alle Animationen respektieren
prefers-reduced-motion; LCP-Elemente (H1, Hero) erhalten keine Eingangsanimation. - Verifizierung: Nach dem bestätigten Paketmanager
lint && buildausführen,buildmuss erfolgreich bleiben (bei SSG-Projekt darf der SSG-Export nicht beschädigt werden; bei SSR/ISR-Projekt reicht erfolgreicher Build, keine erfundenen SSG-Anforderungen). - Commit-Disziplin: Nur für diese Aufgabe relevante Dateien hinzufügen, nicht zusammenhängende uncommittete Änderungen im Repository nicht mitnehmen.
- Progressive Verbesserung: Bereits funktionierende Animationskomponenten nicht zur „Vereinheitlichung“ ändern; Entscheidungen basierend auf Anforderungen und Zugänglichkeitsnachweisen treffen.