Diorama

Diorama: un pequeño mundo que se mueve

Para miniaturas narrativas detalladas o escenas con acabado de píxel, usa la habilidad separada diorama-worlds. Esta habilidad sigue siendo el flujo de trabajo de ilustración SVG sin dependencias.

Estás haciendo un diorama: una escena construida a partir de bloques sobre una base redondeada, vista desde una cámara isométrica, con algunas cosas que se mueven por sí mismas y responden al puntero, dibujada en un tema. El tema predeterminado, toy, son bloques pastel, un sol cálido, sombras suaves, cada objeto un puñado de cajas y cilindros, sin texturas, alegre y legible de un vistazo. El mismo archivo de escena se dibuja en soft (crema, más suave), mono (un acento, el resto tintas de tinta), line (un dibujo de línea fina: rellenos blancos, bordes de tinta, sin sombras), print (tonos planos por cara y líneas de tinta, una ilustración impresa) y night (atardecer, lámparas encendidas), y cada campo del tema se puede sobrescribir: wobble dibuja la tinta a mano, halo es la sombra suave que la base proyecta sobre la página, accent es el color del sujeto en cada tema. Los dieciocho ejemplos en examples/ son la referencia, y están en el formato que escribirás.

Escribes una sola cosa: la figura, un archivo .js. El núcleo (kit/diorama.js) y la página (bench.html) son fijos. Nunca los edites, nunca pegues una copia modificada y nunca vuelvas a escribir lo que el núcleo ya te proporciona (una cámara, luces, sombras, un bucle que duerme fuera de pantalla, un puntero, resortes, caminos, propiedades).

Cada archivo nombrado a continuación está en la carpeta de esta habilidad. La figura y la página se escriben en el directorio de trabajo de la persona; ejecuta scripts/build.mjs, scripts/validate.mjs y scripts/look.mjs desde allí, con su ruta en esta carpeta.

1. Tamaño y concepto

Primero decide el tamaño, porque establece el presupuesto:

Tamaño	Vive	Escenario	Partes	Líneas	Movimiento
hero	parte superior de una página de aterrizaje, un README, un tour del producto	3:2, ancho completo	150–400 primitivas	≤ 420	tres o cuatro bucles independientes, algo siempre en movimiento
card	una página de documentación, una publicación de blog, una sección de características	4:3, ~500px	60–150	≤ 240	uno o dos bucles y una respuesta al puntero
mini	cualquier lugar pequeño: un estado vacío, una característica en una lista, un 404, una sección de configuración	1:1, 160–240px	15–40	≤ 150	un movimiento ambiental silencioso

Luego lee references/concepts.md y escribe el concepto en una línea, con el tema al final:

Nombre. El lugar y lo que hay en él. Lo que se mueve por sí mismo. Lo que hace el puntero. (Para un mini: lo que falta.) Tema.

Elige el lugar del propio mundo del producto, no de los ejemplos: un puerto, una cocina, una azotea, un escritorio, un invernadero, un andén de tren, una plataforma de lanzamiento, una esquina de la calle son todos dioramas. Luego elige el tema según donde vivirá la figura, no por gusto: toy para una página de producto que busca calidez y color; soft para una página editorial o crema; mono para una interfaz de producto que tiene su propio acento (pásalo como accent), documentación o cualquier cosa junto a texto denso; line para una página minimalista o técnica, una marca de texto oscuro sobre fondo blanco, o un estado vacío que debe susurrar; night para una página oscura. Cuando la persona tiene un color de marca, este va como accent, que recolorea el sujeto en cada tema; un segundo color a través de palette. references/craft.md tiene las reglas que cada tema añade.

Luego escribe la lista de partes, antes de cualquier código: cinco líneas, una por grupo, nombrando cada objeto y las dos o tres características que lo definen. Ground (la losa, zonas, carreteras, agua), structure (lo que se levanta: edificios, estanterías, árboles), movers (lo que se desplaza, camina, gira o levanta), furniture (lo que llena los bordes: lámparas, conos, cajas, bancos, vallas), light (lo que brilla: ventanas, lámparas, balizas). Cada parte se apoya en otra parte; nada flota. Una lista hero llega a treinta objetos, una card a diez, una mini a tres. La lista es la escena: si se lee delgada, la figura también lo será.

Ofrece dos o tres cuando haya alguien a quien preguntar, y espera. Si no hay nadie a quien preguntar, elige la que tenga el fotograma fijo más fuerte y di cuál tomaste. Un diorama, un lugar, una historia. Una escena que necesita un pie de foto para ser entendida aún no es un concepto.

2. Construcción

1. Lee references/craft.md. Las diez reglas son lo que hace que un diorama parezca un lugar en lugar de un montón de cubos; una figura que rompa una no está terminada.
2. Lee el índice al principio de kit/diorama.js (el comentario arriba de var Diorama). Enumera todo lo que puedes llamar. No leas el código debajo.
3. Lee el ejemplo más cercano a tu tamaño y tema: examples/town.js (hero, toy: un pueblo entero construido con pequeñas funciones auxiliares, varios recorridos, luces que ciclan), examples/island.js (hero, toy: un lugar con agua, un recorrido con una parada, gaviotas y nubes), examples/farm.js (hero, toy: campos, animales, un recorrido con una parada) o examples/warehouse.js (hero, toy: un patio con un transporte y un muelle) o examples/harbour.js (hero, toy: un muelle con una grúa que levanta contenedores en un ciclo de 18 s, un recorrido de tractor con una parada y una barrera que se levanta, un remolcador, un faro, un toque que inicia una elevación, un indicador); examples/cafe.js (card, soft: personas y cosas pequeñas), examples/kitchen.js (card, toy: una habitación con una pared trasera y una ventana colocada en ella, una nevera construida como una carcasa cuya puerta se abre al pasar el ratón, una tostadora que sale al tocar, un reloj), examples/launchpad.js (card, night: lámparas, un evento raro, un cohete que se desmonta bajo el puntero, un toque que lo lanza, un indicador de cuenta atrás), examples/server.js (card, mono con acento: luces en ritmos, un hover que ilumina un grupo entero) o examples/rack.js (card, mono con un acento: un estado vacío con una respuesta al puntero) o examples/assembly.js (card, mono con un acento: una cinta de trabajos a través de una puerta que un toque detiene, un brazo de estampación, un indicador que cuenta); examples/mailbox.js (mini, toy), examples/seedling.js (mini, line: un estado vacío dibujado en tinta), examples/observatory.js (mini, line con wobble: una cúpula que gira y un telescopio que mira), examples/desk.js (mini, line con acento) o examples/vending.js (mini, print: una máquina construida como un marco alrededor de un hueco, bobinas desnudas, un ventilador). No son todas fábricas a propósito: un diorama es cualquier lugar.
4. Escribe la figura como <nombre>.js en el directorio de trabajo, con la forma de los ejemplos: una llamada a Diorama.figure({ … }) con:
   • name: minúsculas, una palabra o separada por guiones; size: hero | card | mini.
   • theme: un nombre, o { base: 'mono', accent: '#f2c230', shadows: false, … } para sobrescribir cualquier campo (palette, accent, lights, shadows, finish, tone, tint, edges, outline, stroke, strokeWidth, round, glow, halo, wobble). Construye una vez; el tema es aplicado por el núcleo a cada primitiva, por lo que una figura nunca bifurca en él. Pinta lo que importa con pal.accent: es el color del sujeto en cada tema, el color que mono y line conservan, el que un hex de marca reemplaza, y el que las muestras de color del banco recoloran en vivo. Para una figura line dibujada a mano añade wobble: 1.4 (px css de temblor: 1.2 un bolígrafo, 2.5 un rotulador).
   • means: una oración, ≤ 140 caracteres, mostrada debajo del escenario. Dice lo que la escena muestra y lo que se mueve.
   • hint: una línea, ≤ 90 caracteres, qué hace el puntero y qué hace un toque ("Pasa el ratón sobre el cohete para ver sus etapas; toca la sala de control para lanzar ahora"). La página lo muestra para que un visitante sepa que puede jugar, y look.mjs presiona lo que nombra.
   • title: el nombre de la figura, que la página muestra sobre el escenario. Las palabras que la propia interfaz de la persona pone alrededor de la figura (un encabezado, una línea, un botón) son suyas para escribir; la escena no lleva ninguna.
   • camera: { az, el, pad } en grados. az 45 es el valor isométrico predeterminado; 30–40 muestra una base ancha en un hero 3:2. Deja el en 35.264 a menos que la escena sea alta.
   • still: el segundo del bucle que muestran el movimiento reducido y las miniaturas. Elige un momento donde todo esté en un lugar revelador (el camión en el muelle, las horquillas arriba).
   • build({ D, pal }): construye la escena una vez con el kit de herramientas y devuelve parts: cada grupo y malla que tick moverá, más parts.hot, los grupos que el puntero puede seleccionar. Da a cada grupo caliente un .name (boat.name = 'boat'): la página lo muestra como un indicador mientras el puntero está sobre él.
   • tick(ctx): cada fotograma, posa las partes desde ctx.t con D.phase, D.pulse, D.wave, D.inOut, D.path y D.spring. Responde al puntero con ctx.hover y una pulsación con ctx.pressed o ctx.active (un toque es cómo responde un teléfono, así que un hero o una card tiene una cosa que presionar: un interruptor, una llamada o el gemelo del hover). D.apart desmonta algo bajo el puntero y lo vuelve a montar. Establece ctx.read a una línea corta que diga lo que la escena está haciendo en este momento ('camión · en el muelle'): la página lo muestra como el indicador, y es cómo un visitante aprende que la escena es un modelo de trabajo y no un bucle. references/motion.md tiene los patrones.
5. Ensambla: node <skill>/scripts/build.mjs <nombre>.js escribe diorama-<nombre>.html: el banco de pruebas, el núcleo y la figura. El núcleo dibuja SVG como un ilustrador falsifica la profundidad (una proyección isométrica, un tono plano por cara, las piezas pintadas desde atrás de la escena hacia adelante, las sombras proyectadas en el suelo como formas), por lo que la página no lleva ningún motor de renderizado, no necesita WebGL y no realiza ninguna solicitud de red; el dibujo es vectorial, nítido a cualquier tamaño, y la página puede estilizarlo.

3. Verificación

1. node <skill>/scripts/look.mjs <nombre>.js. Construye la página, la valida, la abre en Chromium sin cabeza, y escribe diorama-<nombre>-look.png: el fotograma fijo, tres momentos del bucle, la respuesta del puntero, la inclinación de la cámara, una pulsación, la miniatura y toda la página. Imprime la consola, el relleno, el movimiento, la respuesta y la pulsación como números. Arregla cada FAIL, y lee las líneas SMALL, STILL, FAINT y MUTE como preguntas, hasta que salga con 0. La pulsación aterriza en el grupo caliente que la pista nombra después de "tap", "click" o "press" (o --press nombre, o --press x,y); MUTE significa que la pista prometió una pulsación y nada cambió. Añade --theme line (o cualquier nombre) para mirar la misma figura en otro tema; una figura que se lee en toy y en line está bien construida. También imprime clash: partes móviles que atraviesan otras partes; un vehículo a través de un árbol o un coche a través de un autobús es un error que arreglar, horquillas en un estante o una bandera en su bisagra está bien.
2. Lee references/look.md, luego la hoja, y responde sus preguntas. Arregla lo que falla, luego vuelve al paso 1.

look.mjs necesita un navegador; encuentra el de Playwright o instala playwright-core una vez fuera de esta carpeta. Sin un navegador, ejecuta node <skill>/scripts/validate.mjs diorama-<nombre>.html después de cada compilación y haz la inspección como dice look.md bajo "Sin un navegador". No entregues una página que el validador rechace. No digas que la inspección está hecha si no miraste.

4. Entrega

Entrega diorama-<nombre>.html como la persona pidió: cuando quiera el archivo, da el archivo y di dónde está; de lo contrario, publícalo como un artefacto si puedes. Luego di, una línea cada uno:

• el concepto: el lugar, qué se mueve, qué hacen el puntero y un toque, y el tema (y cómo cambiarlo: theme: en la figura, ?theme= y ?accent= en la página, { theme } en Diorama.mount; las muestras de color del banco recoloran el sujeto en vivo);
• el fotograma fijo: qué segundo, y por qué ese momento;
• dónde debería vivir (hero, card o mini) y cómo incrustarlo (references/react.md para React o Next.js; un <script> simple del núcleo más la figura y Diorama.mount(fig, { el }) en cualquier otro lugar);
• cualquier cosa que no hayas podido verificar (sin Node, sin navegador), claramente.

5. Ajuste

Cuando la persona pida un cambio, edita solo <nombre>.js, luego ejecuta look.mjs de nuevo y lee la nueva hoja. La décima versión se mide con la misma vara que la primera.

Lo que sale mal

Si te encuentras	Haz esto en su lugar
recurriendo a three.js, una luz, una cámara, un canvas o WebGL	no hay ninguno: el núcleo dibuja SVG; usa D.box, D.cyl, D.props.*, o.M para un vector, y ctx
escribiendo requestAnimationFrame, setInterval o una animación CSS	posa todo desde ctx.t en tick (regla 07)
moviendo algo con position.x += speed * dt	ponlo en un D.path y lee su distancia desde D.phase(t, period), para que el bucle sea continuo y el fotograma fijo sea reproducible (regla 08)
escribiendo una palabra, un número o una flecha en la escena	dilo con el título o el means; la escena no lleva palabras en absoluto, ni siquiera un letrero (regla 10)
recurriendo a una textura, un degradado, un brillo o un color 15	un bloque más en un color de paleta; pal.* tiene lo que necesitas (reglas 03 y 04)
escribiendo if (theme === 'line') en la figura	el núcleo entona, traza e ilumina cada primitiva por tema; una figura es la misma en los cinco
un color de marca pegado en veinte partes, o el sujeto pintado con un nombre de paleta	pinta el sujeto con pal.accent y pon el hex de la marca en accent, una vez, en la declaración; palette: { cobalt: … } para un segundo color
una respuesta hover y nada para un dedo	da a una cosa una pulsación (ctx.pressed, ctx.active): hover previsualiza, un toque confirma (motion.md, "La pulsación")
una figura line que se lee como una exportación CAD	wobble: 1.4 en el tema: la tinta se curva y sobrepasa como una mano
apagando halo porque la base "se ve sucia"	el halo es lo que asienta el diorama en la página; bájalo (.1) en un fondo ocupado, mantenlo
un indicador que dice lo que dice el título	ctx.read es el reloj en palabras: la fase, la parada, la cuenta, desde el mismo T que posa las partes
construyendo la base después de la escena, o no construyéndola en absoluto	D.slab primero: las sombras necesitan algún lugar donde aterrizar (regla 01)
una escena que se lee como una cuadrícula de cubos idénticos	da a cada objeto las dos o tres características que lo definen (regla 05)
un mini con ocho cosas en él	un objeto, un movimiento ambiental (concepts.md, "Un mini")
un hero donde todo se mueve al mismo tempo	tres bucles con diferentes períodos (regla 07)
un modelo de trabajo sin fallo: cada sensor, cerradura, brazo, luz que podría fallar y parece real	repara fallos con D.pulse y D.spring (motion.md, "Fallo")