HMDesign/docs/components/hover-card.md at feat/chart-package

shkim4/HMDesign

Private

Public Access

0 Fork 0

Files

T

shkim4 b6a0a61103 Initial commit: HMDesignSystem baseline

2026-10-08 16:58:09 +09:00

4.7 KiB

Raw Permalink Blame History

현재 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.

4.7 KiB Raw Permalink Blame History Unescape Escape

Hover Card