Navigation Menu

--- description: Hướng dẫn Agent tự động tạo UI Component Navigation Bar / Header dựa trên Design Tokens, có ngữ nghĩa chuẩn Material 3 & iOS HIG

Navigation Bar Component Generation Skill

Skill này hướng dẫn bạn (AI Agent) tạo component Navigation Bar / Header — thanh điều hướng chính nằm trên cùng mọi trang, chứa logo, nav links, và actions.

1. Mục tiêu (Objective)

Tạo component navigation-menu responsive, hỗ trợ sticky/transparent modes, mobile hamburger menu, và tích hợp 100% Design Tokens. Component phải tái sử dụng được trên mọi page.

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

Khi nào dùng navigation-menu?

• Mọi page: navigation-menu là component bắt buộc trên mọi trang
• Chứa brand identity: Logo, brand name
• Primary navigation: Links đến các section chính
• User actions: Search, notifications, user avatar/menu

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

Decision Tree cho AI

Cần navigation chính?
├─ Horizontal bar, top of page → navigation-menu
│   ├─ Transparent overlay trên hero → variant="transparent"
│   ├─ Sticky khi scroll → sticky={true}
│   └─ Mobile responsive → auto hamburger menu
├─ Vertical sidebar (dashboard) → Sidebar
├─ Breadcrumb path → Breadcrumb
└─ Bottom bar (mobile) → Bottom Navigation

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

3.1. Variants

3.2. Behavior

3.3. Layout Zones

┌─────────────────────────────────────────────────────┐
│  [Logo]    [Nav Item] [Nav Item] [Nav Item]    [search] [bell] [Avatar ▼]  │
│  ← Left              ← Center                     → Right           │
└─────────────────────────────────────────────────────┘

• Left zone: Logo/brand + optional hamburger (mobile)
• Center zone: Nav links (ẩn trên mobile → hamburger menu)
• Right zone: Action buttons (search, notifications, user menu)

3.4. Mobile Behavior

• Nav links ẩn → hamburger icon hiện
• Click hamburger → mở Drawer/Sheet từ trái hoặc full-screen overlay
• Active link indicator vẫn hiện trong mobile menu

3.4. Slot Map (Figma ↔ Code)

📎 Source: slot-manifest.json → navigation-menu · Layer: ground

4. Token Mapping

?? Atomic Mapping: Xem ATOMIC-MAPPING.md ? m?c navigation-menu. 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 navigation-menuProps {
  /** Visual variant */
  variant?: 'default' | 'transparent' | 'blur';
  /** Scroll behavior */
  behavior?: 'static' | 'sticky' | 'auto-hide';
  /** Height size */
  size?: 'sm' | 'md' | 'lg';
  /** Logo / brand element */
  logo?: ReactNode;
  /** Navigation items */
  children: ReactNode;
  /** Right-side action elements */
  actions?: ReactNode;
  /** Mobile breakpoint (px) — hide nav links, show hamburger */
  mobileBreakpoint?: number; // default 768
}

interface NavItemProps {
  /** Label text */
  label: string;
  /** Navigation target */
  href?: string;
  onClick?: () => void;
  /** Active state */
  active?: boolean;
  /** Leading icon */
  icon?: ReactNode;
  /** Submenu items (dropdown on hover/click) */
  children?: ReactNode;
}

6. Accessibility (a11y)

• Semantic HTML: Dùng <nav> element + aria-label="Main navigation".
• Active link: aria-current="page" cho trang hiện tại.
• Dropdown: Submenu phải có aria-expanded, aria-haspopup="menu".
• Mobile menu: Hamburger button phải có aria-label="Open menu" / "Close menu", aria-expanded.
• Keyboard: Tab di chuyển giữa nav items. Enter/Space activate link. Escape đóng dropdown/mobile menu.
• Skip link: Thêm "Skip to main content" link ẩn ở đầu navigation-menu — hiện khi Tab focus.
• Brand link: Logo nên wrap trong <a href="/"> với aria-label="Home".

7. Best Practices & Rules

• Không quá 7 nav items: Quá nhiều → gây cognitive overload. Dùng dropdown để nhóm.
• Sticky mặc định: Hầu hết enterprise apps nên sticky navigation-menu.
• Mobile-first: Design mobile menu trước, expand cho desktop.
• Z-index: navigation-menu có z-index cao hơn content nhưng thấp hơn modals/drawers.
• Transition smooth: Background thay đổi khi scroll (transparent → blur) phải smooth.
• Không Hardcode: Mọi giá trị từ Token.
• Dark Mode: Tự động qua Mode tokens.
• Icon: CHỈ dùng Lucide icon từ assets/icons/ cho search (search), notifications (bell), hamburger (menu). CẤM dùng text emoji. Xem icon.md mục 10.

8. Example Usage

{/* Default sticky navigation-menu */}
<navigation-menu behavior="sticky" logo={<Logo />} actions={
  <>
    <IconButton icon={<SearchIcon />} aria-label="Search" />
    <IconButton icon={<BellIcon />} aria-label="Notifications" />
    <Avatar src="/user.jpg" name="Ngọc Lê" size="sm" />
  </>
}>
  <NavItem label="Tổng quan" href="/dashboard" active />
  <NavItem label="Giao dịch" href="/transactions" />
  <NavItem label="Thẻ" href="/cards" />
  <NavItem label="Cài đặt" href="/settings" />
</navigation-menu>

{/* Transparent navigation-menu on hero */}
<navigation-menu variant="transparent" behavior="sticky">
  <NavItem label="Home" href="/" active />
  <NavItem label="Features" href="/features" />
  <NavItem label="Pricing" href="/pricing" />
</navigation-menu>