Badge

상태나 카테고리를 표시하는 소형 라벨입니다. 비-인터랙티브.

Mobile

비-인터랙티브 시각 라벨 — 플랫폼 분기 없음. Web 명세 그대로 mobile에 적용.

Anatomy

단일 <div> (또는 <span>)에 cva 스타일을 적용한 구조입니다.

Dot (optional): 6×6px 원형 상태 인디케이터
Icon (optional): 텍스트 앞 아이콘 슬롯
Label (required): 텍스트 콘텐츠

Variants

variant(형태) × tone(색상) 매트릭스.

Subtle tone 색상 규칙: bg-{scale}-100 text-{scale}-700. error만 bg-rose-50 (더 옅게).

States

비-인터랙티브 — hover/focus/active 없음. 클릭이 필요한 경우 <button>으로 wrap하고 별도 focus styling을 추가합니다.

Sizes

Default: md

Size	Height	px	py	Text token	Primary use
`xs`	16px	6	0	`caption2Medium` 11/14	매우 작은 인라인 라벨. 리스트 아이템 옆 BETA / NEW 같이 본문보다 한 단계 작아야 할 때
`sm`	20px	8	1	`caption1Regular` 12/16	인라인 카운트, 상태 dot
`md`	24px	10	1.5	`caption1Medium` 12/16	Default. 상태 pill, 카테고리
`lg`	28px	12	2	`label2Medium` 13/20	"Beta", "Pro", 강조 라벨

Radius: rounded-full (pill). 사각 badge는 rounded-md (r1_5, 6px).

Token Mapping

Token	Value
radius (pill)	`rounded-full`
radius (rect)	`rounded-md` (r1_5, 6px)
dot size	6×6px
icon-label gap	4px
solid bg (brand)	`brown-800` · text `white`
subtle bg (brand)	`brown-30` · text `brown-800`
subtle bg	`{tone}-100` · text `{tone}-700`
subtle bg (error)	`rose-50` · text `rose-700`
outline	`border border-stone-200` · text `stone-500`

Props

interface BadgeProps extends React.HTMLAttributes<HTMLDivElement> {
  variant?: 'solid' | 'subtle' | 'outline'  // default: 'subtle'
  tone?: 'neutral' | 'brand' | 'success' | 'warning' | 'error' | 'info'  // default: 'neutral'
  size?: 'xs' | 'sm' | 'md' | 'lg'  // default: 'md'
  dot?: boolean
  icon?: React.ReactNode
}

Usage

<Badge tone="brand" variant="solid">Premium</Badge>

<Badge tone="success">진행중</Badge>

<Badge tone="warning">대기중</Badge>

<Badge tone="error">삭제 보류</Badge>

<Badge tone="success" dot>Active</Badge>

<Badge variant="outline">보관됨</Badge>

<Badge variant="count">3</Badge>

주변 텍스트와 의미가 중복되는 장식 badge: aria-hidden="true"
상태는 텍스트 콘텐츠가 SSOT — 색상만으로 상태 전달 금지
Count badge: 숫자 단독보다 aria-label="읽지 않은 알림 3개" 권장
dot variant: 반드시 인접 텍스트 또는 tooltip으로 의미 보완

Do / Don't

Do: Tone 일관성 유지 — success는 제품 전체에서 긍정 상태에만
Do: dot + label 페어로 상태 표시 ("● 진행중")
Do: 라벨은 10자 이내, count는 "99+"로 truncate
Don't: 같은 화면에서 동일 의미에 다른 tone 혼용
Don't: Badge를 클릭 가능하게 만들지 않음 → Button 또는 Chip 사용
Don't: dot variant를 텍스트 없이 단독으로 사용 (색맹 대응 불가)

Badge

On this page