atwalabs/cube-icons

Cube Icons

Cube Icons rendert kleine Pixelzeichnungen als 3D-Würfel auf einem <canvas>. Jeder farbige Pixel wird zu einem kurzen Würfelstapel. Die Engine ist assets/cubes.js (ca. 9 KB gzipped, keine Abhängigkeiten) und die Icon-Bibliothek ist assets/icons.js. Alles läuft im Browser.

Arbeitsablauf

1. Platzieren. Entscheide, was das Icon tut: Aufbauen bei Hover (Menüs, Buttons, Karten), Aufbauen beim Scrollen (Abschnitte, Hero), einmaliges Anzeigen (Leerzustände, Ladebildschirme) oder Folgen des Zeigers (Magnet). Lasse den echten Text im HTML neben dem Canvas.
2. Installieren. Kopiere assets/cubes.js und assets/icons.js in den statischen Ordner des Projekts und lade sie mit zwei <script>-Tags, zuerst icons.js. Oder lade sie vom CDN: https://cdn.jsdelivr.net/gh/atwalabs/[email protected]/icons.js und .../cubes.js. In Frameworks lade sie nur im Browser (siehe references/recipes.md, „Frameworks“).
3. Icon auswählen oder zeichnen. Verwende einen eingebauten Namen, wenn einer passt (Liste unten). Andernfalls zeichne eines als Zeilen von Palettenschlüsseln, gemäß „Ein Icon zeichnen“ weiter unten.
4. Code schreiben. Erstelle eine Stage auf einem Canvas mit Größe, rufe dann show, scroll, build, sequence oder explode auf. Beginne mit dem passenden Rezept in references/recipes.md.
5. Abschließen. Gib dem Canvas eine CSS-Breite und -Höhe, füge role="img" und ein aria-label hinzu (oder aria-hidden="true" bei dekorativen Icons), führe Hover-Effekte auch bei Tastaturfokus aus und rufe stage.destroy() auf, wenn eine Komponente ausgehängt wird.

Das Minimum

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

Eingebaute Icons

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.

Ein Icon zeichnen

Ein Icon ist ein Array aus gleich langen Strings, die von oben nach unten wie ein Bild gelesen werden. Jedes Zeichen ist ein Palettenschlüssel; . steht für leer.

Schlüssel	Farbe	Schlüssel	Farbe
B	Kobaltblau	G	Grün
W	Papierweiß	P	Flieder
K	Grau	C	Cyan
L	Hellgrau	M	Pink
D	Fast Schwarz	N	Braun
R	Rot	O	Orange
Y	Gelb

Regeln für gut lesbare Icons:

• 8–16 Spalten breit, 6–14 Zeilen hoch. Jede Zeile gleich lang. Größer verliert den klobigen Look; eine Stage fasst standardmäßig 900 Würfel (Zellen × Tiefe).
• Zuerst Silhouette. Mache die Umrisse in einer Farbe erkennbar, bevor du Details hinzufügst; überprüfe sie auf einen Blick, indem du die Zeilen liest.
• Umriss und Füllung: Ein dunklerer oder kontrastierender Umriss (K, D) um eine Füllfarbe, dann ein akzentuiertes Detail (eine goldene Klammer, eine rote Flagge, ein blaues Fenster).
• Symmetrie für Objekte, die symmetrisch sind (Pokale, Glocken, Gesichter): Spiegle jede Zeile.
• Vermeide einzelne isolierte Zellen außer für bewusste Details wie Augen oder Glitzer.
• Um es namentlich zu platzieren, füge es zur Bibliothek hinzu: Object.assign(window.CUBE_ICONS, { badge: [...] }). Oder übergib die Zeilen direkt an stage.show(rows).
• Eigene Farben: Ein Icon kann zusätzliche Palettenschlüssel als { colors: { a: "#eb234f", b: "#79a93e" }, rows: ["..aa..", "bbbbbb"] } tragen. Verwende dafür Kleinbuchstaben. Bevorzuge die eingebaute Palette, es sei denn, die Vorgabe erfordert exakte Farben.

Beispiel (eine Kaffeetasse):

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

Für Wörter verwende CubeIcons.text("Hallo", { color: "B" }): eine 5-zeilige Pixel-Schriftart mit A–Z, 0–9 und . , : ! ? - + ' & /.

Die wichtigsten Optionen

CubeIcons.stage(canvas, {
  look: "soft",      // flat (Standard) · soft · clay · candy · paper · outline · pixel · glass · neon · wire · holo
  view: "front",     // front (Standard) · iso
  depth: 2,          // Würfeltiefe, 1–5
  gap: 0.06,         // Abstand zwischen Würfeln, 0–0.4
  tint: null,        // Eine Markenfarbe, z. B. "#2f3cff": jede Farbe wird in ihren Schattierungen neu gezeichnet
  ease: "expo",     // expo (Standard, sanfte Landung) · cubic · back · elastic · linear
  duration: 700,     // ms pro Würfelflug
  stagger: 260,      // ms zufällige Verzögerung pro Würfel
  spin: 0.25,        // Umdrehungen während des Flugs
  from: "auto",     // auto · below · above · left · right · center
  magnet: 0,         // Würfel springen nahe dem Zeiger nach vorne (versuche 1.5)
  glow: 0,           // Glühen um die Würfel, 0–1 (toll mit tint auf dunklen Seiten)
  float: 0,          // Leerlaufbewegung, 0–1: Das Icon schwebt und wippt, lose Würfel treiben
  tilt: true,        // Tiefe neigt sich mit der Maus
});

Passe den Look an die Seite an: soft, clay, candy, paper und outline passen zu hellen Seiten; glass, neon und holo passen zu dunklen; wire mit hellem tint passt zu dunklen oder farbigen Abschnitten; pixel ist flache Retro-Pixelgrafik überall. Vollständige Optionen- und API-Tabellen findest du in references/api.md.

Methoden

• stage.show(icon): Ein Icon erstellen (ein Name oder Zeilen). Ein anderes Icon anzeigen wandelt es um.
• stage.clear(): Auseinanderfliegen und ausblenden.
• stage.build(icon, progress): Teilweise aufgebaut, 0–1, unterste Reihe zuerst. Steuere es über Scrollen, Upload-Fortschritt, Timer.
• stage.explode(clientX?, clientY?): Würfel lösen sich; sie setzen sich wieder.
• stage.burst(): Die Würfel strömen auf den Betrachter zu und blenden aus (Menü- oder Seitenübergänge).
• stage.scatter(count, { icon }): Lose Würfel über das Canvas verteilen; ein späteres show() sammelt sie im Icon.
• stage.set(options), stage.destroy().
• CubeIcons.scroll(stage, icon, { mode: "scrub" | "trigger" }), CubeIcons.sequence(stage, icons, { every }), CubeIcons.still(canvas, icon, options) für statische Miniaturansichten.

Häufige Fehler

• Keine Canvas-Größe. Das Canvas benötigt eine CSS-Breite und -Höhe, sonst rendert es 0 Pixel Höhe.
• Skript-Reihenfolge. Lade icons.js vor dem Aufruf von show() mit einem Namen und cubes.js vor dem Aufruf von CubeIcons.
• Server-Rendering. Greife in Next.js, Nuxt oder SvelteKit niemals auf Modulebene auf CubeIcons zu; erstelle Stages in einem Effekt oder Mount-Hook.
• Zu viele Würfel. Ein 20×20-Icon bei Tiefe 3 ergibt 1.200 Würfel; verringere die Tiefe, zeichne kleiner oder erhöhe max.
• Nur Hover. Löse auch bei focus aus, damit Tastaturnutzer den Effekt sehen.

Referenzen

• references/recipes.md: Kopierfertiger Code für Menüs, Buttons, Leerzustände, Ladebildschirme, Morph-Sequenzen, Explodieren, Magnet, Text, Feature-Karten, Scroll-Abschnitte und jedes Framework.
• references/api.md: Jede Option, Methode und Hilfsfunktion mit Standardwerten.
• assets/cubes.js, assets/icons.js: Die Engine und die Icon-Bibliothek zum Kopieren in das Projekt.