Avatar

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

1. 상태

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

2. 적용 근거

참고 근거: 외부 ui_viz Reference (ZIP 미포함)의 기존 테스트 규격에는 Avatar가 컴포넌트 이름으로만 있고 규격은 없다. 참고할 수치가 없었다.
현재 HM 규격: 아래 §3. 현재 HM Semantic(accent 면)으로 새로 정했다. size 체계는 Button/Input size를 복사하지 않고 shadcn Avatar API(sm/default/lg)에 맞춰 24/32/40px로 정했다.
구현 방식: shadcn / Radix Avatar 구조(Root, Image, Fallback)를 유지하고 theme CSS로 연결.
보류: §11.

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

항목	값
Size	`sm` 24px, `default` 32px, `lg` 40px (정사각형)
Shape	원형(radius 9999px), `overflow: hidden`
Image	`size-full`, `object-cover`, `aspect-square` (중앙 crop)
Fallback 면	`--accent` (green tint), 글자 `--accent-foreground`
Fallback typography	weight 500, `sm` 10px / `default` 12px / `lg` 14px, line-height 1, 한 줄 `nowrap`, 넘치면 잘림

4. 상태 규격

상태	값
이미지 로드 성공	Radix가 Image를 렌더하고 Fallback은 렌더하지 않는다
이미지 로드 실패 / 로딩 중	Fallback 표시(`delayMs` prop으로 지연 가능)
Focus / Disabled	없음(비 interactive)

5. API

Radix Avatar props 그대로. export: Avatar, AvatarImage, AvatarFallback.

Avatar: size "sm" | "default" | "lg"(기본 default, shadcn API 유지). 출력 data-size.
AvatarImage: src, alt, onLoadingStatusChange. AvatarFallback: delayMs.
접근성: 이름이 보이는 곳에서는 alt="", 단독으로 쓰면 alt로 이름을 준다.
새 prop은 만들지 않았다. 크기는 size prop(또는 --hm-avatar-size-* Token)으로만 바꾼다. theme CSS가 레이어 밖이라 className="size-12" 같은 utility는 이기지 못한다.
shadcn 최신 버전에 있는 AvatarBadge/AvatarGroup은 만들지 않았다(필요가 생기면 추가).

6. Token

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

size-sm|md|lg, radius, fallback-background, fallback-text, fallback-font-weight, fallback-font-size-sm|md|lg. Semantic(--accent, --accent-foreground)만 참조한다. 신규 Primitive 없음.

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

Radix 이미지 로드 상태 처리와 Fallback 표시 규칙, 구조, size prop, data-slot, cn(..., className).

8. HM에서 변경한 항목

shadcn size-8/data-[size=lg]:size-10, bg-muted fallback, 글자 크기 class를 제거하고 Token으로 연결. 크기는 24/32/40.
Fallback 면을 muted가 아니라 accent(green tint)로 했다(HM 팔레트에서 대비가 있는 면).

9. Storybook

대표 Story All("Avatar"): Image(sm/default/lg, data URI 이미지로 네트워크 비의존), Fallback(깨진 이미지 주소로 initials: 한글 두 글자, 영문 두 글자, 한 글자, 긴 fallback), Composition(이름 + 소속)을 한 페이지에 둔다.
verification: Image, Fallback.

10. 사용자 확정 결정

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

11. 미확정 / 보류

Size(24/32/40)와 fallback 색은 현재 HM 규격이며 Dashboard/GNB의 실제 사용이 정해지면 재검토.
긴 fallback(예: 10자)은 가운데에서 잘린다. 1~2자 initials가 전제이며 줄임 규칙은 만들지 않았다.
Icon fallback(사람 아이콘) 규칙, 상태 badge, 겹침 그룹은 정의하지 않았다.
이미지 비율이 다른 원본은 중앙 crop(object-cover)만 한다.

12. 관련 파일

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

13. 검증 상태

npm run typecheck, npm run build: 통과(2026-10-02).
실제 렌더(Browser pane): 로드되는 이미지 Avatar는 img만 있고 fallback 요소가 없음(24/32/40px, radius 9999px). 깨진 이미지 주소의 Avatar는 img 없이 fallback이 렌더되고 김한/HM/한/ABCDEFGHIJ가 32×32 안에서 레이아웃 변동 없이 표시, 배경 rgb(189,223,212)·글자 rgb(18,51,40)·12px.
Responsive(390×844): Avatar 구성이 한 줄로 들어가고 가로 overflow 없음.
미확인: 이미지가 느리게 로드될 때 fallback에서 image로 전환되는 순간의 깜빡임, delayMs, 대비 비율의 수치 측정.

5.0 KiB Raw Blame History Unescape Escape