shkim4/HMDesign
Private
Public Access
1
0 Fork 0
Code Activity
Files
1dd8fb3aad69eee8faa799cce99e2c17411e42e2
HMDesign/docs/components/tooltip.md
T

6.0 KiB
Raw Blame History

Tooltip

현재 HM 구현의 기준 문서. 공통 원칙은 docs/guidelines/프로젝트-지침.md(§6, §7), Token 구조 원칙은 테마-토큰-가이드.md를 따른다. 이 문서는 Tooltip 고유의 API·Token·상태·결정만 기록한다.

1. 상태

항목 내용
구현 상태 구현 완료 (현재 HM 규격)
기준일 2026-10-02
기반 shadcn/ui Tooltip (Radix Tooltip)
대표 Story Components/Overlay/Tooltip → All (이름 "Tooltip")
보류 아래 §11

2. 적용 근거

  • 참고 근거: 외부 ui_viz Reference (ZIP 미포함)의 기존 테스트 규격에는 Tooltip 규격이 없다(인벤토리 "상세 동작·디자인 보류"). 참고할 수치가 없었다.
  • 현재 HM 규격: 아래 §3~§4. 현재 HM Semantic 체계(fg-primary, text-inverse)로 새로 정했다.
  • 구현 방식: shadcn / Radix Tooltip 구조(Provider, Root, Trigger, Content, Arrow)를 유지하고 theme CSS로 HM 스타일을 연결.
  • 보류: §11.

3. 기본 규격 (현재 HM 규격)

항목 값
Background --hm-sem-fg-primary (진한 녹색)
Text --hm-color-text-inverse (White)
Radius --hm-radius-container (4px)
Padding 6px 10px
Max width 240px, 긴 문장은 줄바꿈(text-balance, overflow-wrap: anywhere)
Typography 12 / 18 / 400
Arrow shadcn 회전 사각형, 면과 같은 색(배경·fill)
Position sideOffset 4, shadcn 기본 side(top)
Delay TooltipProvider delayDuration 기본 0 (shadcn 기본 유지)

Tooltip은 짧고 즉각적인 설명만 담는다. 긴 설명·interactive 콘텐츠는 Popover / Hover Card를 쓴다. 그림자와 border는 없다.

4. 상태 규격

상태 값
Open / Closed Radix data-state(delayed-open 포함), shadcn open/close animation
열림 조건 trigger hover 또는 keyboard focus
닫힘 조건 pointer leave, blur, Escape, trigger 클릭

5. API

Radix Tooltip props 그대로. export: TooltipProvider, Tooltip, TooltipTrigger, TooltipContent.

  • Tooltip은 상위 HM TooltipProvider가 없을 때만 자체 Provider를 만든다. 단독 사용은 그대로 지원하며 기본 delayDuration은 0이다.
  • 그룹에는 @hm-design/ui의 TooltipProvider를 둔다. 내부 Provider를 추가하지 않아 가장 가까운 Provider의 delayDuration, skipDelayDuration, disableHoverableContent와 그룹의 skip-delay 상태를 공유한다. Radix Provider를 직접 사용하는 대신 HM Provider를 사용한다.
  • 개별 Tooltip delayDuration은 Provider의 delay를 override한다. skipDelayDuration은 Provider에서 지정하며, skip 구간의 다음 Tooltip은 즉시 열린다. skipDelayDuration={0}이면 각 hover에 delay가 적용된다. keyboard focus는 delay 없이 열리고 Escape로 닫힌다.
  • TooltipContent: sideOffset 기본 4. 출력 속성: data-slot="tooltip-*", Radix data-state·data-side. Arrow는 data-slot="tooltip-arrow".
<TooltipProvider delayDuration={700} skipDelayDuration={300}>
  <Tooltip>
    <TooltipTrigger asChild><button>저장</button></TooltipTrigger>
    <TooltipContent>변경 사항을 저장합니다</TooltipContent>
  </Tooltip>
  {/* 같은 Provider 아래의 Tooltip은 skip-delay 상태를 공유한다. */}
</TooltipProvider>

6. Token

Component Mapping 위치: packages/ui/src/theme/tooltip.css (--hm-tooltip-*).

background, text, radius, padding-x, padding-y, max-width, font-size, line-height, font-weight. 다른 컴포넌트의 Component Token을 참조하지 않는다. 신규 Primitive 없음.

7. shadcn / Radix에서 유지한 항목

Radix 구조·ARIA(role=tooltip, aria-describedby)·Escape·hover/focus 동작, Provider 구조와 delay, Portal·positioning·collision, data-slot, cn(..., className), animation class, z-50, Arrow.

8. HM에서 변경한 항목

  • shadcn bg-foreground text-background rounded-md px-3 py-1.5 text-xs 및 arrow의 bg-foreground fill-foreground class 제거 → theme CSS.
  • 최대 폭 240px 추가(shadcn은 w-fit만 있어 긴 문장 한계가 없었다).

9. Storybook

  • 대표 Story All("Tooltip"): 기본, 긴 텍스트, 비활성 버튼(wrapper trigger), 4방향 placement 비교.
  • verification: Open(열린 상태).
  • interactive control은 넣지 않는다.

10. 사용자 확정 결정

  • 2026-10-02: ui-viz는 참고 자료이며 최종 기준은 현재 HM 구현과 이 문서다(작업 지시). 개별 수치에 대한 별도 결정은 없다.

11. 미확정 / 보류

  • 수치(240px, padding, 12px 글자)는 현재 HM 규격이며 디자인 확정 시 재검토.
  • delay: shadcn 기본 0 유지. HM delay 규칙은 없다.
  • Motion 규칙은 정의되지 않아 shadcn 기본 animation 유지.
  • 비활성 control에 붙이는 방식은 소비 조합(wrapper element).

12. 관련 파일

packages/ui/src/components/ui/tooltip.tsx
packages/ui/src/theme/tooltip.css
packages/ui/src/theme.css            (import)
packages/ui/src/index.ts             (export)
src/components/tooltip.stories.tsx

13. 검증 상태

  • 2026-10-08: 공개 패키지 빌드·타입 검사 통과. Browser에서 mouse PointerEvent로 단독 사용, 상위/중첩 HM Provider delay, Root override, 그룹 skip-delay·만료·0 설정과 pointer leave를 검증했다. 실제 키보드로 focus·blur·Escape, controlled open/onOpenChange, asChild·ref, 비활성 wrapper를 확인했다. 주요 computed style은 수정 전과 동일하다. 실제 마우스 이동을 통한 hover는 별도 미검증이다.
  • npm run typecheck, npm run build: 통과(2026-10-02).
  • 실제 interaction(Browser pane): keyboard focus로 열림(role=tooltip 확인), Escape 닫힘.
  • computed style: bg rgb(10,34,29), text white, radius 4px, padding 6px 10px, 12/18, arrow fill 같은 색.
  • 미확인: 실제 pointer hover 열림·pointer leave 닫힘, 긴 텍스트 줄바꿈 시각, 4방향 placement 시각, 비활성 wrapper trigger.
View Git Blame Copy Permalink