Cube Icons
Cube Icons는 <canvas> 위에 작은 픽셀 그림을 3D 큐브로 렌더링합니다. 각 색깔 픽셀은 짧은 큐브 더미가 됩니다. 엔진은 assets/cubes.js(약 9KB gzip, 의존성 없음)이고 아이콘 라이브러리는 assets/icons.js입니다. 모든 것이 브라우저에서 실행됩니다.
워크플로우
- 배치하기. 아이콘이 무엇을 할지 결정합니다: 호버 시 조립(메뉴, 버튼, 카드), 스크롤 시 조립(섹션, 히어로), 한 번만 표시(빈 상태, 로더), 또는 포인터 따라가기(자석). 실제 텍스트는 캔버스 옆에 HTML로 유지합니다.
- 설치.
assets/cubes.js와assets/icons.js를 프로젝트의 정적 폴더에 복사하고 두 개의<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 width와 height를 지정하고,
role="img"와aria-label(또는 장식용이면aria-hidden="true")을 추가하고, 호버 효과를 키보드 포커스에서도 동작하게 하고, 컴포넌트가 언마운트될 때stage.destroy()를 호출합니다.
최소 코드
<canvas id="hero-icon" style="width:360px;height:280px" role="img" aria-label="로켓"></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개의 큐브(셀 × 깊이)를 보유합니다.
- 먼저 실루엣. 세부 사항을 추가하기 전에 한 가지 색상으로 윤곽을 알아볼 수 있게 만듭니다. 행을 읽어 한눈에 확인합니다.
- 윤곽선과 채우기: 채우기 색상 주위에 더 어둡거나 대비되는 윤곽선(
K,D)을 넣고, 하나의 악센트 세부 사항(금색 걸쇠, 빨간 깃발, 파란 창문)을 추가합니다. - 대칭 대칭인 물체(트로피, 종, 얼굴)는 각 행을 대칭으로 만듭니다.
- 눈이나 반짝임 같은 의도적인 세부 사항을 제외하고는 단일 고립 셀을 피합니다.
- 이름으로 배치하려면 라이브러리에 추가합니다:
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, // 큐브 비행 시간(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, // 깊이가 마우스와 함께 기울어짐
});
페이지에 맞는 look을 선택하세요: 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 width와 height가 필요합니다. 그렇지 않으면 높이가 0픽셀로 렌더링됩니다.
- 스크립트 순서. 이름으로
show()를 호출하기 전에icons.js를 로드하고,CubeIcons를 호출하기 전에cubes.js를 로드합니다. - 서버 렌더링. Next.js, Nuxt 또는 SvelteKit의 모듈 최상위 레벨에서
CubeIcons를 절대 사용하지 마세요. effect 또는 mount 훅 안에서 스테이지를 생성하세요. - 너무 많은 큐브. 깊이 3의 20×20 아이콘은 1,200개의 큐브입니다. 깊이를 낮추거나, 더 작게 그리거나,
max를 높이세요. - 호버만.
focus에서도 트리거하여 키보드 사용자가 효과를 볼 수 있도록 하세요.
참고 자료
references/recipes.md: 메뉴, 버튼, 빈 상태, 로더, 변형 시퀀스, 폭발, 자석, 텍스트, 기능 카드, 스크롤 섹션 및 모든 프레임워크에 대한 바로 사용 가능한 코드.references/api.md: 모든 옵션, 메서드 및 헬퍼와 기본값.assets/cubes.js,assets/icons.js: 프로젝트에 복사할 엔진 및 아이콘 라이브러리.