Skeleton

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

1. 상태

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

2. 적용 근거

참고 근거: 외부 ui_viz Reference (ZIP 미포함)의 기존 테스트 규격에는 Skeleton이 컴포넌트 이름으로만 있고 규격은 없다. 참고할 수치가 없었다.
현재 HM 규격: 아래 §3. 현재 HM Primitive로 새로 정했다.
구현 방식: shadcn Skeleton을 유지. loading 로직이 없는 시각 placeholder primitive이며 크기·모양은 className으로 정한다.
보류: §11.

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

항목	값
배경	`--hm-sem-palette-warm-neutral-light`
Radius	`--hm-radius-control-md` (4px). 원형은 `className="rounded-full"`
Animation	shadcn `animate-pulse`(2s). `prefers-reduced-motion: reduce`에서는 animation 없음
크기	없음. `className`으로 `h-`, `w-`, `size-*` 지정

4. 상태 규격

상태 없음(placeholder). 배경과 radius는 @layer components에 있어 className의 utility(rounded-full, bg-*)가 이긴다. 다른 컴포넌트의 theme CSS(레이어 없음)와 달리 Skeleton은 모양을 소비자가 정하는 것이 역할이기 때문이다.

5. API

export: Skeleton. div props 그대로. 출력 data-slot="skeleton".

width/height/variant prop은 만들지 않았다. Text line, Avatar, Card 등은 Story처럼 className으로 조합한다.
접근성: placeholder 자체에는 ARIA를 두지 않는다. loading 영역의 aria-busy 등은 소비자 책임.

6. Token

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

background, radius. Theme palette(--hm-sem-palette-warm-neutral-light)와 공통 control radius만 참조한다. 신규 Primitive 없음.

7. shadcn에서 유지한 항목

div 구조, animate-pulse, data-slot, cn(..., className).

8. HM에서 변경한 항목

shadcn bg-muted rounded-md(또는 bg-accent) class를 제거하고 Token으로 연결(배경 --hm-warm-neutral-light, radius 4px).
reduced-motion에서 pulse를 끈다(shadcn 기본에는 대응이 없다). 새 Motion token은 만들지 않았다.
배경·radius 규칙을 @layer components에 둔 것은 이 컴포넌트만의 결정이다(§4).

9. Storybook

대표 Story All("Skeleton"): Text(3줄), Avatar + text, Card/list loading(Card 안 조합)을 한 페이지에 둔다. 데이터 fetch는 없다.
verification: Text, Card List.

10. 사용자 확정 결정

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

11. 미확정 / 보류

배경색과 radius는 현재 HM 규격이며 디자인 확정 시 재검토.
Pulse 속도·형태(shimmer 등)는 Motion 규칙이 정해질 때 다룬다.
Text line 높이 등 사전 정의된 크기 preset은 만들지 않았다.
전체 loading 영역의 ARIA(aria-busy, live region) 가이드는 Data Table Pattern 등 조합 단계에서 정한다.

12. 관련 파일

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

13. 검증 상태

npm run typecheck, npm run build: 통과(2026-10-02).
실제 렌더(Browser pane): 배경 rgb(224,218,206), radius 4px, animation pulse 2s. className="size-10 rounded-full"이 radius override를 받아 원형으로 표시(처음에는 unlayered CSS가 rounded-full을 덮는 문제가 있어 @layer components로 수정).
Responsive(390×844): Text, Avatar+text, Card 구성이 부모 폭 안에 들어가고 가로 overflow 없음.
미확인: 실제 prefers-reduced-motion 환경에서의 animation 정지(CSS만 작성).

4.3 KiB Raw Permalink Blame History Unescape Escape