HeatmapChart

한눈에#

HeatmapChart는 행×열 매트릭스의 값을 색 강도로 인코딩하는 차트입니다. 요일×시간대 트래픽, 상관행렬, 캘린더 활동량처럼 두 범주축의 교차값을 한눈에 비교할 때 씁니다.

사용 시점#

두 범주축의 교차값(요일×시간대, 상관행렬)을 색 강도로 비교할 때가 히트맵의 자리입니다. 한 축만의 비교나 정밀한 값 읽기에는 막대가 낫습니다.

어떻게 동작하나#

격자 레이아웃과 값의 버킷 레벨(0…steps-1)은 순수 코어 buildHeatmapGrid가 계산합니다(ADR-018, Flutter wiz_charts 포팅 단위). 색은 렌더 레이어가 입힙니다:

• 순차 색 = 단일 토큰(--wds-chart-1)의 레벨 불투명도 — 새 순차 토큰을 만들지 않고 차트 1번 색 하나만 참조합니다. 레벨이 높을수록 불투명도가 올라가 진해집니다.
• 다크 모드 자동 적응 — 불투명도가 표면 위에 블렌드되므로, 라이트/다크 어느 표면에서도 자연스럽게 읽힙니다(토큰이 테마별 재바인딩).
• 결측 셀 — 값이 null이거나 없는 칸은 중립 표면색 + 점선 테두리로 칠해 “값 0”이나 최저 레벨과 구분합니다(색맹·저대비 안전, 형태 채널).
• 정사각 셀 — 셀은 항상 정사각(균일 색 스케일 보장)이라 figure 비율 = 열:행 비율입니다. 긴 행 라벨은 줄여서 넣으세요(좌측 라벨 영역 고정).

데이터 API#

const cells = [
  { x: '월', y: '오전', value: 70 },
  { x: '화', y: '오전', value: 74 },
  { x: '월', y: '오후', value: 140 },
  // …
];

<HeatmapChart
  cells={cells}
  xLabels={['월', '화', '수', '목', '금', '토', '일']}
  yLabels={['새벽', '오전', '오후', '저녁', '심야']}
  label="요일·시간대별 방문량"
/>;

xLabels·yLabels로 행·열 순서를 고정합니다(생략 시 셀 삽입 순서). steps(기본 5)로 색 단계 수를, cellSize(기본 30)로 셀 크기를 조정합니다.

접근성#

색 강도 비교는 어려우므로(SC 1.4.1), 행×열 값 표가 정본입니다 — sr-only <table>로 노출하고 SVG는 aria-hidden입니다. 결측 칸은 표에서 —로 표기됩니다. 범례는 단계별 색을 보여주되, 정확한 값은 표가 담당합니다.

토큰#