Communitygithub.com

ComeOnOliver/skillshub

참조 — SwiftUI 탐색 가이드 종합: NavigationStack (iOS 16+), NavigationSplitView (iOS 16+), NavigationPath, 딥 링킹, 상태 복원, Tab+Navigation 통합 (iOS 18+), Liquid Glass 탐색 (iOS 26+), 코디네이터 패턴

skillshub란 무엇인가요?

이 스킬은 SwiftUI의 데이터 중심 탐색 API에 대한 포괄적인 참조 가이드를 제공합니다. iOS 16에서 도입된 NavigationStack, NavigationSplitView, NavigationPath를 중심으로, iOS 18의 Tab/Sidebar 통합, iOS 26의 Liquid Glass 디자인까지 진화하는 탐색 방식을 다룹니다. 개발자는 이 가이드를 사용하여 데이터 기반 탐색, 다중 열 레이아웃, 상태 복원, 딥 링킹을 구현하는 방법을 배울 수 있습니다. 특히 NavigationPath를 활용한 프로그래밍 방식의 push/pop과 Codable을 통한 상태 저장/복원 패턴에 중점을 둡니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/CharlesWiltgen/Axiom/axiom-swiftui-nav-ref

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

SwiftUI 탐색 API 참조

개요

SwiftUI의 탐색 API는 단순한 스택부터 복잡한 다중 열 레이아웃까지 확장 가능한 데이터 중심의 프로그래밍 방식 탐색을 제공합니다. iOS 16(2022)에서 NavigationStack 및 NavigationSplitView로 도입되었고, iOS 18(2024)에서 Tab/Sidebar 통합으로, iOS 26(2025)에서 Liquid Glass 디자인으로 발전했습니다.

발전 타임라인

  • 2022 (iOS 16) NavigationStack, NavigationSplitView, NavigationPath, 값 기반 NavigationLink
  • 2024 (iOS 18) Tab/Sidebar 통합, sidebarAdaptable 스타일, 확대/축소 탐색 전환
  • 2025 (iOS 26) Liquid Glass 탐색 크롬, 하단 정렬 검색, 플로팅 탭 바, backgroundExtensionEffect

주요 기능

  • 데이터 기반 탐색 NavigationPath는 스택 상태를 나타내어 프로그래밍 방식의 push/pop 및 딥 링킹을 가능하게 합니다.
  • 다중 열 레이아웃 NavigationSplitView는 자동으로 적응합니다(iPad에서는 3열 → iPhone에서는 단일 스택).
  • 상태 복원 Codable NavigationPath + SceneStorage를 사용하여 앱 실행 간 상태를 유지합니다.
  • 탭 통합 탭 전환 시 상태를 유지하는 탭별 NavigationStack (iOS 18+).
  • Liquid Glass 자동 유리 탐색 바, 사이드바, 툴바 (iOS 26+).

UIKit과 비교하여 언제 사용할까

  • SwiftUI 탐색 새로운 앱, 멀티플랫폼, 간단한 탐색 흐름 → NavigationStack/SplitView 사용
  • UINavigationController 복잡한 코디네이터 패턴, 레거시 코드, 특정 UIKit 기능 → UIKit 고려

관련 스킬

  • axiom-swiftui-nav 안티 패턴, 결정 트리, 압박 시나리오에 사용
  • axiom-swiftui-nav-diag 탐색 문제의 체계적인 문제 해결에 사용

이 스킬을 사용해야 할 때

다음과 같은 경우 이 스킬을 사용하세요:

  • 탐색 API 구현 NavigationStack, NavigationSplitView, NavigationPath, Tab+Navigation
  • 딥 링킹 또는 상태 복원 URL 라우팅, Codable NavigationPath, SceneStorage
  • iOS 26+ 기능 채택 Liquid Glass 탐색, 하단 정렬 검색, 탭 바 최소화
  • 탐색 아키텍처 선택 Stack vs SplitView vs 코디네이터 패턴

API 진화

타임라인

연도iOS 버전주요 기능
2020iOS 14NavigationView (iOS 16에서 deprecated)
2022iOS 16NavigationStack, NavigationSplitView, NavigationPath, 값 기반 NavigationLink
2024iOS 18Tab/Sidebar 통합, sidebarAdaptable, TabSection, 확대/축소 전환
2025iOS 26Liquid Glass 탐색, backgroundExtensionEffect, tabBarMinimizeBehavior

NavigationView (Deprecated)

NavigationView는 iOS 16부터 사용이 중단되었습니다. 새 코드에서는 NavigationStack(단일 열 push/pop) 또는 NavigationSplitView(다중 열)만 사용하십시오. 주요 개선 사항: 단일 NavigationPath가 링크별 isActive 바인딩을 대체하고, 값 기반 타입 안전성, 내장 Codable 상태 복원을 제공합니다. "새 탐색 유형으로 마이그레이션" 문서를 참조하세요.


NavigationStack 전체 참조

NavigationStack은 iPhone의 설정 또는 macOS의 시스템 설정과 같은 push-pop 인터페이스를 나타냅니다.

1.1 NavigationStack 생성

기본 NavigationStack

NavigationStack {
    List(Category.allCases) { category in
        NavigationLink(category.name, value: category)
    }
    .navigationTitle("Categories")
    .navigationDestination(for: Category.self) { category in
        CategoryDetail(category: category)
    }
}

경로 바인딩 사용 (WWDC 2022, 6:05)

struct PushableStack: View {
    @State private var path: [Recipe] = []
    @StateObject private var dataModel = DataModel()

    var body: some View {
        NavigationStack(path: $path) {
            List(Category.allCases) { category in
                Section(category.localizedName) {
                    ForEach(dataModel.recipes(in: category)) { recipe in
                        NavigationLink(recipe.name, value: recipe)
                    }
                }
            }
            .navigationTitle("Categories")
            .navigationDestination(for: Recipe.self) { recipe in
                RecipeDetail(recipe: recipe)
            }
        }
        .environmentObject(dataModel)
    }
}

경로 바인딩 + 값 제공 NavigationLink + navigationDestination(for:)가 핵심 데이터 기반 탐색 패턴을 구성합니다.

1.2 NavigationLink (값 기반)

값 제공 NavigationLink

// 올바름: 값 기반 (iOS 16+)
NavigationLink(recipe.name, value: recipe)

// 올바름: 사용자 정의 레이블 사용
NavigationLink(value: recipe) {
    RecipeTile(recipe: recipe)
}

// 사용 중단됨: 뷰 기반 (iOS 13-15)
NavigationLink(recipe.name) {
    RecipeDetail(recipe: recipe)  // 새 코드에서는 사용하지 마세요
}

NavigationLink가 NavigationStack과 함께 작동하는 방식

  1. NavigationStack은 path 컬렉션을 유지합니다.
  2. 값 제공 링크를 탭하면 값이 경로에 추가됩니다.
  3. NavigationStack은 navigationDestination 수정자를 경로 값에 매핑합니다.
  4. 대상 매핑을 기반으로 뷰가 스택에 푸시됩니다.

1.3 navigationDestination 수정자

단일 타입

.navigationDestination(for: Recipe.self) { recipe in
    RecipeDetail(recipe: recipe)
}

여러 타입

NavigationStack(path: $path) {
    RootView()
        .navigationDestination(for: Recipe.self) { recipe in
            RecipeDetail(recipe: recipe)
        }
        .navigationDestination(for: Category.self) { category in
            CategoryList(category: category)
        }
        .navigationDestination(for: Chef.self) { chef in
            ChefProfile(chef: chef)
        }
}

탐색 안티 패턴

  • 동일한 NavigationStack 계층에서 navigationDestination(for:)와 NavigationLink(destination:)를 절대 혼용하지 마세요 — 정의되지 않은 동작을 유발합니다.
  • 데이터 타입당 한 번 navigationDestination(for:)를 등록하세요 — 중복되면 잘못된 뷰가 나타납니다.

배치 규칙

  • navigationDestination을 지연 컨테이너 외부에 배치하세요(ForEach 내부가 아님).
  • 코드 구성을 위해 관련 NavigationLink 근처에 배치하세요.
  • NavigationStack 계층 내부에 있어야 합니다.
// 올바름: 지연 컨테이너 외부
ScrollView {
    LazyVGrid(columns: columns) {
        ForEach(recipes) { recipe in
            NavigationLink(value: recipe) {
                RecipeTile(recipe: recipe)
            }
        }
    }
}
.navigationDestination(for: Recipe.self) { recipe in
    RecipeDetail(recipe: recipe)
}

// 잘못됨: ForEach 내부 (로드되지 않을 수 있음)
ForEach(recipes) { recipe in
    NavigationLink(value: recipe) { RecipeTile(recipe: recipe) }
        .navigationDestination(for: Recipe.self) { r in  // 이렇게 하지 마세요
            RecipeDetail(recipe: r)
        }
}

1.4 NavigationPath

NavigationPath는 이기종 탐색 스택을 위한 타입 지워진 컬렉션입니다.

타입 배열 vs NavigationPath

// 타입 배열: 모든 값이 동일한 타입
@State private var path: [Recipe] = []

// NavigationPath: 혼합 타입
@State private var path = NavigationPath()

NavigationPath 연산

// 값 추가
path.append(recipe)

// 이전으로 이동
path.removeLast()

// 루트로 이동
path.removeLast(path.count)
// 또는
path = NavigationPath()

// 개수 확인
if path.count > 0 { ... }

// 딥 링크: 여러 값 설정
path.append(category)
path.append(recipe)

Codable 지원

// 모든 값이 Codable일 때 NavigationPath는 Codable입니다.
@State private var path = NavigationPath()

// 인코딩
let data = try JSONEncoder().encode(path.codable)

// 디코딩
let codableRep = try JSONDecoder().decode(NavigationPath.CodableRepresentation.self, from: data)
path = NavigationPath(codableRep)

NavigationSplitView 전체 참조

NavigationSplitView는 기기 크기에 적응하는 다중 열 레이아웃을 만듭니다.

2.1 두 열 레이아웃

기본 두 열 (WWDC 2022, 10:40)

struct MultipleColumns: View {
    @State private var selectedCategory: Category?
    @State private var selectedRecipe: Recipe?
    @StateObject private var dataModel = DataModel()

    var body: some View {
        NavigationSplitView {
            List(Category.allCases, selection: $selectedCategory) { category in
                NavigationLink(category.localizedName, value: category)
            }
            .navigationTitle("Categories")
        } detail: {
            if let recipe = selectedRecipe {
                RecipeDetail(recipe: recipe)
            } else {
                Text("Select a recipe")
            }
        }
    }
}

2.2 세 열 레이아웃

사이드바와 세부 정보 사이에 중간 열을 위한 content: 클로저를 추가합니다:

NavigationSplitView {
    List(Category.allCases, selection: $selectedCategory) { category in
        NavigationLink(category.localizedName, value: category)
    }
} content: {
    List(dataModel.recipes(in: selectedCategory), selection: $selectedRecipe) { recipe in
        NavigationLink(recipe.name, value: recipe)
    }
} detail: {
    RecipeDetail(recipe: selectedRecipe)
}

2.3 NavigationStack과 함께 NavigationSplitView 사용

사이드바 선택을 유지하면서 그리드에서 세부 정보로 드릴다운하기 위해 세부 정보 열 내부에 NavigationStack(path:)를 배치합니다:

NavigationSplitView {
    List(Category.allCases, selection: $selectedCategory) { ... }
} detail: {
    NavigationStack(path: $path) {
        RecipeGrid(category: selectedCategory)
            .navigationDestination(for: Recipe.self) { recipe in
                RecipeDetail(recipe: recipe)
            }
    }
}

2.4 열 표시 여부

@State private var columnVisibility: NavigationSplitViewVisibility = .all

NavigationSplitView(columnVisibility: $columnVisibility) {
    Sidebar()
} content: {
    Content()
} detail: {
    Detail()
}

// 프로그래밍 방식으로 표시 여부 제어
columnVisibility = .detailOnly  // 사이드바 및 콘텐츠 숨기기
columnVisibility = .all          // 모든 열 표시
columnVisibility = .automatic    // 시스템이 결정

2.5 자동 적응

NavigationSplitView는 자동으로 적응합니다:

  • iPad 가로 모든 열 표시 (구성에 따라 다름)
  • iPad 세로/Slide Over 오버레이 또는 단일 열로 축소
  • iPhone 단일 탐색 스택
  • Apple Watch/TV 단일 탐색 스택

선택 변경은 iPhone에서 push/pop으로 자동 변환됩니다.

2.6 iOS 26+ Liquid Glass 사이드바 (WWDC 2025, 323)

NavigationSplitView {
    List { ... }
} detail: {
    DetailView()
}
// iPad/macOS에서 사이드바가 자동으로 Liquid Glass 모양을 얻습니다.

// 유리 사이드바 뒤로 콘텐츠 확장
.backgroundExtensionEffect()  // 안전 영역 외부의 콘텐츠를 미러링하고 흐리게 합니다.

딥 링킹 및 URL 라우팅

3.1 딥 링크 패턴

.onOpenURL을 사용하여 URL을 수신하고, URLComponents로 구문 분석한 다음, NavigationPath를 조작합니다:

.onOpenURL { url in
    guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
          let host = components.host else { return }
    path.removeLast(path.count)  // 먼저 루트로 이동
    // 호스트/경로를 구문 분석하여 대상을 결정한 다음, path.append(value)
}

다중 단계 딥 링크(myapp://category/desserts/recipe/apple-pie)의 경우 URL 경로 구성 요소를 반복하고 각 해결된 값을 추가하여 전체 탐색 스택을 구축합니다.

포괄적인 딥 링킹 예제, 오류 진단 및 테스트 워크플로우는 axiom-swiftui-nav-diag(패턴 3)를 참조하세요.


상태 복원

4.1 완전한 상태 복원 (WWDC 2022, 18:12)

struct UseSceneStorage: View {
    @StateObject private var navModel = NavigationModel()
    @SceneStorage("navigation") private var data: Data?
    @StateObject private var dataModel = DataModel()

    var body: some View {
        NavigationSplitView {
            List(Category.allCases, selection: $navModel.selectedCategory) { category in
                NavigationLink(category.localizedName, value: category)
            }
            .navigationTitle("Categories")
        } detail: {
            NavigationStack(path: $navModel.recipePath) {
                RecipeGrid(category: navModel.selectedCategory)
            }
        }
        .task {
            // 나타날 때 복원
            if let data = data {
                navModel.jsonData = data
            }
            // 변경 사항 저장
            for await _ in navModel.objectWillChangeSequence {
                data = navModel.jsonData
            }
        }
        .environmentObject(dataModel)
    }
}

4.2 Codable NavigationModel

class NavigationModel: ObservableObject, Codable {
    @Published var selectedCategory: Category?
    @Published var recipePath: [Recipe] = []

    enum CodingKeys: String, CodingKey {
        case selectedCategory
        case recipePathIds  // 전체 객체가 아닌 ID 저장
    }

    func encode(to encoder: Encoder) throws {
        var container = encoder.container(keyedBy: CodingKeys.self)
        try container.encodeIfPresent(selectedCategory, forKey: .selectedCategory)
        try container.encode(recipePath.map(\.id), forKey: .recipePathIds)
    }

    init() {}

    required init(from decoder: Decoder) throws {
        let container = try decoder.container(keyedBy: CodingKeys.self)
        self.selectedCategory = try container.decodeIfPresent(Category.self, forKey: .selectedCategory)
        let recipePathIds = try container.decode([Recipe.ID].self, forKey: .recipePathIds)
        self.recipePath = recipePathIds.compactMap { DataModel.shared[$0] } // 삭제된 항목은 무시
    }
}

전체 모델 객체 대신 ID를 저장하고 compactMap을 사용하여 삭제된 항목을 정상적으로 처리합니다. 4.1에 표시된 대로 SceneStorage 통합을 위해 jsonData 계산 속성과 objectWillChangeSequence를 추가하세요.


탭 + 탐색 통합

5.1 탭 문법 (iOS 18+) (WWDC 2024, 4:27)

TabView {
    Tab("Watch Now", systemImage: "play") {
        WatchNowView()
    }
    Tab("Library", systemImage: "books.vertical") {
        LibraryView()
    }

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ComeOnOliver/skillshub

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

ComeOnOliver/skillshub

Next.js 16+ 和 Turbopack — 增量打包、文件系统缓存、开发速度,以及何时使用 Turbopack 与 webpack。

ComeOnOliver/skillshub

SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices.

ComeOnOliver/skillshub

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.

ComeOnOliver/skillshub

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

ComeOnOliver/skillshub

Next.js 15 애플리케이션을 위한 프론트엔드 개발 가이드라인. React 19, TypeScript, Shadcn/ui, Tailwind CSS를 사용한 모던 패턴. Server Components, Client Components, App Router, 파일 구조, Shadcn/ui 컴포넌트, 성능 최적화, TypeScript 모범 사례 포함. 컴포넌트, 페이지, 기능 생성, 데이터 페칭, 스타일링, 라우팅, 프론트엔드 코드 작업 시 사용.

ComeOnOliver/skillshub

Provides Tamagui patterns for config v4, compiler optimization, styled context, and cross-platform styling. Must use when working with Tamagui projects (tamagui.config.ts, @tamagui imports).

ComeOnOliver/skillshub

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

ComeOnOliver/skillshub

Create high-converting, visually distinctive landing pages. Use when building marketing pages, product launches, SaaS homepages, or any single-page conversion-focused website. Guides section-by-section composition with anti-AI-slop principles.

ComeOnOliver/skillshub

Auto-loaded context for Portfolio Buddy 2 development. Use for ANY task involving: React 19 development, TypeScript, portfolio analysis features, metrics calculations, trading strategy comparison, or working with the Portfolio Buddy 2 codebase. Contains tech stack, known issues, and architectural constraints.

ComeOnOliver/skillshub

Next.js development tooling via MCP. Inspect routes, components, build info, and debug Next.js apps. Use when working on Next.js applications, debugging routing, or inspecting app structure. NOT for general React or non-Next.js projects.

ComeOnOliver/skillshub

Implement UI using Shadcn MCP (atoms/theme) and 21st.dev MCP (complex sections). Use when adding buttons, layouts, or generating landing pages.

ComeOnOliver/skillshub

A conceptual skill for building an API client in Next.js that handles JWT tokens

ComeOnOliver/skillshub

Best practices and patterns for Next.js App Router, Server Actions, and Routing in this project.

ComeOnOliver/skillshub

The Design System, Theme, and UX rules for the Physical AI Hub.

ComeOnOliver/skillshub

Comprehensive frontend development skill for building modern, performant web applications using ReactJS, NextJS, TypeScript, Tailwind CSS. Includes component scaffolding, performance optimization, bundle analysis, and UI best practices. Use when developing frontend features, optimizing performance, implementing UI/UX designs, managing state, or reviewing frontend code.

ComeOnOliver/skillshub

This document captures learnings from fixing keyboard navigation issues when floating components (Select, DropdownMenu, Popover) have CSS open/close animations.

ComeOnOliver/skillshub

Build Next.js 16 applications with correct patterns and distinctive design. Use when creating pages, layouts, dynamic routes, upgrading from Next.js 15, or implementing proxy.ts. Covers breaking changes (async params/searchParams, Turbopack, cacheComponents) and frontend aesthetics. NOT when building non-React or backend-only applications.

ComeOnOliver/skillshub

Comprehensive Framer Motion animation library for React. Covers motion components, variants, gestures, page transitions, and scroll animations. Use when adding animations to React/Next.js applications.

ComeOnOliver/skillshub

Build interfaces that resonate, not just render. This skill enforces bold, intentional

관련 스킬