atwalabs/cube-icons

Cube Icons

O Cube Icons renderiza pequenos desenhos pixel como cubos 3D em um <canvas>. Cada pixel colorido se torna uma pequena pilha de cubos. O mecanismo é assets/cubes.js (cerca de 9 KB compactado, sem dependências) e a biblioteca de ícones é assets/icons.js. Tudo roda no navegador.

Fluxo de trabalho

1. Posicione. Decida o que o ícone faz: constrói ao passar o mouse (menus, botões, cards), constrói ao rolar a página (seções, heróis), aparece uma vez (estados vazios, carregadores) ou segue o ponteiro (ímã). Mantenha o texto real em HTML próximo ao canvas.
2. Instale. Copie assets/cubes.js e assets/icons.js para a pasta estática do projeto e carregue-os com duas tags <script>, icons.js primeiro. Ou carregue-os do CDN: https://cdn.jsdelivr.net/gh/atwalabs/[email protected]/icons.js e .../cubes.js. Em frameworks, carregue-os apenas no navegador (veja references/recipes.md, "Frameworks").
3. Escolha ou desenhe o ícone. Use um nome embutido quando um se encaixar (lista abaixo). Caso contrário, desenhe um como linhas de chaves de paleta, seguindo "Desenhando um ícone" abaixo.
4. Escreva o código. Crie um palco em um canvas com tamanho definido e então chame show, scroll, build, sequence ou explode. Comece pela receita correspondente em references/recipes.md.
5. Finalize. Dê ao canvas uma largura e altura CSS, adicione role="img" e um aria-label (ou aria-hidden="true" se for decorativo), execute efeitos de hover também no foco do teclado e chame stage.destroy() quando um componente for desmontado.

O mínimo

<canvas id="hero-icon" style="width:360px;height:280px" role="img" aria-label="Um foguete"></canvas>
<script src="icons.js"></script>
<script src="cubes.js"></script>
<script>
  const stage = CubeIcons.stage(document.getElementById("hero-icon"), { look: "soft" });
  stage.show("rocket");
</script>

Ícones embutidos

close, bolt, sword, briefcase, person, phone, browser, envelope, chart, terminal, heart, star, rocket, bulb, camera, gamepad, music, globe, lock, folder, coffee, chat, clock, check, search, download, cursor, home, bell, gear, calendar, pin, wifi, battery, play, arrow, trash, pencil, code, key, bag, cart, gift, trophy, diamond, crown, book, headphones, umbrella, flag, sun, moon, cloud, tree, leaf, fire, planet, sparkle, smile, ghost, robot.

Desenhando um ícone

Um ícone é um array de strings de igual comprimento, lido de cima para baixo como uma imagem. Cada caractere é uma chave de paleta; . é vazio.

Chave	Cor	Chave	Cor
B	azul cobalto	G	verde
W	branco papel	P	lilás
K	cinza	C	ciano
L	cinza claro	M	rosa
D	quase preto	N	marrom
R	vermelho	O	laranja
Y	amarelo

Regras que fazem os ícones lerem bem:

• 8–16 colunas de largura, 6–14 linhas de altura. Cada linha com o mesmo comprimento. Maior perde o visual encorpado; um palco comporta 900 cubos (células × profundidade) por padrão.
• Silhueta primeiro. Torne o contorno reconhecível em uma cor antes de adicionar detalhes; verifique rapidamente lendo as linhas.
• Contorno e preenchimento: um contorno mais escuro ou contrastante (K, D) ao redor de uma cor de preenchimento, depois um detalhe de destaque (um fecho dourado, uma bandeira vermelha, uma janela azul).
• Simetria para objetos simétricos (troféus, sinos, rostos): espelhe cada linha.
• Evite células isoladas únicas exceto para detalhes intencionais como olhos ou brilhos.
• Para colocá-lo por nome, adicione-o à biblioteca: Object.assign(window.CUBE_ICONS, { badge: [...] }). Ou passe as linhas diretamente para stage.show(rows).
• Cores próprias: um ícone pode carregar chaves extras de paleta como { colors: { a: "#eb234f", b: "#79a93e" }, rows: ["..aa..", "bbbbbb"] }. Use letras minúsculas para elas. Prefira a paleta embutida a menos que o briefing exija cores exatas.

Exemplo (uma xícara de café):

coffee: [
  "..W..W.....",
  "...W..W....",
  "...........",
  "KKKKKKKKK..",
  "KWWWWWWWKKK",
  "KWWWWWWWK.K",
  "KWWWWWWWKKK",
  "KWWWWWWWK..",
  ".KKKKKKK...",
],

Para palavras, use CubeIcons.text("Olá", { color: "B" }): uma fonte pixel de 5 linhas com A–Z, 0–9 e . , : ! ? - + ' & /.

Opções que mais importam

CubeIcons.stage(canvas, {
  look: "soft",      // flat (padrão) · soft · clay · candy · paper · outline · pixel · glass · neon · wire · holo
  view: "front",     // front (padrão) · iso
  depth: 2,          // profundidade dos cubos, 1–5
  gap: 0.06,         // espaço entre cubos, 0–0.4
  tint: null,        // uma cor de marca, ex. "#2f3cff": cada cor redesenhada em seus tons
  ease: "expo",      // expo (padrão, pouso suave) · cubic · back · elastic · linear
  duration: 700,     // ms por voo do cubo
  stagger: 260,      // ms de atraso aleatório por cubo
  spin: 0.25,        // voltas enquanto voa
  from: "auto",      // auto · below · above · left · right · center
  magnet: 0,         // cubos próximos ao ponteiro saltam para frente (tente 1.5)
  glow: 0,           // brilho ao redor dos cubos, 0–1 (ótimo com tint em páginas escuras)
  float: 0,          // movimento inativo, 0–1: o ícone balança e oscila, cubos soltos flutuam
  tilt: true,        // profundidade inclina com o mouse
});

Combine o visual com a página: soft, clay, candy, paper e outline combinam com páginas claras; glass, neon e holo combinam com escuras; wire com um tint claro combina com seções escuras ou coloridas; pixel é arte pixel retrô plana em qualquer lugar. Tabelas completas de opções e API estão em references/api.md.

Métodos

• stage.show(icon): constrói um ícone (um nome ou linhas). Mostrar um ícone diferente faz a transição (morph) para ele.
• stage.clear(): voa para longe e desvanece.
• stage.build(icon, progress): parcialmente construído, 0–1, primeira linha de baixo. Acione a partir de scroll, progresso de upload, temporizadores.
• stage.explode(clientX?, clientY?): solta cubos; eles se reassentam.
• stage.burst(): os cubos correm em direção ao visualizador e desvanecem (transições de menu ou página).
• stage.scatter(count, { icon }): cubos soltos pelo canvas; um show() posterior os reúne no ícone.
• stage.set(options), stage.destroy().
• CubeIcons.scroll(stage, icon, { mode: "scrub" | "trigger" }), CubeIcons.sequence(stage, icons, { every }), CubeIcons.still(canvas, icon, options) para miniaturas estáticas.

Erros comuns

• Sem tamanho de canvas. O canvas precisa de uma largura e altura CSS, ou renderiza 0 pixels de altura.
• Ordem dos scripts. Carregue icons.js antes de chamar show() com um nome, e cubes.js antes de chamar CubeIcons.
• Renderização no servidor. Nunca acesse CubeIcons no nível superior de um módulo em Next.js, Nuxt ou SvelteKit; crie palcos em um effect ou hook de montagem.
• Muitos cubos. Um ícone 20×20 na profundidade 3 são 1.200 cubos; reduza a profundidade, desenhe menor ou aumente max.
• Apenas hover. Acione também no focus para que usuários de teclado vejam o efeito.

Referências

• references/recipes.md: código pronto para copiar para menus, botões, estados vazios, carregadores, sequências morph, explosão, ímã, texto, cards de recurso, seções de scroll e todos os frameworks.
• references/api.md: todas as opções, métodos e auxiliares, com padrões.
• assets/cubes.js, assets/icons.js: o mecanismo e a biblioteca de ícones para copiar para o projeto.