atwalabs/cube-icons

Cube Icons

Cube Icons restitue de petits dessins pixel sous forme de cubes 3D sur un <canvas>. Chaque pixel coloré devient une courte pile de cubes. Le moteur est assets/cubes.js (environ 9 Ko compressé, sans dépendance) et la bibliothèque d'icônes est assets/icons.js. Tout s'exécute dans le navigateur.

Workflow

1. Placez-le. Décidez ce que fait l'icône : construction au survol (menus, boutons, cartes), construction au défilement (sections, héros), affichage unique (états vides, chargeurs), ou suivi du curseur (aimant). Gardez le vrai texte en HTML à côté du canvas.
2. Installez. Copiez assets/cubes.js et assets/icons.js dans le dossier statique du projet et chargez-les avec deux balises <script>, d'abord icons.js. Ou chargez-les depuis le CDN : https://cdn.jsdelivr.net/gh/atwalabs/[email protected]/icons.js et .../cubes.js. Dans les frameworks, chargez-les uniquement côté navigateur (voir references/recipes.md, « Frameworks »).
3. Choisissez ou dessinez l'icône. Utilisez un nom intégré quand il convient (liste ci-dessous). Sinon, dessinez-en une sous forme de lignes de clés de palette, selon « Dessiner une icône » ci-dessous.
4. Écrivez le code. Créez une scène sur un canvas dimensionné, puis appelez show, scroll, build, sequence ou explode. Commencez par la recette correspondante dans references/recipes.md.
5. Finalisez. Donnez au canvas une largeur et une hauteur CSS, ajoutez role="img" et un aria-label (ou aria-hidden="true" si décoratif), déclenchez les effets de survol aussi au focus clavier, et appelez stage.destroy() lors du démontage d'un composant.

Le minimum

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

Icônes intégrées

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.

Dessiner une icône

Une icône est un tableau de chaînes de même longueur, lues de haut en bas comme une image. Chaque caractère est une clé de palette ; . est vide.

Clé	Couleur	Clé	Couleur
B	bleu cobalt	G	vert
W	blanc papier	P	lilas
K	gris	C	cyan
L	gris clair	M	rose
D	presque noir	N	marron
R	rouge	O	orange
Y	jaune

Règles pour des icônes lisibles :

• 8 à 16 colonnes de large, 6 à 14 lignes de haut. Chaque ligne de même longueur. Au-delà, on perd l'aspect compact ; une scène contient 900 cubes (cellules × profondeur) par défaut.
• Silhouette d'abord. Réalisez d'abord le contour reconnaissable avec une seule couleur avant d'ajouter les détails ; vérifiez d'un coup d'œil en lisant les lignes.
• Contour et remplissage : un contour plus foncé ou contrasté (K, D) autour d'une couleur de remplissage, puis un détail d'accent (une fermeture dorée, un drapeau rouge, une fenêtre bleue).
• Symétrie pour les objets symétriques (trophées, cloches, visages) : miroir de chaque ligne.
• Évitez les cellules isolées sauf pour des détails intentionnels comme les yeux ou les étincelles.
• Pour la placer par nom, ajoutez-la à la bibliothèque : Object.assign(window.CUBE_ICONS, { badge: [...] }). Ou transmettez les lignes directement à stage.show(rows).
• Couleurs personnalisées : une icône peut porter des clés de palette supplémentaires sous la forme { colors: { a: "#eb234f", b: "#79a93e" }, rows: ["..aa..", "bbbbbb"] }. Utilisez des lettres minuscules pour elles. Privilégiez la palette intégrée sauf si le cahier des charges exige des couleurs exactes.

Exemple (une tasse de café) :

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

Pour les mots, utilisez CubeIcons.text("Bonjour", { color: "B" }) : une police pixel de 5 lignes avec A–Z, 0–9 et . , : ! ? - + ' & /.

Les options les plus importantes

CubeIcons.stage(canvas, {
  look: "soft",      // flat (défaut) · soft · clay · candy · paper · outline · pixel · glass · neon · wire · holo
  view: "front",     // front (défaut) · iso
  depth: 2,          // profondeur des cubes, 1–5
  gap: 0.06,         // espace entre les cubes, 0–0.4
  tint: null,        // une teinte de marque, ex. "#2f3cff" : chaque couleur redessinée dans ses nuances
  ease: "expo",      // expo (défaut, atterrissage en douceur) · cubic · back · elastic · linear
  duration: 700,     // ms par vol de cube
  stagger: 260,      // ms de délai aléatoire par cube
  spin: 0.25,        // tours pendant le vol
  from: "auto",      // auto · below · above · left · right · center
  magnet: 0,         // cubes près du curseur avancent (essayez 1.5)
  glow: 0,           // lueur autour des cubes, 0–1 (excellent avec tint sur pages sombres)
  float: 0,          // mouvement au repos, 0–1 : l'icône se balance et oscille, les cubes libres dérivent
  tilt: true,        // l'inclinaison suit la souris
});

Associez l'apparence à la page : soft, clay, candy, paper et outline conviennent aux pages claires ; glass, neon et holo conviennent aux pages sombres ; wire avec une tint claire convient aux sections sombres ou colorées ; pixel est un pixel art rétro plat partout. Le tableau complet des options et de l'API se trouve dans references/api.md.

Méthodes

• stage.show(icon) : construit une icône (un nom ou des lignes). Afficher une icône différente effectue un morphing vers celle-ci.
• stage.clear() : les cubes s'éparpillent et disparaissent.
• stage.build(icon, progress) : construction partielle, 0–1, première ligne en bas. Pilotez-la avec le défilement, la progression d'upload, des minuteurs.
• stage.explode(clientX?, clientY?) : fait voler les cubes en éclats ; ils se remettent en place.
• stage.burst() : les cubes se précipitent vers le spectateur et disparaissent (transitions de menu ou de page).
• stage.scatter(count, { icon }) : cubes libres éparpillés sur le canvas ; un show() ultérieur les rassemble en l'icône.
• stage.set(options), stage.destroy().
• CubeIcons.scroll(stage, icon, { mode: "scrub" | "trigger" }), CubeIcons.sequence(stage, icons, { every }), CubeIcons.still(canvas, icon, options) pour les miniatures statiques.

Erreurs courantes

• Pas de taille de canvas. Le canvas a besoin d'une largeur et d'une hauteur CSS, sinon il fait 0 pixel de haut.
• Ordre des scripts. Chargez icons.js avant d'appeler show() avec un nom, et cubes.js avant d'appeler CubeIcons.
• Rendu serveur. Ne touchez jamais à CubeIcons au niveau racine d'un module dans Next.js, Nuxt ou SvelteKit ; créez les scènes dans un effet ou un hook de montage.
• Trop de cubes. Une icône 20×20 avec une profondeur de 3 donne 1 200 cubes ; réduisez la profondeur, dessinez plus petit, ou augmentez max.
• Survol uniquement. Déclenchez aussi l'effet au focus pour que les utilisateurs de clavier voient l'effet.

Références

• references/recipes.md : code prêt à copier pour menus, boutons, états vides, chargeurs, séquences de morphing, explosion, aimant, texte, fiches de fonctionnalités, sections défilantes et chaque framework.
• references/api.md : toutes les options, méthodes et utilitaires, avec leurs valeurs par défaut.
• assets/cubes.js, assets/icons.js : le moteur et la bibliothèque d'icônes à copier dans le projet.