CSS만으로 그리는 등각 2.5D 데이터 시각화

이렇게 만듭니다

• 2D 변환만. preserve-3d, 캔버스, 렌더 루프를 쓰지 않습니다.
• 색 하나로 세 면. 옆면 음영은 color-mix(in oklch)로 만들어, --iso-c 하나만 바꾸면 블록 전체가 바뀝니다.
• 텍스트는 DOM. 값과 이름은 일반 텍스트라 선택·복사·번역·스크린 리더가 그대로 동작합니다. 모든 값을 담은 숨김 표도 함께 만듭니다.
• 테마와 동작 줄이기. 다크 모드(prefers-color-scheme, data-theme)와 prefers-reduced-motion을 토큰 단계에서 따릅니다.
• 학생 개인정보 원칙. 교육용 컴포넌트와 템플릿의 모든 데이터는 가상 예시 데이터이며 학생은 번호로만 식별되고 외부로 전송되지 않습니다.

렌더링 방식

엘리먼트는 두 경로 중 하나로 그립니다. 고르는 것은 renderer 속성(React는 renderer prop)이고, 기본값 auto는 블록 수로 고릅니다. 기준은 측정으로 정했습니다(docs/adr/0001-render-approach.md).

두 경로에서 같은 것: iso-select 이벤트(클릭·Enter·Space), 키보드 탭 순서와 포커스 유지, 블록의 role·aria-label, 숨김 접근성 표, 색 검사와 빈·오류 상태, 다크 테마·팔레트 토큰, 호버·포커스 들림과 동작 줄이기.

알려진 한계 (v0.1)

• 값이 바뀔 때의 높이 애니메이션은 두 경로 모두 프레임 예산(표시 프레임 드롭 ≤ 5%)을 지키지 못합니다. 개선은 v0.2로 미뤘습니다.
• SVG 경로는 값 변경을 움직이지 않고 새 높이로 바로 바꿉니다(iso-ledger의 빼냄도 바로 옮깁니다).
• 블록마다 --iso-x·-y·-w·-d·-h·-z를 CSS로 덮어쓰는 것은 CSS 경로에서만 듣습니다. SVG 경로는 좌표를 JS가 다각형에 직접 씁니다. 색 --iso-c는 두 경로 모두 듣습니다.

<!-- 블록 수와 무관하게 SVG로 -->
<iso-heatmap renderer="svg" data='…'></iso-heatmap>

// React
<IsoHeatmap renderer="svg" data={data} />

설치 및 사용법

1. npm 패키지로 설치

프로젝트에 npm 패키지 2.5d-ui를 설치하여 번들러(Vite, Webpack, Next.js 등)에서 직접 import할 수 있습니다.

npm install 2.5d-ui

// JavaScript / TypeScript 번들러
import "2.5d-ui/css";
import "2.5d-ui";

// 교육용 컴포넌트 (map, layers, city) 필요 시
import "2.5d-ui/edu/css";
import "2.5d-ui/edu"; // 또는 경량 엔트리: import "2.5d-ui/edu/map" 등

2. CDN으로 HTML에 직접 넣기 (jsDelivr / unpkg)

별도 설치나 빌드 과정 없이 전 세계 CDN을 통해 HTML 문서에 태그 두 줄로 즉시 사용할 수 있습니다. npm에 등록된 패키지는 jsDelivr와 unpkg에서 실시간 미러링됩니다.

<!-- jsDelivr CDN -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/2.5d-ui@0.2/dist/iso.min.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/2.5d-ui@0.2/dist/iso-edu.min.css">
<script type="module" src="https://cdn.jsdelivr.net/npm/2.5d-ui@0.2/dist/iso.min.js"></script>
<script type="module" src="https://cdn.jsdelivr.net/npm/2.5d-ui@0.2/dist/iso-edu.min.js"></script>

3. 로컬 소스로 개발 및 빌드

저장소를 클론받아 Vite 개발 서버나 정적 빌드를 직접 돌릴 수도 있습니다.

git clone https://github.com/neohum/2.5d-ui.git
cd 2.5d-ui && npm ci
npm run site      # 로컬 개발 서버 (http://localhost:5173/)
npm run build     # core 번들 생성 (packages/core/dist/)

구성 요소

• 3D 인터랙티브 쇼케이스X·Y·Z 축 안내와 실시간 수치 조절, 다양한 실무 사례
• CSS 프리미티브JS 없이 블록·바닥판·라벨을 직접 배치
• <iso-bars>한 줄 막대
• <iso-stack>기둥 안에 계열을 쌓는 적층 막대
• <iso-heatmap>행×열 격자, 셀 높이로 값
• <iso-ledger>장부처럼 쌓은 기록, 한 장을 앞으로
• <iso-kpi>지표 하나를 채움 높이로
• <iso-map>바닥 평면 위 임의 칸 배치 (교육용)
• <iso-layers>위아래 순서 판과 층 펼침 (교육용)
• <iso-city>트리맵 기반 구역과 건물 (교육용)
• 플레이그라운드JSON과 속성을 바꿔 가며 바로 확인

템플릿

여러 컴포넌트를 함께 쓴 화면 예시입니다. 모든 값은 가상 예시 데이터입니다.

• 자원 대시보드기기 자원 사용량을 한 화면에
• KPI 보드핵심 지표 여섯 개와 비교 막대
• 버전 기록 뷰어릴리스 장부에서 한 버전 살펴보기
• 교실 좌석표iso-map 활용 20인 좌석 및 과제 기록
• 학교 평면도iso-map 활용 1~4층 탭 전환 및 기기 현황
• 성취기준 층 구조iso-layers 활용 3~6학년 단원 성취 분석
• 학교 도시iso-city 활용 6개 학년 학급 독서 활동