MetricStrip

목적

MetricStrip은 서로 관련된 핵심 지표를 한 표면의 균일한 셀로 묶어 비교하게 한다. 운영자가 전체 상태를 빠르게 판단하고 조치가 필요한 값으로 이동할 수 있도록 레이블, 값, 보조 설명의 위치를 일관되게 유지한다.

선택 기준

• 같은 기간과 범위를 공유하는 2개 이상의 요약 지표에 사용한다.
• 하나의 지표만 강조하면 StatCard 또는 본문 metric을 사용한다.
• 순위나 세부 시계열 비교에는 table이나 chart를 사용한다.
• 서로 단위, 기간, 데이터 신뢰도가 다른 값을 설명 없이 한 strip에 섞지 않는다.

구조

각 MetricStripItem은 다음 영역을 가진다.

1. label: 측정 대상
2. icon: 선택적 의미 보조
3. value: 가장 높은 위계의 값
4. hint: 기간, 기준선, 변화 이유 같은 보조 정보

전체 strip은 section으로 렌더되고 ariaLabel로 지표 묶음의 목적을 설명한다.

변형과 크기

• tone: neutral, success, warning, destructive를 item별로 선택한다.
• 기본 cell padding은 20px이다.
• compactOnMobile은 작은 화면에서 cell padding을 줄이고 hint를 시각적으로 숨긴다. hint는 접근성 트리에는 남는다.
• grid는 사용 가능한 폭에 맞춰 자동으로 줄을 바꾼다.

상태와 동작

• 자체 클릭 동작은 없다. 지표가 상세 화면으로 이동해야 하면 바깥에 명확한 링크를 두거나 별도 interactive composition을 제품에서 만든다.
• 로딩 중에는 값의 자리를 유지하는 skeleton을 사용한다.
• 일부 지표만 실패하면 성공 값 전체를 숨기지 말고 해당 cell에 불러오지 못한 상태와 복구 경로를 표시한다.
• 데이터가 지연되었으면 hint에 마지막 갱신 시각을 제공한다.
• items의 label은 React key로 사용되므로 같은 strip 안에서 고유해야 한다.

콘텐츠

• label은 짧고 서로 같은 문법으로 쓴다.
• value에는 단위를 붙이되 비교할 숫자의 정렬을 해치지 않게 구성한다.
• hint는 단순 반복이 아니라 기준 기간, 전주 대비, 데이터 상태를 설명한다.
• tone은 값의 좋고 나쁨이 도메인 규칙으로 확정된 경우에만 사용한다.
• 성공 값까지 모두 초록색으로 만들지 않는다. 정상은 neutral이 기본이다.

접근성

• ariaLabel은 기본 영어 문자열을 제품 맥락에 맞는 한국어로 바꾸는 것을 권장한다.
• 색상만으로 상태를 전달하지 말고 label, value 또는 hint에 의미를 텍스트로 포함한다.
• icon은 장식이면 aria-hidden을 전달한다. 별도 의미가 있으면 인접 텍스트로 같은 의미를 설명한다.
• 큰 숫자는 시각적으로 tabular-nums를 사용하며 스크린 리더가 이해할 수 있는 문자열 구조를 유지한다.

좁은 화면과 긴 콘텐츠

• item은 최소 폭을 기준으로 자동 줄바꿈되며 좁은 화면에서는 한 열이 될 수 있다.
• compactOnMobile에서 hint가 시각적으로 숨겨지므로 판단에 필수인 정보는 label이나 value에도 반영한다.
• 긴 label은 여러 줄이 될 수 있지만 같은 strip의 정보 밀도를 해치면 용어를 줄인다.
• value가 매우 길면 축약 표기와 전체 값의 접근 가능한 설명을 제품에서 함께 제공한다.

공개 API

MetricStripProps

MetricStripItem

공개 타입은 MetricStripProps, MetricStripItem, MetricTone이다.

예제

import { MetricStrip } from '@classum/dot-design-system/ui';

export function JobMetrics() {
  return (
    <MetricStrip
      ariaLabel="오늘의 비동기 작업 지표"
      compactOnMobile
      items={[
        { label: '처리 완료', value: '1,284건', hint: '오늘 00:00부터', tone: 'neutral' },
        { label: '처리 중', value: '18건', hint: '가장 오래된 작업 4분', tone: 'neutral' },
        { label: '확인 필요', value: '3건', hint: '재시도 가능한 실패', tone: 'warning' },
      ]}
    />
  );
}

피해야 할 사용

• 관련 없는 KPI를 한 strip에 나열
• 정상 값 전체에 success tone 적용
• trend의 기준 기간 없이 증가·감소만 표시
• 상세 분석을 metric cell 안에 과도하게 넣기
• 같은 label을 중복해 key 충돌을 만드는 경우
• 클릭 가능한 카드처럼 보이지만 아무 동작이 없는 표현

관련 항목

• StatCard
• 대시보드와 모니터링
• 데이터 비교