Badge
상태/라벨 칩 — 의미별 variant 6종. 상태색은 *-text 잉크 + 8% 틴트 배경으로 라이트/다크 모두 AA를 보장합니다.
마지막 업데이트 2026-06-11
한눈에#
개수·상태·분류를 한 단어/숫자로 표시하는 읽기 전용 칩입니다 — 색은 장식이 아니라 상태 어휘로 의미를 가집니다.
- 의미 6종
- 8% 틴트 + *-text 잉크
- count·dot
- AA 보장
상태색 배경은 base 8% color-mix 고정 — *-text 잉크로 라이트/다크 모두 AA 4.5:1 보장
사용 시점#
읽기 전용 상태·개수 표식이면 Badge — 사용자가 다루거나 클릭하는 칩은 다른 컴포넌트입니다.
권장 — 이렇게 쓰세요
지양 — 이러지 마세요
쓴다 — 상태·개수·분류를 한 단어/숫자로 표식(색은 상태 어휘, 사용자가 조작하지 않음)
대신 Tag — 사용자가 제거(×)하는 필터·선택 값 칩일 때
대신 Chip — 클릭·토글·제안 같은 상호작용이 있는 칩일 때
플레이그라운드#
컨트롤로 props를 조작하면 미리보기와 코드가 실시간 갱신됩니다.
Badge를 직접 조작해 보세요
속성·테마·토큰을 바꾸고 React·Flutter 코드를 확인하는 풀스크린 빌더로 엽니다.
플레이그라운드는 넓은 작업 영역이 필요해 웹·태블릿에서 편집할 수 있어요.
변형#
상태색(success/warning/error/info) 배경은 base 색의 8% color-mix
고정입니다 — 12%는 success-text와 4.39:1로 AA 미달(AgentCard axe 실측).
크기#
size prop이 없습니다 — caption 폰트 + space.1/2 패딩의 단일 크기입니다.
상태#
정적 컴포넌트라 인터랙션 상태가 없습니다(RSC). 텍스트는 nowrap으로
한 줄을 유지합니다.
Props#
| Prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
variant | 'neutral' | 'primary' | 'success' | 'warning' | 'error' | 'info' | neutral | 의미 색 — 장식이 아닌 상태 어휘로 사용한다 |
count | number | — | 숫자 배지 — 값이 주어지면 children 대신 표시. max 초과 시 "max+" (ADR-012 B-P1) |
max | number | 99 | count 클램프 상한 — 기본 99 ("99+") |
dot | boolean | false | 점 배지 — 내용 없는 작은 알림 점. 의미가 있으면 aria-label을 함께 전달 (ADR-012 B-P1) |
ref | Ref<HTMLSpanElement> | — | 루트 <span>으로 전달되는 ref (React 19 ref-as-prop) |
접근성#
- 의미는 색 + 텍스트 병행 — 색만으로 상태를 구분하지 않습니다(색맹 안전)
- 잉크는
*-text토큰 — 8% 틴트 배경 위에서 AA 4.5:1이 빌드 게이트로 보장됩니다 - 일반
span이라 별도 role이 없습니다 — 동적으로 바뀌는 개수 알림이 필요하면 호출부에서 라이브 리전을 구성하세요
토큰#
component 토큰 없이 semantic을 직접 소비합니다(신설 기준 §4 미충족).
| 속성 | 토큰 |
|---|---|
| neutral | color.surface-muted + color.text-muted |
| primary | color.primary-subtle + color.primary-text |
| success/warning/error/info | base 색 8% color-mix 틴트 + color.*-text |
| 형태 | radius.full · space.1/2 |
| 타이포 | font-size.caption + font-weight.medium + line-height.tight |