diorama

Diorama: um pequeno mundo que se move

Para miniaturas narrativas detalhadas ou cenas de acabamento pixel, use o skill separado diorama-worlds. Este skill permanece o fluxo de trabalho de ilustração SVG sem dependências.

Você está criando um diorama: uma cena construída a partir de blocos sobre uma base arredondada, vista de uma câmera isométrica, com algumas coisas que se movem sozinhas e respondem ao ponteiro, desenhadas em um tema. O tema padrão, toy, é blocos pastéis, um sol quente, sombras suaves, cada objeto um punhado de caixas e cilindros, nada texturizado, alegre e legível à primeira vista. O mesmo arquivo de cena desenha em soft (creme, mais suave), mono (um acento, o resto em tons de tinta), line (um desenho de traço fino: preenchimentos brancos, bordas de tinta, sem sombras), print (tons planos por face e linhas de tinta, uma ilustração impressa) e night (entardecer, luminárias acesas), e cada campo do tema pode ser sobrescrito: wobble desenha a tinta à mão, halo é a sombra suave que a base projeta na página, accent é a cor do sujeito em todos os temas. Os dezoito exemplos em examples/ são a referência, e estão no formato que você escreverá.

Você escreve uma coisa: a figura, um arquivo .js. O kernel (kit/diorama.js) e a página (bench.html) são fixos. Nunca os edite, nunca cole uma cópia alterada e nunca escreva novamente o que o kernel já fornece (câmera, luzes, sombras, um loop que dorme fora da tela, ponteiro, molas, caminhos, adereços).

Cada arquivo nomeado abaixo está na pasta deste skill. A figura e a página são escritas no diretório de trabalho da pessoa; execute scripts/build.mjs, scripts/validate.mjs e scripts/look.mjs a partir daí, pelo caminho nesta pasta.

1. Tamanho e conceito

Primeiro, decida o tamanho, porque ele define o orçamento:

Tamanho	Vive	Palco	Peças	Linhas	Movimento
hero	topo de uma landing page, um README, um tour do produto	3:2, largura total	150–400 primitivas	≤ 420	três ou quatro loops independentes, algo sempre se movendo
card	uma página de docs, um post de blog, uma seção de recurso	4:3, ~500px	60–150	≤ 240	um ou dois loops e uma resposta ao ponteiro
mini	qualquer espaço pequeno: um estado vazio, um recurso em uma lista, um 404, uma seção de configurações	1:1, 160–240px	15–40	≤ 150	um movimento ambiente silencioso

Em seguida, leia references/concepts.md e escreva o conceito em uma linha, com o tema no final:

Nome. O lugar e o que há nele. O que se move sozinho. O que o ponteiro faz. (Para um mini: o que está faltando.) Tema.

Escolha o lugar do próprio mundo do produto, não dos exemplos: um porto, uma cozinha, um terraço, uma mesa, uma estufa, uma plataforma de trem, uma rampa de lançamento, uma esquina de rua são dioramas. Depois, escolha o tema de onde a figura viverá, não por gosto: toy para uma página de produto que quer calor e cor; soft para uma página editorial ou creme; mono para uma UI de produto que tem seu próprio acento (passe como accent), docs ou qualquer coisa ao lado de texto denso; line para uma página minimalista ou técnica, uma marca de texto escuro sobre branco, ou um estado vazio que deve sussurrar; night para uma página escura. Quando a pessoa tem uma cor de marca, ela vai como accent, que recoloriza o sujeito em todos os temas; uma segunda através de palette. references/craft.md tem as regras que cada tema adiciona.

Em seguida, escreva a lista de peças, antes de qualquer código: cinco linhas, uma por grupo, nomeando cada objeto e as duas ou três características que o tornam o que é. Chão (a laje, zonas, estradas, água), estrutura (o que está em pé: edifícios, estantes, árvores), moventes (o que anda, caminha, gira ou levanta), mobiliário (o que preenche as bordas: luminárias, cones, caixotes, bancos, cercas), luz (o que brilha: janelas, lâmpadas, balizas). Cada peça fica sobre outra peça; nada flutua. Uma lista de herói chega a trinta objetos, um cartão a dez, um mini a três. A lista é a cena: se parecer fina, a figura também será.

Ofereça duas ou três opções quando houver alguém para perguntar, e espere. Se não houver ninguém para perguntar, pegue a que tiver o quadro parado mais forte e diga qual você escolheu. Um diorama, um lugar, uma história. Uma cena que precisa de uma legenda para ser compreendida ainda não é um conceito.

2. Construção

1. Leia references/craft.md. As dez regras são o que faz um diorama parecer um lugar em vez de uma pilha de cubos; uma figura que quebra uma não está terminada.
2. Leia o índice no topo de kit/diorama.js (o comentário acima de var Diorama). Ele lista tudo que você pode chamar. Não leia o código abaixo dele.
3. Leia o exemplo mais próximo do seu tamanho e tema: examples/town.js (hero, toy: uma cidade inteira construída com pequenas funções auxiliares, várias voltas, luzes que ciclam), examples/island.js (hero, toy: um lugar com água, uma volta com parada, gaivotas e nuvens), examples/farm.js (hero, toy: campos, animais, uma volta com parada) ou examples/warehouse.js (hero, toy: um pátio com um vaivém e uma doca) ou examples/harbour.js (hero, toy: um cais com um guindaste que levanta contêineres em um ciclo de 18 s, uma volta de trator com parada e uma barreira que sobe, um rebocador, um farol, um toque que inicia uma elevação, um indicador); examples/cafe.js (card, soft: pessoas e coisas pequenas), examples/kitchen.js (card, toy: um cômodo com uma parede de fundo e uma janela colocada nela, uma geladeira construída como uma casca cuja porta abre ao passar o mouse, uma torradeira que estoura ao tocar, um relógio), examples/launchpad.js (card, night: lâmpadas, um evento raro, um foguete que se desmonta sob o ponteiro, um toque que o lança, um indicador que faz contagem regressiva), examples/server.js (card, mono com um acento: luzes em ritmos, um hover que acende um grupo inteiro) ou examples/rack.js (card, mono com um acento: um estado vazio com resposta ao ponteiro) ou examples/assembly.js (card, mono com um acento: uma esteira de trabalhos através de um portão que um toque segura, um braço de estamparia, um indicador que conta); examples/mailbox.js (mini, toy), examples/seedling.js (mini, line: um estado vazio desenhado a tinta), examples/observatory.js (mini, line com wobble: uma cúpula que gira e um telescópio que olha), examples/desk.js (mini, line com um acento) ou examples/vending.js (mini, print: uma máquina construída como uma moldura ao redor de um recesso, bobinas nuas, um ventilador). Eles não são todas fábricas de propósito: um diorama é qualquer lugar.
4. Escreva a figura como <nome>.js no diretório de trabalho, no formato dos exemplos: uma chamada Diorama.figure({ … }) com
   • name: minúsculo, uma palavra ou hifenizado; size: hero | card | mini.
   • theme: um nome, ou { base: 'mono', accent: '#f2c230', shadows: false, … } para sobrescrever qualquer campo (palette, accent, lights, shadows, finish, tone, tint, edges, outline, stroke, strokeWidth, round, glow, halo, wobble). Construa uma vez; o tema é aplicado pelo kernel a cada primitiva, então uma figura nunca ramifica nele. Pinte o que importa com pal.accent: é a cor do sujeito em todos os temas, a cor que mono e line mantêm, aquela que um hex de marca substitui, e aquela que as amostras da bancada recolorizam ao vivo. Para uma figura line desenhada à mão, adicione wobble: 1.4 (px css de tremor: 1.2 uma caneta, 2.5 uma ponta de feltro).
   • means: uma frase, ≤ 140 caracteres, exibida sob o palco. Diz o que a cena mostra e o que se move.
   • hint: uma linha, ≤ 90 caracteres, o que o ponteiro faz e o que um toque faz ("Passe o mouse sobre o foguete para ver seus estágios; toque na sala de controle para lançar agora"). A página mostra para que um visitante saiba que pode brincar, e look.mjs pressiona o que ele nomeia.
   • title: o nome da figura, que a página mostra acima do palco. As palavras que a própria UI da pessoa coloca ao redor da figura (um título, uma linha, um botão) são dela para escrever; a cena não carrega nenhuma.
   • camera: { az, el, pad } em graus. az 45 é o padrão isométrico; 30–40 mostra uma base ampla em um hero 3:2. Deixe el em 35.264 a menos que a cena seja alta.
   • still: o segundo do loop que movimento reduzido e miniaturas mostram. Escolha um momento onde tudo está em um lugar revelador (o caminhão na doca, os garfos para cima).
   • build({ D, pal }): construa a cena uma vez com o kit e retorne parts: cada grupo e malha que tick moverá, mais parts.hot, os grupos que o ponteiro pode selecionar. Dê a cada grupo quente um .name (boat.name = 'boat'): a página mostra como um indicador enquanto o ponteiro está sobre ele.
   • tick(ctx): a cada quadro, pose as peças a partir de ctx.t com D.phase, D.pulse, D.wave, D.inOut, D.path e D.spring. Responda ao ponteiro com ctx.hover e uma pressão com ctx.pressed ou ctx.active (um toque é como um telefone responde, então um hero ou um card tem uma coisa para pressionar: um interruptor, uma chamada, ou o gêmeo do hover). D.apart desmonta uma coisa sob o ponteiro e a recoloca. Defina ctx.read como uma linha curta que diz o que a cena está fazendo agora ('caminhão · na doca'): a página mostra como o indicador, e é como um visitante aprende que a cena é um modelo funcional e não um loop. references/motion.md tem os padrões.
5. Monte: node <caminho-do-skill>/scripts/build.mjs <nome>.js escreve diorama-<nome>.html: a bancada, o kernel e a figura. O kernel desenha SVG da maneira que um ilustrador finge profundidade (uma projeção isométrica, um tom plano por face, as peças pintadas de trás para frente da cena, as sombras projetadas no chão como formas), então a página não carrega renderizador, não precisa de WebGL e não faz requisição de rede; o desenho é vetorial, nítido em qualquer tamanho, e a página pode estilizá-lo.

3. Verificação

1. node <caminho-do-skill>/scripts/look.mjs <nome>.js. Ele constrói a página, valida-a, abre-a no Chromium headless e escreve diorama-<nome>-look.png: o quadro parado, três momentos do loop, a resposta do ponteiro, a inclinação da câmera, uma pressão, a miniatura e a página inteira. Ele imprime o console, o preenchimento, o movimento, a resposta e a pressão como números. Corrija cada FAIL, e leia as linhas SMALL, STILL, FAINT e MUTE como perguntas, até que ele saia com 0. A pressão cai no grupo quente que a dica nomeia após "tap", "click" ou "press" (ou --press nome, ou --press x,y); MUTE significa que a dica prometeu uma pressão e nada mudou. Adicione --theme line (ou qualquer nome) para olhar a mesma figura em outro tema; uma figura que lê em toy e em line está construída corretamente. Ele também imprime clash: partes móveis que atravessam outras partes; um veículo através de uma árvore ou um carro através de um ônibus é um bug para corrigir, garfos em uma prateleira ou uma bandeira em sua dobradiça está bem.
2. Leia references/look.md, depois a folha, e responda suas perguntas. Corrija o que falha, depois volte para 1.

look.mjs precisa de um navegador; ele localiza o Playwright ou instala playwright-core uma vez fora desta pasta. Sem um navegador, execute node <caminho-do-skill>/scripts/validate.mjs diorama-<nome>.html após cada construção e faça a inspeção como look.md diz em "Sem um navegador". Não entregue uma página que o validador rejeita. Não diga que a inspeção está concluída se você não inspecionou.

4. Entrega

Entregue diorama-<nome>.html da maneira que a pessoa pediu: quando ela quiser o arquivo, dê o arquivo e diga onde está; caso contrário, publique-o como um artefato se puder. Depois, diga, uma linha cada:

• o conceito: o lugar, o que se move, o que o ponteiro e um toque fazem, e o tema (e como mudá-lo: theme: na figura, ?theme= e ?accent= na página, { theme } em Diorama.mount; as amostras da bancada recolorizam o sujeito ao vivo);
• o quadro parado: qual segundo, e por que aquele momento;
• onde deve viver (hero, card ou mini) e como incorporá-lo (references/react.md para React ou Next.js; um <script> simples do kernel mais a figura e Diorama.mount(fig, { el }) em qualquer outro lugar);
• qualquer coisa que você não pôde verificar (sem Node, sem navegador), claramente.

5. Ajuste

Quando a pessoa pedir uma mudança, edite apenas <nome>.js, depois execute look.mjs novamente e leia a nova folha. A décima versão é mantida ao mesmo padrão que a primeira.

O que dá errado

Se você se pegar	Faça isso em vez disso
recorrendo a three.js, uma luz, uma câmera, um canvas ou WebGL	não há nenhum: o kernel desenha SVG; use D.box, D.cyl, D.props.*, o.M para um vetor, e ctx
escrevendo requestAnimationFrame, setInterval ou uma animação CSS	pose tudo a partir de ctx.t em tick (regra 07)
movendo algo com position.x += speed * dt	coloque-o em um D.path e leia sua distância de D.phase(t, period), para que o loop seja contínuo e o quadro parado seja reproduzível (regra 08)
escrevendo uma palavra, um número ou uma flecha na cena	diga com o título ou means; a cena não carrega palavras, nem mesmo uma placa (regra 10)
recorrendo a uma textura, um gradiente, um brilho ou uma 15ª cor	mais um bloco em uma cor da paleta; pal.* tem o que você precisa (regras 03 e 04)
escrevendo if (theme === 'line') na figura	o kernel tonifica, contorna e ilumina cada primitiva por tema; uma figura é a mesma nos cinco
uma cor de marca colada em vinte peças, ou o sujeito pintado com um nome de paleta	pinte o sujeito com pal.accent e coloque o hex da marca em accent, uma vez, na declaração; palette: { cobalt: … } para uma segunda cor
uma resposta de hover e nada para um dedo	dê a uma coisa uma pressão (ctx.pressed, ctx.active): hover antecipa, um toque confirma (motion.md, "A pressão")
uma figura line que parece uma exportação CAD	wobble: 1.4 no tema: a tinta curva e ultrapassa como uma mão
desligando halo porque a base "parece suja"	o halo é o que assenta o diorama na página; abaixe-o (.1) em um fundo ocupado, mantenha-o
um indicador que diz o que o título diz	ctx.read é o relógio em palavras: a fase, a parada, a contagem, do mesmo T que pose as peças
construindo a base depois da cena, ou não construindo-a	D.slab primeiro: as sombras precisam de um lugar para pousar (regra 01)
uma cena que parece uma grade de cubos idênticos	dê a cada objeto as duas ou três características que o tornam o que é (regra 05)
um mini com oito coisas	um objeto, um movimento ambiente (concepts.md, "Um mini")
um hero onde tudo se move no mesmo tempo	três loops com diferentes

…

[truncado para tradução]