Badge

짧은 분류나 보조 속성을 인라인으로 표시합니다.

목적

Badge는 대상의 범주, 짧은 속성, 작은 수량처럼 본문을 보조하는 압축된 정보를 표시한다. 사용자가 이해해야 하는 업무 상태에는 더 명확한 문구와 tone 계약을 가진 StatusPill을 우선한다.

선택 기준

필수, Beta, 3개처럼 짧고 독립적인 보조 정보를 붙일 때 사용한다.
상태가 제품 흐름을 바꾸거나 복구 행동이 필요하면 Badge만 쓰지 않는다.
클릭 가능한 필터, 선택 토글, 삭제 가능한 tag에는 별도의 interactive component가 필요하다.

실제 패키지 렌더링

기본 사용 예시

예시 데이터

기본완료검토 필요초안

구조

Badge 하나가 inline span을 렌더한다. 텍스트를 기본으로 하고 필요한 경우 작은 아이콘을 앞에 둘 수 있다. 아이콘은 텍스트의 의미를 보강해야 하며 단독으로 쓰지 않는다.

변형과 크기

별도 size prop은 없으며 기본 padding과 text-xs를 사용한다.

default: primary 계열의 기본 강조
secondary: 중립 보조 정보
outline: 배경 강조가 필요 없는 속성
muted: 낮은 우선순위의 메타데이터
success: 완료·정상
warning: 주의가 필요한 상태
destructive: 실패·위험
info: 안내·진행 맥락
solid: 가장 강한 중립 강조

한 화면에서 의미 없이 여러 variant를 장식처럼 섞지 않는다.

상태와 동작

Badge는 기본적으로 상호작용하지 않고 hover, selected, disabled 상태를 제공하지 않는다. 상호작용이 필요하면 Badge에 click handler를 붙이지 말고 Button, Tabs, Checkbox 등 의미에 맞는 component를 사용한다.

콘텐츠

한눈에 읽히는 명사나 짧은 수치로 제한한다. 문장, 오류 복구 방법, 긴 날짜 범위는 Badge 밖에 쓴다. 상태 문구는 내부 코드 값 대신 검토 필요, 발행됨처럼 사용자가 이해하는 표현을 사용한다.

접근성

색만으로 의미를 전달하지 않는다. warning이나 destructive를 사용해도 텍스트 자체가 상태를 설명해야 한다. 아이콘만 넣지 않는다. Badge가 주변 문장을 보충한다면 screen reader가 자연스러운 순서로 읽을 수 있는 DOM 위치에 둔다.

좁은 화면과 긴 콘텐츠

Badge는 내용에 따라 늘어나지만 지나치게 긴 문자열은 행의 핵심 정보를 밀어낸다. 긴 상태는 짧은 사용자 언어로 정리하거나 별도 설명 영역으로 옮긴다. 여러 Badge가 줄바꿈될 때 읽기 순서와 간격을 유지한다.

공개 API

Badge: span의 HTML attributes와 variant를 지원한다.
BadgeProps: 공개 prop type
badgeVariants: 동일한 variant 스타일을 composition에서 재사용할 때 쓰는 helper

variant 기본값은 default다. 전용 size, loading, selected prop은 없다.

예제

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

export function ReviewState() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      <Badge variant="warning">검토 필요</Badge>
      <Badge variant="outline">질문 12개</Badge>
    </div>
  );
}

피해야 할 사용

Badge를 작은 Button처럼 사용하지 않는다.
색만 다른 빈 원이나 아이콘만으로 상태를 표시하지 않는다.
한 항목에 중요도가 비슷한 Badge를 과도하게 나열하지 않는다.
긴 설명이나 오류 메시지를 Badge 안에 넣지 않는다.
모든 텍스트에 solid를 적용해 강조 우선순위를 무너뜨리지 않는다.

목적