Tooltip

한눈에#

트리거 위에 뜨는 짧은 텍스트 힌트입니다 — hover는 400ms 지연, focus는 즉시 표시하며 role="tooltip" + aria-describedby로 연결됩니다.

hover 또는 Tab 포커스로 실제 힌트를 띄워 보세요:

사용 시점#

아이콘 버튼·축약 라벨에 짧은 보조 설명을 덧붙이면 Tooltip — 링크·버튼 등 상호작용이 필요하면 Popover입니다.

플레이그라운드#

컨트롤로 props를 조작하면 미리보기와 코드가 실시간 갱신됩니다.

import { Tooltip, Button } from '@wds/ui-web';

<Tooltip content="최근 7일 평균"><Button>호버하세요</Button></Tooltip>

변형#

variant로 두 형태를 지원합니다 (ADR-012 B-P1).

• plain(기본) — 짧은 텍스트 힌트(content 한 줄)
• rich — title(제목) + content(본문) 구조 카드. 더 넓고 좌측 정렬

색은 텍스트/배경 토큰을 반전해(color.text 배경 + color.bg 글자) 라이트/다크 모두 대비를 확보합니다. 버블은 hover 가능(pointer-events: auto)하지만 role="tooltip"은 텍스트 보조 설명 용도이므로, 버튼·링크 등 인터랙티브 콘텐츠가 필요하면 Popover를 쓰세요(rich도 텍스트 전용).

크기#

단일 크기입니다 — caption 타이포 + 최대 폭 16rem(긴 문구는 줄바꿈).

상태#

• Hover — HOVER_SHOW_DELAY_MS(400ms) 지연 후 표시 — 스치는 마우스 과발화 방지
• Focus — 지연 없이 즉시 표시
• 호버 유지 — leave 후 HOVER_HIDE_GRACE_MS(120ms) 유예를 둬, 포인터가 트리거→버블로 넘어가면 버블 진입이 유예를 취소합니다 — 내용 위에 머물 수 있습니다(WCAG 1.4.13)
• 숨김 — 트리거·버블 양쪽에서 벗어난 뒤(유예 경과) · blur · Escape

Props#

접근성#

• role="tooltip" + 표시 중 트리거에 aria-describedby 주입 — 트리거가 단일 요소일 때만 가능하므로 단일 포커서블 요소를 권장합니다
• 키보드 사용자는 포커스만으로 즉시 볼 수 있습니다(지연 없음)
• Escape로 닫기 — 포커스/호버 위치 무관(WCAG 1.4.13 Dismissable)
• Hoverable(WCAG 1.4.13) — 버블은 pointer-events: auto라, 트리거에서 버블로 포인터를 옮겨도 사라지지 않습니다(leave는 짧은 유예 후 숨김)
• 툴팁은 이름이 아니라 설명입니다 — 아이콘 버튼의 접근성 이름은 aria-label로 따로 부여하세요
• 등장 모션은 prefers-reduced-motion 존중

토큰#

component 토큰 없이 semantic을 직접 소비합니다(신설 기준 §4 미충족).