# Badge

현재 HM 구현의 기준 문서. 공통 원칙은 `docs/guidelines/프로젝트-지침.md`(§6, §7), Token 구조 원칙은 `테마-토큰-가이드.md`를 따른다. 이 문서는 Badge 고유의 API·Token·상태·결정만 기록한다.

## 1. 상태

| 항목 | 내용 |
|---|---|
| 구현 상태 | 구현 완료 (현재 HM 규격) |
| 기준일 | 2026-10-02 |
| 기반 | shadcn/ui Badge (CVA, `asChild` Slot) |
| 대표 Story | `Components/Data & Display/Badge` → `All` (이름 "Badge") |
| 보류 | 아래 §11 |

## 2. 적용 근거

- **참고 근거**: ui-viz 기존 테스트 규격에는 Badge 문서가 없다(Border 1px 등 일부 언급만). 참고만 했다.
- **현재 HM 규격**: §3~§4.
- **구현 방식**: shadcn Badge 구조(CVA `variant`, `data-slot`, `asChild`, `cn(..., className)`)를 유지하고 `data-variant`로 theme CSS를 선택. Button variant를 재사용하지 않는다.
- **보류**: §11.

## 3. 기본 규격

| 항목 | 값 |
|---|---|
| Typography | 12 / 18 / 500 |
| Padding | `2px 8px` (높이 24px) |
| Border / Radius | 1px / `--hm-radius-control-md` (4px) |
| Gap | shadcn `gap-1`, 아이콘 12px (`size-3`) |

## 4. 상태 규격

| variant | 면 | 글자 | 테두리 |
|---|---|---|---|
| `default` | `--hm-sem-action-primary` (Primary Green `#123328`) | `--hm-sem-on-action-primary` (White) | 면과 동일 |
| `secondary` | `--hm-sem-bg-subtle` | `--hm-sem-fg-secondary` | 면과 동일 |
| `destructive` | `--hm-sem-action-destructive` | White | 면과 동일 |
| `outline` | `--hm-sem-bg-surface` | `--hm-sem-fg-primary` | `--hm-sem-stroke-default` |

상호작용 상태 없음 (`asChild`로 링크/버튼에 감쌀 때 그 요소가 담당).

## 5. API

```
Badge:
  variant?: "default" | "secondary" | "destructive" | "outline"   기본 "default"
  asChild?: boolean
```
나머지는 `<span>` props. 출력 속성: `data-slot="badge"`, `data-variant`. `badgeVariants`도 export.

## 6. Token

`packages/ui/src/theme/badge.css` (`--hm-badge-*`): `radius`, `padding-x/y`, `border-width`, `font-size/line-height/font-weight`, variant별 `{default,secondary,destructive,outline}-{background,text,border-color}`. Semantic 참조. Primitive 신규 추가 없음.

Dashboard 업무 상태의 outline Badge는 [공식 상태 mapping](../patterns/dashboard-layout.md#dashboard-업무-상태-공통-계약)에서 기존 Token을 연결한다. 이 문서화된 소비 예제는 사용자별 디자인 의도 승인이나 Runtime Theme JSON key 확장이 아니다. Guard는 선언 확인·DOM 적용값·override 의도를 [별도 판정](../guidelines/ai-generation-guard.md#css-intent와-동적-token-검사-2026-10-10)하며 실제 Badge 스타일·API는 변경하지 않는다.

## 7. shadcn / Radix에서 유지한 항목

CVA 구조, `asChild`(Radix Slot), `data-slot`, `cn(..., className)`, 아이콘 크기 규칙(`[&>svg]:size-3`).

## 8. HM에서 변경한 항목

shadcn `rounded-full`·`px-2 py-0.5 text-xs`·focus/invalid ring·hover class 제거 → theme CSS(radius 4). variant 이름은 shadcn 4종을 유지하고 색만 HM으로 매핑.

## 9. Storybook

대표 Story `All`: `variants`, `icon`, `long`, `link`(asChild). verification: `Variants`, `Playground`.

## 10. 사용자 확정 결정

2026-10-02: ui-viz는 참고 자료이며 최종 기준은 현재 HM 구현과 이 문서다(작업 지시). 이 컴포넌트에 대한 개별 수치 결정은 없다.

2026-10-06 (Badge 원복): 직전 Active Semantic 후속에서 `default`를 Light 2(`--hm-sem-state-active`)로 바꾼 변경을 취소했다. `default`는 Strong Brand / Primary인 Primary Green(`--hm-sem-action-primary` / `--hm-sem-on-action-primary`)을 쓰며 Active Semantic 적용 대상이 아니다. Component Token 이름은 유지하고 참조만 되돌렸다. `secondary`·`outline`·`destructive`는 그대로다. Badge는 비인터랙티브 label이라 hover 면을 두지 않는다.

## 11. 미확정 / 보류

- success / warning / information 같은 상태 variant: HM 상태 색이 정해지지 않아 만들지 않았다.
- size 변형, 점(dot) badge: 미결정.
- 수치(12/18/500, 2/8, radius 4)는 현재 HM 규격이며 디자인 확정 시 재검토.

## 12. 관련 파일

```
packages/ui/src/components/ui/badge.tsx
packages/ui/src/theme/badge.css
packages/ui/src/theme.css            (import)
packages/ui/src/index.ts             (export Badge, badgeVariants)
src/components/badge.stories.tsx
```

## 13. 검증 상태

- `npm run typecheck`, `npm run build`: 통과(2026-10-02).
- computed style: 4 variant 모두 12px/18px/500, padding `2px 8px`, radius 4px, 높이 24px, 색 위 표와 일치, 아이콘 12px.
- 미확인: `asChild` 링크 focus 표시, 사이드바 화면, 390px 폭.
- 2026-10-06 Badge 원복: `default` 면·테두리 `rgb(18,51,40)`(`#123328`), 글자 `rgb(255,255,255)`. secondary·destructive·outline 값 변화 없음.