Radio

Radio Component Generation Skill

Skill này hướng dẫn bạn (AI Agent) tạo component Radio / Radio Group — điều khiển cho phép chọn DUY NHẤT một giá trị trong nhóm.

1. Mục tiêu (Objective)

Tạo component Radio Group hoàn chỉnh, đảm bảo mutual exclusivity (chỉ 1 option được chọn), hỗ trợ orientation, và tích hợp 100% Design Tokens.

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

Khi nào dùng Radio?

• Chọn DUY NHẤT 1 từ nhóm 2–5 options
• User cần thấy tất cả options cùng lúc để so sánh
• Trong form (giá trị được submit cùng form)

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

Decision Tree cho AI

User cần chọn 1 từ nhóm?
├─ 2–5 options, cần thấy hết → Radio Group
├─ > 5 options → Select (single)
├─ 2 options dạng toggle → Switch
├─ 2–3 options, inline switching → Segmented Control / Tabs
└─ Cần chọn nhiều → Checkbox Group

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

3.1. Radio States

3.2. Radio Group Variants

• Default: Vertical stack, radio + label.
• Card Radio: Mỗi option là 1 card có border, selected state highlight — dùng khi option cần mô tả chi tiết (vd: chọn gói cước).

3.5. Slot Map (Figma ↔ Code)

📎 Source: slot-manifest.json → radio · 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 RadioGroupProps {
  /** Label của group */
  label?: string;
  /** Options */
  options: { value: string; label: string; description?: string; disabled?: boolean }[];
  /** Value đã chọn */
  value?: string;
  /** Orientation */
  orientation?: 'vertical' | 'horizontal';
  /** Visual variant */
  variant?: 'default' | 'card';
  /** Size */
  size?: 'sm' | 'md' | 'lg';
  /** Error message */
  errorMessage?: string;
  /** onChange callback */
  onChange?: (value: string) => void;
}

6. Accessibility (a11y)

• Role: Dùng <input type="radio"> native với cùng name attribute.
• Group: Wrap trong <fieldset> + <legend>, hoặc role="radiogroup" + aria-labelledby.
• Keyboard: Arrow Up/Down hoặc Arrow Left/Right chuyển giữa options (roving tabindex), Tab ra ngoài group.
• Required: aria-required="true" trên group nếu bắt buộc.
• Error: aria-invalid="true" + aria-describedby cho error message.

7. Best Practices & Rules

• Semantic HTML: Dùng native <input type="radio">, custom visual bằng CSS.
• Mutual exclusivity: Chỉ cho phép 1 selection. Cùng name attribute.
• Default selection: Thường nên có 1 option selected mặc định — tránh dùng Radio khi không cần mặc định.
• Touch target: Vùng bấm ≥ 44×44px bao gồm label.
• Không Hardcode: Mọi giá trị từ Token.

8. Example Usage

{/* Basic radio group */}
<RadioGroup
  label="Phương thức thanh toán"
  options={[
    { value: 'qr', label: 'QR Pay' },
    { value: 'card', label: 'Thẻ liên kết' },
    { value: 'bank', label: 'Chuyển khoản ngân hàng' },
  ]}
  value="qr"
/>

{/* Card variant */}
<RadioGroup
  variant="card"
  label="Chọn gói cước"
  options={[
    { value: 'basic', label: 'Basic', description: 'Miễn phí, giới hạn 5 giao dịch/ngày' },
    { value: 'pro', label: 'Pro', description: '99.000đ/tháng, không giới hạn' },
  ]}
/>