Avatar

Avatar Component Generation Skill

Skill này hướng dẫn bạn (AI Agent) tạo component Avatar — hiển thị ảnh đại diện user hoặc entity, có fallback initials/icon.

1. Mục tiêu (Objective)

Tạo component Avatar hỗ trợ image, initials fallback, icon fallback, multiple sizes, status indicator, và group stacking. Tích hợp 100% Design Tokens.

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

Khi nào dùng Avatar?

• Đại diện user: profile picture, comment author, chat participant
• Đại diện entity: team, organization, workspace
• Danh sách user: member list, participant list (Avatar Group)

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

Decision Tree cho AI

Cần hiển thị đại diện?
├─ User / person → Avatar (image hoặc initials)
├─ Team / organization → Avatar (icon hoặc initials)
├─ Nhóm users → Avatar Group (stacked)
├─ Ảnh sản phẩm → Image component
└─ Brand logo → Image/Logo component

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

3.1. Content Priority (Fallback chain)

1. Image (src provided + loads successfully)
   ↓ Image load fails
2. Initials (từ name: "Ngọc Lê" → "NL")
   ↓ Không có name
3. Icon fallback (user icon mặc định)

3.2. Sizes

3.3. Shape

• Circle (mặc định): Dùng cho user avatars.
• Rounded square: Dùng cho workspace/organization/bot.

3.4. Status Indicator

Badge nhỏ góc dưới-phải hiển thị trạng thái:

3.5. Slot Map (Figma ↔ Code)

📎 Source: slot-manifest.json → avatar · 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 AvatarProps {
  /** Image source URL */
  src?: string;
  /** Alt text (accessibility) */
  alt?: string;
  /** User/entity name — dùng cho initials fallback */
  name?: string;
  /** Size preset */
  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
  /** Shape */
  shape?: 'circle' | 'square';
  /** Online status indicator */
  status?: 'online' | 'offline' | 'busy' | 'away';
  /** Custom fallback icon */
  fallbackIcon?: ReactNode;
}

interface AvatarGroupProps {
  /** Max avatars visible — vượt quá hiện "+N" */
  max?: number;
  /** Size applied to all children */
  size?: AvatarProps['size'];
  /** Children = Avatar components */
  children: ReactNode;
}

6. Accessibility (a11y)

• Alt text: <img> phải có alt mô tả (vd: alt="Ngọc Lê's avatar").
• Initials: Container cần role="img" + aria-label="[Name]".
• Status: Status dot cần aria-label (vd: aria-label="Online").
• Group: Avatar Group cần role="group" + aria-label="Team members".
• "+N" counter: Cần aria-label="and N more members".

7. Best Practices & Rules

• Initials algorithm: Lấy ký tự đầu của 2 từ đầu tiên, uppercase. "Ngọc Lê" → "NL", "Admin" → "A".
• Image loading: Hiện initials/icon TRƯỚC, khi image load xong mới swap — tránh layout shift.
• Group stacking: Dùng negative margin + z-index tăng dần + border ring trắng.
• Không Hardcode: Mọi giá trị từ Token.
• Responsive: Size có thể thay đổi theo breakpoint.

8. Example Usage

{/* With image */}
<Avatar src="/avatar.jpg" name="Ngọc Lê" size="lg" status="online" />

{/* Initials fallback */}
<Avatar name="Ngọc Lê" size="md" />
{/* → Hiển thị "NL" */}

{/* Icon fallback */}
<Avatar size="md" />
{/* → Hiển thị user icon mặc định */}

{/* Avatar group */}
<AvatarGroup max={3} size="sm">
  <Avatar src="/a.jpg" name="User A" />
  <Avatar src="/b.jpg" name="User B" />
  <Avatar name="User C" />
  <Avatar name="User D" />
  <Avatar name="User E" />
</AvatarGroup>
{/* → Hiển thị 3 avatars + "+2" */}