# Badge

Nhãn ngắn cho một status hoặc một danh mục. Nó dùng nền soft, hoặc outline khi cần giữ nhẹ. Nó không bao giờ dùng hue solid. Nền solid với text-on-<hue> dành cho Avatar.

**Phụ thuộc:** npm: 1 trực tiếp, 2 tổng; registry: 2 trực tiếp, 2 tổng.

## Cách dùng

### Khi nào dùng

- Hiện trạng thái của một mục ngay cạnh nó: Thất bại, Sẵn sàng, Sắp hết hạn.
- Gắn danh mục cho một mục mà người dùng đọc nhưng không thao tác: Thiết kế, Beta.

### Khi nào không dùng

- Thứ gì nhấn được hoặc bật tắt được. Dùng Button.
- Một value đã chọn mà người dùng gỡ được, chẳng hạn một bộ lọc đang bật. Dùng Token với button gỡ.
- Đặt tên một token thiết kế hoặc một giá trị máy khác. Dùng Token.
- Câu văn hoặc nhãn dài. Giữ nhãn badge ngắn: Beta, Thất bại, Mới.

## Biến thể

### variant

default là nhãn xám trung tính. accent dùng muted accent. outline không có nền, chỉ một viền mỏng. destructive, success, warning và info thể hiện status. red, orange, yellow, green, teal, blue, purple và pink đánh dấu danh mục. Mọi variant có nền ghép nền soft với màu chữ tương ứng, không bao giờ dùng solid.

Giá trị: `default`, `accent`, `outline`, `destructive`, `success`, `warning`, `info`, `red`, `orange`, `yellow`, `green`, `teal`, `blue`, `purple`, `pink`. Mặc định: `default`.

## Ví dụ

### Mặc định

```tsx
<Badge>Beta</Badge>
```

### Có icon

```tsx
<Badge variant="success">
  <IconCheck size={12} />
  Sẵn sàng
</Badge>
```

### Info

```tsx
<Badge variant="info">Đã lên lịch</Badge>
```

## Nên và không nên

### Nên

- Dùng các variant status (destructive, success, warning, info) cho trạng thái, và hue cho danh mục.
- Giữ nhãn ngắn: Beta, Thất bại, Mới.
- Hiện tối đa một badge status trên mỗi hàng hoặc card.
- Đặt icon (12px) trước nhãn.
- Dùng outline cho nhãn trung tính nhẹ cạnh các badge có nền.

### Không nên

- Đừng làm badge nhấn được.
- Đừng dùng Badge cho chip lọc hoặc tag gỡ được. Thứ gì bật tắt hoặc có hành động gỡ là một Button.
- Đừng đặt chữ hoặc icon lên hue solid (bg-red). Nền solid dành cho chấm và chart.
- Đừng dùng danger solid với text-on-danger cho badge; destructive là cặp soft.
- Đừng chỉnh màu qua className. Chọn một variant. Nếu không cái nào khớp, mở một issue thay vì ghi đè.

## Props

| Tên | Kiểu | Giá trị | Mặc định | Mô tả |
| --- | --- | --- | --- | --- |
| `variant` | `enum` | `default`, `accent`, `outline`, `destructive`, `success`, `warning`, `info`, `red`, `orange`, `yellow`, `green`, `teal`, `blue`, `purple`, `pink` | `default` | default là nhãn xám trung tính. accent dùng muted accent. outline không có nền, chỉ một viền mỏng. destructive, success, warning và info thể hiện status. red, orange, yellow, green, teal, blue, purple và pink đánh dấu danh mục. Mọi variant có nền ghép nền soft với màu chữ tương ứng, không bao giờ dùng solid. |

### Slot

| Tên | Bắt buộc | Mô tả |
| --- | --- | --- |
| `label` | có | Nhãn ngắn, sentence case hoặc một từ status. |
| `icon` | không | Icon dẫn đầu, tùy chọn. |

## Cấu tạo

| Phần | Mô tả |
| --- | --- |
| `root` | Bề mặt badge: cao 24px (h-6 trên thang size số, chưa có size token), nền soft, radius-element, chữ gọn. |
| `icon` | Icon Tabler tùy chọn trước nhãn, 12px. |

## Khả năng truy cập

Role: `generic`

- Badge không tương tác. Đừng biến nó thành link hoặc button; đặt hành động lên hàng hoặc card.
- Màu không phải tín hiệu duy nhất: giữ một nhãn chữ ngắn (Thất bại, không chỉ một chấm đỏ).
- Root là một span thuần, không có role, nên badge không bao giờ là live region theo mặc định. Nếu chữ của badge đổi và phải được thông báo (một bản build từ Đang chạy sang Thất bại), thêm role="status" tại nơi gọi.

## Cài đặt

```bash
npx werewolf-ui add badge
```

Chạy `npx werewolf-ui init` một lần trong app trước khi thêm component. Init cài token, thêm CSS import và luật cho agent. Add cài component này cùng các dependency và giữ nguyên theme của bạn. Xem [Cài đặt](https://www.werewolf-ui.dev/vi/docs/installation.md) để biết yêu cầu và cách cài qua registry.