Communitygithub.com

immersive-web

Crie experiências imersivas e cinematográficas de "site do futuro" que permanecem rápidas e acessíveis — cenas 3D no navegador (Three.js, React Three Fiber, WebGL, WebGPU), shaders (GLSL, TSL), storytelling com rolagem, animações cinematográficas e transições de página, e o caminho do Blender para o navegador (glTF, Draco, meshopt, KTX2, iluminação assada).

O que é immersive-web?

O skill immersive-web é uma ferramenta especializada para desenvolvedores que desejam construir experiências web imersivas, combinando gráficos 3D, shaders e storytelling cinematográfico com rolagem, mantendo desempenho e acessibilidade. Ele funciona como uma camada sobre o design de interface comum (gerenciado pelo skill `ui-craft`), adicionando cenas, luzes, câmeras e animações sem comprometer o conteúdo textual. Suporta plataformas como Three.js, React Three Fiber, WebGL e WebGPU, além de ferramentas de compressão de modelos 3D como glTF, Draco e meshopt. O skill impõe regras rigorosas: prioriza conteúdo real em HTML, exige três estados para cada efeito (completo, com movimento reduzido e sem GPU), e estabelece orçamentos de desempenho para garantir que a página carregue rapidamente em dispositivos móveis e desktop. Também inclui um fluxo de trabalho estruturado que começa com a criação de um brief imersivo e termina com verificações de acessibilidade e desempenho.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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.

  1. 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: 0 no CSS esperando um script revelá-lo.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. 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.
  9. 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)

  1. 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 --immersive e 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.

  2. 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.

  3. Escolha a ferramenta mais leve que pode fazer o trabalho.

    NecessidadeUseCusto
    Revelar, efeitos de rolagem sem parallax, transições de páginaCSS apenas: animações acionadas por rolagem, position: sticky, View Transitions0 KB
    Uma textura viva plana, linhas, um campo, uma figura 2DCanvas 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 movimentothree.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 expressarGSAP ScrollTrigger (gratuito, não open source: carregue, nunca copie) ou Motion25-45 KB
    Recursos GPU mais recentesWebGPU 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.

  4. 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
    
  5. 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.js fornece 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.js para 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.

  6. 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 --app para 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.png salva a caixa da cena da passagem desktop (--scheme light ou dark escolhe o tema), pronto para usar como imagem de fallback. Em seguida, execute o ui-audit.mjs do ui-craft para contraste, alvos de toque e tipo, e julgue o telefone com a mesma rigidez do desktop. Passagem final: lista de verificação references/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ívelO que éAdequado aNão adequado a
0 EstáticoSem 3D, shaders ou efeitos de rolagem. Apenas movimento de interface comumferramentas financeiras, admin, governo, formulários de saúde, dashboards densos, qualquer coisa usada o dia todo-
1 DestaqueUm 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 rolagemApps SaaS, documentação, a maioria das UIs de produto, aplicativos desktop e mobiletarefas onde as pessoas estão ansiosas ou apressadas
2 MarcanteUm momento herói: um objeto ou shader que responde ao ponteiro ou à primeira rolagem. Depois, uma página normalLanding pages, páginas de produto, portfólios, integração, tela de inicializaçãopáginas que as pessoas revisitam diariamente
3 HistóriaUma sequência acionada por rolagem de 3-5 batidas com uma cena persistenteLançamentos, campanhas, recursos editoriais, histórias de museu e marcaaplicativos, 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êTelefoneDesktop
Maior pintura de conteúdo (deve ser texto ou um pôster, nunca o canvas)2,5 s ou menos2,5 s ou menos
Script solicitado antes da primeira pinturaabaixo de 170 KB comprimidomesmo
Motor (three.js cerca de 180 KB gzip)após a primeira pintura, dynamic import(), apenas quando a cena está perto da viewportmesmo
Primeiro payload da cena: motor + modelos + texturas *abaixo de 1,5 MBabaixo de 4 MB
Modelo herói (GLB, comprimido) *abaixo de 2 MB, 20-60k triângulosabaixo de 5 MB, até 100k
Texturas1024 px; 2048 apenas para o herói; KTX2 para memória GPU2048; 4096 apenas para close-ups
Proporção de pixelslimite 1,5, cair para 1 quando lentolimite 2
Chamadas de desenho por quadro *abaixo de 100abaixo de 300
Luzes em tempo real1 chave (+ ambiente); 1 mapa de sombra de 1024, ou uma sombra assada / blob1-3; mapa de sombra no máximo 2048
Passagens de pós-processamento0-11-3
Tempo de quadro60 qps estável; reduza a qualidade antes de cair abaixo de 3060 qps
História de rolagem3-5 batidas, 100-150vh cada, execução fixa abaixo de 5 telas *, um link de pularmesmo
Pré-carregadornenhum; a página é legível em 1-2 s e a cena aparece gradualmente quando prontamesmo

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() em assets/theme-bridge.js retorna cada uma como RGB linear para cálculos de iluminação e sRGB para desenho plano, e watchTheme() 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-out moldam 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-display e --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.

Individual skills in this repo

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

Habilidades Relacionadas