# Image Frame URL: /components/image-frame Source: https://github.com/daangn/seed-design/blob/dev/docs/content/components/image-frame.mdx 사용자가 업로드한 이미지를 표시하기 위한 컴포넌트입니다. | Platform | Status | | --- | --- | | Figma | Done | | [React](/react/components/image-frame) | Done | | Lynx | Not Ready | | iOS | Done | | Android | Done | ## Anatomy ![Image Frame의 Anatomy 이미지. Image Area, Corner Radius, Border로 구성됩니다.](https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/0bb066dd-6cff-476d-8708-fce444f3b4ca) Image Frame은 이미지를 표시하는 Image Area, Corner Radius, Border로 구성되어 있습니다. ## Properties ### Ratio ![Image Frame의 Ratio Property](https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/3d321fac-9d20-4c69-841d-1759322bd104) Ratio 속성으로 이미지 사이즈에 상관없이 고정된 비율로 표시할 수 있습니다. ### Size ![Image Frame의 Size Property - 1:1 비율 전용](https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/6b61a10e-f802-4d8c-bf7c-562e424b1efb) 1:1 비율에서 Size 속성을 제공합니다. 이는 구현 상의 스펙은 아니며, 권장하는 사이즈 가이드에 가깝습니다. 이외의 사이즈를 사용하는 경우 Free 사이즈를 선택하여 사용해주세요. ### Fallback Image ![Image Frame의 Has Image Contents Property](https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/0942a671-34d3-4971-840b-328b7a6b6c91) ![Image Frame의 Fallback Image 종류](https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/97418a05-9fb5-40c4-a5c4-4e911a047fa8) 이미지 컨텐츠를 표시할 수 없는 경우 Fallback 이미지가 표시됩니다. Fallback 이미지는 [Content Placeholder](/components/content-placeholder)를 사용하여 사용처에 따라 다르게 표시할 수 있습니다. ### Border Radius ![Image Frame의 Border Radius Property](https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/91b379d9-ce01-4bdc-a9f6-344c638acd36) Border Radius 옵션으로 모서리를 둥글게 처리할 수 있습니다. ### Show Overlay ![Image Frame의 Overlay Element 배치 예시](https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/4a79acc2-ff72-4848-b1d7-e118c4cc94e5) Show Overlay 옵션을 사용하면 이미지 위에 보조 UI 요소(Overlay Element)를 표시할 수 있습니다. ![Image Frame의 Overlay Element 배치 위치와 Element 종류](https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/2bb8ce1e-1730-49f0-98dd-2b7bf6c27dc5) Overlay 요소는 네 모서리를 기준으로 Slot에 배치되며, 각 Slot에는 하나의 요소만 표시됩니다. Slot에 표시할 수 있는 요소는 다음과 같으며, Custom Slot을 통해 추가 요소도 사용할 수 있습니다. | 요소 | 용도 | | -------------------------- | ---------------------------- | | [Badge](/components/badge) | 상태, 분류, 강조할 라벨 표시 | | Indicator | 이미지 개수, 영상 길이 등 콘텐츠 메타 정보 전달 | | Reaction Button | 사용자 상호작용 유도 (관심 버튼 등) | | Icon | 콘텐츠 타입 표시 (재생 아이콘 등) | ## Guidelines ### Corner Radius 적용 ![Corner Radius 적용 예시 - 가로 크기 24까지 r1, 48까지 r1.5, 그 이상은 r2 적용](https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/215eec5f-cc85-48b9-a17e-a960fff7b873) Rounded 속성 활성화 시 Corner Radius는 [`$radius.r2`](/foundations/design-token/reference/%24radius.r2)(8px)로 설정됩니다. 이미지의 가로 크기가 48 이하인 경우에는 Corner Radius 값을 적절히 조정하는 것을 권장합니다. Radius 토큰을 확인합니다. ### Rounded 속성의 사용 ![Rounded 속성 사용 예시 - 화면에 꽉 차는 이미지에서는 비활성화](https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/eaf98133-eb7e-48b2-8df4-8f0ed507837d) 이미지가 화면 가로 크기에 맞춰 꽉 차게 표시되는 경우에는 Rounded 옵션을 비활성화합니다. ### State ![Image Frame의 State - init, loading, loaded, failed](https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/b3722048-8708-4732-b2f3-ee27adb4e429) 이미지는 초기화(init), 로딩 중(loading), 로드 완료(loaded), 실패(failed) 상태를 가집니다. 이미지 파일이 큰 경우, 평균 로딩 시간이 0.2초 이상이면 로딩 상태를 표시하는 것을 권장합니다. 반면 0.2초 미만이면 로딩 상태 표시가 깜빡임을 유발하여 시각적 불편함을 초래할 수 있습니다. 로딩 표시는 기본적으로 [Skeleton](/components/skeleton) 방식을 제공하며, 필요에 따라 블러(blur), 단색(mono color) 등 다양한 방식을 선택할 수 있습니다. ### 이미지 위에 Overlay 요소 표시하기 ![Overlay Element 사용 예시 - Badge + Reaction Button](https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/52172d8b-b771-4cbb-9009-19bae39fa413) 이미지 위에 보조 UI 요소인 Overlay Element를 표시할 수 있습니다. Overlay 요소는 네 모서리의 Slot에 배치되며, 각 Slot당 하나의 요소만 배치 가능합니다. Overlay는 가독성을 우선하며 주 콘텐츠를 가리지 않습니다. Overlay Element는 최대 2개를 권장하고, 표시되는 요소에 따라 위치를 조정할 수 있습니다. ![Overlay Element 사용 예시](https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/0501ce66-8ae1-4043-8289-e445c81a6fbe) \*\*[Badge](/components/badge)\*\*는 상태나 분류를 표현할 때만 사용하며, 시간·개수·길이 같은 메타 정보에는 사용하지 않습니다. Indicator는 사용자가 콘텐츠를 보기 전에 알면 좋은 설명적 정보를 보여줄 때만 사용하며, 상태 표시나 강조 용도로 쓰지 않습니다. **Reaction Button**은 명확한 사용자 액션이 있을 때만 사용하며, 별도의 터치 영역을 가집니다. Icon은 콘텐츠 타입을 표시하는 용도로만 사용하며, 액션을 가지지 않습니다. ## Specification ### Image Frame Component spec (JSON): /rootage/components/image-frame.json ### Content Placeholder Component spec (JSON): /rootage/components/content-placeholder.json ### Image Frame Floater Component spec (JSON): /rootage/components/image-frame-floater.json ### Image Frame Indicator Component spec (JSON): /rootage/components/image-frame-indicator.json ### Image Frame Reaction Button Component spec (JSON): /rootage/components/image-frame-reaction-button.json