PHL-Mechanics/cinematic-web

Cinematic Web — Bewegung mit Absicht

Skill zur Erstellung von filmischen Web-Erlebnissen: Websites, die sich wie ein Film anfühlen, bei denen das Scrollen einer Kamera gleicht und jedes Element mit Timing, Gewicht und Eleganz erscheint. Der Basis-Stack ist Next.js + Tailwind + GSAP + ScrollTrigger + Lenis, aber der Kern (das Bewegungssystem) ist auf reines HTML/CSS, WordPress/Divi und LearnWorlds übertragbar.

Kernphilosophie: Filmische Websites sind nicht schnell – sie sind langsam mit Absicht. Eile ist der Feind von Eleganz. Bevor eine einzige Codezeile geschrieben wird, ist die Bewegung entschieden; der Code gehorcht nur.

---

Die goldene Regel (das unveränderliche Gesetz)

Drei Bibliotheken, drei Verantwortlichkeiten. Diese zu vermischen ist die Hauptursache für ruckelndes Scrollen und Fehler auf mobilen Geräten:

Bibliothek	EINZIGE Verantwortung	Tut niemals
Lenis	Sanftes Scrollen (die Trägheit, das „Gewicht“ des Scrollens)	Animiert keine Elemente
GSAP	Bewegung der Elemente (Position, Deckkraft, Skalierung)	Steuert nicht das Seiten-Scrollen
ScrollTrigger	Orchestrierung – wann/wie jede Animation beim Scrollen ausgelöst wird	Führt keine eigene Schleife aus

Und das Detail, das Amateure von Profis trennt: Lenis und ScrollTrigger müssen denselben Zeit-Takt (gsap.ticker) teilen. Wenn sie in separaten RAFs laufen, wird scrub ruckelig (Jitter). Die kanonische Integration befindet sich in assets/lib/lenis-provider.tsx – immer dieses Muster verwenden, niemals zwei lose requestAnimationFrame.

// Das Herz der Integration (vollständige Details in references/01-setup.md):
lenis.on('scroll', ScrollTrigger.update);          // Lenis benachrichtigt ScrollTrigger bei jedem Scrollen
gsap.ticker.add((time) => lenis.raf(time * 1000)); // GSAP steuert den RAF von Lenis (einzige Zeitquelle)
gsap.ticker.lagSmoothing(0);

---

Das Bewegungssystem (Tokens, keine Improvisation)

Die „künstlerische Verfeinerung“ wird nicht am Ende nach Augenmaß vorgenommen – sie wird von Anfang an durch zentrale Tokens in assets/lib/motion.ts erzwungen. Jede Animation bezieht sich hierauf. Das macht die Verfeinerung deterministisch.

Kanonische Dauern (in Sekunden):

Token	Wert	Für
fast	0.6	Das absolute Minimum. Nichts Filmisches ist kürzer als 0,6 s.
base	0.9	Standard-Reveals von Text und Bild
slow	1.2	Hero-Bereiche, Sektions-Einblendungen, Momente der Atempause
epic	1.8	Anker-Übergänge, „Kameramomente“

Kanonische Eases (die „Signatur“ der Bewegung):

Token	Wert	Gefühl
out	power3.out	der Standard. Entschlossener Eintritt, der mit Anmut verlangsamt
inOut	power3.inOut	Bewegungen, die hin und her gehen (Pin, Kamera)
expo	expo.out	Dramatische Reveals, hoher Geschwindigkeitskontrast
soft	power2.out	Subtile Mikro-Interaktionen

Verfeinerungsregel (Phase 5): Jeder Übergang < 0,6 s wird verlängert. Jedes ease, das nicht power oder expo ist (z. B. linear, back, bounce, elastic), wird ersetzt – sie zerstören die filmische Nüchternheit. stagger zwischen aufeinanderfolgenden Elementen: 0,15–0,2 s.

---

Workflow – die 5 Phasen

In der Reihenfolge ausführen. Jede Phase hat eine Referenzdatei mit vollständigen, direkt einsetzbaren Rezepten. Lies die Referenz der Phase, bevor du Code dafür generierst.

Phase 1 – Die Projektbibel (niemals die KI raten lassen)

Bevor irgendeine Komponente erstellt wird, die Regeln festlegen. Erstelle/aktualisiere die CLAUDE.md im Stammverzeichnis des Projekts mit der Vorlage aus assets/CLAUDE.md und richte den Stack gemäß references/01-setup.md ein.

• Installiere: gsap @gsap/react lenis (+ Next/Tailwind, falls neues Projekt).
• Fixiere die goldene Regel und das Bewegungssystem in der CLAUDE.md.
• Kopiere assets/lib/lenis-provider.tsx und assets/lib/motion.ts in das Projekt.
• Noch keine Komponenten generieren. Erst das Fundament.

Phase 2 – Der filmische Hero

Der erste Eindruck definiert den Ton: Spannung und Flüssigkeit noch vor der ersten Interaktion. Vollständiges Rezept in references/02-hero.md.

• Vollbild, Hintergrundvideo in Schleife (mit Bild-Fallback und Overlay).
• Text erscheint mit sanftem Reveal (Maske + y/opacity, slow + expo.out), sequenziell mit stagger.
• Scroll-Indikator, der verschwindet, sobald der Benutzer zu scrollen beginnt.

Phase 3 – Scrollen mit „Kamerablick“

Hier geschieht die Magie: Das Scrollen wird zur Kamerabewegung. Rezepte (Pin, Sequenz, Parallax, Scrub) in references/03-scroll-camera.md.

• Abschnitte mit Pin-Scroll via ScrollTrigger.
• Elemente erscheinen in Sequenz (stagger 0,15–0,2 s) mit power3.out.
• Kontrolliertes Scrollen (scrub), keine lose Animation – das Tempo folgt dem Finger des Benutzers.

Phase 4 – Das mobile Chaos bändigen

Komplexe Animationen brechen auf Mobilgeräten nicht zufällig, sondern aus Designgründen. Strategie in references/04-mobile-a11y.md.

• Trenne Desktop ≠ Mobile mit gsap.matchMedia() – kein if über den Code verteilt.
• Respektiere prefers-reduced-motion (Barrierefreiheit + Übelkeitsvermeidung + rechtliches Risiko).
• Performance: Nur transform/opacity animieren, schwere pin-Nutzung auf Touch-Geräten vermeiden, Lenis↔ScrollTrigger-Konflikt prüfen.
• Ändere nicht die Desktop-Ästhetik, wenn du Mobile korrigierst.

Phase 5 – Künstlerische Verfeinerung

Der letzte Schliff, der „animiert“ von „filmisch“ trennt. Checkliste in references/05-refinamento.md.

• Jeder Übergang < 0,6 s → verlängert.
• Jeder ease außerhalb von power/expo → ersetzt.
• Konsistenz prüfen: Alles aus motion.ts? Harmonisieren die Zeiten miteinander?

---

Qualitäts-Checkliste (vor der Auslieferung durchführen)

• Lenis und ScrollTrigger teilen sich gsap.ticker (kein doppelter RAF).
• React-Animationen verwenden useGSAP (aus @gsap/react) mit scope → automatische Bereinigung, kein Verschleppen zwischen Routen.
• Komponenten mit GSAP sind "use client" und registrieren das Plugin (gsap.registerPlugin(ScrollTrigger, useGSAP)).
• Jedes Timing/Jeder ease stammt aus motion.ts – null magische Zahlen im Code verteilt.
• gsap.matchMedia() deckt Desktop und Mobile ab; prefers-reduced-motion deaktiviert/verkürzt die Bewegung.
• Nur transform und opacity werden animiert (kein Animieren von width, top, margin → Reflow).
• ScrollTrigger.refresh() wird nach dem Laden von Schriftarten/Bildern aufgerufen, die die Seitenhöhe ändern.
• Nichts unter 0,6 s; kein linear/back/bounce/elastic.

---

Portabilität (außerhalb von Next)

Das Bewegungssystem und die goldene Regel gelten in jeder Umgebung. Für reines HTML/CSS, WordPress/Divi oder LearnWorlds: Verwende GSAP + ScrollTrigger + Lenis via CDN, behalte dieselben Tokens für Dauer/Ease bei und präfixe Klassen/Selektoren, um Stil-Konflikte in der Plattform zu vermeiden. Spezifische Hinweise am Ende von references/01-setup.md.

---

Dateiübersicht der Skill

• assets/CLAUDE.md – Vorlage für die Projektbibel (ins Stammverzeichnis kopieren und anpassen).
• assets/lib/lenis-provider.tsx – React/Next-Provider mit der kanonischen Lenis↔GSAP-Integration.
• assets/lib/motion.ts – Bewegungs-Tokens (Dauern, Eases, Helfer für Reveals).
• references/01-setup.md – Stack, Installation, Integration, SSR/Next, Portabilität.
• references/02-hero.md – Vollständiges Rezept für den filmischen Hero.
• references/03-scroll-camera.md – Pin, Stagger, Parallax, Scrub, horizontales Scrollen.
• references/04-mobile-a11y.md – MatchMedia, Reduced-Motion, Performance, Mobile-Debugging.
• references/05-refinamento.md – Detailliertes Bewegungssystem und Polier-Checkliste.