Toast

Toast Component Generation Skill

Skill này hướng dẫn bạn (AI Agent) tạo component Toast / Notification — thông báo tạm thời tự động dismiss.

1. Mục tiêu (Objective)

Tạo component Toast (single) + Toast Container (stacking), hỗ trợ auto-dismiss, manual close, action button, và tích hợp 100% semantic color tokens.

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

Khi nào dùng Toast?

• Feedback ngắn sau action: "Đã lưu!", "Đã copy link!", "Gửi thành công"
• Error tạm thời: "Không thể kết nối"
• Undo feedback: "Đã xoá. Hoàn tác?"

⚠️ Phân biệt Toast vs Alert vs Modal (QUAN TRỌNG)

Decision Tree cho AI

Cần thông báo?
├─ Feedback tạm thời sau action → Toast
│   ├─ Thành công → variant="success"
│   ├─ Lỗi có thể retry → variant="destructive" + action
│   ├─ Cảnh báo nhẹ → variant="warning"
│   └─ Info trung lập → variant="default"
├─ Info persistent trên page → Alert
├─ Cần action bắt buộc → Modal
└─ Cần user confirm → Modal (alert dialog)

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

3.1. Variants

3.2. Position (Container level)

3.3. Stacking

• Nhiều toast xếp chồng (stack), toast mới ở trên.
• Max visible: 3–5 toasts. Cũ nhất tự dismiss khi vượt quá.

3.4. Slot Map (Figma ↔ Code)

📎 Source: slot-manifest.json → toast · Layer: surface

4. Token Mapping

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

5. Props & API

// Toast function API (imperative)
interface ToastOptions {
  /** Severity variant */
  variant?: 'default' | 'success' | 'warning' | 'destructive' | 'info';
  /** Title text */
  title: string;
  /** Description/body */
  description?: string;
  /** Auto-dismiss duration (ms). 0 = persistent */
  duration?: number; // default: 4000
  /** Action button */
  action?: {
    label: string;
    onClick: () => void;
  };
  /** Show close button */
  closable?: boolean; // default: true
  /** Show progress bar (auto-dismiss indicator) */
  showProgress?: boolean;
}

// Usage: toast({ variant: 'success', title: 'Saved!' })
// Or: toast.success('Saved!')

// Container component
interface ToastContainerProps {
  /** Position on screen */
  position?: 'top-right' | 'top-center' | 'bottom-right' | 'bottom-center';
  /** Max visible toasts */
  maxVisible?: number; // default: 5
}

6. Accessibility (a11y)

• Role: role="status" + aria-live="polite" (info/success). role="alert" + aria-live="assertive" (error/warning).
• Screen reader: Nội dung toast phải được announce tự động.
• Close button: aria-label="Dismiss notification".
• Auto-dismiss: Pause timer khi hover hoặc focus (cho user đọc).
• Keyboard: Tab focus vào action/close button. Escape dismiss focused toast.
• Focus không bị steal: Toast xuất hiện KHÔNG steal focus từ user's current task.
• Reduced motion: Respect prefers-reduced-motion — giảm/tắt animation.

7. Best Practices & Rules

• Imperative API: Toast dùng function call (toast.success(...)) — KHÔNG dùng JSX render.
• Container singleton: Chỉ 1 <ToastContainer /> render ở root app.
• Duration: Success 3–4s, Error 5–8s (user cần đọc lỗi), info 4s.
• Persistent error: Error quan trọng NÊN có duration: 0 (phải manual close).
• Undo pattern: "Đã xoá. [Hoàn tác]" — action button + 5s timer.
• Stacking: Toast mới xuất hiện phía trên, cũ di chuyển xuống.
• Không Hardcode: Mọi giá trị từ Token.
• Progress bar: Thanh tiến trình hiện thời gian còn lại trước khi auto-dismiss.
• Icon: CHỈ dùng Lucide icon từ assets/icons/ (xem icon.md mục 10). CẤM dùng text emoji.

8. Example Usage

{/* Render container once at root */}
<ToastContainer position="top-right" maxVisible={5} />

{/* Imperative calls */}
toast.success('Đã lưu thành công!')

toast({
  variant: 'destructive',
  title: 'Lỗi kết nối',
  description: 'Không thể kết nối đến máy chủ.',
  duration: 8000,
  action: { label: 'Thử lại', onClick: retry },
})

toast({
  variant: 'default',
  title: 'Đã xoá giao dịch',
  action: { label: 'Hoàn tác', onClick: undo },
  duration: 5000,
})

toast.info('Có bản cập nhật mới!')