Prisma

Tooltip

Reference for Tooltip

Live Preview

Tooltip Component Generation Skill

Skill này hướng dẫn bạn (AI Agent) tạo component Tooltip — chú thích nổi khi hover/focus lên một element.

1. Mục tiêu (Objective)

Tạo component Tooltip hỗ trợ nhiều vị trí, delay, và rich content. Tích hợp 100% Design Tokens.

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

Khi nào dùng Tooltip?

  • Giải thích icon/button không có text label: icon-only buttons
  • Bổ sung context: Hover lên term → giải thích ngắn
  • Keyboard shortcut hint: Hover button → hiện shortcut

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

Tình huống Component đúng Lý do
Chú thích ngắn khi hover Tooltip Text-only, non-interactive
Nội dung phức tạp (links, buttons) Popover Interactive content
Dropdown menu Menu / Dropdown Action list
Form validation hint Helper text / Error trong Input Persistent, không hover
Thông báo nổi Toast Auto-dismiss notification

Decision Tree cho AI

text
Cần hiển thị thông tin phụ?
├─ Text ngắn, hover/focus → Tooltip
├─ Nội dung phức tạp (links, form) → Popover
├─ Danh sách actions → Menu / Dropdown
├─ Form field hint → Input helper text
└─ Thông báo tạm thời → Toast

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

3.1. Position

Position Mô tả Fallback
top Phía trên trigger (mặc định) bottom nếu không đủ space
bottom Phía dưới trigger top
left Bên trái trigger right
right Bên phải trigger left

3.2. Trigger

Trigger Platform
Hover Desktop Delay 200ms → show, delay 100ms → hide
Focus Keyboard Hiện khi focus, ẩn khi blur
Touch (long-press) Mobile Hiện khi long-press, ẩn khi release

3.4. Slot Map (Figma ↔ Code)

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

Figma Slot data-slot CSS Class Required Accepts
Root tooltip .tooltip ✅ —
Trigger tooltip-trigger — ✅ any-interactive-element
Content tooltip-content .tooltip-content ✅ text (max 2 lines)

4. Token Mapping

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

Token Type Value Mô tả
padding-x number {spacing.3}
padding-y number {spacing.2}
radius number {border-radius.md}
max-width number 224 Max tooltip width before wrapping
font-size number {font.size.xs}
font-weight number {font.weight.medium}
arrow-size number {spacing.2}
delay-show number 200 Delay before showing (ms)
delay-hide number 100 Delay before hiding (ms)
color.background color {base.surface-strong} Dark tooltip bg
color.foreground color {base.surface-strong-foreground} Light tooltip text
color.focus-ring color {focus.ring-color} Focus ring color — ref shared/focus
color.disabled-bg color {base.muted} Disabled state background
color.disabled-fg color {base.muted-foreground} Disabled state foreground
color.hover color {state-layer.hover} Hover state overlay — MD3 state layer pattern
elevation shadow {shadow.sm}
z-index number {z-index.tooltip}
transition string {duration.fast-2} {easing.standard} Fade in/out

5. Props & API

typescript
interface TooltipProps {
  /** Nội dung tooltip */
  content: string;
  /** Vị trí ưu tiên */
  position?: 'top' | 'bottom' | 'left' | 'right';
  /** Delay trước khi hiện (ms) */
  delayShow?: number; // default 200
  /** Delay trước khi ẩn (ms) */
  delayHide?: number; // default 100
  /** Có hiện arrow chỉ hướng */
  hasArrow?: boolean; // default true
  /** Trigger element */
  children: ReactNode;
}

6. Accessibility (a11y)

  • ARIA: Trigger phải có aria-describedby trỏ đến tooltip ID.
  • Role: Tooltip element có role="tooltip".
  • Keyboard: Tooltip hiện khi trigger nhận focus, ẩn khi blur hoặc Escape.
  • Escape: Nhấn Escape phải dismiss tooltip.
  • Không interactive: Tooltip content KHÔNG có link/button — dùng Popover nếu cần.
  • Accessible name: Icon-only button vẫn cần aria-label riêng, tooltip chỉ bổ sung.

7. Best Practices & Rules

  • Ngắn gọn: Tooltip text nên ≤ 1–2 câu ngắn. Nội dung dài → dùng Popover.
  • Không essential info: Tooltip ẩn mặc định — không đặt thông tin bắt buộc trong tooltip.
  • Delay: Luôn có delay hiện (200ms) để tránh flash khi di chuột ngang qua.
  • Auto-flip: Tự động đổi vị trí khi không đủ viewport space.
  • Portal: Render qua Portal để tránh overflow hidden.
  • Không Hardcode: Mọi giá trị từ Token.

8. Example Usage

jsx
{/* Icon button with tooltip */}
<Tooltip content="Sao chép">
  <Button variant="ghost" size="sm" aria-label="Sao chép">
    <CopyIcon />
  </Button>
</Tooltip>

{/* With shortcut hint */}
<Tooltip content="Tìm kiếm (Ctrl+K)" position="bottom">
  <Button variant="ghost" leftIcon={<SearchIcon />}>Search</Button>
</Tooltip>

{/* On text */}
<Tooltip content="Tổng doanh thu trong 30 ngày qua">
  <span style={{ borderBottom: '1px dashed' }}>Doanh thu</span>
</Tooltip>
© 2026 VNPay JSC · Mar 16, 2026