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

참고 근거: 외부 ui_viz Reference (ZIP 미포함)의 기존 테스트 규격에는 Aspect Ratio가 없다. 참고할 수치가 없다.
현재 HM 규격: 시각 규격이 없다. 비율 박스만 제공하며 surface, background, radius, border, 이미지 처리는 소비자가 자식에 구성한다(HM 디자인을 이유로 이미지 스타일을 내부에 넣지 않는다).
구현 방식: Radix AspectRatio를 그대로 감싼다(data-slot="aspect-ratio").
보류: §10.

항목	값
Ratio	`ratio` prop(너비 / 높이, 예: `16 / 9`). 기본 1
폭	부모 폭 100%(Radix wrapper가 `padding-bottom`으로 높이를 계산)
시각	없음(배경, 윤곽, radius 모두 투명/0)
자식	Radix가 `position:absolute; inset:0`으로 채운다. 이미지는 소비자가 `size-full object-cover rounded-md` 등으로 구성

상태 없음.

Radix AspectRatio props 그대로. export: AspectRatio.

새 dependency 없음(radix-ui에 이미 포함).

없다. 시각 규격이 없어 --hm-aspect-ratio-* Token과 aspect-ratio.css를 만들지 않았고 theme.css에도 연결하지 않았다.

폭은 부모가 정한다(Story는 wrapper의 max-width). className/style이 그대로 적용된다.
이미지 fit, radius, border는 자식 요소에서 소비자가 정한다. Card와 조합해도 AspectRatio는 Card에 의존하지 않는다(Story에서 Card 안에 4:3으로 조합).

대표 Story All("Aspect Ratio"): 16:9, 4:3, 1:1 이미지(inline data URI, 네트워크 비의존), video-like placeholder, Card 안 조합을 한 페이지에 둔다.
verification: 16:9, 1:1.

2026-10-03: ui-viz는 참고 자료이며 최종 기준은 현재 HM 구현과 이 문서다(작업 지시). 시각 규격은 정하지 않는다.
보류: 비율 preset(예: ratio="video"), 이미지 로딩 placeholder, 모서리 radius 기본값은 만들지 않았다.
CSS aspect-ratio 속성 기반 구현(Radix는 padding-bottom hack)은 Radix 구현을 따르며 바꾸지 않았다.

packages/ui/src/components/ui/aspect-ratio.tsx
packages/ui/src/index.ts             (export)
src/components/aspect-ratio.stories.tsx

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 동적 변경.