sodalive-ios/docs/prd/20260519_오디오콘텐츠카드컴포넌트_PRD.md

# PRD: 오디오 콘텐츠 카드 컴포넌트

## 1. Overview

Figma의 오디오 콘텐츠 카드 3종(`large`, `medium`, `small`)을 iOS SwiftUI에서 재사용 가능한 V2 컴포넌트로 제공한다.

---

## 2. Problem

- Figma에 정의된 3개 컴포넌트는 형태가 동일하고 크기만 다르지만, 구현 전에 요구사항 문서가 충분히 정리되지 않아 구현 기준이 불명확했다.
- 크기, 라벨, 제외 범위, 에셋 처리 기준이 문서화되지 않으면 구현자가 임의로 API나 시각 요소를 해석할 수 있다.
- 향후 메인/콘텐츠 영역에서 동일한 오디오 카드가 반복 사용될 가능성이 있어 단일 기준 컴포넌트가 필요하다.

---

## 3. Goals

- Figma 노드 `20:3800`, `20:3818`, `20:3829`의 오디오 카드 공통 구조를 하나의 SwiftUI 컴포넌트로 표현한다.
- 호출부는 크기, 제목, 부제, 썸네일 표시 방식을 명시적으로 주입할 수 있다.
- 크기별 썸네일/라벨/폰트/간격 스펙을 문서와 코드에서 일관되게 유지한다.
- 외부 Figma localhost asset URL을 production code에 하드코딩하지 않는다.
- 신규 컴포넌트는 `SodaLive/Sources/V2/Component/**`의 기존 SwiftUI 컴포넌트 스타일을 따른다.

---

## 4. Non-Goals

- 이번 작업에서 실제 콘텐츠 API 연동, 네트워크 로딩 정책, 캐싱 정책은 구현하지 않는다.
- Figma의 임시 썸네일 이미지를 앱 asset으로 추가하지 않는다.
- `series` 타입 콘텐츠 카드는 구현하지 않는다.
- `ORIGINAL` 태그는 구현하지 않는다.
- `FIRST` 태그는 구현하지 않는다.
- `무료` 태그는 구현하지 않는다.
- 태그 아이콘 에셋은 이번 범위에서 추가하지 않는다.
- 시리즈 카드(`type = series`) 또는 세로형 콘텐츠 카드 전체를 함께 일반화하지 않는다.
- 기존 화면에 컴포넌트를 배치하거나 사용자 플로우를 변경하지 않는다.

---

## 5. Target Users

- V2 SwiftUI 화면을 구현하는 iOS 개발자
- 콘텐츠 카드 UI를 재사용해야 하는 홈/콘텐츠/오디오 영역 구현자
- Figma와 앱 구현 사이의 시각 기준을 확인해야 하는 리뷰어

---

## 6. User Stories

- 개발자는 `large`, `medium`, `small` 중 하나를 선택해 동일한 구조의 오디오 카드를 표시할 수 있다.
- 개발자는 실제 이미지, placeholder, `AsyncImage`, Kingfisher 기반 이미지 View 등 썸네일 표시 방식을 호출부에서 결정할 수 있다.
- 리뷰어는 PRD와 계획 문서만 보고 구현 범위와 제외 범위를 확인할 수 있다.

---

## 7. Core Features

### 7.1 단일 오디오 콘텐츠 카드 컴포넌트

#### Requirements
- 컴포넌트 파일은 `SodaLive/Sources/V2/Component/AudioContentCard.swift`에 둔다.
- 크기는 `AudioContentCardSize` enum으로 표현한다.
- 카드 구조는 썸네일 영역과 라벨 영역으로 분리한다.
- 제목과 부제는 각각 한 줄로 표시하고 초과 시 tail truncation 처리한다.
- 썸네일은 호출부가 `@ViewBuilder`로 주입한다.

#### Edge Cases
- 제목/부제가 긴 경우 한 줄 말줄임 처리한다.
- 태그는 이번 범위에서 표시하지 않는다.

### 7.2 크기별 스펙

| Size | Figma node | Card width | Thumbnail | Label width | Label horizontal padding | Title | Subtitle |
| --- | --- | ---: | ---: | ---: | ---: | --- | --- |
| `large` | `20:3800` | 185 | 185x185 | 185 | 0 | 18 bold | 14 medium |
| `medium` | `20:3818` | 163 | 163x163 | 151 | 6 | 18 bold | 14 medium |
| `small` | `20:3829` | 122 | 122x122 | 114 | 4 | 16 bold | 12 medium |

#### Requirements
- 썸네일은 모든 크기에서 정사각형이다.
- 썸네일 corner radius는 14pt다.
- `large`, `medium` 제목은 기존 typography 기준 `.heading4`를 사용한다.
- `small` 제목은 기존 typography 기준 `.body1`을 사용한다.
- `large`, `medium` 부제는 기존 typography 기준 `.body5`를 사용한다.
- `small` 부제는 기존 typography 기준 `.caption2`를 사용한다.
- 썸네일과 제목 사이 간격은 모든 크기에서 8pt다.
- 제목과 부제 사이 간격은 모든 크기에서 2pt다.
- 라벨 영역의 horizontal padding은 `large` 0pt, `medium` 6pt, `small` 4pt다.

## 8. UX / UI Expectations

- Figma와 동일한 카드 외곽 크기, 썸네일 크기, 라벨 폭을 유지한다.
- 썸네일은 호출부에서 전달한 View가 카드 영역을 채우도록 렌더링할 수 있어야 한다.
- 카드 자체는 배경색을 강제하지 않는다. 배경은 사용하는 화면이 결정한다.
- SwiftUI Preview는 세 크기를 한 화면에서 비교할 수 있게 제공한다.

---

## 9. Technical Constraints

- SwiftUI 기반으로 구현한다.
- 기존 디자인 토큰과 확장(`SodaSpacing`, `Color`, `SodaTypography`, `appFont`)을 우선 사용한다.
- 신규 dependency를 추가하지 않는다.
- `Pods/**`, `generated/**`, `build/**`는 수정하지 않는다.
- production code에 Figma localhost asset URL을 넣지 않는다.
- 프로젝트 파일 수정은 신규 Swift 파일이 Xcode 빌드 대상에 포함되어야 할 때만 수행한다.

---

## 10. Success Criteria

- `AudioContentCard`가 `large`, `medium`, `small` 세 크기를 모두 지원한다.
- 각 크기별 수치와 라벨 간격/패딩이 PRD의 size spec과 일치한다.
- 컴포넌트 API가 썸네일 View 주입, 제목, 부제를 명시적으로 제공한다.
- `series`, `ORIGINAL`, `FIRST`, `무료` 관련 API나 UI가 포함되지 않는다.
- `xcodebuild -workspace "SodaLive.xcworkspace" -scheme "SodaLive-dev" -configuration Debug build`가 성공한다.
- `docs/plan-task/20260519_오디오콘텐츠카드컴포넌트.md`에 구현 작업 순서와 검증 기록이 남는다.

---

## 11. Open Questions

- 컴포넌트를 어느 실제 화면에 처음 적용할지는 이번 PRD 범위 밖이다.
- 카드 접근성 label 조합 규칙은 실제 화면 적용 시 데이터 정책에 맞춰 확정한다.