Communitygithub.com

Erlin 动效技能

为 Next.js/React 站点引入 motion 动效库、从 framer-motion 迁移导入,并铺设滚动揭示、stagger 网格、页面过渡、导航动效。

Was ist Erlin 动效技能?

Diese Fähigkeit ist speziell für Entwickler von Next.js/React-Seiten konzipiert, die Animationen mit der `motion`-Bibliothek einführen oder von `framer-motion` migrieren möchten. Sie bietet eine bewährte Methodik für Scroll-Enthüllungen, Stagger-Grids, Seitenübergänge und Navigationseffekte, wobei die Zugänglichkeit und Sichtbarkeit von Inhalten stets oberste Priorität hat – ein zentraler Grundsatz, der aus einem realen Fehler (Projektkarten blieben aufgrund von `whileInView` auf `opacity:0` hängen) abgeleitet wurde. Die Fähigkeit unterstützt sowohl den App Router als auch den Pages Router von Next.js und passt sich automatisch an das verwendete Paketmanagement (pnpm, npm, yarn, bun) an. Sie enthält eine detaillierte Schritt-für-Schritt-Anleitung zur Integration der `Reveal`-Komponente, einschließlich einer Ausfallsicherung für Sichtbarkeit, Respektierung von `prefers-reduced-motion` und strikten Grenzen zwischen Server- und Client-Komponenten. Die Fähigkeit zielt darauf ab, konsistente, barrierefreie Animationen zu liefern, die die Ladeleistung (LCP-Elemente werden nicht animiert) und die semantische HTML-Struktur nicht beeinträchtigen. Sie ersetzt keine SwiftUI-, CSS-only- oder Remotion-Videoanimationen.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/erlinerd/erlin-skills/tree/HEAD/skills/web/erlin-web-motion

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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

  1. 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.lock oder bun.lockb → bun. Bei mehreren Lockfiles anhalten und den Benutzer fragen; bei keiner Lockfile den packageManager in der package.json lesen. 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; nur pages/ → Pages Router, kein template.tsx Mechanismus, stattdessen in pages/_app.tsx oder 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 in app/[locale]/template.tsx ablegen; ohne locale-Routen (z. B. clientseitiger Sprachwechsel) in app/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.
  2. Bestehende Abhängigkeiten beibehalten: Wenn framer-motion bereits 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, motion mit 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.

  3. Animationen einrichten: Nach Bedarf auf Reveal verweisen: Die Vorlage befindet sich in assets/reveal.tsx, nach components/motion/reveal.tsx kopieren 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 whileInView oder 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)), kein motion.div, null Animations-Laufzeit-Overhead.
    • Reveal hat eine eigene className-Prop: Karten, die ursprünglich <div> sind (z. B. glass-Karten), übergeben die Klasse direkt an Reveal, spart eine Verschachtelungsebene; semantische Elemente wie <article>/<section> werden mit Reveal umschlossen, um ihre Semantik zu bewahren.
  4. Anwendungspositionen und Stagger-Formel:

    PositionVorgehendelay
    Kartengitter (mehrere Blöcke auf der Startseite)Jedes Element mit Reveal umschließenMath.min(i * 0.08, 0.4), gedeckelt, um lange Grids nicht träge zu machen
    Artikellisten (writing, latest-writing)Jede Zeile mit Reveal umschließeni * 0.05~0.07, gedeckelt mit Math.min(i*0.05, 0.3), um lange Listen nicht träge zu machen
    Textzeilen bei großen Projekt-BildernRevealFest 0.15, um mit dem Bild-Versatz zu variieren
    Text-/Kontaktkarten (about)Große Blöcke mit RevealZweiter Block 0.1
    Navigationsleistemotion.header initial y:"-100%" einfliegen lassen, beim Scrollen Ausblenden unter Verwendung derselben Transform—
    Mobiles MenüAnimatePresence + opacity/y Übergang, ersetzt block/hidden Umschaltung—
    RoutenwechselNeue app/template.tsx (ohne locale-Routen) oder app/[locale]/template.tsx (locale-prefixed; Next mountet template bei jeder Navigation neu) mit opacity+y Fade-In, 0.35s—
  5. 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-Projekt
    

    Nur 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-motion zu motion (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: SkewReveal hat eine instant-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.
  • Bestehende Komponenten-Zugehörigkeit: SkewReveal (Eingang), Parallax, Magnetic, MouseParallax beibehalten, neue Effekte im selben Verzeichnis hinzufügen; wenn das Projekt bereits ein .zcode/.agents Animationskomponenten-Verzeichnis (z. B. components/motion/) hat, neue Komponenten dort ablegen.
  • Server/Client-Grenze: Serverkomponenten können Reveal direkt 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: aus assets/reveal.tsx nach components/motion/reveal.tsx kopieren und Pfad-Aliase anpassen.
  • Routenübergang: app/template.tsx (ohne locale-Routen) oder app/[locale]/template.tsx (locale-prefixed), opacity+y Fade-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 && build ausführen, build muss 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.

Verwandte Skills