Files

Yu Sung 942c581eaf feat(component): 재사용 타이틀 탭 바를 추가한다

2026-05-19 20:32:26 +09:00

8.0 KiB

Raw Permalink Blame History

PRD: 재사용 타이틀 바 및 탭 텍스트 바 컴포넌트

1. Overview

화면 상단에서 공통으로 사용할 Title Bar 계열 컴포넌트와 텍스트 기반 탭 전환에 사용할 Tab-Text Bar 컴포넌트를 SwiftUI 재사용 컴포넌트로 정의한다. 구현 대상은 신규 코드 위치 규칙에 따라 SodaLive/Sources/V2/Component/** 아래에 배치할 재사용 UI 단위다.

2. Background

현재 프로젝트에는 기존 SodaLive/Sources/NavigationBar/HomeNavigationBar.swift, SodaLive/Sources/NavigationBar/DetailNavigationBar.swift가 있으나 높이, 로고, 우측 메뉴 슬롯, V2 디자인 토큰 기준이 이번 요구사항과 다르다.

최근 코드에는 다음 기반 요소가 이미 존재한다.

SodaLive/Sources/Extensions/FontModifier.swift: SodaTypography.heading3 및 .appFont(_:) 제공
SodaLive/Sources/UI/Theme/Color.swift: Color.gray600, Color.white, Color.black 사용 가능
SodaLive/Resources/Assets.xcassets/v2/img_text_logo_v2.imageset: 홈 타이틀 바 로고 에셋 존재
SodaLive/Resources/Assets.xcassets/v2/ic_bar_search.imageset, ic_bar_bell.imageset, ic_bar_cash.imageset: 화면별로 교체 가능한 우측 메뉴 아이콘 후보 존재

3. Goals

Home Title Bar를 재사용 컴포넌트로 제공한다.
Default Title Bar를 재사용 컴포넌트로 제공한다.
Tab-Text Bar를 재사용 컴포넌트로 제공한다.
각 컴포넌트는 Figma 요구사항의 높이, 배경색, 세로 가운데 정렬, 선택 색상 규칙을 따른다.
화면별 우측 메뉴 아이콘과 액션은 호출부에서 변경할 수 있게 한다.
Tab-Text Bar는 최대 3개 메뉴와 단일 선택 상태를 보장한다.

4. Non-Goals

기존 HomeNavigationBar, DetailNavigationBar를 삭제하거나 대규모 리팩터링하지 않는다.
실제 화면에 컴포넌트를 적용하는 작업은 이 범위에 포함하지 않는다.
신규 이미지 에셋 제작은 하지 않는다.
탭별 콘텐츠 화면이나 비즈니스 로직은 구현하지 않는다.
Figma Code Connect 매핑 작업은 하지 않는다.

5. Core Requirements

5.1 Title Bar 공통 규칙

Width: full
Height: 60
Alignment: 세로 가운데 정렬
Background: Color.black
좌측 콘텐츠, 빈 영역, 우측 메뉴 영역의 HStack 구조를 사용한다.
우측 메뉴 아이콘은 사용하는 화면마다 다르므로 호출부에서 주입 가능해야 한다.

5.2 Home Title Bar

Figma: https://www.figma.com/design/HmN1yNdJ3EIpqknFL0Hkab/-%EA%B3%B5%EC%9C%A0%EC%9A%A9-%EB%B3%B4%EC%9D%B4%EC%8A%A4%EC%98%A8-UI-UX-%EA%B8%B0%ED%9A%8D%EB%AC%B8%EC%84%9C?node-id=20-3575&m=dev
좌측에는 img_text_logo_v2 이미지를 표시한다.
중앙은 Spacer()로 빈 영역을 채운다.
우측에는 호출부가 제공하는 메뉴 아이콘 또는 메뉴 View를 표시한다.

5.3 Default Title Bar

Figma: https://www.figma.com/design/HmN1yNdJ3EIpqknFL0Hkab/-%EA%B3%B5%EC%9C%A0%EC%9A%A9-%EB%B3%B4%EC%9D%B4%EC%8A%A4%EC%98%A8-UI-UX-%EA%B8%B0%ED%9A%8D%EB%AC%B8%EC%84%9C?node-id=20-3576&m=dev
좌측에는 화면명을 표시한다.
화면명은 호출부에서 변경 가능해야 한다.
중앙은 Spacer()로 빈 영역을 채운다.
우측에는 호출부가 제공하는 메뉴 아이콘 또는 메뉴 View를 표시한다.

5.4 Tab-Text Bar

Figma: https://www.figma.com/design/HmN1yNdJ3EIpqknFL0Hkab/-%EA%B3%B5%EC%9C%A0%EC%9A%A9-%EB%B3%B4%EC%9D%B4%EC%8A%A4%EC%98%A8-UI-UX-%EA%B8%B0%ED%9A%8D%EB%AC%B8%EC%84%9C?node-id=20-3585&m=dev
Width: full
Height: 52
Alignment: 세로 가운데 정렬
Background: Color.black
Typography: SodaTypography.heading3
Normal Color: Color.gray600
Selected Color: Color.white
메뉴 선택 시 해당 메뉴만 Selected 상태가 된다.
Selected 상태는 반드시 하나만 존재해야 한다.
메뉴 개수는 최대 3개까지만 허용한다.

6. Recommended Approach

접근안 A: Title Bar와 Tab-Text Bar를 각각 독립 컴포넌트로 작성

HomeTitleBar, DefaultTitleBar, TextTabBar를 분리한다. 호출부에서 사용법이 명확하고 각 컴포넌트의 요구사항을 그대로 표현하기 쉽다. 단점은 Title Bar의 공통 레이아웃이 중복될 수 있다.

접근안 B: 공통 `TitleBar` 기반에 Home/Default 편의 생성자를 제공

하나의 공통 TitleBar가 좌측 콘텐츠와 우측 메뉴 슬롯을 받고, HomeTitleBar와 DefaultTitleBar는 얇은 래퍼로 제공한다. 중복이 적고 우측 메뉴 커스터마이징이 쉽다. 단점은 최초 구현 시 구조가 접근안 A보다 조금 더 추상적이다.

접근안 C: 모든 영역을 ViewBuilder 슬롯으로만 받는 범용 Bar 작성

가장 유연하지만 현재 요구사항보다 범위가 넓다. 화면마다 다른 배치가 가능해지는 대신 디자인 규칙이 느슨해질 수 있다.

권장

접근안 B를 권장한다. Title Bar의 공통 규칙은 한 곳에서 유지하고, Home/Default 사용처는 명확한 이름의 래퍼로 제공한다. TextTabBar는 선택 상태와 최대 3개 제약을 자체적으로 갖는 별도 컴포넌트로 둔다.

7. Technical Constraints

SwiftUI 기반으로 작성한다.
신규 파일은 구현 시 SodaLive/Sources/V2/Component/** 아래에 둔다.
SodaLive/Sources/V2/Common/**은 UI 컴포넌트보다 공통 유틸리티/기반 타입으로 해석될 여지가 있으므로 이번 컴포넌트 위치로 사용하지 않는다.
색상은 기존 Color.black, Color.gray600, Color.white를 우선 사용한다.
폰트는 기존 .appFont(.heading3) 사용을 우선한다.
TextTabBar는 호출부가 선택 상태를 소유할 수 있도록 Binding 또는 선택 콜백 기반 API를 사용한다.
메뉴가 0개이거나 4개 이상인 경우는 구현 단계에서 안전한 실패 방식이 필요하다. 단순 구현을 우선해 1...3개 입력만 정상 사용 조건으로 문서화한다.

8. Success Criteria

문서 기준 구현 후 Home Title Bar는 높이 60, 검정 배경, 좌측 img_text_logo_v2, 우측 교체 가능한 메뉴 아이콘을 표시한다.
문서 기준 구현 후 Default Title Bar는 높이 60, 검정 배경, 좌측 화면명, 우측 교체 가능한 메뉴 아이콘을 표시한다.
문서 기준 구현 후 Tab-Text Bar는 높이 52, 검정 배경, 최대 3개 텍스트 메뉴를 표시한다.
Tab-Text Bar의 일반 메뉴는 Color.gray600, 선택 메뉴는 Color.white로 표시된다.
Tab-Text Bar의 텍스트는 SodaTypography.heading3를 사용한다.
탭 선택 시 선택 상태는 항상 하나만 유지된다.

9. Decisions

문서 단계에서는 코드 구현을 하지 않는다.
Figma에서 Code Connect 매핑을 요구했지만, 이번 요청 범위가 문서 생성으로 축소되었으므로 매핑 작업은 제외한다.
img_text_logo_v2는 기존 v2 에셋을 사용한다.
우측 메뉴는 특정 아이콘명으로 고정하지 않고 호출부 주입 방식으로 정의한다.
파일 생성 위치는 SodaLive/Sources/V2/Component/**로 결정한다.

10. Verification Notes

SodaLive/Sources/NavigationBar/HomeNavigationBar.swift, DetailNavigationBar.swift를 확인해 기존 NavigationBar 패턴과 차이를 확인했다.
SodaLive/Sources/Extensions/FontModifier.swift를 확인해 SodaTypography.heading3와 .appFont(_:) 사용 가능성을 확인했다.
SodaLive/Sources/UI/Theme/Color.swift를 확인해 Color.gray600 토큰 값을 확인했다.
SodaLive/Resources/Assets.xcassets/v2/img_text_logo_v2.imageset가 존재함을 확인했다.
SodaLive/Sources/V2 아래에는 현재 Main만 있고 전역 Common/Component는 없지만, 기존 UI 재사용 View는 UI/Component 및 도메인별 .../V2/Component 명명 관례를 사용하므로 V2/Component를 선택했다.
이번 작업은 문서 생성만 수행하며 Swift 소스 변경은 하지 않는다.

8.0 KiB Raw Permalink Blame History