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:
| Subjekt | Was 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:
- Vom Benutzer bereitgestellt – gewinnt immer. Frage im Assistenten danach, niemals danach.
- Generiert –
mcp__image-gen-mcp__generate_image(gpt-image-2,background: "transparent"für Produkte, bis zu3840x2160), oderedit_image, um ein echtes Produktfoto in einen gestalteten Render zu verwandeln. - 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.
| Muster | Verwende es für |
|---|---|
reveal-on-enter | Standard-Abschnittseingänge, Kartenraster |
text-reveal | Überschriften, Pullquotes (SplitText, maskiert) |
pin-scrub | Der zentrale „Wow“-Moment – gepinnte Bühne, gescrubbte Timeline |
parallax-layers | Tiefe: Hintergründe, Vordergrund-Requisiten |
media-scrub-sequence | Apple-artige Produktenthüllung (Canvas + Frames) |
media-scrub-video | Gleicher Effekt aus einer Videodatei (currentTime) |
horizontal-scroll | Portfolios, Galerien, Zeitleisten |
mask-reveal | Ein Bild, das sich öffnet, um den Viewport zu verschlingen |
sticky-stack | Funktionslisten, stapelnde Karten |
scroll-progress | Fortschrittsbalken, Zähler, Abschnittsanzeiger |
theme-morph | Hintergrund-/Farbwechsel zwischen Abschnitten |
snap-sections | Deck-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:
- Ein ScrollTrigger pro Timeline, auf der Timeline – niemals auf einem untergeordneten Tween, niemals innerhalb einer übergeordneten Timeline verschachtelt.
- 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 separaterequestAnimationFrame-Schleife für Lenis hinzu. ease: "none"bei jedem Tween, dascontainerAnimationoder einen Media-Scrub antreibt.scrubodertoggleActions, niemals beide beim selben Trigger.ScrollTrigger.refresh()nachdem Schriftarten und Bilder geladen sind – nicht nur bei Größenänderung.- Vor jedem Pin durchlaufe die Vorfahren auf
transform/filter/contain. Jede davon brichtposition: fixedstillschweigend, sodass der Pin erstellt wird,pin: truemeldet und nichts tut. Entferne die Eigenschaft oder setzepinType: 'transform'. Siehe08-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: trueexistiert 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| < 10innerhalb 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.jsonstimmt mit dem tatsächlich Gebauten überein - Jeder Beat auf Desktop und Mobilgerät verifiziert
- Keine Konsolenfehler, keine 404er
-
prefers-reduced-motionreduziert 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.logoder einTODOim ausgelieferten Code versenden - ❌
gsap-trialverwenden 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