Communitygithub.com

immersive-web

Créez des expériences immersives et cinématographiques de « site web du futur », rapides et accessibles : scènes 3D dans le navigateur (Three.js, React Three Fiber, WebGL, WebGPU), shaders (GLSL, TSL), narration par défilement, animations cinématographiques et transitions de page, et le chemin de Blender au navigateur (glTF, Draco, meshopt, KTX2, éclairage cuit).

Qu'est-ce que immersive-web ?

Cette compétence « immersive-web » est conçue pour les développeurs et les agents IA qui souhaitent intégrer des expériences 3D, des shaders et des animations basées sur le défilement dans des applications web (HTML, React, Vue), de bureau (Electron, Tauri) ou mobiles, en suivant les meilleures pratiques d'accessibilité et de performance. Elle guide l'utilisateur depuis la sélection du niveau d'immersion (de 0 à 3, allant d'un contenu statique à une histoire narrative) jusqu'à la mise en œuvre technique, avec des règles strictes sur le contenu en premier, la gestion des états réduits (mouvement réduit, absence de GPU) et des budgets de performance explicites. La compétence travaille en tandem avec « ui-craft » pour le design d'interface classique (typographie, couleurs, composants) et se concentre sur la couche visuelle et interactive : scènes 3D, éclairage, caméras, shaders, animations cinématographiques et narration par défilement. Elle propose des workflows détaillés, des référentiels pour les shaders, l'éclairage et la caméra, et des scripts de validation automatisée (immersive-check.mjs) pour garantir la conformité aux règles d'accessibilité et de performance. L'objectif est de créer des expériences « comme les meilleurs films et jeux » qui se chargent comme une page normale et excluent personne, en utilisant des outils comme Three.js, GSAP ScrollTrigger, <model-viewer> ou des animations CSS pures selon le besoin.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Que fait immersive-web ?

Comment créer des expériences 3D, shaders et de défilement qui ressemblent aux meilleurs films et jeux, se chargent comme une page normale et n'excluent personne.

Cette compétence n'est qu'une couche. La compétence ui-craft (même plugin) gère le design d'interface ordinaire : mise en page, hiérarchie, typographie, couleur, composants, formulaires, états. Utilisez-la pour tout cela, et ne le répétez pas ici. Cette compétence ajoute la couche par-dessus : scène, lumière, matériau, shader, caméra, défilement et mouvement cinématographique. Les deux lisent les mêmes jetons de thème, donc un thème pilote la page et la scène (references/theme-bridge.md).

Limite honnête. Vous pouvez diriger une scène, l'éclairer, déplacer une caméra, écrire des shaders et intégrer un modèle. Vous ne pouvez pas sculpter un art 3D de qualité cinéma à partir de rien. Composez à partir de géométries simples, de shaders, de typographie et de lumière, ou utilisez un modèle fourni par l'équipe. Ne trichez jamais avec un dessin grossier du sujet.

1. Les neuf règles strictes

En enfreindre une, et le travail n'est pas terminé, même s'il a belle apparence.

  1. Le contenu d'abord. Titres, textes, liens et boutons sont du vrai HTML, lisible avant l'exécution de tout script. La scène est ajoutée par-dessus et peut disparaître sans perte. Ne dessinez jamais les mots de la page dans un canvas. Ne cachez jamais de contenu à opacity: 0 dans le CSS en attendant qu'un script le révèle.
  2. Trois états pour chaque effet. Complet ; mouvement réduit (une image fixe ou un court fondu : prefers-reduced-motion, et le paramètre système dans les applications natives) ; pas de GPU (une image d'aperçu ou un art CSS/SVG affiché lorsque WebGL ou WebGPU est manquant, échoue, ou que le contexte est perdu). Concevez les deux alternatives d'abord. Ce sont aussi ce qui se charge en premier. Une alternative est la même image, plus calme : le même sujet sous le même angle (une image fixe réalisée à partir de la scène elle-même), et pour une scène de données, les mêmes données tracées à plat. Une boîte vide, un dégradé uni ou « image à venir » est un échec.
  3. Un budget de performance, décidé avant la construction (§4). Le texte de la page s'affiche en premier ; le moteur se charge après. Sur un téléphone, la scène coûte moins que le contenu.
  4. Un moment signature par page, et qu'il compte. Une scène, une idée, réalisée complètement. Tout le reste reste discret. Des effets partout donnent l'impression d'un modèle et épuisent les gens. La retenue limite le nombre d'effets, pas leur force : le moment unique est un événement qui appartient à ce produit (la bouilloire verse ; le ciel se remplit d'étoiles à mesure que les yeux s'habituent), mis en scène avec assez d'audace pour que quelqu'un le décrive à un ami. Un objet qui tourne simplement lorsque vous faites défiler n'est pas un moment.
  5. Ne jamais prendre le contrôle du défilement. Le navigateur défile ; vous lisez seulement la position. Pas de changement de vitesse ou de direction, pas de détournement de molette, pas de barre de défilement factice. Épinglez avec position: sticky, gardez-le court, donnez un moyen de passer outre.
  6. Les mots et la scène ne partagent jamais un espace. À chaque position de défilement, le texte se trouve à côté du sujet ou sur sa propre surface, jamais dessus. La navigation et les boutons placés sur une scène reçoivent un voile ou une surface. Vérifiez chaque capture d'écran de défilement, pas seulement la première.
  7. Le clavier et les lecteurs d'écran atteignent tout ce qui est réel. L'ordre de tabulation suit l'ordre de lecture. Un canvas décoratif est aria-hidden="true" ; un canvas significatif a un équivalent textuel à côté. Tout ce que vous pouvez faire en faisant glisser la scène, vous pouvez le faire avec un bouton.
  8. Le mouvement se calme, le son attend, rien ne clignote. Le mouvement ambiant s'arrête en moins de 5 secondes ou dispose d'un contrôle de pause visible. Le son est désactivé jusqu'à ce qu'il soit demandé. Pas plus de 3 flashs par seconde, jamais. Rien ne s'exécute hors écran ou dans un onglet caché.
  9. Original et sous licence. Apprenez le langage d'un genre ; ne copiez jamais l'apparence, les modèles, les personnages, les logos ou les sons d'un produit. Utilisez uniquement des actifs que vous avez créés ou qui ont une licence claire (les bibliothèques CC0 telles que Poly Haven et ambientCG sont sûres), et enregistrez chacun d'eux.

2. Flux de travail (faites ceci à chaque fois)

  1. Regardez avant de construire. Trouvez le thème : theme.css, DESIGN.md (du studio ui-craft), les jetons, une configuration Tailwind, les couleurs de la marque. Lisez --immersive et la section « Immersive et mouvement » du brief si elle est présente : ils indiquent l'intensité choisie par le propriétaire. Vérifiez la pile (HTML simple, React, Vue, une coque d'application) et les actifs 3D déjà fournis. Sans thème du tout, utilisez d'abord ui-craft pour choisir une direction.

  2. Choisissez le niveau sur l'échelle du §3. Prenez-le du thème s'il est indiqué ; sinon choisissez le niveau le plus bas qui réalise l'idée. Le niveau 3 est rare.

  3. Choisissez l'outil le plus léger qui puisse le faire.

    BesoinUtiliserCoût
    Révélation, effets de défilement sans parallaxe, transitions de pageCSS uniquement : animations de défilement, position: sticky, View Transitions0 Ko
    Une texture vivante plate, des lignes, un champ, une figure 2DCanvas 2D ou SVG, ou un fragment shader sur un seul triangle (WebGL brut, sans bibliothèque)2-5 Ko
    Afficher un modèle 3D que les gens peuvent faire tourner<model-viewer>environ 250 Ko, chargé paresseusement
    Une vraie scène : plusieurs objets, lumières, une caméra mobilethree.js (application React : React Three Fiber) chargé avec import() dynamique150-180 Ko gzip, chargé paresseusement
    Chronologies liées au défilement que CSS ne peut pas exprimerGSAP ScrollTrigger (gratuit, pas open source : chargez-le, ne le copiez jamais) ou Motion25-45 Ko
    Fonctionnalités GPU les plus récentesWebGPU en tant que mise à niveau sur un chemin WebGL, jamais seul-

    N'ajoutez pas de bibliothèque de défilement fluide par défaut. Si le brief l'exige, elle doit se désactiver en mouvement réduit.

  4. Rédigez le bref immersif (ajoutez-le au brief de conception ui-craft), avant le code :

    Niveau : 2 signature (le thème dit --immersive: 2)        Pile : HTML simple + three.js, chargé paresseusement
    Moment signature (un événement, pas un plateau tournant) : au battement 3 la bouilloire bascule et un mince filet coule, maintenant sa ligne
    Scène : une bouilloire en céramique mate dans un cône de lumière sur le fond de la page ; clé douce depuis le haut à gauche, bord chaud
    Couloir de texte : copie dans la colonne de gauche sur desktop, sous la scène épinglée sur téléphone ; la bouilloire ne le traverse jamais
    Caméra : style 35 mm, légèrement au-dessus, ne bouge jamais d'elle-même         Tempo : doux (--dur-slow 400ms)
    Battements (niveau 3 uniquement) : 1 bouilloire entière - 2 le bec, proche - 3 qui verse - 4 l'ensemble sur une table
    Mouvement réduit : un rendu fixe par battement, fondu enchaîné        Pas de GPU : une image fixe de la même scène, sous le même angle
    Budget : le texte s'affiche en premier ; le moteur après ; la scène sous 1,5 Mo sur téléphone ; rapport de pixels 1,5 sur tactile
    
  5. Construisez dans cet ordre. (a) La page entière en HTML simple et CSS avec ui-craft, avec l'image fixe ou l'alternative CSS à la place de la scène. Ce doit déjà être une bonne page. (b) La coque de la scène : assets/scene-shell.js fournit un démarrage paresseux, des images fixes, une alternative, une pause hors écran, un plafond de rapport de pixels, une récupération de contexte perdu. (c) Le pont de thème : assets/theme-bridge.js pour que les couleurs, le rayon et le tempo proviennent des jetons. (d) La scène elle-même, dans sa forme la plus simple. (e) Le mouvement et le défilement. (f) Le polissage : lumière, matériau, grain, timing. assets/starter.html est une page fonctionnelle avec (a)-(c) effectués ; remplacez sa scène d'espace réservé.

  6. Vérifiez, puis regardez. Exécutez node <skill-dir>/scripts/immersive-check.mjs page.html. Il charge la page de cinq manières (desktop, téléphone, mouvement réduit, sans WebGL, sans JavaScript), mesure le poids, les appels de dessin, le rapport de pixels, le défilement natif et les pauses, et enregistre des captures d'écran. Pour une fenêtre d'application (Electron, Tauri, une application web connectée), ajoutez --app pour ignorer le test sans JavaScript. Ouvrez chaque capture d'écran. Corrigez ce qui échoue. Regardez le plus attentivement trois choses : le milieu du défilement (un texte croise-t-il le sujet ?), le milieu du téléphone (scène et texte ensemble dans un écran, pas de bande vide ?), et la capture sans WebGL (la même image, ou un trou ?). Générez l'image fixe à partir de la scène elle-même : --poster hero-poster.png enregistre la boîte de la scène à partir du passage desktop (--scheme light ou dark choisit le thème), prête à être utilisée comme image de secours. Exécutez ensuite ui-audit.mjs de ui-craft pour le contraste, les cibles tactiles et la typographie, et jugez le téléphone aussi strictement que le desktop. Dernier passage : la liste de contrôle references/accessibility-fallbacks.md.

3. L'échelle d'immersion

Chaque produit se trouve sur un échelon. Le thème peut le porter comme --immersive: 0-3 ; chacune des 16 directions ui-craft définit une valeur par défaut (references/theme-bridge.md).

NiveauCe que c'estConvientNe convient pas
0 StatiquePas de 3D, shaders ou effets de défilement. Mouvement d'interface ordinaire uniquementoutils financiers, administration, gouvernement, formulaires de santé, tableaux de bord denses, tout ce qui est utilisé toute la journée-
1 AccentUn détail vivant discret : un matériau, une texture de shader lente, une transition de vue. Il se calme après quelques secondes. Pas de scènes de défilementapplications SaaS, documentation, la plupart des UI de produits, applications de bureau et mobilestâches où les gens sont anxieux ou pressés
2 SignatureUn moment héroïque : un objet ou un shader qui répond au pointeur ou au premier défilement. Ensuite une page normalepages d'atterrissage, pages produit, portfolios, intégration, écran de lancementpages que les gens revisitent quotidiennement
3 HistoireUne séquence de 3 à 5 battements basée sur le défilement avec une scène persistantelancements, campagnes, articles éditoriaux, histoires de musées et de marquesapplications, paiement, tout ce qui implique une tâche

Règles de l'échelle : le niveau est un plafond, pas un objectif. La fréquence l'abaisse : plus une personne voit un écran souvent, plus le niveau est bas. Une tâche l'abaisse : là où quelqu'un paie, signe ou résout un problème, utilisez le niveau 0. En cas de doute, descendez d'un niveau et terminez-le mieux.

4. Budgets

Objectifs de travail. Mesurez ; ne devinez pas. Les nombres marqués * sont des valeurs par défaut raisonnables, pas des limites publiées.

QuoiTéléphoneDesktop
Largest Contentful Paint (doit être du texte ou une image fixe, jamais le canvas)2,5 s ou moins2,5 s ou moins
Script demandé avant la première peinturemoins de 170 Ko compresséidentique
Moteur (three.js environ 180 Ko gzip)après la première peinture, import() dynamique, seulement lorsque la scène est proche du viewportidentique
Premier chargement de la scène : moteur + modèles + textures *moins de 1,5 Momoins de 4 Mo
Modèle héroïque (GLB, compressé) *moins de 2 Mo, 20-60k trianglesmoins de 5 Mo, jusqu'à 100k
Textures1024 px ; 2048 uniquement pour le héros ; KTX2 pour la mémoire GPU2048 ; 4096 uniquement pour les gros plans
Rapport de pixelsplafond 1,5, passe à 1 en cas de lenteurplafond 2
Appels de dessin par image *moins de 100moins de 300
Lumières en temps réel1 clé (+ environnement) ; 1 carte d'ombre de 1024, ou une ombre cuite / de type blob1-3 ; carte d'ombre 2048 au maximum
Passes de post-traitement0-11-3
Temps par image60 ips stables ; réduisez la qualité avant de passer sous 30 ips60 ips
Histoire de défilement3-5 battements, 100-150vh chacun, épinglee sous 5 écrans *, un lien de sautidentique
Préchargeuraucun ; la page est lisible en 1-2 s et la scène apparaît en fondu quand elle est prêteidentique

Une texture de 2048 px coûte environ 22 Mo de mémoire vidéo une fois décompressée, quelle que soit sa taille de fichier, à moins qu'elle ne soit en KTX2. Détails et ordre de réduction : references/performance.md.

5. Un thème pilote chaque couche

  • Lisez les couleurs à partir des jetons (--bg, --surface, --accent, --accent-soft, --text, --border...), ne codez jamais un hexadécimal en dur dans un shader ou un matériau. readTheme() dans assets/theme-bridge.js renvoie chacun en RVB linéaire pour les calculs d'éclairage et en sRVB pour le dessin plat, et watchTheme() relit lors d'un changement clair/foncé.
  • La scène se situe sur le fond de la page : un canvas transparent, ou une couleur claire égale à --bg. Pas de rectangle visible, pas de deuxième couleur de fond.
  • L'accent reste rare en 3D aussi : un objet, une lumière, une ligne. Principalement neutre.
  • La forme du thème est conservée : le rayon des coins devient le biseau et le rayon des bords ; le style de profondeur devient le style d'ombre (fin : contour fin, presque pas d'ombre ; doux : ombre de contact large et douce ; net : plus serré et plus brillant ; lèvre : bord décalé dur ; plat : aucun).
  • Les jetons de mouvement définissent le tempo : --dur-* et --ease-out façonnent les mouvements de la caméra et l'assouplissement du défilement (bezier() dans le pont), de sorte qu'un outil « instantané » et une maison de luxe « lente » bougent différemment avec le même code. Rebondissez uniquement là où la courbe du thème dépasse.
  • La typographie reste en HTML dans --font-display et --font-sans, disposée par-dessus ou à côté du canvas.

6. Artisanat, en bref

Scène et caméra (references/scene-camera.md)

  • Un sujet, une silhouette claire, beaucoup d'espace calme. Composez d'abord pour le cadre étroit du téléphone.
  • Un objectif long (champ de vision de 20 à 35 degrés) flatte les objets ; les angles larges déforment. La caméra se déplace lentement et avec une raison, ou pas du tout.
  • Rendu à la demande. Une scène qui ne change pas ne dessine rien.

Lumière et matériau (references/materials-lighting.md)

  • Une lumière clé depuis le haut (la même source lumineuse unique que l'UI), un remplissage doux, un bord pour séparer le sujet de l'arrière-plan. La lumière n'est jamais blanc pur ; les ombres ne sont jamais noir pur.
  • Ancrez le sujet : une ombre de contact douce, ou il flotte.
  • Définissez les espaces colorimétriques avant de juger quoi que ce soit. Trop sombre ou délavé est une erreur d'espace colorimétrique, pas d'éclairage.
  • Cuisez la lumière dans les textures lorsque la scène est statique. C'est la lumière la moins chère qui soit.

Shaders (references/shaders.md)

  • Un shader est un matériau, une lumière ou une texture avec un travail. Pas un papier peint.
  • Palette de 2 à 4 couleurs du thème, mélangées en OKLab pour que le milieu reste propre. Pas d'arc-en-ciel.
  • Ajoutez 2 à 4 % de grain pour masquer les bandes dans les dégradés doux. Gardez le travail des fragments bon marché sur les téléphones : peu de lectures de textures, pas de longues boucles.

Narration par défilement (references/scroll-storytelling.md)

  • Chaque battement est une idée avec une ligne de texte réel. Si un battement n'a rien à dire, supprimez-le.
  • Le texte défile normalement ; la scène reste fixe (sticky) et change avec lui. Scrutez la position, jamais le temps.
  • Le mouvement réduit transforme le film en diapositives : une image fixe par battement.

Mouvement cinématographique (references/cinematic-motion.md)

  • Coupez ou dissolvez entre les idées ; bougez à l'intérieur d'une seule. Attardez-vous sur ce qui compte. L'assouplissement est un jeu : poids, pas décoration.
  • Le mouvement de l'interface conserve le timing de ui-craft (100-300 ms). Les mouvements de scène et de caméra prennent 600-1200 ms. Les transitions de page 200-500 ms, et l'URL, le bouton retour et le focus continuent de fonctionner.

Blender vers le navigateur (references/blender-pipeline.md)

  • Principled BSDF uniquement, cuisez le reste, exportez en GLB, puis compressez : gltf-transform optimize, meshopt ou Draco, textures KTX2. Inspectez le fichier avant de l'envoyer. Une bouilloire en céramique sortant de Blender pèse 800 Ko en .blend et doit faire moins de 200 Ko sur la page.

Individual skills in this repo

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

Skills associés