Breadcrumb

--- description: Hướng dẫn Agent tự động tạo UI Component Breadcrumb dựa trên Design Tokens

Breadcrumb Component Generation Skill

Skill này hướng dẫn bạn (AI Agent) tạo component Breadcrumb — trail hiển thị vị trí hiện tại trong hierarchy trang.

1. Mục tiêu (Objective)

Tạo component Breadcrumb hỗ trợ auto-truncation, custom separators, và tích hợp 100% Design Tokens. Web-specific nhưng critical cho enterprise navigation.

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

Khi nào dùng Breadcrumb?

• Multi-level navigation: Khi page nằm sâu > 2 levels
• E-commerce: Home > Category > Sub-category > Product
• Admin panel: Dashboard > Users > User Detail > Edit
• File browser: Root > Folder > Sub-folder

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

Decision Tree cho AI

Cần hiển thị vị trí trong site hierarchy?
├─ Page nằm sâu > 2 levels → Breadcrumb
├─ Dashboard sections → Breadcrumb (optional)
├─ Single-level pages → Không cần
└─ Mobile → Cân nhắc giản lược (chỉ "← Back to [Parent]")

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

3.1. Anatomy

Home  /  Products  /  Electronics  /  Smartphones  /  iPhone 16
 ↑        ↑            ↑               ↑               ↑
link     link         link            link          current (not clickable)

3.2. Separator Types

3.3. Truncation (khi quá nhiều items)

Trước: Home / Products / Electronics / Smartphones / Apple / iPhone 16
Sau:   Home / ... / Apple / iPhone 16
              ↑
         Click "..." → dropdown hiện full path

• Giữ đầu (Home/root) + cuối (2 items cuối)
• Items giữa collapse thành "..." (dropdown)

3.4. Slot Map (Figma ↔ Code)

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

4. Token Mapping

?? Atomic Mapping: Xem ATOMIC-MAPPING.md ? m?c breadcrumb. Component token JSON files d� deprecated.

Semantic color tokens (qua Mode layer) và state-specific colors được define đầy đủ trong file .tokens.json.

5. Props & API

interface BreadcrumbProps {
  /** Breadcrumb items */
  items: BreadcrumbItem[];
  /** Separator type */
  separator?: 'chevron' | 'slash' | 'arrow' | 'dot' | ReactNode;
  /** Max visible items before truncation (default 4) */
  maxItems?: number;
  /** Custom className */
  className?: string;
}

interface BreadcrumbItem {
  /** Label text */
  label: string;
  /** Navigation URL (undefined = current page, not clickable) */
  href?: string;
  /** Leading icon */
  icon?: ReactNode;
}

6. Accessibility (a11y)

• Semantic HTML: Wrap trong <nav aria-label="Breadcrumb">. Dùng <ol> ordered list.
• Current page: Item cuối cùng có aria-current="page" — KHÔNG phải link.
• Separator: Separator là decorative → thêm aria-hidden="true".
• Truncation: "..." phải có aria-label="Show more breadcrumbs".
• Keyboard: Tab focus vào các link items.
• Screen reader: Đọc tuần tự: "Breadcrumb. Home link, Products link, current page: iPhone 16".

7. Best Practices & Rules

• Luôn bắt đầu từ Home/Root: Item đầu tiên là gốc.
• Item cuối không clickable: Trang hiện tại = text thường, không phải link.
• Không dùng cho step/process: Breadcrumb = location, Stepper = process.
• Mobile: Cân nhắc chỉ hiện "← [Parent]" link thay vì full breadcrumb.
• Max depth: Nếu > 5 levels → auto truncation.
• Không Hardcode: Mọi giá trị từ Token.
• Icon: Separator icon (chevron-right) và Home icon (home) CHỈ dùng Lucide icon từ assets/icons/. CẤM dùng text emoji. Xem icon.md mục 10.

8. Example Usage

{/* Simple breadcrumb */}
<Breadcrumb items={[
  { label: 'Trang chủ', href: '/', icon: <HomeIcon /> },
  { label: 'Giao dịch', href: '/transactions' },
  { label: 'Chi tiết giao dịch' },
]} />

{/* With truncation */}
<Breadcrumb
  maxItems={3}
  separator="slash"
  items={[
    { label: 'Home', href: '/' },
    { label: 'Products', href: '/products' },
    { label: 'Electronics', href: '/products/electronics' },
    { label: 'Smartphones', href: '/products/electronics/phones' },
    { label: 'iPhone 16' },
  ]}
/>
{/* → Home / ... / Smartphones / iPhone 16 */}