80 lines
3.8 KiB
Markdown
80 lines
3.8 KiB
Markdown
# Aspect Ratio
|
||
|
||
현재 HM 구현의 기준 문서. 공통 원칙은 `docs/guidelines/프로젝트-지침.md`(§6, §7), Token 구조 원칙은 `테마-토큰-가이드.md`를 따른다. 이 문서는 Aspect Ratio 고유의 API·결정만 기록한다.
|
||
|
||
## 1. 상태와 성격
|
||
|
||
| 항목 | 내용 |
|
||
|---|---|
|
||
| 성격 | **Layout primitive** (비율 유지). 시각 디자인이 없는 utility |
|
||
| 구현 상태 | 구현 완료 |
|
||
| 기준일 | 2026-10-03 |
|
||
| 기반 | shadcn/ui Aspect Ratio = Radix `AspectRatio` |
|
||
| 대표 Story | `Components/Data & Display/Aspect Ratio` → `All` (이름 "Aspect Ratio") |
|
||
| 보류 | 아래 §10 |
|
||
|
||
## 2. 적용 근거
|
||
|
||
- **참고 근거**: 외부 ui_viz Reference (ZIP 미포함)의 기존 테스트 규격에는 Aspect Ratio가 없다. 참고할 수치가 없다.
|
||
- **현재 HM 규격**: 시각 규격이 없다. 비율 박스만 제공하며 surface, background, radius, border, 이미지 처리는 소비자가 자식에 구성한다(HM 디자인을 이유로 이미지 스타일을 내부에 넣지 않는다).
|
||
- **구현 방식**: Radix AspectRatio를 그대로 감싼다(`data-slot="aspect-ratio"`).
|
||
- **보류**: §10.
|
||
|
||
## 3. 기본 규격
|
||
|
||
| 항목 | 값 |
|
||
|---|---|
|
||
| Ratio | `ratio` prop(너비 / 높이, 예: `16 / 9`). 기본 1 |
|
||
| 폭 | 부모 폭 100%(Radix wrapper가 `padding-bottom`으로 높이를 계산) |
|
||
| 시각 | 없음(배경, 윤곽, radius 모두 투명/0) |
|
||
| 자식 | Radix가 `position:absolute; inset:0`으로 채운다. 이미지는 소비자가 `size-full object-cover rounded-md` 등으로 구성 |
|
||
|
||
## 4. 상태 규격
|
||
|
||
상태 없음.
|
||
|
||
## 5. API
|
||
|
||
Radix AspectRatio props 그대로. export: `AspectRatio`.
|
||
|
||
- `ratio`, `asChild`, 그리고 `div` props. `size`, `variant`, `mediaType`은 만들지 않았다.
|
||
|
||
## 6. Dependency
|
||
|
||
새 dependency 없음(`radix-ui`에 이미 포함).
|
||
|
||
## 7. Token / Theme CSS
|
||
|
||
**없다.** 시각 규격이 없어 `--hm-aspect-ratio-*` Token과 `aspect-ratio.css`를 만들지 않았고 `theme.css`에도 연결하지 않았다.
|
||
|
||
## 8. 소비자 확장성
|
||
|
||
- 폭은 부모가 정한다(Story는 wrapper의 `max-width`). `className`/`style`이 그대로 적용된다.
|
||
- 이미지 fit, radius, border는 자식 요소에서 소비자가 정한다. Card와 조합해도 AspectRatio는 Card에 의존하지 않는다(Story에서 Card 안에 4:3으로 조합).
|
||
|
||
## 9. Storybook
|
||
|
||
- 대표 Story `All`("Aspect Ratio"): 16:9, 4:3, 1:1 이미지(inline data URI, 네트워크 비의존), video-like placeholder, Card 안 조합을 한 페이지에 둔다.
|
||
- verification: `16:9`, `1:1`.
|
||
|
||
## 10. 사용자 확정 결정 / 보류
|
||
|
||
- 2026-10-03: ui-viz는 참고 자료이며 최종 기준은 현재 HM 구현과 이 문서다(작업 지시). 시각 규격은 정하지 않는다.
|
||
- 보류: 비율 preset(예: `ratio="video"`), 이미지 로딩 placeholder, 모서리 radius 기본값은 만들지 않았다.
|
||
- CSS `aspect-ratio` 속성 기반 구현(Radix는 `padding-bottom` hack)은 Radix 구현을 따르며 바꾸지 않았다.
|
||
|
||
## 11. 관련 파일
|
||
|
||
```
|
||
packages/ui/src/components/ui/aspect-ratio.tsx
|
||
packages/ui/src/index.ts (export)
|
||
src/components/aspect-ratio.stories.tsx
|
||
```
|
||
|
||
## 12. 검증 상태
|
||
|
||
- `npm run typecheck`, `npm run build`: 통과(2026-10-03).
|
||
- 레이아웃(Browser pane, 390×844): 16:9는 320×180(비율 1.778), 4:3은 320×240(1.333), 1:1은 320×320(1.000), video placeholder 320×180, Card 안 4:3은 270×203(1.333). wrapper style은 `position: relative; width: 100%; padding-bottom: 56.25%` 등 Radix 계산이며 이미지가 같은 크기로 채워지고(`object-fit: cover`, 로드됨) 배경·border·radius가 없다. 페이지 가로 overflow 없음.
|
||
- 부모 폭이 바뀌면 높이가 비율대로 변한다(Story의 max-width 320 → 390px 뷰포트에서 320, Card 안에서는 270).
|
||
- 미확인: 부모 폭을 연속으로 resize할 때의 reflow, `ratio` 동적 변경.
|