본문으로 건너뛰기
Dot Design System
v0.3.1

StatCard

독립적으로 해석해야 하는 하나의 핵심 지표를 설명합니다.

목적

StatCard는 하나의 핵심 값과 선택적인 변화·설명을 독립된 card로 보여준다. 사용자가 특정 지표를 빠르게 읽고 기준 시점이나 변화 방향을 이해하게 한다.

선택 기준

  • 각 지표가 독립된 설명이나 배치를 가져야 할 때 사용한다.
  • 같은 범위의 여러 값을 빠르게 비교하는 것이 목적이면 MetricStrip을 우선한다.
  • 세부 추이, 분포, 원인 분석은 chart나 table로 이동한다.
  • 행동이 주목적인 카드에는 사용하지 않는다.

구조

  1. label: 지표 이름
  2. icon: 선택적 의미 보조
  3. value: 핵심 값
  4. trend: 변화값과 방향 tone
  5. hint: 기준 기간, 분모, 데이터 상태

변형과 크기

  • 별도 card size prop은 없다.
  • trend.tone은 positive, negative, neutral 중 하나다.
  • value는 tabular number와 높은 시각 위계를 사용한다.
  • className으로 grid 배치나 최소 폭을 조정한다.

상태와 동작

  • 자체 클릭 동작은 없다.
  • 로딩 시 card 크기와 label을 유지하고 value 영역을 skeleton으로 바꾼다.
  • 값 일부를 불러오지 못하면 0으로 대체하지 말고 알 수 없음 상태를 명시한다.
  • 지연 데이터는 hint에 마지막 갱신 시각 또는 기준 시점을 표시한다.
  • trend는 비교 기준이 있을 때만 전달한다.

콘텐츠

  • label은 측정 대상을 짧고 구체적으로 쓴다.
  • value와 단위의 간격·표기를 같은 dashboard에서 통일한다.
  • trend의 +12%만 보여주지 말고 hint에 지난 7일 대비 같은 기준을 제공한다.
  • 증가가 항상 좋거나 감소가 항상 나쁘다고 가정하지 않는다. 도메인 의미에 따라 tone을 결정한다.
  • 값이 없는 것과 실제 0을 구분한다.

접근성

  • 색상만으로 trend 방향을 구분하지 않도록 trend.value에 증가, 감소 또는 부호와 충분한 문맥을 제공한다.
  • icon은 장식이면 aria-hidden을 전달한다.
  • card 묶음에는 별도의 section heading 또는 접근 가능한 이름을 제공한다.
  • 자동 갱신되는 값은 매번 무분별하게 낭독하지 말고 중요한 상태 변화만 live region으로 알린다.

좁은 화면과 긴 콘텐츠

  • 여러 StatCard는 작은 화면에서 한 열 또는 의미 있는 두 열로 전환한다.
  • 긴 label과 trend가 한 행에서 충돌하면 label을 줄이거나 trend를 hint로 이동한다.
  • 큰 값이 영역을 넘으면 무조건 작은 글자로 축소하지 말고 읽을 수 있는 단위로 축약하고 전체 값을 제공한다.
  • card 높이를 강제로 같게 맞추기 위해 핵심 설명을 잘라내지 않는다.

공개 API

속성타입기본값설명
labelstring필수지표 이름
valueReactNode필수핵심 값
hintReactNode없음기준 또는 보조 설명
iconReactNode없음선택적 아이콘
trend{ value: string; tone: 'positive' | 'negative' | 'neutral' }없음변화값과 의미 tone
classNamestring없음card 클래스

공개 타입은 StatCardProps다.

예제

사용 코드 · TSX
import { StatCard } from '@classum/dot-design-system/ui';

export function CompletionStat() {
  return (
    <StatCard
      label="학습 완료율"
      value="82.4%"
      trend={{ value: '3.1%p 증가', tone: 'positive' }}
      hint="지난 7일과 비교"
    />
  );
}

피해야 할 사용

  • 기준 기간 없이 trend만 표시
  • 증가를 무조건 positive tone으로 처리
  • 알 수 없는 값을 0으로 표시
  • 관련 지표를 많은 독립 card로 쪼개 비교를 어렵게 함
  • card 전체를 클릭 가능하게 보이도록 스타일만 변경
  • 정상 값 전체를 상태색으로 강조

관련 항목