O que immersive-web faz?
Como construir experiências 3D, com shaders e rolagem que parecem os melhores filmes e jogos, carregam como uma página normal e não deixam ninguém de fora.
Este skill é uma camada. O skill ui-craft (mesmo plugin) é responsável pelo design de interface comum: layout, hierarquia, tipografia, cor, componentes, formulários, estados. Use-o para tudo isso e não repita aqui. Este skill adiciona a camada superior: cena, luz, material, shader, câmera, rolagem e movimento cinematográfico. Ambos leem os mesmos tokens de tema, então um único tema dirige a página e a cena (references/theme-bridge.md).
Limite honesto. Você pode dirigir uma cena, iluminá-la, mover uma câmera, escrever shaders e conectar um modelo. Você não pode esculpir arte 3D de qualidade cinematográfica do nada. Componha a partir de geometria simples, shaders, tipografia e luz, ou use um modelo fornecido pela equipe. Nunca finja com um desenho tosco do assunto.
1. As nove regras rígidas
Quebre uma e o trabalho não está pronto, por mais bonito que pareça.
- Conteúdo primeiro. Títulos, texto, links e botões são HTML real, legíveis antes de qualquer script ser executado. A cena é adicionada por cima e pode desaparecer sem perda. Nunca desenhe as palavras da página em um canvas. Nunca esconda conteúdo com
opacity: 0no CSS esperando um script revelá-lo. - Três estados para cada efeito. Completo; movimento reduzido (um quadro estático ou um fade curto:
prefers-reduced-motion, e a configuração do SO em apps nativos); sem GPU (uma imagem de pôster ou arte CSS/SVG exibida quando WebGL ou WebGPU está ausente, falha ou o contexto é perdido). Projete os dois fallbacks primeiro. Eles também são o que carrega primeiro. Um fallback é a mesma imagem, mais silenciosa: o mesmo assunto do mesmo ângulo (um pôster feito da própria cena) e, para uma cena de dados, os mesmos dados desenhados planos. Uma caixa em branco, um gradiente simples ou "imagem a ser inserida" é uma falha. - Um orçamento de velocidade, decidido antes de construir (§4). O texto da página pinta primeiro; o motor carrega depois. Em um telefone, a cena custa menos que o conteúdo.
- Um momento marcante por página, e faça valer a pena. Uma cena, uma ideia, feita completamente. Todo o resto permanece quieto. Efeitos em todos os lugares parecem um modelo e cansam as pessoas. Moderação limita o número de efeitos, não sua intensidade: o momento único é um evento que pertence a este produto (a chaleira derrama; o céu se enche de estrelas enquanto os olhos se ajustam), encenado com força suficiente para que alguém o descrevesse a um amigo. Um objeto que só gira enquanto você rola não é um momento.
- Nunca tome o controle da rolagem. O navegador rola; você apenas lê a posição. Sem velocidade ou direção alterada, sem sequestro da roda, sem barra de rolagem falsa. Prenda com
position: sticky, mantenha curto, dê uma maneira de pular. - Palavras e cena nunca compartilham o mesmo lugar. Em cada posição de rolagem, o texto fica ao lado do assunto ou em sua própria superfície, nunca sobre ele. Navegação e botões sobrepostos a uma cena recebem um véu ou uma superfície. Verifique cada captura de tela da rolagem, não apenas a primeira.
- Teclado e leitor de tela alcançam tudo que é real. A ordem de tabulação segue a ordem de leitura. Um canvas decorativo tem
aria-hidden="true"; um significativo tem um equivalente de texto ao lado. Qualquer coisa que você possa fazer arrastando a cena, você pode fazer com um botão. - Movimento descansa, som espera, nada pisca. Movimento ambiente se estabiliza em 5 segundos ou tem um controle de pausa visível. O som está desligado até ser solicitado. Não mais que 3 flashes por segundo, nunca. Nada é executado fora da tela ou em uma guia oculta.
- Original e licenciado. Aprenda a linguagem de um gênero; nunca copie a aparência, modelos, personagens, logotipos ou sons de um produto. Use apenas ativos que você fez ou que têm uma licença clara (bibliotecas CC0 como Poly Haven e ambientCG são seguras) e registre cada um.
2. Fluxo de trabalho (faça isso sempre)
-
Olhe antes de construir. Encontre o tema:
theme.css,DESIGN.md(do estúdio ui-craft), tokens, uma configuração Tailwind, cores da marca. Leia--immersivee a seção "Imersivo e movimento" do briefing, se presente: eles indicam a intensidade que o proprietário escolheu. Verifique a stack (HTML simples, React, Vue, um shell de aplicativo) e quaisquer ativos 3D já fornecidos. Sem tema algum, use ui-craft primeiro para escolher uma direção. -
Escolha o nível na escada da §3. Pegue do tema se ele disser; caso contrário, escolha o nível mais baixo que entregue a ideia. O nível 3 é raro.
-
Escolha a ferramenta mais leve que pode fazer o trabalho.
Necessidade Use Custo Revelar, efeitos de rolagem sem parallax, transições de página CSS apenas: animações acionadas por rolagem, position: sticky, View Transitions0 KB Uma textura viva plana, linhas, um campo, uma figura 2D Canvas 2D ou SVG, ou um shader de fragmento em um único triângulo (WebGL puro, sem biblioteca) 2-5 KB Mostrar um modelo 3D que as pessoas possam girar <model-viewer>cerca de 250 KB, lazy Uma cena real: vários objetos, luzes, uma câmera em movimento three.js (aplicativo React: React Three Fiber) carregado com dynamic import()150-180 KB gzip, lazy Linhas do tempo ligadas à rolagem que CSS não pode expressar GSAP ScrollTrigger (gratuito, não open source: carregue, nunca copie) ou Motion 25-45 KB Recursos GPU mais recentes WebGPU como uma atualização sobre um caminho WebGL, nunca sozinho - Não adicione uma biblioteca de rolagem suave por padrão. Se o briefing exigir uma, ela deve se desativar em movimento reduzido.
-
Escreva o briefing imersivo (adicione ao briefing de design do ui-craft), antes do código:
Nível: 2 marcante (tema diz --immersive: 2) Stack: HTML simples + three.js, lazy Momento marcante (um evento, não um girador): no batida 3 a chaleira inclina e um filete fino jorra, mantendo sua linha Cena: uma chaleira de cerâmica fosca em uma poça de luz no fundo da página; luz chave suave de cima esquerda, borda quente Faixa de texto: cópia na coluna esquerda no desktop, abaixo da cena fixa em telefones; a chaleira nunca a cruza Câmera: tipo 35mm, ligeiramente acima, nunca se move sozinha Ritmo: suave (--dur-slow 400ms) Batidas (apenas nível 3): 1 chaleira inteira - 2 bocal, perto - 3 derramando - 4 conjunto sobre uma mesa Movimento reduzido: um quadro estático por batida, com cross-fade Sem GPU: um pôster da mesma cena, mesmo ângulo Orçamento: texto pinta primeiro; motor depois; cena abaixo de 1,5 MB em telefones; proporção de pixels 1,5 em toque -
Construa nesta ordem. (a) A página inteira como HTML e CSS simples com ui-craft, com o pôster ou fallback CSS no lugar da cena. Já deve ser uma boa página. (b) O shell da cena:
assets/scene-shell.jsfornece início lazy, quadros estáticos, fallback, pausa fora da tela, limite de proporção de pixels, recuperação de contexto perdido. (c) A ponte do tema:assets/theme-bridge.jspara que cores, raio e ritmo venham dos tokens. (d) A cena em si, em sua forma mais simples. (e) Movimento e rolagem. (f) Polimento: luz, material, granulação, timing.assets/starter.htmlé uma página funcional com (a)-(c) feitos; substitua sua cena placeholder. -
Verifique, depois olhe. Execute
node <skill-dir>/scripts/immersive-check.mjs page.html. Ele carrega a página de cinco maneiras (desktop, telefone, movimento reduzido, sem WebGL, sem JavaScript), mede peso, chamadas de desenho, proporção de pixels, rolagem nativa e pausas, e salva capturas de tela. Para uma janela de aplicativo (Electron, Tauri, um aplicativo web com login) adicione--apppara pular o teste sem JavaScript. Abra cada captura de tela. Corrija o que falhar. Olhe com mais atenção para três: o meio da rolagem (algum texto está cruzando o assunto?), o meio do telefone (cena e texto juntos em uma tela, sem faixa vazia?), e a sem WebGL (a mesma imagem, ou um buraco?). Faça o pôster da própria cena:--poster hero-poster.pngsalva a caixa da cena da passagem desktop (--scheme lightoudarkescolhe o tema), pronto para usar como imagem de fallback. Em seguida, execute oui-audit.mjsdo ui-craft para contraste, alvos de toque e tipo, e julgue o telefone com a mesma rigidez do desktop. Passagem final: lista de verificaçãoreferences/accessibility-fallbacks.md.
3. A escada da imersão
Cada produto está em um degrau. O tema pode carregá-lo como --immersive: 0-3; cada uma das 16 direções ui-craft define um padrão (references/theme-bridge.md).
| Nível | O que é | Adequado a | Não adequado a |
|---|---|---|---|
| 0 Estático | Sem 3D, shaders ou efeitos de rolagem. Apenas movimento de interface comum | ferramentas financeiras, admin, governo, formulários de saúde, dashboards densos, qualquer coisa usada o dia todo | - |
| 1 Destaque | Um detalhe vivo quieto: um material, uma textura de shader lenta, uma transição de visualização. Descansa após alguns segundos. Sem cenas acionadas por rolagem | Apps SaaS, documentação, a maioria das UIs de produto, aplicativos desktop e mobile | tarefas onde as pessoas estão ansiosas ou apressadas |
| 2 Marcante | Um momento herói: um objeto ou shader que responde ao ponteiro ou à primeira rolagem. Depois, uma página normal | Landing pages, páginas de produto, portfólios, integração, tela de inicialização | páginas que as pessoas revisitam diariamente |
| 3 História | Uma sequência acionada por rolagem de 3-5 batidas com uma cena persistente | Lançamentos, campanhas, recursos editoriais, histórias de museu e marca | aplicativos, checkout, qualquer coisa com uma tarefa |
Regras da escada: o nível é um teto, não um alvo. A frequência o reduz: quanto mais frequentemente uma pessoa vê uma tela, menor o nível. Uma tarefa o reduz: onde alguém está pagando, assinando ou resolvendo um problema, use o nível 0. Quando estiver em dúvida, desça um nível e termine melhor.
4. Orçamentos
Metas funcionais. Meça; não adivinhe. Números marcados com * são padrões sensíveis, não limites publicados.
| O quê | Telefone | Desktop |
|---|---|---|
| Maior pintura de conteúdo (deve ser texto ou um pôster, nunca o canvas) | 2,5 s ou menos | 2,5 s ou menos |
| Script solicitado antes da primeira pintura | abaixo de 170 KB comprimido | mesmo |
| Motor (three.js cerca de 180 KB gzip) | após a primeira pintura, dynamic import(), apenas quando a cena está perto da viewport | mesmo |
| Primeiro payload da cena: motor + modelos + texturas * | abaixo de 1,5 MB | abaixo de 4 MB |
| Modelo herói (GLB, comprimido) * | abaixo de 2 MB, 20-60k triângulos | abaixo de 5 MB, até 100k |
| Texturas | 1024 px; 2048 apenas para o herói; KTX2 para memória GPU | 2048; 4096 apenas para close-ups |
| Proporção de pixels | limite 1,5, cair para 1 quando lento | limite 2 |
| Chamadas de desenho por quadro * | abaixo de 100 | abaixo de 300 |
| Luzes em tempo real | 1 chave (+ ambiente); 1 mapa de sombra de 1024, ou uma sombra assada / blob | 1-3; mapa de sombra no máximo 2048 |
| Passagens de pós-processamento | 0-1 | 1-3 |
| Tempo de quadro | 60 qps estável; reduza a qualidade antes de cair abaixo de 30 | 60 qps |
| História de rolagem | 3-5 batidas, 100-150vh cada, execução fixa abaixo de 5 telas *, um link de pular | mesmo |
| Pré-carregador | nenhum; a página é legível em 1-2 s e a cena aparece gradualmente quando pronta | mesmo |
Uma textura de 2048 px custa cerca de 22 MB de memória de vídeo quando descompactada, qualquer que seja seu tamanho de arquivo, a menos que seja KTX2. Detalhes e a ordem de redução: references/performance.md.
5. Um único tema dirige cada camada
- Leia as cores dos tokens (
--bg,--surface,--accent,--accent-soft,--text,--border...), nunca codifique um hex em um shader ou material.readTheme()emassets/theme-bridge.jsretorna cada uma como RGB linear para cálculos de iluminação e sRGB para desenho plano, ewatchTheme()relê em uma troca claro/escuro. - A cena fica no fundo da página: um canvas transparente, ou uma cor clara igual a
--bg. Sem retângulo visível, sem segunda cor de fundo. - O destaque permanece raro também em 3D: um objeto, uma luz, uma linha. Principalmente neutro.
- A forma do tema é carregada: o raio do canto se torna bisel e raio da borda; o estilo de profundidade se torna o estilo de sombra (hairline: contorno fino, quase sem sombra; soft: sombra de contato suave e larga; crisp: mais apertada e brilhante; lip: uma borda dura deslocada; flat: nenhuma).
- Os tokens de movimento definem o ritmo:
--dur-*e--ease-outmoldam movimentos de câmera e easing de rolagem (bezier()na ponte), de modo que uma ferramenta "instantânea" e uma casa de luxo "lenta" se movem de forma diferente com o mesmo código. Salto apenas onde a curva do tema ultrapassa. - O tipo permanece HTML em
--font-displaye--font-sans, sobreposto ou ao lado do canvas.
6. Ofício, em resumo
Cena e câmera (references/scene-camera.md)
- Um assunto, uma silhueta clara, muito espaço quieto. Componha primeiro para o quadro alto do telefone.
- Uma lente longa (campo de visão de 20-35 graus) favorece objetos; ângulos amplos distorcem. A câmera se move devagar e com uma razão, ou não se move.
- Renderize sob demanda. Uma cena que não está mudando não desenha nada.
Luz e material (references/materials-lighting.md)
- Uma luz chave de cima (a mesma fonte de luz única da interface), um preenchimento suave, uma borda para separar o assunto do fundo. A luz nunca é branca pura; as sombras nunca são pretas puras.
- Fundamente o assunto: uma sombra de contato suave, ou ele flutua.
- Defina os espaços de cor antes de julgar qualquer coisa. Muito escuro ou desbotado é um erro de espaço de cor, não de iluminação.
- Asse luz em texturas quando a cena é estática. É a luz mais barata que existe.
Shaders (references/shaders.md)
- Um shader é um material, uma luz ou uma textura com um trabalho. Não um papel de parede.
- Paleta de 2-4 cores do tema, misturadas em OKLab para que o meio permaneça limpo. Sem arco-íris.
- Adicione 2-4% de granulação para esconder bandeamento em gradientes suaves. Mantenha o trabalho do fragmento barato em telefones: poucas leituras de textura, sem loops longos.
Storytelling com rolagem (references/scroll-storytelling.md)
- Cada batida é uma ideia com uma linha de texto real. Se uma batida não tem nada a dizer, corte-a.
- O texto rola normalmente; a cena fica parada (sticky) e muda com ele. Posição de varredura, nunca tempo.
- Movimento reduzido transforma o filme em slides: um quadro estático por batida.
Movimento cinematográfico (references/cinematic-motion.md)
- Corte ou dissolva entre ideias; mova-se dentro de uma. Segure o que importa. Easing é atuação: peso, não decoração.
- O movimento da interface mantém o timing do ui-craft (100-300 ms). Movimentos de cena e câmera levam 600-1200 ms. Transições de página 200-500 ms, e a URL, o botão voltar e o foco continuam funcionando.
Blender para o navegador (references/blender-pipeline.md)
- Apenas Principled BSDF, asse o resto, exporte GLB, depois comprima:
gltf-transform optimize, meshopt ou Draco, texturas KTX2. Inspecione o arquivo antes de ir para a web.