atwalabs/cube-icons

Cube Icons

Cube Icons renderiza pequeños dibujos de píxeles como cubos 3D en un <canvas>. Cada píxel coloreado se convierte en una pila corta de cubos. El motor es assets/cubes.js (aproximadamente 9 KB comprimido, sin dependencias) y la biblioteca de iconos es assets/icons.js. Todo se ejecuta en el navegador.

Flujo de trabajo

1. Ubícalo. Decide qué hace el icono: se construye al pasar el ratón (menús, botones, tarjetas), se construye al hacer scroll (secciones, héroes), se muestra una vez (estados vacíos, cargadores), o sigue al puntero (imán). Mantén el texto real en HTML junto al canvas.
2. Instálalo. Copia assets/cubes.js y assets/icons.js en la carpeta estática del proyecto y cárgalos con dos etiquetas <script>, primero icons.js. O cárgalos desde el CDN: https://cdn.jsdelivr.net/gh/atwalabs/[email protected]/icons.js y .../cubes.js. En frameworks, cárgalos solo en el navegador (ver references/recipes.md, "Frameworks").
3. Elige o dibuja el icono. Usa un nombre incorporado si hay uno que encaje (lista abajo). De lo contrario, dibuja uno como filas de claves de paleta, siguiendo "Dibujando un icono" más abajo.
4. Escribe el código. Crea un escenario en un canvas con tamaño, luego llama a show, scroll, build, sequence o explode. Empieza con la receta correspondiente en references/recipes.md.
5. Finaliza. Dale al canvas un ancho y alto CSS, añade role="img" y un aria-label (o aria-hidden="true" si es decorativo), ejecuta los efectos de hover también en el foco del teclado, y llama a stage.destroy() cuando un componente se desmonte.

El mínimo

<canvas id="hero-icon" style="width:360px;height:280px" role="img" aria-label="Un cohete"></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>

Iconos incorporados

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.

Dibujando un icono

Un icono es un arreglo de cadenas de igual longitud, leídas de arriba a abajo como una imagen. Cada carácter es una clave de paleta; . está vacío.

Clave	Color	Clave	Color
B	azul cobalto	G	verde
W	blanco papel	P	lila
K	gris	C	cian
L	gris claro	M	rosa
D	casi negro	N	marrón
R	rojo	O	naranja
Y	amarillo

Reglas que hacen que los iconos se vean bien:

• De 8 a 16 columnas de ancho, de 6 a 14 filas de alto. Cada fila de la misma longitud. Un tamaño mayor pierde el aspecto macizo; un escenario admite 900 cubos (celdas × profundidad) por defecto.
• Silueta primero. Haz que el contorno sea reconocible con un solo color antes de añadir detalles; compruébalo de un vistazo leyendo las filas.
• Contorno y relleno: un contorno más oscuro o contrastante (K, D) alrededor de un color de relleno, luego un detalle de acento (un cierre dorado, una bandera roja, una ventana azul).
• Simetría para objetos simétricos (trofeos, campanas, caras): refleja cada fila.
• Evita celdas aisladas individuales excepto para detalles deliberados como ojos o destellos.
• Para colocarlo por nombre, añádelo a la biblioteca: Object.assign(window.CUBE_ICONS, { badge: [...] }). O pasa las filas directamente a stage.show(rows).
• Colores propios: un icono puede llevar claves de paleta adicionales como { colors: { a: "#eb234f", b: "#79a93e" }, rows: ["..aa..", "bbbbbb"] }. Usa letras minúsculas para ellos. Prefiere la paleta incorporada a menos que el encargo necesite colores exactos.

Ejemplo (una taza de café):

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

Para palabras, usa CubeIcons.text("Hola", { color: "B" }): una fuente de píxeles de 5 filas con A–Z, 0–9 y . , : ! ? - + ' & /.

Las opciones más importantes

CubeIcons.stage(canvas, {
  look: "soft",      // flat (predeterminado) · soft · clay · candy · paper · outline · pixel · glass · neon · wire · holo
  view: "front",     // front (predeterminado) · iso
  depth: 2,          // profundidad de cubos, 1–5
  gap: 0.06,         // espacio entre cubos, 0–0.4
  tint: null,        // un tono de marca, ej. "#2f3cff": cada color redibujado en sus matices
  ease: "expo",      // expo (predeterminado, aterrizaje suave) · cubic · back · elastic · linear
  duration: 700,     // ms por vuelo de cubo
  stagger: 260,      // ms de retardo aleatorio por cubo
  spin: 0.25,        // giros mientras vuela
  from: "auto",      // auto · below · above · left · right · center
  magnet: 0,         // los cubos cerca del puntero sobresalen (prueba con 1.5)
  glow: 0,           // resplandor alrededor de los cubos, 0–1 (genial con tint en páginas oscuras)
  float: 0,          // movimiento en reposo, 0–1: el icono se balancea y flota, los cubos sueltos derivan
  tilt: true,        // la profundidad se inclina con el ratón
});

Combina el estilo con la página: soft, clay, candy, paper y outline son adecuados para páginas claras; glass, neon y holo para páginas oscuras; wire con un tint claro sirve para secciones oscuras o coloreadas; pixel es arte pixelado retro plano en cualquier lugar. Las tablas completas de opciones y API están en references/api.md.

Métodos

• stage.show(icon): construye un icono (un nombre o filas). Mostrar un icono diferente hace una transición morph.
• stage.clear(): vuela y se desvanece.
• stage.build(icon, progress): parcialmente construido, 0–1, primera fila desde abajo. Condúcelo desde scroll, progreso de carga, temporizadores.
• stage.explode(clientX?, clientY?): suelta los cubos; se recolocan.
• stage.burst(): los cubos se lanzan hacia el espectador y se desvanecen (transiciones de menú o página).
• stage.scatter(count, { icon }): cubos sueltos por todo el canvas; un posterior show() los reúne en el icono.
• 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.

Errores comunes

• Sin tamaño de canvas. El canvas necesita un ancho y alto CSS, o se renderiza con 0 píxeles de altura.
• Orden de scripts. Carga icons.js antes de llamar a show() con un nombre, y cubes.js antes de llamar a CubeIcons.
• Renderizado del lado del servidor. Nunca toques CubeIcons al nivel superior del módulo en Next.js, Nuxt o SvelteKit; crea escenarios en un efecto o hook de montaje.
• Demasiados cubos. Un icono de 20×20 con profundidad 3 son 1.200 cubos; reduce la profundidad, dibuja más pequeño o aumenta max.
• Solo hover. Actívalo también con focus para que los usuarios de teclado vean el efecto.

Referencias

• references/recipes.md: código listo para copiar para menús, botones, estados vacíos, cargadores, secuencias morph, explosión, imán, texto, tarjetas de características, secciones de scroll y cada framework.
• references/api.md: cada opción, método y ayuda, con valores predeterminados.
• assets/cubes.js, assets/icons.js: el motor y la biblioteca de iconos para copiar en el proyecto.