¿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.
- 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: 0en el CSS esperando que un script lo revele. - 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. - 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.
- 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.
- 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. - 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.
- 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. - 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.
- 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)
-
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--immersivey 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. -
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.
-
Elige la herramienta más ligera que pueda hacerlo.
Necesidad Uso Coste Efectos de desplazamiento sin paralaje, revelados, transiciones de página Solo CSS: animaciones basadas en desplazamiento, position: sticky, View Transitions0 KB Una textura viva plana, líneas, un campo, una figura 2D Canvas 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 movimiento three.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 expresar GSAP ScrollTrigger (gratuito, no de código abierto: cárgalo, nunca lo copies) o Motion 25-45 KB Funciones GPU más nuevas WebGPU 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.
-
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 -
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.jsda 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.jspara 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.htmles una página funcional con (a)-(c) hechos; reemplaza su escena de marcador de posición. -
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--apppara 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.pngguarda el recuadro de la escena de la pasada de escritorio (--scheme lightodarkelige el tema), listo para usar como imagen de alternativa. Luego ejecutaui-audit.mjsde 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 dereferences/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).
| Nivel | Qué es | Se ajusta | No se ajusta |
|---|---|---|---|
| 0 Estático | Sin 3D, shaders o efectos de desplazamiento. Solo movimiento de interfaz ordinario | herramientas financieras, administración, gobierno, formularios de salud, paneles densos, cualquier cosa usada todo el día | - |
| 1 Acento | Un 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 desplazamiento | apps SaaS, documentación, la mayoría de las UI de productos, apps de escritorio y móviles | tareas donde las personas están ansiosas o apuradas |
| 2 Emblemático | Un momento héroe: un objeto o shader que responde al puntero o al primer desplazamiento. Luego una página normal | páginas de aterrizaje, páginas de producto, portafolios, incorporaciones, una pantalla de inicio | páginas que las personas visitan a diario |
| 3 Historia | Una secuencia basada en desplazamiento de 3-5 compases con una escena persistente | lanzamientos, campañas, artículos editoriales, historias de museos y marcas | apps, 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éfono | Escritorio |
|---|---|---|
| Largest Contentful Paint (debe ser texto o un póster, nunca el canvas) | 2.5 s o menos | 2.5 s o menos |
| Script solicitado antes del primer pintado | bajo 170 KB comprimido | mismo |
| Motor (three.js unos 180 KB gzip) | después del primer pintado, dynamic import(), solo cuando la escena está cerca del viewport | mismo |
| Primer payload de escena: motor + modelos + texturas * | bajo 1.5 MB | bajo 4 MB |
| Modelo héroe (GLB, comprimido) * | bajo 2 MB, 20-60k triángulos | bajo 5 MB, hasta 100k |
| Texturas | 1024 px; 2048 solo para el héroe; KTX2 para memoria GPU | 2048; 4096 solo para primeros planos |
| Relación de píxeles | límite 1.5, baja a 1 cuando es lento | límite 2 |
| Llamadas de dibujo por fotograma * | bajo 100 | bajo 300 |
| Luces en tiempo real | 1 clave (+ entorno); 1 mapa de sombras de 1024, o una sombra horneada / mancha | 1-3; mapa de sombras de 2044 como máximo |
| Pasadas de post-procesamiento | 0-1 | 1-3 |
| Tiempo por fotograma | 60 fps estables; reduce la calidad antes de caer por debajo de 30 | 60 fps |
| Historia de desplazamiento | 3-5 compases, 100-150vh cada uno, ejecución fija bajo 5 pantallas *, un enlace de salto | mismo |
| Precargador | ninguno; la página es legible en 1-2 s y la escena aparece gradualmente cuando está lista | mismo |
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()enassets/theme-bridge.jsdevuelve cada uno como RGB lineal para matemáticas de iluminación y sRGB para dibujo plano, ywatchTheme()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-outdan 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-displayy--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]