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.
- 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: 0im CSS, die darauf warten, von einem Skript enthüllt zu werden. - Drei Zustände für jeden Effekt. Voll; reduzierte Bewegung (ein Standbild oder eine kurze Einblendung:
prefers-reduced-motionund 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. - 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.
- 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.
- 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. - 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.
- 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. - 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.
- 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)
-
Schau, bevor du baust. Finde das Theme:
theme.css,DESIGN.md(vom ui-craft Studio), Tokens, eine Tailwind-Konfiguration, Markenfarben. Lies--immersiveund 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. -
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.
-
Wähle das leichteste Werkzeug, das die Aufgabe erledigen kann.
Bedarf Verwende Kosten Enthüllung, parallaxfreie Scrolleffekte, Seitenübergänge Nur CSS: scrollgesteuerte Animationen, position: sticky, View Transitions0 KB Eine flache lebendige Textur, Linien, ein Feld, eine 2D-Figur Canvas 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 Kamera three.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 kann GSAP ScrollTrigger (kostenlos, nicht Open Source: lade es, kopiere es nie hinein) oder Motion 25-45 KB Neueste GPU-Funktionen WebGPU 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.
-
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 -
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.jsbietet 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.htmlist eine funktionierende Seite mit (a)-(c) bereits erledigt; ersetze ihre Platzhalterszene. -
Überprüfe, dann schau. Führe
node <skill-dir>/scripts/immersive-check.mjs page.htmlaus. 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--apphinzu, 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.pngspeichert die Box der Szene aus dem Desktop-Durchlauf (--scheme lightoderdarkwählt das Theme), bereit zur Verwendung als Fallback-Bild. Führe dann ui-craftsui-audit.mjsfür Kontrast, Tippziele und Schrift aus und beurteile das Telefon so streng wie den Desktop. Letzter Durchlauf:references/accessibility-fallbacks.mdCheckliste.
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).
| Stufe | Was es ist | Passt | Passt nicht |
|---|---|---|---|
| 0 Still | Kein 3D, Shader oder Scrolleffekte. Nur gewöhnliche Interface-Bewegung | Finanzwerkzeuge, Administration, Regierung, Gesundheitsformulare, dichte Dashboards, alles, was den ganzen Tag genutzt wird | - |
| 1 Akzent | Ein ruhiges lebendiges Detail: ein Material, eine langsame Shader-Textur, ein View Transition. Es beruhigt sich nach ein paar Sekunden. Keine scrollgesteuerten Szenen | SaaS-Apps, Doks, die meisten Produkt-UI, Desktop- und mobile Apps | Aufgaben, bei denen die Leute ängstlich oder gehetzt sind |
| 2 Signatur | Ein Held-Moment: ein Objekt oder Shader, das auf den Zeiger oder das erste Scrollen antwortet. Dann eine normale Seite | Landingpages, Produktseiten, Portfolios, Onboarding, ein Startbildschirm | Seiten, die die Leute täglich wieder besuchen |
| 3 Geschichte | Eine scrollgesteuerte Sequenz von 3-5 Beats mit einer durchgehenden Szene | Launches, Kampagnen, redaktionelle Features, Museums- und Markengeschichten | Apps, 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.
| Was | Telefon | Desktop |
|---|---|---|
| Largest Contentful Paint (muss Text oder ein Poster sein, niemals die Canvas) | 2,5 s oder weniger | 2,5 s oder weniger |
| Skript, das vor dem ersten Paint angefordert wird | unter 170 KB komprimiert | gleich |
| Engine (three.js etwa 180 KB gzip) | nach dem ersten Paint, dynamisches import(), nur wenn die Szene in der Nähe des Viewports ist | gleich |
| Erste Szenenladung: Engine + Modelle + Texturen * | unter 1,5 MB | unter 4 MB |
| Held-Modell (GLB, komprimiert) * | unter 2 MB, 20-60k Dreiecke | unter 5 MB, bis zu 100k |
| Texturen | 1024 px; 2048 nur für den Helden; KTX2 für GPU-Speicher | 2048; 4096 nur für Nahaufnahmen |
| Pixel Ratio | Deckel 1,5, auf 1 fallen, wenn langsam | Deckel 2 |
| Draw Calls pro Frame * | unter 100 | unter 300 |
| Echtzeit-Lichter | 1 Key (+ Umgebung); 1 Schattenkarte von 1024, oder ein gebackener / Klumpenschatten | 1-3; Schattenkarte höchstens 2048 |
| Post-Processing-Durchgänge | 0-1 | 1-3 |
| Frame-Zeit | 60 fps konstant; Qualität schrittweise reduzieren, bevor unter 30 gefallen wird | 60 fps |
| Scroll-Geschichte | 3-5 Beats, je 100-150vh, angehefteter Lauf unter 5 Bildschirmen *, ein Skip-Link | gleich |
| Preloader | keiner; die Seite ist in 1-2 Sekunden lesbar und die Szene blendet ein, wenn sie bereit ist | gleich |
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()inassets/theme-bridge.jsgibt jede als lineares RGB für Beleuchtungsmathematik und sRGB für flaches Zeichnen zurück, undwatchTheme()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-outformen 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-displayund--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.