Communitygithub.com

ComeOnOliver/skillshub

Referencia — Guía completa de navegación en SwiftUI que cubre NavigationStack (iOS 16+), NavigationSplitView (iOS 16+), NavigationPath, deep linking, restauración de estado, integración Tab+Navigation (iOS 18+), navegación Liquid Glass (iOS 26+) y patrones de coordinador

¿Qué es skillshub?

Esta habilidad es una referencia integral para dominar las APIs de navegación de SwiftUI, desde los fundamentos hasta las últimas novedades en iOS 26. Está diseñada para desarrolladores que trabajan con SwiftUI y necesitan implementar flujos de navegación robustos y modernos en sus aplicaciones para múltiples plataformas Apple. La habilidad detalla el uso de NavigationStack y NavigationSplitView, explicando cómo crear desde pilas simples hasta diseños de varias columnas que se adaptan automáticamente al tamaño del dispositivo. También cubre temas avanzados como el enrutamiento profundo (deep linking) con `onOpenURL`, la restauración del estado de navegación usando `SceneStorage` y `NavigationPath` codificable, y la integración de pestañas con estados de navegación independientes. Finalmente, incluye las últimas incorporaciones de iOS 26, como el diseño Liquid Glass para barras de navegación y la minimización de barras de pestañas, así como patrones de coordinador para arquitecturas más complejas. La habilidad es compatible con cualquier proyecto SwiftUI a partir de iOS 16 y está pensada para desarrolladores que buscan una guía de referencia rápida y completa en español.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Referencia de la API de Navegación de SwiftUI

Resumen

Las APIs de navegación de SwiftUI proporcionan una navegación programática basada en datos que escala desde pilas simples hasta diseños complejos de varias columnas. Introducidas en iOS 16 (2022) con NavigationStack y NavigationSplitView, evolucionaron en iOS 18 (2024) con la unificación de pestañas/barra lateral y se refinaron en iOS 26 (2025) con el diseño Liquid Glass.

Cronología de evolución

  • 2022 (iOS 16) NavigationStack, NavigationSplitView, NavigationPath, NavigationLink basado en valores
  • 2024 (iOS 18) Unificación de pestañas/barra lateral, estilo sidebarAdaptable, transición de navegación con zoom
  • 2025 (iOS 26) Navegación Liquid Glass, búsqueda alineada en la parte inferior, barras de pestañas flotantes, backgroundExtensionEffect

Capacidades clave

  • Navegación basada en datos NavigationPath representa el estado de la pila, lo que permite push/pop programático y enlaces profundos
  • Diseños de varias columnas NavigationSplitView se adapta automáticamente (3 columnas en iPad → pila única en iPhone)
  • Restauración de estado NavigationPath codificable + SceneStorage para persistencia entre lanzamientos de la aplicación
  • Integración de pestañas NavigationStack por pestaña con preservación del estado al cambiar de pestaña (iOS 18+)
  • Liquid Glass Barras de navegación, barras laterales y barras de herramientas de vidrio automáticas (iOS 26+)

Cuándo usar vs UIKit

  • Navegación SwiftUI Nuevas aplicaciones, multiplataforma, flujos de navegación más simples → Usar NavigationStack/SplitView
  • UINavigationController Patrones de coordinador complejos, código heredado, características específicas de UIKit → Considerar UIKit

Habilidades relacionadas

  • Usar axiom-swiftui-nav para anti-patrones, árboles de decisión, escenarios de presión
  • Usar axiom-swiftui-nav-diag para solución sistemática de problemas de navegación

Cuándo Usar Esta Habilidad

Usa esta habilidad cuando:

  • Implementes APIs de navegación NavigationStack, NavigationSplitView, NavigationPath, Tab+Navigation
  • Realices enlaces profundos o restauración de estado Enrutamiento de URL, NavigationPath codificable, SceneStorage
  • Adoptes características de iOS 26+ Navegación Liquid Glass, búsqueda alineada en la parte inferior, minimización de la barra de pestañas
  • Elijas una arquitectura de navegación Pila vs SplitView vs patrones de coordinador

Evolución de la API

Cronología

AñoVersión de iOSCaracterísticas clave
2020iOS 14NavigationView (obsoleto desde iOS 16)
2022iOS 16NavigationStack, NavigationSplitView, NavigationPath, NavigationLink basado en valores
2024iOS 18Unificación de pestañas/barra lateral, sidebarAdaptable, TabSection, transiciones con zoom
2025iOS 26Navegación Liquid Glass, backgroundExtensionEffect, tabBarMinimizeBehavior

NavigationView (Obsoleto)

NavigationView está obsoleto desde iOS 16. Usa NavigationStack (push/pop de una columna) o NavigationSplitView (varias columnas) exclusivamente en código nuevo. Mejoras clave: un solo NavigationPath reemplaza los enlaces isActive por enlace, seguridad de tipos basada en valores, restauración de estado codificable incorporada. Consulta la documentación "Migración a nuevos tipos de navegación".


Referencia Completa de NavigationStack

NavigationStack representa una interfaz de push-pop como Ajustes en iPhone o Preferencias del Sistema en macOS.

1.1 Creación de 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)
    }
}

Con Enlace de Ruta (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)
    }
}

El enlace de ruta + NavigationLink que presenta valores + navigationDestination(for:) forman el patrón central de navegación basada en datos.

1.2 NavigationLink (Basado en Valores)

NavigationLink que Presenta Valores

// Correcto: Basado en valores (iOS 16+)
NavigationLink(recipe.name, value: recipe)

// Correcto: Con etiqueta personalizada
NavigationLink(value: recipe) {
    RecipeTile(recipe: recipe)
}

// Obsoleto: Basado en vista (iOS 13-15)
NavigationLink(recipe.name) {
    RecipeDetail(recipe: recipe)  // No usar en código nuevo
}

Cómo funciona NavigationLink con NavigationStack

  1. NavigationStack mantiene una colección path
  2. Tocar un enlace que presenta un valor agrega el valor a la ruta
  3. NavigationStack asigna modificadores navigationDestination sobre los valores de la ruta
  4. Las vistas se colocan en la pila según las asignaciones de destino

1.3 Modificador navigationDestination

Tipo Único

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

Múltiples 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-patrones de Navegación

  • Nunca mezcles navigationDestination(for:) y NavigationLink(destination:) en la misma jerarquía de NavigationStack — causa comportamiento indefinido
  • Registra navigationDestination(for:) una vez por tipo de datos — los duplicados hacen que aparezca la vista incorrecta

Reglas de ubicación

  • Coloca navigationDestination fuera de los contenedores perezosos (no dentro de ForEach)
  • Colócalo cerca de los NavigationLinks relacionados para organizar el código
  • Debe estar dentro de la jerarquía de NavigationStack
// Correcto: Fuera del contenedor perezoso
ScrollView {
    LazyVGrid(columns: columns) {
        ForEach(recipes) { recipe in
            NavigationLink(value: recipe) {
                RecipeTile(recipe: recipe)
            }
        }
    }
}
.navigationDestination(for: Recipe.self) { recipe in
    RecipeDetail(recipe: recipe)
}

// Incorrecto: Dentro de ForEach (puede que no se cargue)
ForEach(recipes) { recipe in
    NavigationLink(value: recipe) { RecipeTile(recipe: recipe) }
        .navigationDestination(for: Recipe.self) { r in  // No hagas esto
            RecipeDetail(recipe: r)
        }
}

1.4 NavigationPath

NavigationPath es una colección de tipo borrado para pilas de navegación heterogéneas.

Array Tipado vs NavigationPath

// Array tipado: Todos los valores del mismo tipo
@State private var path: [Recipe] = []

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

Operaciones de NavigationPath

// Agregar valor
path.append(recipe)

// Volver al anterior
path.removeLast()

// Volver a la raíz
path.removeLast(path.count)
// o
path = NavigationPath()

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

// Enlace profundo: Establecer múltiples valores
path.append(category)
path.append(recipe)

Soporte Codable

// NavigationPath es Codable cuando todos los valores son 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)

Referencia Completa de NavigationSplitView

NavigationSplitView crea diseños de varias columnas que se adaptan al tamaño del dispositivo.

2.1 Diseño de Dos Columnas

Básico de Dos Columnas (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 Diseño de Tres Columnas

Agrega un cierre content: entre la barra lateral y el detalle para una columna intermedia:

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 con NavigationStack

Coloca un NavigationStack(path:) dentro de la columna de detalle para una exploración en profundidad de cuadrícula a detalle mientras se preserva la selección de la 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 Visibilidad de Columna

@State private var columnVisibility: NavigationSplitViewVisibility = .all

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

// Controlar visibilidad programáticamente
columnVisibility = .detailOnly  // Ocultar barra lateral y contenido
columnVisibility = .all          // Mostrar todas las columnas
columnVisibility = .automatic    // El sistema decide

2.5 Adaptación Automática

NavigationSplitView se adapta automáticamente:

  • iPad horizontal Todas las columnas visibles (según la configuración)
  • iPad vertical/Slide Over Se colapsa a superposición o una sola columna
  • iPhone Pila de navegación única
  • Apple Watch/TV Pila de navegación única

Los cambios de selección se traducen automáticamente a push/pop en iPhone.

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

NavigationSplitView {
    List { ... }
} detail: {
    DetailView()
}
// La barra lateral obtiene automáticamente la apariencia Liquid Glass en iPad/macOS

// Extiende el contenido detrás de la barra lateral de vidrio
.backgroundExtensionEffect()  // Refleja y difumina el contenido fuera del área segura

Enlaces Profundos y Enrutamiento de URL

3.1 Patrón de Enlace Profundo

Usa .onOpenURL para recibir URLs, analízalas con URLComponents, luego manipula NavigationPath:

.onOpenURL { url in
    guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
          let host = components.host else { return }
    path.removeLast(path.count)  // Primero volver a la raíz
    // Analizar host/ruta para determinar el destino, luego path.append(valor)
}

Para enlaces profundos de varios pasos (myapp://category/desserts/recipe/apple-pie), itera sobre los componentes de la ruta de la URL y agrega cada valor resuelto para construir la pila de navegación completa.

Para ejemplos completos de enlaces profundos, diagnóstico de errores y flujos de trabajo de prueba, consulta axiom-swiftui-nav-diag (Patrón 3).


Restauración de Estado

4.1 Restauración 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 al aparecer
            if let data = data {
                navModel.jsonData = data
            }
            // Guardar en cambios
            for await _ in navModel.objectWillChangeSequence {
                data = navModel.jsonData
            }
        }
        .environmentObject(dataModel)
    }
}

4.2 NavigationModel Codificable

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

    enum CodingKeys: String, CodingKey {
        case selectedCategory
        case recipePathIds  // Almacenar IDs, no 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] } // Descartar elementos eliminados
    }
}

Almacena IDs (no objetos de modelo completos) y usa compactMap para manejar elementos eliminados de forma segura. Agrega la propiedad computada jsonData y objectWillChangeSequence para la integración con SceneStorage como se muestra en 4.1.


Integración de Pestañas + Navegación

5.1 Sintaxis de Pestañas (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

Skills relacionados