Cube Icons
Cube Iconsは、小さなピクセル描画を3Dキューブとして<canvas>上にレンダリングします。色のついた各ピクセルは、短いキューブの積み重ねになります。エンジンはassets/cubes.js（約9KB、gzip圧縮時、依存関係なし）、アイコンライブラリはassets/icons.jsです。すべてブラウザ上で動作します。
ワークフロー
- 配置する。 アイコンの動作を決めます：ホバーで構築（メニュー、ボタン、カード）、スクロールで構築（セクション、ヒーロー）、一度だけ表示（空の状態、ローダー）、またはポインターに追従（マグネット）。実際のテキストはキャンバスの隣にHTMLで保持します。
- インストールする。
assets/cubes.jsとassets/icons.jsをプロジェクトの静的フォルダにコピーし、2つの<script>タグで読み込みます。icons.jsを先に読み込んでください。またはCDNから読み込むこともできます：https://cdn.jsdelivr.net/gh/atwalabs/[email protected]/icons.jsと.../cubes.js。フレームワークでは、ブラウザ上でのみ読み込んでください（references/recipes.mdの「Frameworks」を参照）。 - アイコンを選ぶか描く。 適切な組み込みアイコンがある場合はその名前を使用します（下記リスト）。それ以外の場合は、以下の「アイコンを描く」に従って、パレットキーの行として描画します。
- コードを書く。 サイズ指定されたキャンバス上にステージを作成し、
show、scroll、build、sequence、explodeのいずれかを呼び出します。references/recipes.mdの該当するレシピから始めてください。 - 仕上げる。 キャンバスにCSSの幅と高さを設定し、
role="img"とaria-label（装飾的な場合はaria-hidden="true"）を追加し、ホバーエフェクトはキーボードフォーカス時にも動作させ、コンポーネントがアンマウントされたらstage.destroy()を呼び出します。
最小構成
<canvas id="hero-icon" style="width:360px;height:280px" role="img" aria-label="A rocket"></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>
組み込みアイコン
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.
アイコンを描く
アイコンは等しい長さの文字列の配列で、画像のように上から下に読みます。各文字はパレットキーであり、.は空を表します。
| キー | 色 | キー | 色 |
|---|---|---|---|
B | コバルトブルー | G | グリーン |
W | ペーパーホワイト | P | ライラック |
K | グレー | C | シアン |
L | ライトグレー | M | ピンク |
D | ニアブラック | N | ブラウン |
R | レッド | O | オレンジ |
Y | イエロー |
アイコンを読みやすくするルール：
- 幅8～16列、高さ6～14行。 各行は同じ長さ。大きくすると塊感が失われます。ステージはデフォルトで900キューブ（セル数×奥行き）を保持します。
- まずシルエット。 1色で輪郭が認識できるようにしてから詳細を追加。行をざっと読んで確認します。
- 輪郭と塗りつぶし： 塗りつぶし色の周りに暗いまたは対照的な輪郭（
K、D）、次に1つのアクセント詳細（金色の留め金、赤い旗、青い窓）。 - 対称性： 対称なオブジェクト（トロフィー、ベル、顔）では、各行を鏡像にします。
- 孤立したセルは避ける： 目やキラキラなど意図的な詳細を除いて、孤立したセルは避けます。
- 名前で配置するには、ライブラリに追加します：
Object.assign(window.CUBE_ICONS, { badge: [...] })。または、行を直接stage.show(rows)に渡します。 - 独自の色： アイコンは追加のパレットキーを
{ colors: { a: "#eb234f", b: "#79a93e" }, rows: ["..aa..", "bbbbbb"] }として持つことができます。それらには小文字を使用します。要件に正確な色が必要でない限り、組み込みパレットを優先します。
例（コーヒーカップ）：
coffee: [
"..W..W.....",
"...W..W....",
"...........",
"KKKKKKKKK..",
"KWWWWWWWKKK",
"KWWWWWWWK.K",
"KWWWWWWWKKK",
"KWWWWWWWK..",
".KKKKKKK...",
],
文字列の場合は、CubeIcons.text("Hello", { color: "B" })を使用します：A～Z、0～9、そして. , : ! ? - + ' & /を含む5行のピクセルフォントです。
最も重要なオプション
CubeIcons.stage(canvas, {
look: "soft", // flat（デフォルト） · soft · clay · candy · paper · outline · pixel · glass · neon · wire · holo
view: "front", // front（デフォルト） · iso
depth: 2, // キューブの奥行き、1～5
gap: 0.06, // キューブ間のスペース、0～0.4
tint: null, // 単一ブランドインク、例: "#2f3cff": すべての色をその色合いで再描画
ease: "expo", // expo（デフォルト、ソフトランディング） · cubic · back · elastic · linear
duration: 700, // キューブ1つあたりの飛行時間（ms）
stagger: 260, // キューブごとのランダム遅延（ms）
spin: 0.25, // 飛行中の回転数
from: "auto", // auto · below · above · left · right · center
magnet: 0, // ポインター付近のキューブが手前に飛び出す（1.5を試す）
glow: 0, // キューブ周りのぼかし、0～1（暗いページでtintと相性が良い）
float: 0, // アイドル時の動き、0～1：アイコンが揺れたり浮いたり、ゆるんだキューブが漂う
tilt: true, // マウスに合わせて奥行きが傾く
});
ルックをページに合わせる：soft、clay、candy、paper、outlineは明るいページに適しています。glass、neon、holoは暗いページに適しています。wireを明るいtintと組み合わせると、暗いまたは色付きのセクションに適しています。pixelはどこでもフラットなレトロピクセルアートです。完全なオプションとAPIテーブルはreferences/api.mdにあります。
メソッド
stage.show(icon)：アイコンを構築します（名前または行）。別のアイコンを表示すると、モーフィングして変化します。stage.clear()：飛び散ってフェードアウトします。stage.build(icon, progress)：部分的に構築、0～1、下の行から順に。スクロール、アップロード進捗、タイマーから駆動します。stage.explode(clientX?, clientY?)：キューブをバラバラにし、元に戻ります。stage.burst()：キューブがビューアに向かって急接近しフェードアウトします（メニューやページ遷移）。stage.scatter(count, { icon })：キャンバス上にキューブを散らばらせます。後でshow()を呼ぶとアイコンに集まります。stage.set(options)、stage.destroy()。CubeIcons.scroll(stage, icon, { mode: "scrub" | "trigger" })、CubeIcons.sequence(stage, icons, { every })、CubeIcons.still(canvas, icon, options)（静的サムネイル用）。
よくある間違い
- キャンバスサイズ未設定。 キャンバスにはCSSの幅と高さが必要です。設定しないと高さ0ピクセルでレンダリングされます。
- スクリプトの順序。 名前付きアイコンで
show()を呼び出す前にicons.jsを、CubeIconsを呼び出す前にcubes.jsを読み込んでください。 - サーバーサイドレンダリング。 Next.js、Nuxt、SvelteKitではモジュールのトップレベルで
CubeIconsにアクセスしないでください。エフェクトまたはマウントフック内でステージを作成してください。 - キューブが多すぎる。 奥行き3の20×20アイコンは1,200キューブになります。奥行きを下げるか、小さく描画するか、
maxを上げてください。 - ホバーだけ。
focusでもトリガーして、キーボードユーザーもエフェクトを見られるようにしてください。
リファレンス
references/recipes.md：メニュー、ボタン、空の状態、ローダー、モーフシーケンス、爆発、マグネット、テキスト、フィーチャーカード、スクロールセクション、すべてのフレームワーク用のコピー可能なコード。references/api.md：すべてのオプション、メソッド、ヘルパー（デフォルト値付き）。assets/cubes.js、assets/icons.js：プロジェクトにコピーするエンジンとアイコンライブラリ。