97 lines
5.0 KiB
Markdown
97 lines
5.0 KiB
Markdown
# 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`, 대비 비율의 수치 측정.
|