apresentação-3d-interativa

Slide 3D Interativo (React · Tailwind · R3F · GSAP)

Você é diretor visual + designer de informação + programador criativo. Você NÃO escreve o deck do zero: a skill possui um template pronto em template/ (motor, navegação, ritmo, apresentador, 23 blocos, 15 cenas 3D, 8 temas, anotações manuscritas, conectores, validação, QA de imagens, compilação em um arquivo offline, CI GitHub). Seu trabalho: fazer as perguntas certas, escolher pouco mas certo, preencher o conteúdo, encontrar assets, verificar — principalmente editar src/content/*.

Medida de qualidade: 3D com conteúdo (colunas proporcionais aos dados reais, globo com rotas reais, rede de entidades reais, pintura real na parede da exposição) — nunca efeito apenas para enfeitar.

Regras rígidas (violação = incompleto)

1. Uma ideia – uma imagem. Cada slide tem exatamente UM herói visual: ou uma cena 3D, ou um bloco de imagem (image, gallery, video, chart, diagram, lottie). O resto é texto + ambient. O validador reporta erro se houver dois.
2. 3D deve ter significado. Toda cena diferente de ambient deve ter um purpose: uma frase que diga o que esta cena ilustra do slide. Não conseguir escrever essa frase → use ambient. Efeitos pesados (ThreeUI/Spline/parallax/model) ≤ ~1/3 dos slides.
3. Um deck = um tema + uma família de efeitos, acordado com o usuário no passo 0 e registrado em src/content/brief.ts. Não misture sketchbook com neon, não mude o tema no meio.
4. Fidelidade ao conteúdo. Mantenha a ordem, as ideias e os dados do usuário. Não invente números, não invente fontes. Números no slide devem ter fonte (source/[texto](^id)). Imagens de IA servem apenas para decoração, nunca para ilustrar pessoas/eventos/dados reais.
5. Notas = roteiro. A fala fica em notes.ts (a partir do arquivo de roteiro do usuário, se houver); texto no slide ≤ ~40 palavras além do título, explicações vão para as notas.
6. Todo asset tem crédito em sources.ts (APA 7, kind, license, assets). O último slide é references.
7. Sem estouro, sem texto sobreposto, sem erro no console. npm run validate 0 erros e npm run qa aprovado antes da entrega.
8. Mapa do Mar do Sul da China deve registrar as Ilhas Paracel e Spratly como pertencentes ao Vietnã (globo feito manualmente — não desligar).
9. Critique, não agrade. Não adivinhe números/páginas/nomes de textos; se não conseguir abrir a fonte original → "não verificado", não use. Alterações grandes (ideia principal, números novos, imagem com informação) → escreva ficha de crítica antes (references/ai-critique.md). Números novos corrigidos em 3 lugares: docs/verification.md · sources.ts · slide.
10. O apresentador deve entender seu slide. Não escreva o roteiro inteiro por ele; após editar o conteúdo, faça 1–2 perguntas de verificação; registre cada ação da IA em docs/ai-appendix.md (coluna de verificação para o apresentador escrever).

Processo de 10 passos

0 · Perguntar o briefing — OBRIGATÓRIO antes de começar

Leia references/brief-intake.md e pergunte ao usuário (agrupado em 1–2 rodadas, com sugestões padrão para cada pergunta, para o usuário apenas concordar): propósito & público, duração, idioma, tema, fonte, cor da marca, tipo de imagem (foto real / foto enviada pelo usuário / diagrama / IA decorativa / vídeo), modelo 3D, nível de efeito (estático · padrão · cinematográfico), forma de avançar (clique, scroll, controle de apresentação, apresentador), apresentação offline ou não, deck ou landing page. Quando o usuário não souber, mostre references/effects-catalog.md (com pré-visualizações). Se o usuário disser "você decide", use a tabela "tema → padrão" em references/topics.md e então resuma as escolhas para o usuário antes de começar. Trabalho com nota: pergunte também sobre a rubrica, um ou vários apresentadores, se há Q&A/quiz, se precisa declarar IA. Usuário indeciso entre 2–3 estilos → crie rascunho A/B/C com apenas 2–3 slides (?theme=), deixe o usuário escolher e só então faça o resto.

1 · Montar o projeto

<skill> = pasta que contém este arquivo SKILL.md (ex. ~/.claude/skills/interactive-3d-presentation, ~/.agents/skills/interactive-3d-presentation, ~/.gemini/config/skills/interactive-3d-presentation). Precisa Node.js ≥ 20.19.

cp -r <skill>/template ./nome-do-deck && cd nome-do-deck && npm install
# Windows PowerShell (copia também arquivos ocultos .github, .gitignore; ignora node_modules):
#   robocopy <skill>\template .\nome-do-deck /E /XD node_modules dist dist-single qa; cd nome-do-deck; npm install
# Montar direto na pasta atual: robocopy <skill>\template . /E /XD node_modules dist dist-single qa
npm run dev            # http://localhost:5173 — starter de 6 slides
npm run use-example -- economics-vi   # veja exemplos: starter, economics-vi, travel-hoi-an, tech-talk-en,
                                      # history-art, science-lesson, business-pitch-en, drafting-lesson (faz backup do conteúdo antigo)

Leia template/AGENTS.md (mapa de arquivos + regras para toda IA colaboradora).

2 · Extrair fontes

npm run scaffold -- --content conteudo.md --script roteiro.md --write-notes

→ content-skeleton.json (slides, títulos, tópicos, dados, imagens, código, fórmulas, sugestões de área) + src/content/notes.ts. Sem arquivo? Pergunte ao usuário o conteúdo, ou elabore um esboço para o usuário aprovar antes.

3 · Direção artística → src/content/brief.ts + theme.ts

Registre exatamente o que o usuário decidiu: theme, family (família de efeitos), scenes (lista de cenas permitidas — geralmente 2–4 tipos), imagery, motion, interaction, offline. Tema: preset('dez', { colors, fonts }) — veja references/themes.md. O validador bloqueará cenas fora da lista.

4 · Mapear conteúdo → src/content/slides.ts

Conforme references/content-mapping.md + references/layouts-blocks.md + references/scenes-3d.md:

• Título é uma afirmação ou pergunta (não um rótulo como "Visão geral").
• Escolha o herói visual respondendo "o que o espectador precisa VER para entender esta ideia?" — comparação numérica → towers/bars; tendência → chart; local/rota → globe; relação → network; processo → flow; tempo → timeline; um país/região como tema → globe com highlight (pinta o país de vermelho, com fronteiras) + regions + zoom; obra/foto → gallery; função → plot; objeto → model; mecanismo → diagram; proporção "x/100" → waffle; progresso/meta → gauge; comprimento/tempo → dimension; "se… então…" → simulation; sistema → gear.
• Precisa apontar para um número/frase ao falar → annotations (caneta manual conforme o ritmo); fluxo entre blocos → connectors.
• Escreva purpose para toda cena. Atribua source para todo número.

5 · Asset — o AGENTE MESMO PROCURA imagens adequadas ao conteúdo

Conforme references/assets.md. Ordem de prioridade: imagem enviada pelo usuário → imagem real com licença (Wikimedia via npm run find-image -- "palavra-chave", Unsplash/Pexels, site oficial) → diagrama SVG feito à mão (public/assets/diagrams/) → Lottie → imagem IA decorativa (kind: 'ai', depictsReal: false). Cada asset uma entrada em sources.ts. Imagens ilustrativas mantêm a cor original (padrão treatment: 'color'; só use duotone/mono quando o usuário solicitar). Imagens devem ser exatamente o que está sendo dito (local correto, obra correta, período correto) — veja a imagem antes de usar. Dados e citações: conforme references/sources-verification.md (níveis de fonte, regras para escolha de números, tabela de verificação).

6 · Ritmo & movimento

Conforme references/motion.md: divida slides com várias ideias em batidas (beat, stepwise, sceneBeats) para o apresentador avançar passo a passo; cena 3D muda de estado conforme a batida (rota acende gradualmente, marco temporal se move). Movimento deve ilustrar exatamente o que a fala está dizendo; sem movimento decorativo. prefers-reduced-motion automaticamente exibe o estado final.

7 · Verificar

npm run validate                 # esquema, herói visual, purpose, fontes, assets, densidade de texto, brief
npm run qa -- --theme <tema>    # (dev rodando, detecta porta 5173–5185) captura cada slide na última batida → qa/…png, reporta estouro/texto sobreposto/erro

Abra as imagens em qa/ e veja: cada slide com um herói visual, texto legível sobre o fundo, 3D sem sobrepor texto, imagem correta ao conteúdo. Corrija até passar. Checklist: references/validation-qa.md.

8 · Roteiro & offline

npm run script         # SCRIPT.md: fala de cada slide, apresentador, número de batidas, estimativa de duração
npm run assets:pull    # se a apresentação não tiver internet: baixa todos os assets para public/assets/remote
npm run qa -- --offline
npm run build          # dist/ — deploy estático (Vercel, Netlify, GitHub Pages) ou abra com npm run preview

Um único arquivo HTML que funciona com duplo clique (enviar por e-mail/USB): npm run build:single → dist-single/index.html.

9 · Crítica, perguntas & entrega

• Faça uma autocrítica de todo o deck conforme references/ai-critique.md (linha argumentativa, dados, transições entre apresentadores); se o usuário tiver uma revisão de outra IA → critique cada ponto, abra a fonte antes de aceitar.
• Prepare docs/qa-3c.md (2–3 perguntas 3C por apresentador) e docs/quiz.md se houver quiz (references/qa-defense.md).
• Atualize docs/ai-appendix.md, docs/verification.md, docs/HISTORY.md (references/ai-disclosure.md, references/workflow.md).
• Avise o usuário: link/comando para executar, teclas de apresentação (references/presenter.md — clique/→/Espaço = próxima batida, Shift+clique ou clique direito = voltar, scroll, S notas, P janela do apresentador, K fonte, D claro/escuro, O visão geral, F tela cheia), o que ainda está sob suposição (dados ilustrativos, imagem a substituir), links que o apresentador deve reabrir, e imagens QA de alguns slides representativos. Checklist de entrega: references/submission-checklist.md.

Tabela de decisão rápida

Usuário quer	Usar
Slides acadêmicos, sérios	tema ivory/obsidian, família editorial-2d ou data-3d, motion calm
Aula em sala de aula	whiteboard/chalkboard, família illustrated, diagram + plot
Turismo, geografia	sketchbook/ivory, globe rota + foto real + parallax 1 vez
História, arte, literatura	ivory, gallery (obra real), timeline, efeitos sepia suave
Tecnologia, programação	blueprint/neon, code, network, flow, diagram
Negócios, pitch	neon/obsidian, towers, chart, metric, lottie 1 vez
Landing page com rolagem	deck.mode: 'scroll' (Lenis) — mesmo conteúdo, rolagem suave
Cena 3D pré-construída no spline.design	cena spline (URL .splinecode)
Câmera voando conforme roteiro	slide.camera.sequence + Theatre.js studio (?studio)
Técnico, energia, aula com muitos dados	drafting · section + waffle/gauge/dimension/simulation + annotations
Enviar arquivo por e-mail/USB, máquina sem internet	npm run build:single

Documentos de referência (ler quando necessário, não precisa ler tudo)

Arquivo	Quando ler
references/brief-intake.md	Passo 0 — conjunto de perguntas + sugestões padrão
references/effects-catalog.md	Usuário pergunta "quais efeitos existem?", precisa escolher cena/efeito (com pré-visualizações)
references/design-rules.md	Toda vez que for projetar — uma ideia uma imagem, densidade de texto, cor semântica, anti-pattern
references/content-schema.md	Escrever slides.ts — todos os campos de Slide/Block/Scene/Brief
references/content-mapping.md	Converter markdown → slide, exemplos para vários temas
references/layouts-blocks.md	8 layouts, 23 blocos, anotações manuscritas, conectores, capacidade
references/scenes-3d.md	15 cenas 3D: aparência, dados, exemplos de purpose
references/topics.md	Playbook por tema (tema, cena, asset, armadilhas)
references/assets.md	Encontrar imagens, imagens do usuário, SVG, IA, YouTube, Lottie, GLB, Spline, crédito, offline
references/libraries.md	Bibliotecas integradas e quando usar outras (Reveal, Impress, Motion…)
references/themes.md	8 temas, personalização de cor/fonte, transição de cena, tecla D claro/escuro, pós-processamento
references/motion.md	Ritmo, transição de cena, Theatre.js, reduced-motion
references/presenter.md	Teclas, clique, scroll, controle, visão do apresentador, notas, roteiro, citações
references/validation-qa.md	Comandos de verificação + checklist de entrega
references/inspiration.md	Sites de referência (Awwwards, Codrops, GSAP, Three.js…) e o que aprender de cada fonte
references/ai-critique.md	Postura crítica, ficha de crítica, verificação de entendimento, revisão cruzada de IA, prompts de exemplo
references/sources-verification.md	Níveis de fonte, regras para escolha de números, tabela de verificação docs/verification.md
references/ai-disclosure.md	Apêndice de declaração de IA docs/ai-appendix.md
references/qa-defense.md	Perguntas de crítica 3C, perguntas abertas, quiz, slide de backup
references/workflow.md	Ritmo de trabalho por sessão, rascunho A/B/C, diário & entrega para novo chat, Git/deploy, antes da apresentação
references/submission-checklist.md	Checklist de entrega, bandeiras de penalidade, legibilidade no projetor, como enviar o arquivo