Communitygithub.com

ComeOnOliver/skillshub

Referência — Guia abrangente de navegação SwiftUI cobrindo NavigationStack (iOS 16+), NavigationSplitView (iOS 16+), NavigationPath, deep linking, restauração de estado, integração Tab+Navigation (iOS 18+), navegação Liquid Glass (iOS 26+) e padrões de coordenador.

O que é skillshub?

Este skill oferece uma referência completa e atualizada das APIs de navegação do SwiftUI, desde as introduzidas no iOS 16 (NavigationStack, NavigationSplitView, NavigationPath) até as mais recentes inovações do iOS 26 (Liquid Glass). Ele é projetado para desenvolvedores que precisam implementar navegação data-driven, suportar deep linking, restaurar estado de navegação entre sessões, ou integrar abas com NavigationStack preservando o estado. O conteúdo inclui exemplos práticos de código, regras de posicionamento para modificadores como `navigationDestination`, padrões para navegação multi-coluna com adaptação automática entre iPad e iPhone, e integração com TabView a partir do iOS 18. Também cobre a evolução histórica das APIs para auxiliar na migração de NavigationView (depreciado) para as novas abordagens, além de alertar sobre anti-padrões comuns. O skill é compatível com qualquer ferramenta de agente de IA que suporte leitura de documentação em markdown.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Referência da API de Navegação SwiftUI

Visão Geral

As APIs de navegação do SwiftUI fornecem navegação orientada a dados e programática que escala de pilhas simples a layouts complexos de múltiplas colunas. Introduzidas no iOS 16 (2022) com NavigationStack e NavigationSplitView, evoluíram no iOS 18 (2024) com a unificação de Abas/Barras Laterais, e foram refinadas no iOS 26 (2025) com o design Liquid Glass.

Linha do tempo da evolução

  • 2022 (iOS 16) NavigationStack, NavigationSplitView, NavigationPath, NavigationLink baseado em valor
  • 2024 (iOS 18) Unificação de Abas/Barras Laterais, estilo sidebarAdaptable, transição de navegação com zoom
  • 2025 (iOS 26) Chrome de navegação Liquid Glass, pesquisa alinhada à parte inferior, barras de abas flutuantes, backgroundExtensionEffect

Principais capacidades

  • Navegação orientada a dados NavigationPath representa o estado da pilha, permitindo push/pop programático e deep linking
  • Layouts multi-coluna NavigationSplitView adapta-se automaticamente (3 colunas no iPad → pilha única no iPhone)
  • Restauração de estado NavigationPath Codable + SceneStorage para persistência entre inicializações do aplicativo
  • Integração com abas NavigationStack por aba com preservação de estado ao alternar abas (iOS 18+)
  • Liquid Glass Barras de navegação, barras laterais e barras de ferramentas em vidro automáticas (iOS 26+)

Quando usar vs UIKit

  • Navegação SwiftUI Novos aplicativos, multiplataforma, fluxos de navegação mais simples → Use NavigationStack/SplitView
  • UINavigationController Padrões de coordenador complexos, código legado, recursos específicos do UIKit → Considere UIKit

Skills Relacionados

  • Use axiom-swiftui-nav para anti-padrões, árvores de decisão, cenários de pressão
  • Use axiom-swiftui-nav-diag para solução sistemática de problemas de navegação

Quando Usar Este Skill

Use este skill quando:

  • Implementando APIs de navegação NavigationStack, NavigationSplitView, NavigationPath, Tab+Navigation
  • Deep linking ou restauração de estado Roteamento de URL, NavigationPath Codable, SceneStorage
  • Adotando recursos do iOS 26+ Navegação Liquid Glass, pesquisa alinhada à parte inferior, minimização da barra de abas
  • Escolhendo arquitetura de navegação Pilha vs SplitView vs padrões de coordenador

Evolução da API

Linha do tempo

AnoVersão do iOSPrincipais Recursos
2020iOS 14NavigationView (depreciado no iOS 16)
2022iOS 16NavigationStack, NavigationSplitView, NavigationPath, NavigationLink baseado em valor
2024iOS 18Unificação de Abas/Barras Laterais, sidebarAdaptable, TabSection, transições com zoom
2025iOS 26Navegação Liquid Glass, backgroundExtensionEffect, tabBarMinimizeBehavior

NavigationView (Depreciado)

NavigationView foi depreciado a partir do iOS 16. Use NavigationStack (push/pop de coluna única) ou NavigationSplitView (multi-coluna) exclusivamente em código novo. Principais melhorias: NavigationPath único substitui bindings isActive por link, segurança de tipo baseada em valor, restauração de estado Codable integrada. Consulte a documentação "Migrando para novos tipos de navegação".


Referência Completa do NavigationStack

NavigationStack representa uma interface push-pop como Ajustes no iPhone ou Configurações do Sistema no macOS.

1.1 Criando NavigationStack

NavigationStack Básico

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

Com Binding de Caminho (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)
    }
}

Binding de caminho + NavigationLink de apresentação de valor + navigationDestination(for:) formam o padrão central de navegação orientada a dados.

1.2 NavigationLink (Baseado em Valor)

NavigationLink de Apresentação de Valor

// Correto: Baseado em valor (iOS 16+)
NavigationLink(recipe.name, value: recipe)

// Correto: Com rótulo personalizado
NavigationLink(value: recipe) {
    RecipeTile(recipe: recipe)
}

// Depreciado: Baseado em visualização (iOS 13-15)
NavigationLink(recipe.name) {
    RecipeDetail(recipe: recipe)  // Não use em código novo
}

Como NavigationLink funciona com NavigationStack

  1. NavigationStack mantém uma coleção path
  2. Tocar em um link de apresentação de valor adiciona o valor ao caminho
  3. NavigationStack mapeia modificadores navigationDestination sobre os valores do caminho
  4. As visualizações são empurradas para a pilha com base nos mapeamentos de destino

1.3 Modificador navigationDestination

Tipo Único

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

Múltiplos Tipos

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)
        }
}

Anti-Padrões de Navegação

  • Nunca misture navigationDestination(for:) e NavigationLink(destination:) na mesma hierarquia NavigationStack — causa comportamento indefinido
  • Registre navigationDestination(for:) uma vez por tipo de dado — duplicatas fazem a visualização errada aparecer

Regras de posicionamento

  • Coloque navigationDestination fora de contêineres lazy (não dentro de ForEach)
  • Coloque perto de NavigationLinks relacionados para organização do código
  • Deve estar dentro da hierarquia NavigationStack
// Correto: Fora do contêiner lazy
ScrollView {
    LazyVGrid(columns: columns) {
        ForEach(recipes) { recipe in
            NavigationLink(value: recipe) {
                RecipeTile(recipe: recipe)
            }
        }
    }
}
.navigationDestination(for: Recipe.self) { recipe in
    RecipeDetail(recipe: recipe)
}

// Errado: Dentro de ForEach (pode não ser carregado)
ForEach(recipes) { recipe in
    NavigationLink(value: recipe) { RecipeTile(recipe: recipe) }
        .navigationDestination(for: Recipe.self) { r in  // Não faça isso
            RecipeDetail(recipe: r)
        }
}

1.4 NavigationPath

NavigationPath é uma coleção type-erased para pilhas de navegação heterogêneas.

Array Tipado vs NavigationPath

// Array tipado: Todos os valores do mesmo tipo
@State private var path: [Recipe] = []

// NavigationPath: Tipos mistos
@State private var path = NavigationPath()

Operações NavigationPath

// Adicionar valor
path.append(recipe)

// Voltar ao anterior
path.removeLast()

// Voltar à raiz
path.removeLast(path.count)
// ou
path = NavigationPath()

// Verificar contagem
if path.count > 0 { ... }

// Deep link: Definir vários valores
path.append(category)
path.append(recipe)

Suporte Codable

// NavigationPath é Codable quando todos os valores são Codable
@State private var path = NavigationPath()

// Codificar
let data = try JSONEncoder().encode(path.codable)

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

Referência Completa do NavigationSplitView

NavigationSplitView cria layouts multi-coluna que se adaptam ao tamanho do dispositivo.

2.1 Layout de Duas Colunas

Duas Colunas Básico (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 Layout de Três Colunas

Adicione um closure content: entre a barra lateral e o detalhe para uma coluna do meio:

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 NavigationSplitView com NavigationStack

Coloque um NavigationStack(path:) dentro da coluna de detalhes para drill-down de grade para detalhe enquanto preserva a seleção da barra lateral:

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

2.4 Visibilidade da Coluna

@State private var columnVisibility: NavigationSplitViewVisibility = .all

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

// Controlar visibilidade programaticamente
columnVisibility = .detailOnly  // Ocultar barra lateral e conteúdo
columnVisibility = .all          // Mostrar todas as colunas
columnVisibility = .automatic    // O sistema decide

2.5 Adaptação Automática

NavigationSplitView adapta-se automaticamente:

  • iPad paisagem Todas as colunas visíveis (dependendo da configuração)
  • iPad retrato/Slide Over Recolhe para sobreposição ou coluna única
  • iPhone Pilha de navegação única
  • Apple Watch/TV Pilha de navegação única

As mudanças de seleção traduzem-se automaticamente em push/pop no iPhone.

2.6 Barra Lateral Liquid Glass iOS 26+ (WWDC 2025, 323)

NavigationSplitView {
    List { ... }
} detail: {
    DetailView()
}
// A barra lateral recebe automaticamente aparência Liquid Glass no iPad/macOS

// Estender conteúdo atrás da barra lateral de vidro
.backgroundExtensionEffect()  // Espelha e desfoca o conteúdo fora da área segura

Deep Linking e Roteamento de URL

3.1 Padrão de Deep Link

Use .onOpenURL para receber URLs, analise com URLComponents, depois manipule NavigationPath:

.onOpenURL { url in
    guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
          let host = components.host else { return }
    path.removeLast(path.count)  // Primeiro, volte à raiz
    // Analise host/caminho para determinar o destino, depois path.append(valor)
}

Para deep links de múltiplas etapas (myapp://category/desserts/recipe/apple-pie), itere pelos componentes do caminho da URL e anexe cada valor resolvido para construir a pilha de navegação completa.

Para exemplos abrangentes de deep linking, diagnóstico de erros e fluxos de trabalho de teste, consulte axiom-swiftui-nav-diag (Padrão 3).


Restauração de Estado

4.1 Restauração Completa de Estado (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 {
            // Restaurar ao aparecer
            if let data = data {
                navModel.jsonData = data
            }
            // Salvar em alterações
            for await _ in navModel.objectWillChangeSequence {
                data = navModel.jsonData
            }
        }
        .environmentObject(dataModel)
    }
}

4.2 NavigationModel Codable

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

    enum CodingKeys: String, CodingKey {
        case selectedCategory
        case recipePathIds  // Armazene IDs, não objetos completos
    }

    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] } // Descarta itens deletados
    }
}

Armazene IDs (não objetos de modelo completos) e use compactMap para lidar graciosamente com itens deletados. Adicione a propriedade computada jsonData e objectWillChangeSequence para integração SceneStorage conforme mostrado em 4.1.


Integração Tab + Navegação

5.1 Sintaxe de Aba (iOS 18+) (WWDC 2024, 4:27)

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

…

[truncado para tradução]

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

Habilidades Relacionadas