Communitygithub.com

immersive-web

Crea experiencias web envolventes y cinematográficas con escenas 3D, shaders y animaciones basadas en desplazamiento, manteniendo la accesibilidad y el rendimiento.

¿Qué es immersive-web?

Este skill para agentes de IA (como Claude Code, Cursor o Codex) proporciona una metodología completa y rigurosa para construir experiencias web inmersivas que se sientan como las mejores películas y juegos, pero que carguen como una página normal y sean accesibles para todos. Se enfoca en capas de 3D (Three.js, React Three Fiber), shaders (GLSL, TSL), narración basada en desplazamiento (scroll-driven storytelling), animaciones cinemáticas y la integración de modelos 3D de Blender al navegador. El skill establece nueve reglas estrictas que priorizan el contenido real en HTML, tres estados para cada efecto (completo, movimiento reducido, sin GPU), un presupuesto de velocidad decidido antes de construir, y la accesibilidad total mediante teclado y lectores de pantalla. Proporciona un flujo de trabajo detallado, una 'escalera de inmersión' para elegir el nivel adecuado de efecto (0-3), tablas de herramientas ligeras, presupuestos de rendimiento para móvil y escritorio, y un puente de tema (theme bridge) para que el diseño UI y la escena 3D compartan las mismas variables de diseño. Es ideal para landing pages, portafolios, productos interactivos, lanzamientos y sitios de storytelling editorial, y funciona en plataformas web, apps de escritorio (Electron, Tauri) y apps móviles.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace immersive-web?

Cómo construir experiencias 3D, con shaders y basadas en desplazamiento que se sientan como las mejores películas y juegos, carguen como una página normal y no dejen a nadie fuera.

Este skill es una capa. El skill ui-craft (mismo plugin) es dueño del diseño de interfaz ordinario: diseño, jerarquía, tipografía, color, componentes, formularios, estados. Úsalo para todo eso, y no lo repitas aquí. Este skill añade la capa superior: escena, luz, material, shader, cámara, desplazamiento y movimiento cinematográfico. Ambos leen los mismos tokens de tema, por lo que un solo tema dirige la página y la escena (references/theme-bridge.md).

Límite honesto. Puedes dirigir una escena, iluminarla, mover una cámara, escribir shaders y conectar un modelo. No puedes esculpir arte 3D de calidad cinematográfica desde cero. Compón a partir de geometría simple, shaders, tipografía y luz, o usa un modelo que el equipo proporcione. Nunca lo finjas con un dibujo tosco del tema.

1. Las nueve reglas estrictas

Rompe una y el trabajo no está terminado, por bien que se vea.

  1. Primero el contenido. Los encabezados, el texto, los enlaces y los botones son HTML real, legible antes de que se ejecute cualquier script. La escena se añade por encima y puede desaparecer sin pérdida. Nunca dibujes las palabras de la página en un canvas. Nunca escondas contenido con opacity: 0 en el CSS esperando que un script lo revele.
  2. Tres estados para cada efecto. Completo; movimiento reducido (un fotograma fijo o un fundido corto: prefers-reduced-motion, y la configuración del SO en apps nativas); sin GPU (una imagen de póster o arte CSS/SVG que se muestra cuando WebGL o WebGPU falta, falla o se pierde el contexto). Diseña primero las dos alternativas. También son lo que carga primero. Una alternativa es la misma imagen, más tranquila: el mismo tema desde el mismo ángulo (un póster creado a partir de la propia escena), y para una escena de datos, los mismos datos dibujados planos. Un cuadro en blanco, un degradado simple o una "imagen próxima" es un fracaso.
  3. Un presupuesto de velocidad, decidido antes de construir (§4). El texto de la página se pinta primero; el motor carga después. En un teléfono, la escena cuesta menos que el contenido.
  4. Un momento emblemático por página, y que cuente. Una escena, una idea, realizada por completo. Todo lo demás permanece en calma. Los efectos en todas partes se leen como una plantilla y agotan a la gente. La restricción limita la cantidad de efectos, no su intensidad: el momento único es un evento que pertenece a este producto (la tetera vierte; el cielo se llena de estrellas mientras los ojos se adaptan), escenificado con la suficiente audacia para que alguien se lo describa a un amigo. Un objeto que solo gira mientras te desplazas no es un momento.
  5. Nunca te tomes el desplazamiento. El navegador se desplaza; tú solo lees la posición. Sin cambio de velocidad o dirección, sin secuestro de rueda, sin barra de desplazamiento falsa. Fija con position: sticky, mantenlo corto, da una forma de saltarlo.
  6. Las palabras y la escena nunca comparten un lugar. En cada posición de desplazamiento, el texto se sitúa junto al tema o sobre su propia superficie, nunca encima de él. La navegación y los botones superpuestos a una escena obtienen un velo o una superficie. Verifica cada captura de pantalla de desplazamiento, no solo la primera.
  7. El teclado y el lector de pantalla llegan a todo lo real. El orden de tabulación sigue el orden de lectura. Un canvas decorativo es aria-hidden="true"; uno significativo tiene un equivalente de texto a su lado. Cualquier cosa que puedas hacer arrastrando la escena, puedes hacerla con un botón.
  8. El movimiento descansa, el sonido espera, nada parpadea. El movimiento ambiente se estabiliza en 5 segundos o tiene un control de pausa visible. El sonido está apagado hasta que se solicita. No más de 3 destellos por segundo, nunca. Nada se ejecuta fuera de la pantalla o en una pestaña oculta.
  9. Original y con licencia. Aprende el lenguaje de un género; nunca copies la apariencia, los modelos, los personajes, los logotipos o los sonidos de un producto. Usa solo activos que hayas creado o que tengan una licencia clara (bibliotecas CC0 como Poly Haven y ambientCG son seguras), y registra cada uno.

2. Flujo de trabajo (haz esto cada vez)

  1. Mira antes de construir. Encuentra el tema: theme.css, DESIGN.md (del ui-craft Studio), tokens, una configuración de Tailwind, colores de marca. Lee --immersive y la sección "Inmersivo y movimiento" del briefing si está presente: indican la intensidad que el propietario eligió. Verifica la pila (HTML plano, React, Vue, un shell de app) y cualquier activo 3D ya proporcionado. Si no hay ningún tema, usa primero ui-craft para elegir una dirección.

  2. Elige el nivel en la escalera del §3. Tómalo del tema si lo dice; de lo contrario, elige el nivel más bajo que ofrezca la idea. El nivel 3 es raro.

  3. Elige la herramienta más ligera que pueda hacerlo.

    NecesidadUsoCoste
    Efectos de desplazamiento sin paralaje, revelados, transiciones de páginaSolo CSS: animaciones basadas en desplazamiento, position: sticky, View Transitions0 KB
    Una textura viva plana, líneas, un campo, una figura 2DCanvas 2D o SVG, o un shader de fragmento en un solo triángulo (WebGL puro, sin librería)2-5 KB
    Mostrar un modelo 3D que la gente pueda girar<model-viewer>unos 250 KB, perezoso
    Una escena real: varios objetos, luces, una cámara en movimientothree.js (app React: React Three Fiber) cargado con dynamic import()150-180 KB gzip, perezoso
    Líneas de tiempo vinculadas al desplazamiento que CSS no puede expresarGSAP ScrollTrigger (gratuito, no de código abierto: cárgalo, nunca lo copies) o Motion25-45 KB
    Funciones GPU más nuevasWebGPU como mejora sobre una ruta WebGL, nunca solo-

    No añadas una biblioteca de desplazamiento suave por defecto. Si el briefing lo exige, debe desactivarse con movimiento reducido.

  4. Escribe el briefing inmersivo (añádelo al briefing de diseño de ui-craft), antes del código:

    Nivel: 2 emblemático (el tema dice --immersive: 2)        Pila: HTML plano + three.js, perezoso
    Momento emblemático (un evento, no un tocadiscos): en el compás 3 la tetera se inclina y un chorro fino brota, manteniendo su línea
    Escena: una tetera de cerámica mate en un charco de luz sobre el fondo de la página; clave suave desde arriba a la izquierda, borde cálido
    Carril de texto: copia en la columna izquierda en escritorio, debajo de la escena fija en teléfonos; la tetera nunca la cruza
    Cámara: similar a 35 mm, ligeramente por encima, nunca se mueve sola         Tempo: suave (--dur-slow 400ms)
    Compases (solo nivel 3): 1 tetera entera - 2 el pico, cerca - 3 vertiendo - 4 el conjunto sobre una mesa
    Movimiento reducido: un render fijo por compás, fundido cruzado        Sin GPU: un póster de la misma escena, mismo ángulo
    Presupuesto: el texto se pinta primero; el motor después; escena bajo 1.5 MB en teléfonos; relación de píxeles 1.5 en táctil
    
  5. Construye en este orden. (a) Toda la página como HTML y CSS plano con ui-craft, con el póster o la alternativa CSS en el lugar de la escena. Ya debe ser una buena página. (b) El shell de la escena: assets/scene-shell.js da inicio perezoso, fotogramas fijos, alternativa, pausa fuera de pantalla, límite de relación de píxeles, recuperación de contexto perdido. (c) El puente de tema: assets/theme-bridge.js para que los colores, el radio y el tempo provengan de los tokens. (d) La escena misma, en su forma más simple. (e) Movimiento y desplazamiento. (f) Pulido: luz, material, granulado, sincronización. assets/starter.html es una página funcional con (a)-(c) hechos; reemplaza su escena de marcador de posición.

  6. Verifica, luego mira. Ejecuta node <skill-dir>/scripts/immersive-check.mjs page.html. Carga la página de cinco maneras (escritorio, teléfono, movimiento reducido, sin WebGL, sin JavaScript), mide peso, llamadas de dibujo, relación de píxeles, desplazamiento nativo y pausas, y guarda capturas de pantalla. Para una ventana de app (Electron, Tauri, una app web con inicio de sesión) añade --app para saltarte la prueba sin JavaScript. Abre cada captura de pantalla. Arregla lo que falle. Mira con más atención tres: la mitad del desplazamiento (¿algún texto cruza el tema?), la mitad del teléfono (¿escena y texto juntos en una pantalla, sin banda vacía?), y la de sin WebGL (¿la misma imagen, o un agujero?). Haz el póster desde la propia escena: --poster hero-poster.png guarda el recuadro de la escena de la pasada de escritorio (--scheme light o dark elige el tema), listo para usar como imagen de alternativa. Luego ejecuta ui-audit.mjs de ui-craft para contraste, objetivos táctiles y tipografía, y juzga el teléfono tan estrictamente como el escritorio. Pasada final: lista de verificación de references/accessibility-fallbacks.md.

3. La escalera de inmersión

Cada producto se sienta en un peldaño. El tema puede llevarlo como --immersive: 0-3; cada una de las 16 direcciones de ui-craft establece un valor predeterminado (references/theme-bridge.md).

NivelQué esSe ajustaNo se ajusta
0 EstáticoSin 3D, shaders o efectos de desplazamiento. Solo movimiento de interfaz ordinarioherramientas financieras, administración, gobierno, formularios de salud, paneles densos, cualquier cosa usada todo el día-
1 AcentoUn detalle vivo y tranquilo: un material, una textura de shader lenta, una transición de vista. Se detiene tras unos segundos. Sin escenas basadas en desplazamientoapps SaaS, documentación, la mayoría de las UI de productos, apps de escritorio y móvilestareas donde las personas están ansiosas o apuradas
2 EmblemáticoUn momento héroe: un objeto o shader que responde al puntero o al primer desplazamiento. Luego una página normalpáginas de aterrizaje, páginas de producto, portafolios, incorporaciones, una pantalla de iniciopáginas que las personas visitan a diario
3 HistoriaUna secuencia basada en desplazamiento de 3-5 compases con una escena persistentelanzamientos, campañas, artículos editoriales, historias de museos y marcasapps, proceso de pago, cualquier cosa con una tarea

Reglas de la escalera: el nivel es un techo, no un objetivo. La frecuencia lo baja: cuanto más a menudo una persona ve una pantalla, más bajo es el nivel. Una tarea lo baja: donde alguien está pagando, firmando o solucionando un problema, usa el nivel 0. Cuando tengas dudas, baja un nivel y termínalo mejor.

4. Presupuestos

Objetivos funcionales. Mide; no adivines. Los números marcados con * son valores predeterminados razonables, no límites publicados.

QuéTeléfonoEscritorio
Largest Contentful Paint (debe ser texto o un póster, nunca el canvas)2.5 s o menos2.5 s o menos
Script solicitado antes del primer pintadobajo 170 KB comprimidomismo
Motor (three.js unos 180 KB gzip)después del primer pintado, dynamic import(), solo cuando la escena está cerca del viewportmismo
Primer payload de escena: motor + modelos + texturas *bajo 1.5 MBbajo 4 MB
Modelo héroe (GLB, comprimido) *bajo 2 MB, 20-60k triángulosbajo 5 MB, hasta 100k
Texturas1024 px; 2048 solo para el héroe; KTX2 para memoria GPU2048; 4096 solo para primeros planos
Relación de píxeleslímite 1.5, baja a 1 cuando es lentolímite 2
Llamadas de dibujo por fotograma *bajo 100bajo 300
Luces en tiempo real1 clave (+ entorno); 1 mapa de sombras de 1024, o una sombra horneada / mancha1-3; mapa de sombras de 2044 como máximo
Pasadas de post-procesamiento0-11-3
Tiempo por fotograma60 fps estables; reduce la calidad antes de caer por debajo de 3060 fps
Historia de desplazamiento3-5 compases, 100-150vh cada uno, ejecución fija bajo 5 pantallas *, un enlace de saltomismo
Precargadorninguno; la página es legible en 1-2 s y la escena aparece gradualmente cuando está listamismo

Una textura de 2048 px cuesta unos 22 MB de memoria de video una vez desempaquetada, cualquiera que sea su tamaño de archivo, a menos que sea KTX2. Detalles y el orden de reducción: references/performance.md.

5. Un solo tema dirige cada capa

  • Lee los colores de los tokens (--bg, --surface, --accent, --accent-soft, --text, --border...), nunca codifiques un hexadecimal en un shader o material. readTheme() en assets/theme-bridge.js devuelve cada uno como RGB lineal para matemáticas de iluminación y sRGB para dibujo plano, y watchTheme() lo relee en un cambio de claro/oscuro.
  • La escena se sitúa sobre el fondo de la página: un canvas transparente, o un color claro igual a --bg. Sin rectángulo visible, sin segundo color de fondo.
  • El acento sigue siendo raro también en 3D: un objeto, una luz, una línea. Mayormente neutro.
  • La forma del tema se traslada: el radio de las esquinas se convierte en bisel y radio de borde; el estilo de profundidad se convierte en el estilo de sombra (hairline: contorno fino, casi sin sombra; soft: sombra de contacto ancha y suave; crisp: más ajustada y brillante; lip: un borde duro desplazado; flat: ninguna).
  • Los tokens de movimiento establecen el tempo: --dur-* y --ease-out dan forma a los movimientos de cámara y la suavización del desplazamiento (bezier() en el puente), por lo que una herramienta "instantánea" y una casa de lujo "lenta" se mueven de manera diferente con el mismo código. Rebote solo donde la curva del tema sobrepasa.
  • La tipografía sigue siendo HTML en --font-display y --font-sans, colocada sobre o al lado del canvas.

6. Oficio, en resumen

Escena y cámara (references/scene-camera.md)

  • Un tema, una silueta clara, mucho espacio tranquilo. Compón primero para el marco alto del teléfono.
  • Una lente larga (campo de visión de 20-35 grados) favorece los objetos; los ángulos amplios distorsionan. La cámara se mueve lentamente y con una razón, o no se mueve en absoluto.
  • Renderiza bajo demanda. Una escena que no cambia no dibuja nada.

Luz y material (references/materials-lighting.md)

  • Una luz clave desde arriba (la misma fuente de luz única que la UI), un relleno suave, un borde para separar el tema del fondo. La luz nunca es blanca pura; las sombras nunca son negro puro.
  • Conecta el tema a tierra: una sombra de contacto suave, o flota.
  • Establece los espacios de color antes de juzgar nada. Demasiado oscuro o deslavado es un error de espacio de color, no de iluminación.
  • Hornea la luz en las texturas cuando la escena es estática. Es la luz más barata que hay.

Shaders (references/shaders.md)

  • Un shader es un material, una luz o una textura con un trabajo. No un fondo de pantalla.
  • Paleta de 2-4 colores del tema, mezclados en OKLab para que el medio se mantenga limpio. Sin arcoíris.
  • Añade 2-4% de granulado para ocultar bandas en degradados suaves. Mantén el trabajo de fragmento barato en teléfonos: pocas lecturas de textura, sin bucles largos.

Narrativa de desplazamiento (references/scroll-storytelling.md)

  • Cada compás es una idea con una línea de texto real. Si un compás no tiene nada que decir, elimínalo.
  • El texto se desplaza normalmente; la escena se mantiene fija (sticky) y cambia con él. Recorre la posición, nunca el tiempo.
  • El movimiento reducido convierte la película en diapositivas: un fotograma fijo por compás.

Movimiento cinematográfico (references/cinematic-motion.md)

  • Corta o disuelve entre ideas; muévete dentro de una. Mantén lo que importa. La suavización es actuación: peso, no decoración.
  • El movimiento de la interfaz mantiene la sincronización de ui-craft (100-300 ms). Los movimientos de escena y cámara toman 600-1200 ms. Las transiciones de página 200-500 ms, y la URL, el botón atrás y el foco siguen funcionando.

Blender al navegador (references/blender-pipeline.md)

  • Solo Principled BSDF, hornea el resto, exporta GLB, luego comprime: gltf-transform optimize, meshopt o Draco, texturas KTX2. Inspecciona el archivo por...

... [truncado para traducción]

Individual skills in this repo

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

Skills relacionados