zhaodi-Wen/design-agent-skills

Exposição de Produtos com Rolagem e Arrasto

Entrega arquivos de origem editáveis e uma página web funcional. Primeiro, confirme se a interação atual é de rolagem, arrasto ou ambas; ao adicionar uma nova interação a uma página existente, mantenha a outra interação já autorizada. O vídeo de referência é usado para identificar relações visuais e de movimento, não para afirmar que o site original usa um determinado framework. A exibição da página e o sistema real de pedidos de e-commerce devem ser descritos separadamente quanto ao status de conclusão.

Extrair da Referência

Leia a duração e as dimensões do quadro do vídeo local; extraia quadros do início, pontos de transição intermediários e do final; aumente a amostragem conforme necessário para confirmar movimentos contínuos. Registre: posição e tamanho do objeto principal, mudanças de perspectiva, fundo e adereços, tamanho da fonte, ordem de oclusão, direção da rolagem e comportamento de retrocesso. Não confunda bordas de gravação de tela, legendas explicativas ou o cursor do mouse com o design da página.

Organize a referência em uma tabela de ações organizada pelo progresso da rolagem. Marque separadamente o que é diretamente visível no quadro, o que é inferido e a abordagem de implementação escolhida. Consulte references/motion-design.md para o exemplo do café e a lógica de decisão de rota.

Escolher Método de Apresentação

• Necessita de mudança real de perspectiva, rotação interativa ou troca de materiais: Modelo 3D Three.js com GSAP. Reutilize GLB existente quando apropriado; para objetos simples como xícaras, garrafas e latas, use modelagem geométrica paramétrica, deixando claro que são modelos esquemáticos originais.
• Câmera fixa, iluminação complexa, material renderizado existente: Sequência de quadros Canvas. O número do quadro é determinado pelo progresso da rolagem; lide com quadros não carregados e uso de memória; não assuma que qualquer vídeo pode saltar quadro a quadro sem problemas.
• Apenas translação, opacidade e inclinação planar: Camadas DOM/CSS. Uma única imagem não pode produzir uma rotação real de frente para trás.

Depois que a rota do material for determinada, monte a lógica de rolagem. Quando o usuário não especificar uma marca, use dados de marca e produto de demonstração claros; não invente certificações, volume de vendas, avaliações ou resultados reais de transações.

Modelo Inicial

Existem dois modelos autocontidos Vite + Three.js + GSAP, escolha com base no produto e na tarefa; novas marcas ainda precisam de design visual personalizado.

• assets/starter/ (coffee, padrão): Narrativa de rolagem de café com arrasto sobreposto, troca de sabor e sacola de compras local; mini.html é uma interface H5 no estilo de miniaplicativo que compartilha produtos e a sacola de compras.
• assets/gallery/ (gallery): Três temas visuais: perfume, fone de ouvido, relógio. O fone de ouvido suporta expansão por rolagem, três parágrafos de texto e arrasto coexistente; perfume e relógio usam arrasto e botões de estrutura. Use como base para casos que não sejam de café.

Crie em um diretório que ainda não exista (o script não sobrescreve projetos existentes):

python3 /caminho/para/scroll-product-showcase/scripts/create_project.py /caminho/absoluto/para/novo-projeto
cd /caminho/absoluto/para/novo-projeto
npm ci
npm run dev -- --port 5197

Substitua /caminho/para/scroll-product-showcase pelo caminho real de instalação da skill. Se a porta estiver ocupada, use uma porta disponível e forneça o endereço real.

Ao gerar um caso que não seja de café, adicione --template gallery. A entrada para o fone de ouvido é /?case=headphones, e também há /?case=perfume e /?case=watch. Ao modificar um projeto existente, faça as alterações diretamente nele, sem usar o gerador para substituí-lo.

Locais de modificação:

• src/scene.js: Câmera, iluminação, pose de rolagem e ângulo de arrasto independente; o modelo de café está aqui, os modelos da galeria estão em src/models.js.
• src/scroll-story.js: Estágios de rolagem, texto sincronizado e barra de progresso.
• src/main.js: Entrada e estado de interação; gestos de ponteiro do café estão em src/drag.js, a sacola de compras em src/bag.js.
• Café src/products.js, Galeria src/content.js: Texto e cores dos produtos.
• src/style.css e index.html: Layout, design responsivo, texto e estrutura semântica.
• Café mini.html, src/mini.js, src/mini.css, src/cup-viewer.js: Interface no estilo de miniaplicativo; vite.config.js mantém duas entradas de build.

O modelo usa CSS sticky para fixar a cena e ScrollTrigger para impulsionar o progresso; não adicione pin na mesma camada. Outros projetos também podem mudar para ScrollTrigger pin, mas precisam remover o layout sticky conflitante.

Combinações de Interação e Restrições de Implementação

Ao envolver arrasto, rolagem coexistente, botões de estrutura ou interface de miniaplicativo, leia references/interaction-modes.md, que contém sobreposição de poses, divisão de entrada e pontos de verificação de aceitação.

• Use um único progresso de 0 a 1 para controlar o modelo, a câmera e o texto sincronizados com a rolagem; no mesmo ângulo manual, avançar e retroceder para o mesmo progresso deve resultar na mesma pose. O ângulo de arrasto é armazenado independentemente e depois sobreposto à pose de rolagem; não permita que dois manipuladores substituam a rotação um do outro.
• Quando rolagem e arrasto coexistem, o reset padrão apenas limpa o ângulo manual, mantendo o progresso da rolagem e as cores. Se os botões de estrutura controlarem a mesma ação, devem pular para a posição correspondente na linha do tempo, evitando iniciar uma animação separada que conflite com o progresso; siga a solicitação do usuário se ele especificar outro significado para reset.
• Primeiro, determine a área segura do objeto principal, depois posicione o texto; em dispositivos móveis, redefina o tamanho e a trajetória do objeto principal, não apenas reduza proporcionalmente a versão para desktop.
• Título, descrição, botões de seleção e preço devem estar em HTML acessível; o Canvas é responsável pela representação visual.
• Ao trocar texturas, libere a textura antiga; ao destruir, limpe observadores, animações, eventos e recursos da GPU. Limite a proporção de pixels e evite re-renderização contínua de cenas invisíveis.
• Para preferências de movimento reduzido, forneça uma composição estática e informações de produto diretamente acessíveis. Em caso de falha do WebGL, mantenha a seleção de produtos e a sacola de compras.
• A sacola de compras local pode suportar seleção, adicionar/remover, excluir e persistência. Quando não houver integração com backend, indique claramente que é uma demonstração, sem exibir que o pedido foi enviado ou o pagamento foi bem-sucedido.

Verificação e Entrega

Primeiro, construa o projeto e depois verifique a renderização real no navegador. Cubra o início, meio, fim, retrocesso, tela estreita, preferência de movimento reduzido e seleção de produto; no modo de coexistência, teste também o arrasto no meio, continue rolando e o reset. Após alternar casos, verifique o texto, a altura do palco e as cores. Se houver sacola de compras, verifique a quantidade, o total e o estado após a atualização da página. Verifique se há anormalidades na página, carregamento de recursos e overflow horizontal.

O script scripts/verify-browser.mjs do modelo de café é um script de regressão opcional que pode ser direcionado para um módulo Playwright existente via PLAYWRIGHT_MODULE e BASE_URL para o serviço real. Se o ambiente atual exigir o uso de uma ferramenta de navegador, use essa ferramenta para realizar a mesma verificação interativa, sem iniciar um driver de navegador separado. Para a galeria, use a ferramenta de navegador para verificar os cenários descritos. Relate apenas as verificações realmente executadas; ainda é necessário visualizar capturas de tela para julgar se a qualidade visual é aceitável; a construção bem-sucedida ou o HTTP 200 não substituem a verificação visual.

Após a conclusão, forneça o URL de visualização, o diretório do código-fonte e capturas de tela principais. Explique a rota de implementação real e os serviços ainda não conectados. Faça gravação de tela ou vídeo apenas se o usuário solicitar explicitamente; não relate capturas de tela estáticas como verificação interativa ou gravação de tela.

Consulte a documentação técnica conforme necessário: GSAP ScrollTrigger, Three.js GLTFLoader.