Tooltip

보조 설명을 제공하되 필수 정보나 행동을 숨기지 않습니다.

목적

Tooltip은 control의 짧은 이름이나 보충 설명을 hover와 keyboard focus에서 보여준다. 화면을 장식하지 않고 필요한 순간에만 의미를 밝혀 주며, 기존 label을 대체하지 않는다.

선택 기준

icon-only Button의 보이는 이름을 보충하거나 낯선 기능을 짧게 설명할 때 사용한다.
사용자가 반드시 읽어야 하는 도움말은 화면에 직접 표시한다.
여러 문장, link, form control이 필요하면 Popover를 사용한다.
touch에서만 사용하는 핵심 기능을 Tooltip에 의존하지 않는다.

실제 패키지 렌더링

기본 사용 예시

예시 데이터

구조

관련 영역을 TooltipProvider로 감싼다. 각 Tooltip은 Tooltip, TooltipTrigger, TooltipContent로 구성한다. 기존 Button이나 Link를 trigger로 사용할 때 TooltipTrigger asChild를 사용해 중복 interactive element를 만들지 않는다. Content는 theme 경계 안의 portal을 자동으로 사용한다.

변형과 크기

TooltipContent의 기본 sideOffset은 4px이다. 배경은 primary, 글자는 primary foreground, padding은 좌우 12px·상하 6px, 글자 크기는 12px이다. 기반 content의 side, align, 충돌 처리 props를 전달할 수 있다.

Provider의 delay 관련 props로 앱 단위 노출 시간을 조정할 수 있다. SidebarProvider는 내부 TooltipProvider를 이미 제공한다.

상태와 동작

Trigger의 hover 또는 focus에 반응해 열리고 pointer가 떠나거나 focus가 이동하면 닫힌다. 등장과 퇴장에는 짧은 방향 motion이 적용된다. Tooltip 안에 interactive content를 넣지 않는다.

콘텐츠

한 문장보다 짧은 이름이나 설명을 사용한다. 설정보다 발행 설정 열기처럼 control 결과를 말한다. 보이는 label이 이미 충분하면 같은 text를 반복하는 Tooltip을 추가하지 않는다.

접근성

Tooltip은 aria-label을 대신하지 않는다. icon-only Button에는 접근 가능한 이름을 별도로 제공한다. keyboard focus에서도 같은 내용이 보여야 하고 focus indicator를 제거하지 않는다. 중요한 오류, 입력 조건, 상태 변화는 Tooltip 밖에 항상 보이게 둔다.

좁은 화면과 긴 콘텐츠

touch 환경에서는 hover가 없으므로 핵심 정보가 Tooltip에만 있으면 안 된다. 긴 text가 viewport를 가로지르면 문구를 줄이거나 Popover와 inline help로 옮긴다. 화면 가장자리에서 Content가 잘리지 않는지 확인한다.

공개 API

TooltipProvider: 여러 Tooltip의 delay와 전역 동작 범위
Tooltip: root
TooltipTrigger: trigger; 기존 control에는 asChild 사용
TooltipContent: sideOffset={4}가 기본인 content

portal은 Content 내부에서 사용되며 별도 public export가 아니다.

예제

import {
  Button,
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from '@classum/dot-design-system/ui';

export function CompactAction() {
  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <Button size="icon" variant="ghost" aria-label="필터 초기화">
            ↺
          </Button>
        </TooltipTrigger>
        <TooltipContent>필터 초기화</TooltipContent>
      </Tooltip>
    </TooltipProvider>
  );
}

피해야 할 사용

Tooltip을 Label, 오류 문구, 접근 가능한 이름 대신 사용하지 않는다.
link나 Button 같은 interactive content를 Tooltip 안에 넣지 않는다.
이미 보이는 text를 그대로 반복하지 않는다.
touch 사용자가 알아야 하는 정보를 hover에만 숨기지 않는다.
긴 설명이나 여러 단계를 작은 Tooltip에 넣지 않는다.

목적