Badge

--- description: Hướng dẫn Agent tự động tạo UI Component Badge/Tag/Chip dựa trên Design Tokens, có ngữ nghĩa chuẩn Material 3 & iOS HIG

Badge Component Generation Skill

Skill này hướng dẫn bạn (AI Agent) tạo component Badge / Tag / Chip — nhãn nhỏ hiển thị trạng thái, danh mục, hoặc số đếm.

1. Mục tiêu (Objective)

Tạo component Badge đa năng: hiển thị status label, counter (notification count), tag cho categorization, chip có thể xoá. Tích hợp 100% semantic color tokens.

2. AI Context & Intent (Ngữ cảnh cho AI)

Khi nào dùng Badge?

• Hiển thị trạng thái: "Active", "Pending", "Expired"
• Counter / Notification dot: Số unread messages, notification count
• Category tag: Nhãn phân loại ("Frontend", "Backend", "Design")
• Selectable chip: Tag có thể thêm/xoá (vd: filter tags)

Phân biệt Badge / Tag / Chip

Decision Tree cho AI

Cần hiển thị label nhỏ?
├─ Status / trạng thái → Badge (variant theo severity)
├─ Notification count → Badge (counter mode)
├─ Notification dot (không số) → Badge (dot mode)
├─ Category / phân loại → Tag
├─ Filter có thể xoá → Chip (removable)
└─ Selection toggle → Chip (selectable)

3. Ngữ nghĩa & Phân loại (Semantics)

3.1. Variant theo Severity / Semantic

3.2. Mode

3.3. Size

• sm: font.size.xs (12px), padding minimal
• md: font.size.sm (14px), padding cân đối

3.4. Slot Map (Figma ↔ Code)

📎 Source: slot-manifest.json → badge · Layer: item

4. Token Mapping

📦 Token values: Xem ATOMIC-MAPPING.md — single source of truth cho tất cả actual token values.

5. Props & API

interface BadgeProps {
  /** Semantic variant */
  variant?: 'default' | 'primary' | 'secondary' | 'success' | 'warning' | 'destructive' | 'info' | 'outline';
  /** Display mode */
  mode?: 'label' | 'counter' | 'dot';
  /** Size */
  size?: 'sm' | 'md';
  /** Content — text hoặc number */
  children?: ReactNode;
  /** Max count (counter mode) — vượt quá hiển thị "99+" */
  maxCount?: number;
  /** Left icon */
  icon?: ReactNode;
  /** Removable — hiện nút close (chip mode) */
  removable?: boolean;
  /** On remove callback */
  onRemove?: () => void;
}

6. Accessibility (a11y)

• Role: Badge read-only là <span>, không cần role đặc biệt.
• Counter: Dùng aria-label mô tả context (vd: aria-label="3 unread messages").
• Removable (chip): Nút close phải có aria-label="Remove [tag name]".
• Dot: Badge dot BẮT BUỘC có aria-label vì không có text visible.
• Color không đủ: Không chỉ dùng màu sắc để truyền tải thông tin — kết hợp icon hoặc text.

7. Best Practices & Rules

• Không interactive (Badge/Tag): Không có hover/click effect, chỉ hiển thị thông tin.
• Counter max: Khi giá trị > maxCount (mặc định 99), hiển thị "99+".
• Dot position: Khi dùng như notification dot overlapping element khác, dùng absolute positioning.
• Không Hardcode: Mọi giá trị từ Token.
• Semantic color: LUÔN chọn variant phù hợp ngữ nghĩa — success cho trạng thái tốt, destructive cho lỗi...
• Icon: Close/remove icon (x) và leading icon CHỈ dùng Lucide icon từ assets/icons/. CẤM dùng text emoji. Xem icon.md mục 10.

8. Example Usage

{/* Status badges */}
<Badge variant="success">Active</Badge>
<Badge variant="warning">Pending</Badge>
<Badge variant="destructive">Expired</Badge>

{/* Counter */}
<Badge variant="destructive" mode="counter" maxCount={99}>150</Badge>
{/* → Hiển thị "99+" */}

{/* Dot notification */}
<Badge mode="dot" variant="destructive" />

{/* Removable tag/chip */}
<Badge variant="primary" removable onRemove={handleRemove}>
  Frontend
</Badge>