Checkbox

Checkbox Component Generation Skill

Skill này hướng dẫn bạn (AI Agent) tạo component Checkbox — điều khiển cho phép chọn nhiều giá trị, hỗ trợ trạng thái indeterminate.

1. Mục tiêu (Objective)

Tạo component Checkbox hoàn chỉnh gồm Checkbox đơn lẻ và Checkbox Group, hỗ trợ indeterminate state cho "Select All", tích hợp 100% Design Tokens.

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

Khi nào dùng Checkbox?

• Chọn nhiều giá trị từ nhóm options (vd: chọn tính năng, chọn danh mục)
• Toggle đơn lẻ cho agree/consent (vd: "Tôi đồng ý điều khoản")
• Select All / Deselect All trong danh sách

Phân biệt với component khác

Decision Tree cho AI

User cần toggle/chọn?
├─ Nhiều lựa chọn cùng lúc → Checkbox (Group)
├─ Một lựa chọn duy nhất trong nhóm → Radio
├─ On/Off tức thì (không cần save) → Switch
├─ On/Off trong form (cần save/submit) → Checkbox (đơn lẻ)
└─ Agree/consent/terms → Checkbox (đơn lẻ)

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

3.1. Checkbox States

3.2. Checkbox Group

• Wrapper chứa nhiều Checkbox với label, mô tả, error chung.
• Hỗ trợ orientation: vertical (mặc định) hoặc horizontal.
• Có thể có "Select All" checkbox với indeterminate logic tự động.

3.5. Slot Map (Figma ↔ Code)

📎 Source: slot-manifest.json → checkbox · 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 CheckboxProps {
  /** Checked state */
  checked?: boolean;
  /** Indeterminate state (overrides checked visual) */
  indeterminate?: boolean;
  /** Label text */
  label?: string;
  /** Description bên dưới label */
  description?: string;
  /** Disabled */
  disabled?: boolean;
  /** Error state */
  isError?: boolean;
  /** Size */
  size?: 'sm' | 'md' | 'lg';
  /** onChange callback */
  onChange?: (checked: boolean) => void;
}

interface CheckboxGroupProps {
  /** Label của group */
  label?: string;
  /** Options */
  options: { value: string; label: string; description?: string; disabled?: boolean }[];
  /** Values đã chọn */
  value?: string[];
  /** Orientation */
  orientation?: 'vertical' | 'horizontal';
  /** Error message */
  errorMessage?: string;
  /** Select All option */
  showSelectAll?: boolean;
  /** onChange callback */
  onChange?: (values: string[]) => void;
}

6. Accessibility (a11y)

• Role: Dùng <input type="checkbox"> native (có thể ẩn visually).
• Label: Mỗi checkbox phải có <label> kết nối qua htmlFor.
• Indeterminate: Set checkbox.indeterminate = true qua JavaScript (không có HTML attribute).
• Group: Wrap trong <fieldset> + <legend> hoặc role="group" + aria-labelledby.
• Keyboard: Space toggle checked, Tab di chuyển focus giữa checkboxes.
• Error: aria-invalid="true" + aria-describedby trỏ error message.

7. Best Practices & Rules

• Semantic HTML: Dùng native <input type="checkbox">, có thể custom visual bằng CSS.
• Touch target: Vùng bấm tối thiểu 44×44px (iOS) — bao gồm cả label area.
• Indeterminate logic: Khi "Select All" checked → tất cả con checked. Khi bỏ → tất cả unchecked. Khi một phần → indeterminate.
• Không Hardcode: Mọi giá trị từ Token.
• Icon: Check mark (check), indeterminate dash (minus) CHỈ dùng Lucide icon từ assets/icons/. CẤM dùng text emoji. Xem icon.md mục 10.

8. Example Usage

{/* Single checkbox */}
<Checkbox label="Tôi đồng ý với Điều khoản sử dụng" />

{/* Checkbox group */}
<CheckboxGroup
  label="Chọn tính năng"
  showSelectAll
  options={[
    { value: 'qr', label: 'QR Pay', description: 'Thanh toán bằng mã QR' },
    { value: 'nfc', label: 'NFC', description: 'Thanh toán chạm' },
    { value: 'card', label: 'Thẻ liên kết' },
  ]}
  value={['qr', 'nfc']}
/>

{/* Error state */}
<Checkbox label="Tôi đồng ý" isError />