shkim4/HMDesign
Private
Public Access
1
0 Fork 0
Code Activity
Files
65bc13404570d17af64e8d2710ebfe564e4628c8
HMDesign/docs/components/hover-card.md
T

4.7 KiB
Raw Blame History

Hover Card

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

1. 상태

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

2. 적용 근거

  • 참고 근거: 외부 ui_viz Reference (ZIP 미포함)의 기존 테스트 규격에는 Hover Card 규격이 없다. 참고할 수치가 없었다.
  • 현재 HM 규격: 아래 §3~§4. Popover와 같은 floating surface이며 현재 HM Semantic 체계로 새로 정했다.
  • 구현 방식: shadcn / Radix Hover Card 구조를 유지하고 theme CSS로 HM 스타일을 연결.
  • 역할 구분: Tooltip = 짧고 즉각적인 설명, Hover Card = 제목·설명·metadata를 가진 정보 미리보기(non-interactive 중심), Popover = click으로 여는 panel/form.
  • 보류: §11.

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

항목 값
Surface --hm-sem-bg-surface
전경 --hm-sem-fg-primary
Border 1px --hm-sem-floating-border-color
Radius --hm-radius-container (4px)
Shadow 0 0 12px rgb(0 0 0 / .2)
Padding 16px
Width 320px (viewport − 16px 이하로 제한), 긴 문자열은 줄바꿈
Typography 14 / 20 / 400
Position sideOffset 4, align center
Delay Radix 기본 유지(open 700ms, close 300ms)

4. 상태 규격

상태 값
Open / Closed Radix data-state, shadcn open/close animation
열림 조건 trigger hover 또는 keyboard focus
유지 trigger → content로 pointer 이동 시 유지(Radix hover bridge)
닫힘 조건 pointer가 trigger와 content를 떠난 뒤 close delay, blur, Escape

5. API

Radix Hover Card props 그대로. export: HoverCard, HoverCardTrigger, HoverCardContent.

  • HoverCardContent: align 기본 center, sideOffset 기본 4. HoverCard에 openDelay, closeDelay.
  • 출력 속성: data-slot="hover-card-*", Radix data-state·data-side·data-align.
  • 접근성 주의: Hover Card는 sighted pointer user용 보조 정보이며 keyboard focus로도 열리지만 content 안으로 focus를 옮기지 않는다. 필수 정보나 interactive 요소는 넣지 않는다.

6. Token

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

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

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

Radix 구조·delay·hover bridge·Escape·focus 열림, Portal·positioning·collision, data-slot, cn(..., className), animation class, z-50.

8. HM에서 변경한 항목

  • shadcn w-64 rounded-md border p-2.5 shadow-md bg-popover 등 시각 class 제거 → theme CSS.
  • 폭 256 → 320px, padding 10 → 16px(Popover와 구분되는 미리보기 폭).

9. Storybook

  • 대표 Story All("Hover Card"): 기본 preview(제목 / 설명 / metadata), 긴 콘텐츠 edge case.
  • verification: Open(열린 상태).

10. 사용자 확정 결정

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

11. 미확정 / 보류

  • 수치(320px, 16px padding, 그림자)는 현재 HM 규격이며 디자인 확정 시 재검토.
  • delay는 Radix 기본. HM delay 규칙은 없다.
  • arrow 없음(shadcn 기본에 없음).
  • Motion 규칙은 정의되지 않아 shadcn 기본 animation 유지.
  • 제목·metadata 타이포 role은 소비 조합(Story는 shadcn Token 유틸 사용). 전용 slot 컴포넌트 없음.

12. 관련 파일

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

13. 검증 상태

  • npm run typecheck, npm run build: 통과(2026-10-02).
  • 실제 interaction(Browser pane): hover로 열림, trigger → content 이동 시 유지, 영역 이탈 후 닫힘, keyboard focus로 열림, Escape 닫힘.
  • computed style: width 320px, white, border rgb(222,219,210) 1px, padding 16px, shadow 0 0 12px .2.
  • 미확인: open/close delay 시간의 정확한 측정, 긴 콘텐츠 시각, 좁은 viewport collision.
View Git Blame Copy Permalink