Communitygithub.com

hemangjoshi37a/scroll_animated_webpages_skill

Baue preisgekrönte, scroll-animierte Websites von Anfang bis Ende. Führt einen Discovery-Wizard durch (Person/Produkt/Unternehmen/Event/Anliegen), erstellt einen Scroll-Score-Blueprint, richtet das Projekt ein, implementiert GSAP ScrollTrigger-Animationen (optional mit Lenis Smooth Scroll) und verifiziert die Seite dann in einem echten Browser mit Playwright MCP, inklusive Fehlerbehebung.

Was ist scroll_animated_webpages_skill?

Diese Fähigkeit ermöglicht es einem KI-Agenten, vollständige, scroll-getriebene Websites zu erstellen, die für ihre beeindruckenden Animationen bekannt sind, wie man sie von preisgekrönten Apple-Produktseiten oder Awwwards-Gewinnern kennt. Der Prozess ist in sechs Phasen unterteilt: In Phase 1 führt der Agent einen interaktiven Wizard mit dem Benutzer durch, um Thema und Ziel zu ermitteln (z. B. Person, Produkt, Unternehmen, Event oder Anliegen). Ab Phase 2 arbeitet der Agent völlig autonom: Er erstellt einen detaillierten 'Scroll Score'-Bauplan in einer JSON-Datei, generiert oder sammelt alle benötigten Assets (Bilder, Videos, Frames), richtet ein Vite + vanilla TS + GSAP Projekt ein, implementiert jede einzelne Scroll-basierte Animation (wie Pinning, Scrubbing und Parallax), und testet die Seite abschließend in einem echten Browser mittels Playwright MCP. Dabei wird aktiv nach Fehlern gesucht und diese werden behoben, ohne dass der Benutzer nachfragen muss. Die Fähigkeit unterstützt verschiedene Plattformen und Frameworks, standardmäßig Vite mit vanilla TypeScript und GSAPs ScrollTrigger, optional auch Lenis für Smooth Scrolling und React/Next.js auf Anfrage. Sie ist speziell für den Bau von Scrollytelling-Seiten, Produkt-Launch-Seiten, Portfolios und ähnlichen, animationslastigen eindimensionalen Websites konzipiert.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/hemangjoshi37a/scroll_animated_webpages_skill/tree/HEAD/skills/scroll-animated-site

In Ihrer bevorzugten KI fragen

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

Dokumentation

Scroll-Animated Site Builder

Nimm ein Thema und einen Gegenstand vom Benutzer entgegen und erstelle eine vollständige, verifizierte, scrollgesteuerte Website – ohne die Arbeit zwischendurch zurückzugeben.

Bevor du beginnst: Neue Seite oder Nachrüstung?

Das Hinzufügen von Bewegung zu einer Seite, die bereits rankt, ist eine andere Aufgabe mit anderen Risiken – das Scroll-Budget muss die vorhandene Seitenhöhe einbeziehen, und ein Pin ist tote Scroll-Distanz auf einer Seite, die jemand überfliegt, um eine Entscheidung zu treffen. Standardmäßig baust du unter einer separaten Showcase-URL und verlinkst darauf; baue nur dann direkt um, wenn die Seite keinen Traffic zu verlieren hat und ihre Aufgabe eher im Eindruck als in der Referenz liegt. Erstelle immer zuerst eine byteweise Sicherungskopie und übergib dem Benutzer den Wiederherstellungsbefehl. Lies references/08-failure-modes.md §3, bevor du einer Nachrüstung zustimmst.

Die Pipeline

Sechs Phasen. Führe sie in der Reihenfolge aus. Nur Phase 1 spricht mit dem Benutzer.

1 DISCOVER  → Assistent, 2–3 Fragerunden        [interaktiv]
2 SCORE     → scroll-score.json Blaupause erstellen    [autonom]
3 ASSETS    → Bilder, Frames, Video generieren/sammeln [autonom]
4 SCAFFOLD  → Projektgerüst + Bewegungsruntime      [autonom]
5 BUILD     → Jeden Beat im Score umsetzen      [autonom]
6 VERIFY    → Einen echten Browser starten, korrigieren, wiederholen [autonom]

Nachdem der Assistent in Phase 1 geschlossen wurde, hör auf, Fragen zu stellen. Die Phasen 2–6 laufen nach deinem eigenen Ermessen zu Ende. Dokumentiere Annahmen in DECISIONS.md und berichte sie am Ende, anstatt darauf zu warten. Der Benutzer hat eine durchgängige Erstellung verlangt; eine halbfertige Seite plus eine Frage ist ein Fehlschlag.


Phase 1 – DISCOVER (der Assistent)

Frage mit dem AskUserQuestion-Tool, niemals als Textwand. Zwei Runden sind typisch, drei sind das Maximum. Vollständiger Fragenkatalog, Zweig für Zweig:

→ Lies references/01-discovery-wizard.md

Runde 1 besteht immer aus denselben beiden Fragen – Subjekttyp und Hauptziel:

SubjektWas das Scrollen wirklich tut
Person (Portfolio, Lebenslauf, persönliche Marke)Vertrauen aufbauen: Arbeit → Nachweis → Kontakt
Produkt (physisch oder digital)Das Objekt enthüllen: Hero → Funktionen → Kauf
Unternehmen (Agentur, Startup, Studio)Größe etablieren: Manifest → Arbeit → Team
Event / Launch (Konferenz, Drop, Veröffentlichung)Vorfreude aufbauen: Datum → Lineup → Anmeldung
Anliegen / Geschichte (Non-Profit, redaktionell, Bericht)Ein Argument führen: Haken → Beweis → Handlung

Der Zweig, in dem du landest, bestimmt das Abschnittsskelett und das dominierende Bewegungsmuster. Runde 2 stellt zweigspezifische Fragen (welche Arbeit, welches Produkt, welcher Nachweis). Runde 3, nur wenn noch Unklarheiten bestehen, klärt die ästhetische Richtung, die Bewegungsintensität und die Asset-Strategie.

Beende den Assistenten, sobald du Folgendes nennen kannst: das Subjekt, das Ziel, 4–7 Abschnitte, eine ästhetische Richtung und woher die Assets kommen. Den Rest erschließe.


Phase 2 – SCORE (die Blaupause)

Fasse alles in scroll-score.json im Projektstammverzeichnis zusammen. Dies ist der Vertrag, den sowohl der Builder als auch der Verifizierer lesen – schreibe ihn, bevor du eine Komponente schreibst.

→ Lies references/02-scroll-score.md für das vollständige Schema.

Ein Score ist eine Liste von Beats. Ein Beat = ein scrollgesteuerter Moment: was pinnt, was scrubbed, über welche Distanz und was sich bewegt.

{
  "meta":  { "subject": "…", "type": "product", "goal": "…", "stack": "vite-vanilla" },
  "theme": { "bg": "#0a0a0a", "fg": "#fafafa", "accent": "#ff4d17", "font": { … } },
  "motion":{ "intensity": "cinematic", "smoothScroll": false, "reducedMotion": "degrade" },
  "beats": [
    { "id": "hero", "pattern": "media-scrub-sequence", "pin": true,
      "scrub": 1, "start": "top top", "end": "+=200%", "frames": 48, … },
    { "id": "features", "pattern": "sticky-stack", … }
  ]
}

Budgetiere das Scrollen. Die gesamte Seitenhöhe sollte in der Nähe von 100vh × (1 + Σ Beat-Scrollkosten) liegen. Ein gepinnter Scrub-Beat kostet 1,5–2,5 Viewport-Höhen; ein Reveal-Beat kostet ~1. Unter 3 insgesamt wirkt die Seite abrupt; über 12 fühlt sie sich an wie eine lästige Pflicht. Strebe 5–9 an.


Phase 3 – ASSETS

Versende niemals graue Boxen. Jeder im Score genannte Beat benötigt sein echtes Asset vor Phase 5 – ein Build gegen Platzhalter muss immer wiederholt werden.

→ Lies references/05-asset-pipeline.md für die vollständige Pipeline, einschließlich der KI-Render → interpolierten Video → Frame-Sequenz-Kette, aller ffmpeg-Aufrufe und der Gewichtsbudgets.

Drei Quellen, in der Reihenfolge der Präferenz:

  1. Vom Benutzer bereitgestellt – gewinnt immer. Frage im Assistenten danach, niemals danach.
  2. Generiert – mcp__image-gen-mcp__generate_image (gpt-image-2, background: "transparent" für Produkte, bis zu 3840x2160), oder edit_image, um ein echtes Produktfoto in einen gestalteten Render zu verwandeln.
  3. Platzhalter – nur für einen Beat, den der Benutzer explizit zurückgestellt hat, und es muss eine durchdachte Gradienten-/Typografie-Komposition sein, niemals eine graue Box.

Für einen Bildsequenz-Hero (der Apple-artige „Produkt explodiert beim Scrollen“) ist die Kette: Erstes Bild + letztes Bild → interpoliertes Video → extrahierte Frames → WebP-Sequenz → Canvas-Scrub. Halte die Sequenz unter 4 MB insgesamt, 36–60 Frames, 1600px breit. Dieses Budget ist der einzige Grund, warum der Effekt nutzbar bleibt; es zu sprengen ist der häufigste Fehler dieses Musters.


Phase 4 – SCAFFOLD

Standard-Stack, sofern der Benutzer keinen genannt hat: Vite + Vanilla TS + GSAP. Er hat keinen Framework-Lebenszyklus, gegen den man ankämpfen muss, und ScrollTrigger-Fehler in React sind fast immer Aufräumfehler. Verwende Next.js/React nur, wenn der Benutzer es verlangt oder das Projekt Routing benötigt, und dann verwende useGSAP() zum Aufräumen – niemals nacktes useEffect.

Smooth Scroll (Lenis) ist OPT-IN – es ist nicht mehr Teil des Standard-Stacks. Füge es nur hinzu, wenn der Benutzer explizit nach weichem oder trägem Scrollen fragt. Es ersetzt das native Scrollen durch eine eigene animierte Position, und wenn es sich auch nur leicht falsch anfühlt, wirkt die gesamte Seite kaputt – dies ist der häufigste Grund, warum ein technisch korrekter Build abgelehnt wird. ScrollTriggers scrub gibt dir bereits das abgemilderte, filmische Gefühl, das die Leute normalerweise mit „smooth“ meinen. Siehe references/08-failure-modes.md §1.

→ Lies references/07-stack-setup.md für Gerüste und genaue Befehle.

GSAP ist seit v3.13 (Webflow-Übernahme) 100% kostenlos, einschließlich SplitText, ScrollSmoother und MorphSVG. npm install gsap bringt alles – kein Lizenzschlüssel, kein gsap-trial, keine CDN-Plugin-Workarounds. Sage dem Benutzer nicht, dass ein Plugin kostenpflichtig ist.

Inhalte leben in src/content.ts, niemals inline im Markup. Der Benutzer muss in der Lage sein, Texte zu ändern, ohne den Bewegungscode zu berühren.


Phase 5 – BUILD

Setze jeden Beat aus dem Score mit den kanonischen Musterimplementierungen um:

→ Lies references/03-pattern-library.md – 12 Muster, kopierbereit.

MusterVerwende es für
reveal-on-enterStandard-Abschnittseingänge, Kartenraster
text-revealÜberschriften, Pullquotes (SplitText, maskiert)
pin-scrubDer zentrale „Wow“-Moment – gepinnte Bühne, gescrubbte Timeline
parallax-layersTiefe: Hintergründe, Vordergrund-Requisiten
media-scrub-sequenceApple-artige Produktenthüllung (Canvas + Frames)
media-scrub-videoGleicher Effekt aus einer Videodatei (currentTime)
horizontal-scrollPortfolios, Galerien, Zeitleisten
mask-revealEin Bild, das sich öffnet, um den Viewport zu verschlingen
sticky-stackFunktionslisten, stapelnde Karten
scroll-progressFortschrittsbalken, Zähler, Abschnittsanzeiger
theme-morphHintergrund-/Farbwechsel zwischen Abschnitten
snap-sectionsDeck-artige Seiten, ein Abschnitt pro Scroll

Und die nicht verhandelbaren GSAP-Regeln:

→ Lies references/04-gsap-rules.md, bevor du ScrollTrigger-Code schreibst.

Die fünf, die am häufigsten Builds zerstören:

  1. Ein ScrollTrigger pro Timeline, auf der Timeline – niemals auf einem untergeordneten Tween, niemals innerhalb einer übergeordneten Timeline verschachtelt.
  2. Wenn – und nur wenn – du Lenis hinzugefügt hast, teilt es sich GSAPs Schleife. lenis.on('scroll', ScrollTrigger.update) + gsap.ticker.add(t => lenis.raf(t * 1000)) + gsap.ticker.lagSmoothing(0). Füge niemals eine separate requestAnimationFrame-Schleife für Lenis hinzu.
  3. ease: "none" bei jedem Tween, das containerAnimation oder einen Media-Scrub antreibt.
  4. scrub oder toggleActions, niemals beide beim selben Trigger.
  5. ScrollTrigger.refresh() nachdem Schriftarten und Bilder geladen sind – nicht nur bei Größenänderung.
  6. Vor jedem Pin durchlaufe die Vorfahren auf transform / filter / contain. Jede davon bricht position: fixed stillschweigend, sodass der Pin erstellt wird, pin: true meldet und nichts tut. Entferne die Eigenschaft oder setze pinType: 'transform'. Siehe 08-failure-modes.md §2.

Animiere nur transform und opacity. Alles, was beim Scrollen top, left, width, height oder margin berührt, wird Frames fallen lassen.


Phase 6 – VERIFY

Diese Phase ist nicht optional, und sie ist das, was diese Fähigkeit vom manuellen Schreiben von GSAP unterscheidet. Scroll-Animationen können nicht durch das Lesen von Code verifiziert werden – Pins kollabieren, Trigger feuern in der falschen Tiefe, und Frames gehen nur in einem echten Browser bei einem echten Viewport verloren.

→ Lies references/06-verification.md für die vollständige Schleife und die Checkliste. → Lies references/08-failure-modes.md – Fehler, die jede automatisierte Prüfung bestehen. Lese es vor Phase 4, nicht nachdem etwas kaputtgegangen ist.

Starte den Dev-Server, dann steuere ihn mit Playwright MCP:

mcp__playwright__browser_navigate      → die Dev-Server-URL
mcp__playwright__browser_resize        → 1440×900, dann 390×844
mcp__playwright__browser_evaluate      → zu Tiefe scrollen, Zustand lesen
mcp__playwright__browser_take_screenshot → bei jeder Tiefe
mcp__playwright__browser_console_messages → Fehler und GSAP-Warnungen
mcp__playwright__browser_network_requests → 404er, Asset-Gewicht

Scanne 0 %, 15 %, 30 %, 50 %, 70 %, 85 %, 100 % der Seitenhöhe auf Desktop und Mobilgerät. Mache bei jedem Stopp einen Screenshot und schaue ihn dir an. Du überprüfst, ob die Seite richtig aussieht, nicht nur, ob sie keine Fehler geworfen hat.

Bewege die Seite mit ECHTER Eingabe – mouse.wheel() oder Tastendrücken, niemals window.scrollTo. Synthetisches Scrollen wird von Scroll-Hijacking-Bibliotheken verschluckt, was genau der Fehler ist, den du abfangen musst. Wenn drei Raddrehungen die Seite nicht bewegen, ist sie kaputt, egal was die Behauptungen sagen.

Brich den Durchlauf ab und korrigiere, wenn eines dieser Probleme zutrifft:

  • Ein Konsolenfehler oder eine ScrollTrigger-Warnung
  • Ein 404er oder das gesamte Asset-Gewicht über dem Budget
  • Ein leerer/unformatierter Screenshot bei einer beliebigen Tiefe
  • Ein gepinnter Abschnitt, der den nächsten Abschnitt überlappt oder das Layout zusammenbrechen lässt
  • Inhalt, der nie sichtbar wird (ein Reveal, der nie auslöst)
  • Horizontaler Überlauf bei 390px Breite
  • markers: true existiert noch irgendwo im Quellcode
  • Kein prefers-reduced-motion-Fallback
  • Drei echte Raddrehungen bewegen die Seite nicht sichtbar
  • Ein Pin, dessen Bühne immer noch den Scroll verfolgt (behaupte |rect.top| < 10 innerhalb des Bereichs)
  • Gescrubbte Medien erreichen ihr Ende vor ~90% ihres Pins
  • Mehr als ~40 Raddrehungen, um den primären CTA zu erreichen

Schleife korrigieren → erneut verifizieren, bis sauber, bis zu 5 Runden. Wenn nach 5 Runden immer noch etwas fehlschlägt, versende den Rest, deaktiviere diesen einen Beat hinter einem Flag und sage dies im Abschlussbericht klar. Melde niemals Erfolg für eine nicht verifizierte Seite.


Definition von „erledigt“

  • scroll-score.json stimmt mit dem tatsächlich Gebauten überein
  • Jeder Beat auf Desktop und Mobilgerät verifiziert
  • Keine Konsolenfehler, keine 404er
  • prefers-reduced-motion reduziert sich auf sofortige Zustände, keine Bewegung
  • Lighthouse-ähnliche Vernunft: kein Layout-Shift durch Pins, Bilder dimensioniert
  • README.md – wie man es ausführt, wo der Inhalt lebt, wie man Assets austauscht
  • DECISIONS.md – Annahmen, die nach dem Schließen des Assistenten getroffen wurden
  • Abschlussnachricht: was gebaut wurde, was angenommen wurde, was zu überprüfen ist

Nicht tun

  • ❌ Nach dem Schließen des Assistenten Fragen stellen – stattdessen annehmen, protokollieren und berichten
  • ❌ „Erledigt“ melden, ohne Phase 6 in einem echten Browser ausgeführt zu haben
  • ❌ markers: true, console.log oder ein TODO im ausgelieferten Code versenden
  • ❌ gsap-trial verwenden oder behaupten, SplitText/ScrollSmoother benötigten eine Club-Lizenz
  • ❌ Layout-Eigenschaften beim Scrollen animieren
  • ❌ Auf Mobilgeräten pinnen, ohne es zu überprüfen – unter 768px bevorzugt einblenden
  • ❌ Das Asset-Budget für eine Hero-Sequenz überschreiten

Verwandte Skills