Lead Icon

Lead Icon Component Generation Skill

📦 Atomic Mapping: See ATOMIC-MAPPING.md for complete token spec.

Skill này hướng dẫn bạn (AI Agent) tạo component Lead Icon — icon đứng trước nội dung (leading position) trong list, card, navigation, với optional container (circle/square).

1. Mục tiêu (Objective)

Tạo leading icon component hỗ trợ naked (bare icon) và contained (icon trong circle/square bg), 5 sizes, 7 semantic colors, density-aware radius. Tích hợp 100% Design Tokens.

2. AI Context & Intent

Khi nào dùng Lead Icon?

• List items: Settings, navigation, action lists — icon trước title
• Card headers: Metric cards, feature cards — icon trước heading
• Navigation: Sidebar, bottom nav — icon trước label
• Status indicators: Colored circle icon for states

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

Quan hệ với ds-icon

ds-icon        → Raw SVG wrapper (size + color only, NO container)
ds-leadicon    → Icon + optional bg container (size + color + bg + shape)
                 ↳ Inner SVG inherits ds-icon stroke behavior

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

3.1. Modes

3.2. Shapes (Contained only)

3.3. Sizes

3.4. Semantic Colors

4. CSS Classes

5. Props & API

interface LeadIconProps {
  /** Lucide icon element */
  icon: ReactNode;
  /** Size preset */
  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
  /** Shape */
  shape?: 'circle' | 'square';
  /** Mode */
  mode?: 'contained' | 'naked';
  /** Semantic color */
  color?: 'primary' | 'primary-muted' | 'destructive' | 'destructive-muted' | 'success' | 'success-muted' | 'warning' | 'warning-muted' | 'info' | 'info-muted' | 'muted';
}

6. Accessibility

• aria-hidden="true" on icon if decorative (label text adjacent)
• role="img" + aria-label if icon IS the label
• SVG uses stroke: currentColor for auto color inheritance

7. Best Practices

• Strictly Lucide Icons — NO emoji, NO external icons
• No hardcode — ALL sizes/colors from tokens
• Square radius = density — uses var(--comp-radius), NOT var(--radius-md)
• Layer-neutral — ds- prefix, works at any elevation
• Consistent sizing — same size across all items in a list group

8. Example Usage

<!-- iOS Settings: square, sm, colored bg -->
<span class="ds-leadicon ds-leadicon--sm ds-leadicon--square ds-leadicon--primary">
  <svg><!-- lucide wifi --></svg>
</span>

<!-- Card header: circle, lg -->
<span class="ds-leadicon ds-leadicon--lg ds-leadicon--success">
  <svg><!-- lucide trending-up --></svg>
</span>

<!-- Action list: naked, md -->
<span class="ds-leadicon ds-leadicon--naked ds-leadicon--destructive">
  <svg><!-- lucide trash --></svg>
</span>

9. Anatomy

┌─────────────────────────┐
│  Container (Circle/Sq)  │  ← width/height: --spacing-{size}
│  ┌─────────────────┐    │  ← border-radius: --radius-full (circle)
│  │                 │    │     or --comp-radius (square, density-aware)
│  │    SVG Icon     │    │  ← width/height: --icon-{sm|md|lg}
│  │   (Lucide)      │    │  ← stroke: currentColor (inherits fg)
│  │                 │    │
│  └─────────────────┘    │
│                         │  ← background: semantic color token
│                         │  ← color (fg): paired semantic foreground
└─────────────────────────┘

Naked mode: Container bg = transparent, fg = semantic color directly

2 layers: Container (sizing + bg + radius) → SVG Icon (inner sizing + fg inheritance).
No internal padding token — icon centering via align-items: center + justify-content: center.

10. Style Decision Matrix — Khi nào dùng style nào

Rule: Chọn sai style = hỏng visual hierarchy. Bảng dưới đây là MANDATORY cho Agent.

10.1. Mode: contained vs naked

10.2. Shape: circle vs square

10.3. Color: solid vs muted

Decision rule: Solid = one-time emphasis, CTA, confirmation. Muted = persistent, informational, repeated list items.

10.4. Size selection

Consistency rule: Cùng một list group → PHẢI dùng cùng size. KHÔNG mix sizes trong cùng list.

11. States

Lead Icon là decorative component — KHÔNG có interactive states nội tại.

Nếu icon CẦN click riêng → Wrap trong <button> hoặc <a>, KHÔNG thêm interactive states vào .ds-leadicon.

12. Do / Don't

13. Content Guidelines — Icon Choice

Stroke style

• LUÔN dùng Lucide stroke icons — từ assets/icons/
• KHÔNG dùng filled icons — filled icons clash với muted bg (không đủ contrast khi icon + bg cùng color family)
• Exception: circle, square, triangle — geometric shapes OK filled

Icon meaning

• Icon phải self-explanatory OR có text label adjacent (C4: color alone không đủ)
• Mỗi icon chỉ đại diện 1 concept — không reuse cùng icon cho 2 ý nghĩa khác nhau trong cùng screen
• Ưu tiên metaphor phổ biến: trash = delete, settings = gear, wifi = signal, bell = notification

Sizing consistency

• Container-to-icon ratio luôn giữ consistent: container ≈ 1.3–1.6× icon
• Icon inner size tự scale theo size preset — KHÔNG override inner icon size manually