Communitygithub.com

immersive-web

Erstelle immersive, filmreife „Website der Zukunft”-Erlebnisse, die schnell und barrierefrei bleiben – 3D-Szenen im Browser (Three.js, React Three Fiber, WebGL, WebGPU), Shader (GLSL, TSL), scrollgesteuerte Erzählweisen, cineastische Bewegungen und Seitenübergänge sowie den Weg von Blender in den Browser (glTF, Draco, meshopt, KTX2, gebackene Beleuchtung).

Was ist immersive-web?

Diese Skill-Anleitung beschreibt, wie man dreidimensionale, shaderbasierte und scrollgesteuerte Web-Erlebnisse entwickelt, die sich wie die besten Filme und Spiele anfühlen, dabei aber so schnell laden wie eine normale Seite und niemanden ausschließen. Sie ist als Ergänzung zum ui-craft-Skill konzipiert, der für das Interface-Design (Layout, Typografie, Farben, Komponenten) zuständig ist. Der immersive-web-Skill fügt die nächste Ebene hinzu: Szene, Licht, Material, Shader, Kamera, Scroll- und cineastische Bewegungen. Beide Skills nutzen dieselben Theme-Token, sodass ein einziges Theme die gesamte Seite und die 3D-Szene steuert. Die Anleitung enthält neun harte Regeln (z. B. „Content first”, drei Zustände für jeden Effekt, ein fester Geschwindigkeitsbudget), einen detaillierten Arbeitsablauf (vom Suchen des Themes und Schreiben des immersiven Briefings bis zur Überprüfung mit dem Skript immersive-check.mjs) sowie eine „Immersion Ladder” (Stufen 0–3), die den Grad der Interaktivität und Komplexität definiert. Zudem werden Budgets für Performance, Ladezeiten und Szene-Spezifikationen (z. B. Pixel Ratio, Draw Calls, Texturen) vorgegeben. Technische Referenzen finden sich in den angehängten Dokumenten zu Szene/Kamera, Materialien/Licht, Shadern, Scroll-Storytelling, cineastischer Bewegung und der Blender-Pipeline.

Funktioniert mit~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/najeebafridi/ui-craft/tree/HEAD/skills/immersive-web

In Ihrer bevorzugten KI fragen

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

Dokumentation

Was macht immersive-web?

So baust du 3D-, Shader- und scrollgesteuerte Erlebnisse, die sich wie die besten Filme und Spiele anfühlen, wie eine normale Seite laden und niemanden ausschließen.

Dieses Skill ist eine Ebene. Der ui-craft-Skill (gleiches Plugin) gehört zum normalen Interface-Design: Layout, Hierarchie, Schrift, Farbe, Komponenten, Formulare, Zustände. Verwende ihn für all das und wiederhole es hier nicht. Dieses Skill fügt die darüberliegende Ebene hinzu: Szene, Licht, Material, Shader, Kamera, Scroll und cineastische Bewegung. Beide lesen die gleichen Theme-Token, sodass ein Theme die Seite und die Szene steuert (references/theme-bridge.md).

Ehrliche Grenze. Du kannst eine Szene inszenieren, sie beleuchten, eine Kamera bewegen, Shader schreiben und ein Modell einbinden. Du kannst keine filmreife 3D-Kunst aus dem Nichts erschaffen. Setze dich aus einfachen Geometrien, Shadern, Schrift und Licht zusammen oder verwende ein vom Team bereitgestelltes Modell. Simuliere niemals etwas mit einer groben Zeichnung des Motivs.

1. Die neun harten Regeln

Wenn du eine davon brichst, ist die Arbeit nicht getan, egal wie gut sie aussieht.

  1. Inhalt zuerst. Überschriften, Text, Links und Buttons sind echtes HTML, das lesbar ist, bevor ein Skript läuft. Die Szene wird oben draufgesetzt und kann ohne Verlust verschwinden. Zeichne die Wörter der Seite niemals in eine Canvas. Verstecke niemals Inhalte auf opacity: 0 im CSS, die darauf warten, von einem Skript enthüllt zu werden.
  2. Drei Zustände für jeden Effekt. Voll; reduzierte Bewegung (ein Standbild oder eine kurze Einblendung: prefers-reduced-motion und die OS-Einstellung in nativen Apps); keine GPU (ein Poster-Bild oder CSS/SVG-Kunst, das angezeigt wird, wenn WebGL oder WebGPU fehlt, fehlschlägt oder der Kontext verloren geht). Gestalte zuerst die beiden Fallbacks. Sie werden auch zuerst geladen. Ein Fallback ist das gleiche Bild, leiser: das gleiche Motiv aus dem gleichen Winkel (ein Poster, das aus der Szene selbst erstellt wurde), und für eine Datenszene die gleichen Daten flach gezeichnet. Eine leere Box, ein einfacher Verlauf oder „Bild folgt” ist ein Fehler.
  3. Ein Geschwindigkeitsbudget, das vor dem Bau festgelegt wird (§4). Der Text der Seite wird zuerst gemalt; die Engine lädt danach. Auf einem Telefon kostet die Szene weniger als der Inhalt.
  4. Ein markanter Moment pro Seite, und mach ihn zählend. Eine Szene, eine Idee, komplett umgesetzt. Alles andere bleibt ruhig. Effekte überall wirken wie eine Vorlage und erschöpfen die Leute. Zurückhaltung begrenzt die Anzahl der Effekte, nicht ihre Stärke: Der eine Moment ist ein Ereignis, das zu diesem Produkt gehört (der Kessel kippt; der Himmel füllt sich mit Sternen, während sich die Augen gewöhnen), kühn genug inszeniert, dass jemand es einem Freund beschreiben würde. Ein Objekt, das sich nur beim Scrollen dreht, ist kein Moment.
  5. Nimm niemals das Scrollen weg. Der Browser scrollt; du liest nur die Position. Keine geänderte Geschwindigkeit oder Richtung, kein Rad-Hijacking, keine gefälschte Scrollleiste. Fixiere mit position: sticky, halte es kurz, biete eine Möglichkeit zum Überspringen.
  6. Wörter und Szene teilen sich nie einen Platz. Bei jeder Scrollposition sitzt der Text neben dem Motiv oder auf seiner eigenen Fläche, niemals darüber. Navigation und Buttons, die über eine Szene gelegt werden, erhalten eine Scheibe oder eine Fläche. Überprüfe jeden Scroll-Screenshot, nicht nur den ersten.
  7. Tastatur und Screenreader erreichen alles Reale. Die Tab-Reihenfolge folgt der Lesereihenfolge. Eine dekorative Canvas ist aria-hidden="true"; eine bedeutungsvolle hat daneben ein Textäquivalent. Alles, was du durch Ziehen der Szene tun kannst, kannst du auch mit einem Button tun.
  8. Bewegung ruht sich aus, Ton wartet, nichts blinkt. Umgebungsbewegung beruhigt sich innerhalb von 5 Sekunden oder hat einen sichtbaren Pause-Controller. Ton ist aus, bis er angefordert wird. Niemals mehr als 3 Blitze pro Sekunde. Nichts läuft außerhalb des Bildschirms oder in einem versteckten Tab.
  9. Original und lizenziert. Lerne die Sprache eines Genres; kopiere niemals das Aussehen, Modelle, Charaktere, Logos oder Sounds eines Produkts. Verwende nur Assets, die du erstellt hast oder die eine klare Lizenz haben (CC0-Bibliotheken wie Poly Haven und ambientCG sind sicher), und dokumentiere jedes einzelne.

2. Arbeitsablauf (mache das jedes Mal)

  1. Schau, bevor du baust. Finde das Theme: theme.css, DESIGN.md (vom ui-craft Studio), Tokens, eine Tailwind-Konfiguration, Markenfarben. Lies --immersive und den Abschnitt „Immersiv und Bewegung” im Briefing, falls vorhanden: Sie geben die Intensität an, die der Eigentümer gewählt hat. Überprüfe den Stack (einfaches HTML, React, Vue, eine App-Shell) und bereits bereitgestellte 3D-Assets. Wenn es gar kein Theme gibt, verwende zuerst ui-craft, um eine Richtung zu wählen.

  2. Wähle die Stufe auf der Leiter in §3. Übernimm sie aus dem Theme, wenn es sie angibt; wähle andernfalls die niedrigste Stufe, die die Idee umsetzt. Stufe 3 ist selten.

  3. Wähle das leichteste Werkzeug, das die Aufgabe erledigen kann.

    BedarfVerwendeKosten
    Enthüllung, parallaxfreie Scrolleffekte, SeitenübergängeNur CSS: scrollgesteuerte Animationen, position: sticky, View Transitions0 KB
    Eine flache lebendige Textur, Linien, ein Feld, eine 2D-FigurCanvas 2D oder SVG, oder ein Fragment-Shader auf einem einzelnen Dreieck (rohes WebGL, keine Bibliothek)2-5 KB
    Ein 3D-Modell zeigen, das man drehen kann<model-viewer>etwa 250 KB, lazy
    Eine echte Szene: mehrere Objekte, Lichter, eine bewegte Kamerathree.js (React-App: React Three Fiber) geladen mit dynamischem import()150-180 KB gzip, lazy
    Zeitachsen, die an Scroll gebunden sind und die CSS nicht ausdrücken kannGSAP ScrollTrigger (kostenlos, nicht Open Source: lade es, kopiere es nie hinein) oder Motion25-45 KB
    Neueste GPU-FunktionenWebGPU als Upgrade auf einem WebGL-Pfad, niemals allein-

    Füge keine Smooth-Scroll-Bibliothek standardmäßig hinzu. Wenn das Briefing eine verlangt, muss sie sich bei reduzierter Bewegung ausschalten.

  4. Schreibe das immersive Briefing (füge es dem ui-craft Design-Briefing hinzu), vor dem Code:

    Level: 2 signature (theme says --immersive: 2)        Stack: plain HTML + three.js, lazy
    Signature moment (an event, not a turntable): at beat 3 the kettle tips and a thin stream pours, holding its line
    Scene: one matte ceramic kettle in a pool of light on the page background; soft key from above left, warm rim
    Text lane: copy in the left column on desktop, under the pinned scene on phones; the kettle never crosses it
    Camera: 35mm-like, slightly above, never moves by itself         Tempo: gentle (--dur-slow 400ms)
    Beats (level 3 only): 1 whole kettle - 2 the spout, close - 3 pouring - 4 the set on a table
    Reduced motion: one still render per beat, cross-faded        No GPU: a poster of the same scene, same angle
    Budget: text paints first; engine after; scene under 1.5 MB on phones; pixel ratio 1.5 on touch
    
  5. Baue in dieser Reihenfolge. (a) Die gesamte Seite als einfaches HTML und CSS mit ui-craft, mit dem Poster- oder CSS-Fallback an der Stelle der Szene. Es muss bereits eine gute Seite sein. (b) Die Szenenhülle: assets/scene-shell.js bietet Lazy-Start, Standbilder, Fallback, Pause außerhalb des Bildschirms, Pixel-Ratio-Begrenzung, Lost-Context-Wiederherstellung. (c) Die Theme-Brücke: assets/theme-bridge.js, sodass Farben, Radius und Tempo aus den Tokens kommen. (d) Die Szene selbst, in ihrer einfachsten Form. (e) Bewegung und Scroll. (f) Feinschliff: Licht, Material, Körnung, Timing. assets/starter.html ist eine funktionierende Seite mit (a)-(c) bereits erledigt; ersetze ihre Platzhalterszene.

  6. Überprüfe, dann schau. Führe node <skill-dir>/scripts/immersive-check.mjs page.html aus. Es lädt die Seite auf fünf Arten (Desktop, Telefon, reduzierte Bewegung, kein WebGL, kein JavaScript), misst Gewicht, Draw Calls, Pixel Ratio, natives Scrollen und Pausen und speichert Screenshots. Für ein App-Fenster (Electron, Tauri, eine eingeloggte Web-App) füge --app hinzu, um den Test ohne JavaScript zu überspringen. Öffne jeden Screenshot. Behebe, was fehlschlägt. Schaue am genauesten auf drei: die Mitte des Scrollens (kreuzt irgendein Text das Motiv?), die Mitte des Telefons (Szene und Text zusammen auf einem Bildschirm, keine leere Bande?) und den ohne WebGL (das gleiche Bild oder ein Loch?). Erstelle das Poster aus der Szene selbst: --poster hero-poster.png speichert die Box der Szene aus dem Desktop-Durchlauf (--scheme light oder dark wählt das Theme), bereit zur Verwendung als Fallback-Bild. Führe dann ui-crafts ui-audit.mjs für Kontrast, Tippziele und Schrift aus und beurteile das Telefon so streng wie den Desktop. Letzter Durchlauf: references/accessibility-fallbacks.md Checkliste.

3. Die Immersionsleiter

Jedes Produkt sitzt auf einer Stufe. Das Theme kann sie als --immersive: 0-3 mitführen; jede der 16 ui-craft-Richtungen setzt einen Standard (references/theme-bridge.md).

StufeWas es istPasstPasst nicht
0 StillKein 3D, Shader oder Scrolleffekte. Nur gewöhnliche Interface-BewegungFinanzwerkzeuge, Administration, Regierung, Gesundheitsformulare, dichte Dashboards, alles, was den ganzen Tag genutzt wird-
1 AkzentEin ruhiges lebendiges Detail: ein Material, eine langsame Shader-Textur, ein View Transition. Es beruhigt sich nach ein paar Sekunden. Keine scrollgesteuerten SzenenSaaS-Apps, Doks, die meisten Produkt-UI, Desktop- und mobile AppsAufgaben, bei denen die Leute ängstlich oder gehetzt sind
2 SignaturEin Held-Moment: ein Objekt oder Shader, das auf den Zeiger oder das erste Scrollen antwortet. Dann eine normale SeiteLandingpages, Produktseiten, Portfolios, Onboarding, ein StartbildschirmSeiten, die die Leute täglich wieder besuchen
3 GeschichteEine scrollgesteuerte Sequenz von 3-5 Beats mit einer durchgehenden SzeneLaunches, Kampagnen, redaktionelle Features, Museums- und MarkengeschichtenApps, Checkout, alles mit einer Aufgabe

Regeln der Leiter: Die Stufe ist eine Obergrenze, kein Ziel. Häufigkeit senkt sie: je öfter jemand einen Bildschirm sieht, desto niedriger die Stufe. Eine Aufgabe senkt sie: wo jemand bezahlt, unterschreibt oder ein Problem behebt, verwende Stufe 0. Wenn du unsicher bist, gehe eine Stufe nach unten und beende es besser.

4. Budgets

Arbeitsziele. Messe; rate nicht. Mit * markierte Zahlen sind sinnvolle Standardwerte, keine veröffentlichten Grenzen.

WasTelefonDesktop
Largest Contentful Paint (muss Text oder ein Poster sein, niemals die Canvas)2,5 s oder weniger2,5 s oder weniger
Skript, das vor dem ersten Paint angefordert wirdunter 170 KB komprimiertgleich
Engine (three.js etwa 180 KB gzip)nach dem ersten Paint, dynamisches import(), nur wenn die Szene in der Nähe des Viewports istgleich
Erste Szenenladung: Engine + Modelle + Texturen *unter 1,5 MBunter 4 MB
Held-Modell (GLB, komprimiert) *unter 2 MB, 20-60k Dreieckeunter 5 MB, bis zu 100k
Texturen1024 px; 2048 nur für den Helden; KTX2 für GPU-Speicher2048; 4096 nur für Nahaufnahmen
Pixel RatioDeckel 1,5, auf 1 fallen, wenn langsamDeckel 2
Draw Calls pro Frame *unter 100unter 300
Echtzeit-Lichter1 Key (+ Umgebung); 1 Schattenkarte von 1024, oder ein gebackener / Klumpenschatten1-3; Schattenkarte höchstens 2048
Post-Processing-Durchgänge0-11-3
Frame-Zeit60 fps konstant; Qualität schrittweise reduzieren, bevor unter 30 gefallen wird60 fps
Scroll-Geschichte3-5 Beats, je 100-150vh, angehefteter Lauf unter 5 Bildschirmen *, ein Skip-Linkgleich
Preloaderkeiner; die Seite ist in 1-2 Sekunden lesbar und die Szene blendet ein, wenn sie bereit istgleich

Eine 2048 px Textur kostet etwa 22 MB Videospeicher, sobald sie entpackt ist, unabhängig von ihrer Dateigröße, es sei denn, sie ist KTX2. Details und die Schritt-für-Schritt-Reduzierung: references/performance.md.

5. Ein Theme steuert jede Ebene

  • Lies Farben aus den Tokens (--bg, --surface, --accent, --accent-soft, --text, --border...), harte niemals einen Hex-Wert in einem Shader oder Material. readTheme() in assets/theme-bridge.js gibt jede als lineares RGB für Beleuchtungsmathematik und sRGB für flaches Zeichnen zurück, und watchTheme() liest bei einem Hell/Dunkel-Umschalter neu.
  • Die Szene sitzt auf dem Seitenhintergrund: eine transparente Canvas oder eine klare Farbe gleich --bg. Kein sichtbares Rechteck, keine zweite Hintergrundfarbe.
  • Der Akzent bleibt auch in 3D selten: ein Objekt, ein Licht, eine Linie. Meist neutral.
  • Die Form des Themes überträgt sich: Eckenradius wird Abschrägung und Kantenradius; der Tiefenstil wird der Schattenstil (Haarfein: dünne Kontur, fast kein Schatten; weich: breiter weicher Kontaktschatten; klar: enger und glänzender; Lippe: eine harte versetzte Kante; flach: keiner).
  • Die Bewegungs-Tokens setzen das Tempo: --dur-* und --ease-out formen Kamerabewegungen und Scroll-Easing (bezier() in der Brücke), sodass ein „Sofort”-Werkzeug und eine „langsame” Luxusmarke sich mit dem gleichen Code unterschiedlich bewegen. Überschwingen nur dort, wo die Kurve des Themes überschwingt.
  • Schrift bleibt HTML in --font-display und --font-sans, über oder neben die Canvas gelegt.

6. Handwerk, kurz

Szene und Kamera (references/scene-camera.md)

  • Ein Motiv, eine klare Silhouette, viel ruhiger Raum. Gestalte zuerst für den hohen Rahmen des Telefons.
  • Ein langes Objektiv (Blickwinkel 20-35 Grad) schmeichelt Objekten; Weitwinkel verzerrt. Die Kamera bewegt sich langsam und mit Grund oder gar nicht.
  • Bei Bedarf rendern. Eine Szene, die sich nicht ändert, zeichnet nichts.

Licht und Material (references/materials-lighting.md)

  • Ein Key-Licht von oben (die gleiche einzelne Lichtquelle wie die UI), eine weiche Füllung, ein Randlicht, um das Motiv vom Hintergrund zu trennen. Licht ist nie reines Weiß; Schatten sind nie reines Schwarz.
  • Das Motiv verankern: ein weicher Kontaktschatten, oder es schwebt.
  • Farbräume setzen, bevor man etwas beurteilt. Zu dunkel oder ausgewaschen ist ein Farbraumfehler, kein Beleuchtungsfehler.
  • Licht in Texturen backen, wenn die Szene statisch ist. Es ist das billigste Licht, das es gibt.

Shader (references/shaders.md)

  • Ein Shader ist ein Material, ein Licht oder eine Textur mit einem Job. Keine Tapete.
  • Palette aus 2-4 Theme-Farben, gemischt in OKLab, damit die Mitte sauber bleibt. Kein Regenbogen.
  • 2-4 % Körnung hinzufügen, um Banding in weichen Verläufen zu verbergen. Halte die Fragment-Arbeit auf Telefonen billig: wenige Textur-Lesevorgänge, keine langen Schleifen.

Scroll-Storytelling (references/scroll-storytelling.md)

  • Jeder Beat ist eine Idee mit einer Zeile echten Texts. Wenn ein Beat nichts zu sagen hat, streiche ihn.
  • Der Text scrollt normal; die Szene bleibt still (sticky) und ändert sich mit ihm. Scrub-Position, niemals Zeit.
  • Reduzierte Bewegung verwandelt den Film in Folien: ein Standbild pro Beat.

Cineastische Bewegung (references/cinematic-motion.md)

  • Schneide oder überblende zwischen Ideen; bewege dich innerhalb einer. Halte inne bei dem, was zählt. Easing ist Handlung: Gewicht, keine Dekoration.
  • Interface-Bewegung behält das Timing von ui-craft (100-300 ms). Szenen- und Kamerabewegungen dauern 600-1200 ms. Seitenübergänge 200-500 ms, und URL, Zurück-Button und Fokus funktionieren weiterhin.

Blender in den Browser (references/blender-pipeline.md)

  • Nur Principled BSDF, den Rest backen, GLB exportieren, dann komprimieren: gltf-transform optimize, meshopt oder Draco, KTX2-Texturen. Überprüfe die Datei auf Fehler und teste sie vor dem Einbinden.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Verwandte Skills