sandeco D3 Image Animator
Transforma imagens em animações D3.js interativas, geradas dentro de um deck do Mira e prontas
para abrir por file:// (offline). O resultado é um HTML self-contained: imagem embutida em base64
e D3 vendorado localmente (nunca CDN em runtime, igual ao resto do Mira). Foco em fotos e
imagens reais (JPG, PNG).
Regras herdadas (obrigatórias)
- Idioma: siga
agents/_shared/idioma.md— todo texto visível revisado, acentuação 100% correta. - Offline-first: o deck do Mira nasce offline. Vendore o D3 em
<deck>/assets/vendor/e aponte por caminho relativo. Nada de CDN em runtime (quebra atrás de firewall e porfile://). - Nunca destrua o original: a imagem-fonte é copiada para
assets/, nunca movida nem editada.
Fluxo de Trabalho
1. Receber a Imagem
Origem possível:
- Caminho passado pelo usuário → copie a imagem para
decks/<deck>/assets/. - Imagem já no deck → use a que estiver em
decks/<deck>/assets/. - URL da web → baixe para
decks/<deck>/assets/(curl -sL <url> -o decks/<deck>/assets/<nome>). - Imagem no contexto → o Claude já a vê e pode analisar seus elementos.
Se não houver um deck alvo definido, pergunte em qual deck (decks/<deck>/) a animação deve entrar.
Formatos: JPG e PNG são primários. WebP, GIF, SVG e BMP também funcionam, mas podem precisar de
conversão via scripts/image_to_base64.py --convert-to png.
Otimização para fotos: fotos reais são grandes e densas. Redimensione para max 800px de largura
antes de processar partículas — use scripts/resize_image.py antes de scripts/extract_pixels.py.
Os scripts ficam na própria skill. Da raiz do projeto o caminho é agents/mira-img-animator/scripts/;
instalado num projeto do usuário, vira .claude/skills/mira-img-animator/scripts/.
2. Analisar a Imagem
Antes de gerar código, analise a imagem para decidir a abordagem:
- Tipo de conteúdo: foto, logo, diagrama, ilustração, ícone, gráfico, texto
- Complexidade: simples (poucas formas), média, complexa (foto detalhada)
- Cores dominantes: extrair paleta para usar na animação
- Elementos identificáveis: formas geométricas, texto, contornos, regiões
3. Escolher o Tipo de Animação
Catálogo completo de efeitos em references/ANIMATION_CATALOG.md. A escolha depende do tipo de imagem
e do efeito desejado.
Regra geral de decisão:
| Tipo de imagem | Animação recomendada |
|---|---|
| Logo/ícone simples | Partículas, morph, draw-on |
| Foto/imagem complexa | Partículas (sampled), wave, dissolve, pixelate |
| Diagrama/fluxograma | Force-directed, draw-on, highlight |
| Texto/tipografia | Partículas de texto, scramble, typewriter |
| Gráfico/chart | Transições de dados, staggered bars |
Se o usuário não especificou o tipo, pergunte mostrando 2-3 opções que fazem sentido para a imagem, com breve descrição visual de cada.
4. Gerar o Código
Padrões D3.js testados em references/D3_PATTERNS.md.
Regras fundamentais do código gerado:
- HTML self-contained — arquivo
.htmlcom CSS e JS embutidos; imagem em base64. - D3.js v7 vendorado — referencie
assets/vendor/d3.v7.min.jspor caminho relativo, nunca CDN. Vendore uma vez por deck (se ainda não existir):curl -sL https://d3js.org/d3.v7.min.js -o decks/<deck>/assets/vendor/d3.v7.min.js. É a mesma cópia que o/mira-offlinereliga nos decks. - Canvas para performance — use Canvas (não SVG) com mais de 5.000 elementos.
- SVG para interatividade — use SVG para hover/click em elementos individuais.
- Imagem como base64 — converter e embutir no HTML para não depender de arquivo externo.
- Responsivo — a animação se adapta ao tamanho da tela.
- Controles — botões play/pause/reset quando relevante.
- Performance —
requestAnimationFramepara loops, limitar partículas a ~50.000.
Converter imagem em base64:
python agents/mira-img-animator/scripts/image_to_base64.py <caminho_da_imagem>
Extrair paleta de cores dominantes:
python agents/mira-img-animator/scripts/extract_palette.py <caminho_da_imagem> --colors 6
Extrair dados de pixels (posição + cor) para partículas:
python agents/mira-img-animator/scripts/extract_pixels.py <caminho_da_imagem> --sample-rate 4 --min-alpha 128
(Instalado, troque agents/mira-img-animator/scripts/ por .claude/skills/mira-img-animator/scripts/.)
5. Estrutura do HTML Gerado
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>[Nome da Animação]</title>
<script src="assets/vendor/d3.v7.min.js"></script>
<style>
/* Reset + estilos da animação */
/* Controles de UI quando aplicável */
</style>
</head>
<body>
<div id="container"></div>
<script>
// 1. Configuração (dimensões, dados da imagem)
// 2. Setup do Canvas ou SVG
// 3. Extração/processamento de pixels
// 4. Lógica da animação
// 5. Controles e interatividade
// 6. Função de resize responsiva
</script>
</body>
</html>
6. Salvar e Entregar
Salve o HTML dentro do deck, em decks/<deck>/ (ex.: decks/<deck>/animacao-<nome>.html), com
o D3 vendorado em decks/<deck>/assets/vendor/ e a imagem-fonte copiada para decks/<deck>/assets/.
Ao terminar, reporte o caminho do arquivo e lembre que ele abre por duplo clique (file://), sem
internet.
Nota: se o usuário pedir React (.jsx), consulte references/REACT_PATTERNS.md; o padrão do Mira
é o HTML self-contained acima.
Diretrizes de Qualidade
- Estética: cores coesas com o tema do deck (use as CSS variables do deck quando existirem), tipografia elegante, backgrounds atmosféricos.
- Animação fluida: mínimo 30fps, idealmente 60fps; testar com imagens grandes.
- Interatividade significativa: hover, click, drag devem fazer algo visualmente satisfatório.
- Código limpo: comentários em português, variáveis com nomes descritivos.
- Fallback gracioso: se a imagem não carregar, mostrar mensagem amigável.
Tratamento de Erros
Cenários de erro e tratamento em references/ERRORS.md.