Communitygithub.com

ComeOnOliver/skillshub

Úsalo al implementar patrones de navegación, elegir entre NavigationStack y NavigationSplitView, manejar enlaces profundos, adoptar patrones de coordinador o solicitar revisión de código de implementación de navegación; evita la corrupción del estado de navegación, fallos de enlaces profundos y errores de restauración de estado para iOS 18+.

¿Qué es skillshub?

Esta habilidad proporciona una guía completa y práctica para implementar patrones de navegación modernos en SwiftUI, específicamente optimizada para iOS 18+. Ayuda a los desarrolladores a decidir entre NavigationStack, NavigationSplitView y TabView según la estructura de la aplicación, y cubre técnicas avanzadas como navegación programática con NavigationPath, enlaces profundos (deep links), restauración de estado con SceneStorage y el patrón de coordinador (router). La habilidad identifica nueve anti-patrones críticos que pueden causar fallos, como el uso de NavigationView obsoleto, NavigationLink basado en vistas o la modificación de NavigationPath fuera del hilo principal. Incluye un árbol de decisión rápido y siete patrones detallados con ejemplos de código Swift listos para usar, desde navegación básica hasta interfaces adaptables con barra lateral en iPad. También sugiere habilidades relacionadas para diagnósticos sistemáticos y referencias completas de API, y ofrece prompts de ejemplo que reflejan preguntas reales de desarrolladores sobre navegación en SwiftUI.

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

Preguntar en tu IA favorita

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

Documentación

Navegación en SwiftUI

Cuándo Usar Esta Habilidad

Úsala cuando:

  • Elijas la arquitectura de navegación (NavigationStack vs NavigationSplitView vs TabView)
  • Implementes navegación programática con NavigationPath
  • Configures enlaces profundos y enrutamiento de URL
  • Implementes restauración de estado para la navegación
  • Adoptes patrones de pestañas/barra lateral (iOS 18+)
  • Implementes patrones de coordinador/enrutador
  • Solicites revisión de código de una implementación de navegación antes del lanzamiento

Habilidades Relacionadas

  • Usa axiom-swiftui-nav-diag para solución sistemática de problemas de navegación
  • Usa axiom-swiftui-nav-ref para referencia completa de API (incluyendo personalización de pestañas, funciones de iOS 26+) con todos los ejemplos de WWDC

Ejemplos de Prompts

Estas son preguntas reales que los desarrolladores hacen y que esta habilidad está diseñada para responder:

1. "¿Debería usar NavigationStack o NavigationSplitView para mi aplicación?"

-> La habilidad proporciona un árbol de decisión basado en los dispositivos objetivo, la profundidad de la jerarquía de contenido y los requisitos multiplataforma

2. "¿Cómo navego programáticamente en SwiftUI?"

-> La habilidad muestra patrones de manipulación de NavigationPath para push, pop, pop-to-root y enlaces profundos

3. "Mis enlaces profundos no funcionan. La aplicación se abre pero muestra la pantalla incorrecta."

-> La habilidad cubre patrones de análisis de URL, orden de construcción de rutas y problemas de temporización con onOpenURL

4. "El estado de navegación se pierde cuando mi aplicación pasa a segundo plano."

-> La habilidad demuestra NavigationPath codificable, persistencia con SceneStorage y restauración resistente a fallos

5. "¿Cómo implemento un patrón de coordinador en SwiftUI?"

-> La habilidad proporciona ejemplos del patrón Router junto con orientación sobre cuándo los coordinadores añaden valor versus complejidad


Banderas Rojas — Anti-patrones a Prevenir

Si estás haciendo CUALQUIERA de estos, DETENTE y usa los patrones de esta habilidad:

❌ CRÍTICO — Nunca Hagas Esto

1. Usar NavigationView obsoleto en iOS 16+

// ❌ INCORRECTO — Obsoleto, comportamiento diferente en iOS 16+
NavigationView {
    List { ... }
}
.navigationViewStyle(.stack)

Por qué falla: NavigationView está obsoleto desde iOS 16. Carece de soporte para NavigationPath, lo que hace que la navegación programática y los enlaces profundos no sean fiables. El comportamiento diferente entre versiones de iOS causa errores.

2. Usar NavigationLink basado en vistas para navegación programática

// ❌ INCORRECTO — No se puede controlar programáticamente
NavigationLink("Receta") {
    RecipeDetail(recipe: recipe)  // Destino de vista, sin valor
}

Por qué falla: Los enlaces basados en vistas no se pueden controlar programáticamente. No hay manera de hacer un enlace profundo o volver a este destino. Obsoleto desde iOS 16.

3. Poner navigationDestination dentro de contenedores perezosos

// ❌ INCORRECTO — Puede no cargarse cuando se necesita
LazyVGrid(columns: columns) {
    ForEach(items) { item in
        NavigationLink(value: item) { ... }
            .navigationDestination(for: Item.self) { item in  // No hagas esto
                ItemDetail(item: item)
            }
    }
}

Por qué falla: Los contenedores perezosos no cargan todas las vistas inmediatamente. Es posible que navigationDestination no sea visible para NavigationStack, causando que la navegación falle silenciosamente.

4. Almacenar objetos completos del modelo en NavigationPath para restauración

// ❌ INCORRECTO — Duplica datos, obsoleto al restaurar
class NavigationModel: Codable {
    var path: [Recipe] = []  // Objetos Recipe completos
}

Por qué falla: Duplica datos que ya están en tu modelo. Al restaurar, los datos de Recipe pueden estar obsoletos (editados/eliminados en otro lugar). Usa IDs y resuelve a datos actuales.

5. Modificar NavigationPath fuera de MainActor

// ❌ INCORRECTO — Actualización de UI fuera del hilo principal
Task.detached {
    await viewModel.path.append(recipe)  // Hilo de fondo
}

Por qué falla: NavigationPath está vinculado a la UI. Las modificaciones deben ocurrir en MainActor o el estado de navegación se corrompe. Puede causar fallos o fallos silenciosos.

6. Falta de aislamiento @MainActor para el estado de navegación

// ❌ INCORRECTO — No aislado en MainActor
class Router: ObservableObject {
    @Published var path = NavigationPath()  // Sin @MainActor
}

Por qué falla: En concurrencia estricta de Swift 6, las propiedades @Published accedidas desde vistas SwiftUI requieren aislamiento de MainActor. Causa advertencias de condición de carrera y posibles fallos.

7. No manejar el estado de navegación en aplicaciones con múltiples pestañas

// ❌ INCORRECTO — NavigationPath compartido entre pestañas
TabView {
    Tab("Inicio") { HomeView() }
    Tab("Ajustes") { SettingsView() }
}
// Todas las pestañas comparten el mismo NavigationStack — ¡incorrecto!

Por qué falla: Cada pestaña debe tener su propio NavigationStack para preservar el estado de navegación al cambiar de pestaña. El estado compartido causa una UX confusa.

8. Ignorar errores de decodificación de NavigationPath

// ❌ INCORRECTO — Fallo por datos inválidos
let path = NavigationPath(try! decoder.decode(NavigationPath.CodableRepresentation.self, from: data))

Por qué falla: El usuario puede haber eliminado elementos que estaban en la ruta. El esquema puede haber cambiado. Forzar el desenvolvimiento causa un fallo al restaurar.


Pasos Iniciales Obligatorios

SIEMPRE completa estos pasos antes de implementar la navegación:

// Paso 1: Identifica tu estructura de navegación
// Pregunta: ¿Pila única? ¿Varias columnas? ¿Basada en pestañas con navegación por pestaña?
// Registra la respuesta antes de escribir cualquier código

// Paso 2: Elige el contenedor basado en la estructura
// Pila única (principalmente iPhone): NavigationStack
// Varias columnas (principalmente iPad/Mac): NavigationSplitView
// Basada en pestañas: TabView con NavigationStack por pestaña

// Paso 3: Define tus tipos de valor para la navegación
// Todos los valores empujados en NavigationStack deben ser Hashable
// Para enlaces profundos/restauración, también Codable
struct Recipe: Hashable, Codable, Identifiable { ... }

// Paso 4: Planifica URLs de enlaces profundos (si es necesario)
// miapp://receta/{id}
// miapp://categoria/{nombre}/receta/{id}

// Paso 5: Planifica la restauración de estado (si es necesario)
// ¿Usarás SceneStorage? ¿Qué datos deben ser Codable?

Árbol de Decisión Rápido

¿Necesitas navegación?
├─ ¿Interfaz de varias columnas (principalmente iPad/Mac)?
│  └─ NavigationSplitView
│     ├─ ¿Necesitas profundización en la columna de detalle?
│     │  └─ NavigationStack dentro del detalle (Patrón 3)
│     └─ ¿Solo selección en el detalle?
│        └─ Solo enlace de selección (Patrón 2)
├─ ¿Aplicación basada en pestañas?
│  └─ TabView
│     ├─ ¿Cada pestaña necesita profundización?
│     │  └─ NavigationStack por pestaña (Patrón 4)
│     └─ ¿Experiencia de barra lateral en iPad?
│        └─ .tabViewStyle(.sidebarAdaptable) (Patrón 5)
└─ ¿Pila de una sola columna?
   └─ NavigationStack
      ├─ ¿Necesitas enlaces profundos?
      │  └─ Usa NavigationPath (Patrón 1b)
      └─ ¿Push/pop simple?
         └─ Ruta de array tipado (Patrón 1a)

¿Necesitas restauración de estado?
└─ SceneStorage + NavigationPath Codable (Patrón 6)

¿Necesitas abstracción de coordinador?
├─ ¿Flujos condicionales complejos?
├─ ¿Pruebas de lógica de navegación necesarias?
├─ ¿Compartir navegación entre muchas pantallas?
└─ SÍ a cualquier → Patrón de Router (Patrón 7)
   NO a todo → Usa NavigationPath directamente

Patrón 1a: NavigationStack Básico

Cuándo: Navegación simple push/pop, todos los destinos del mismo tipo

Tiempo estimado: 5-10 min

struct RecipeList: View {
    @State private var path: [Recipe] = []

    var body: some View {
        NavigationStack(path: $path) {
            List(recipes) { recipe in
                NavigationLink(recipe.name, value: recipe)
            }
            .navigationTitle("Recetas")
            .navigationDestination(for: Recipe.self) { recipe in
                RecipeDetail(recipe: recipe)
            }
        }
    }

    // Navegación programática
    func showRecipe(_ recipe: Recipe) {
        path.append(recipe)
    }

    func popToRoot() {
        path.removeAll()
    }
}

Puntos clave:

  • Array tipado [Recipe] cuando todos los valores son del mismo tipo
  • NavigationLink(title, value:) basado en valor
  • navigationDestination(for:) fuera de contenedores perezosos

Patrón 1b: NavigationStack con Enlaces Profundos

Cuándo: Múltiples tipos de destino, enlaces profundos basados en URL

Tiempo estimado: 15-20 min

struct ContentView: View {
    @State private var path = NavigationPath()

    var body: some View {
        NavigationStack(path: $path) {
            HomeView()
                .navigationDestination(for: Category.self) { category in
                    CategoryView(category: category)
                }
                .navigationDestination(for: Recipe.self) { recipe in
                    RecipeDetail(recipe: recipe)
                }
        }
        .onOpenURL { url in
            handleDeepLink(url)
        }
    }

    func handleDeepLink(_ url: URL) {
        // URL: miapp://categoria/postres/receta/tarta-de-manzana
        path.removeLast(path.count)  // Pop a la raíz primero

        guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false) else { return }
        let segments = components.path.split(separator: "/").map(String.init)

        var index = 0
        while index < segments.count - 1 {
            switch segments[index] {
            case "categoria":
                if let category = Category(rawValue: segments[index + 1]) {
                    path.append(category)
                }
                index += 2
            case "receta":
                if let recipe = dataModel.recipe(named: segments[index + 1]) {
                    path.append(recipe)
                }
                index += 2
            default:
                index += 1
            }
        }
    }
}

Puntos clave:

  • NavigationPath para tipos heterogéneos
  • Pop a la raíz antes de construir la ruta del enlace profundo
  • Construye la ruta en el orden correcto (padre → hijo)

Patrón 2: NavigationSplitView Basado en Selección

Cuándo: Diseño de varias columnas donde el detalle muestra el elemento seleccionado

Tiempo estimado: 10-15 min

struct MultiColumnView: View {
    @State private var selectedCategory: Category?
    @State private var selectedRecipe: Recipe?

    var body: some View {
        NavigationSplitView {
            List(Category.allCases, selection: $selectedCategory) { category in
                NavigationLink(category.name, value: category)
            }
            .navigationTitle("Categorías")
        } content: {
            if let category = selectedCategory {
                List(recipes(in: category), selection: $selectedRecipe) { recipe in
                    NavigationLink(recipe.name, value: recipe)
                }
                .navigationTitle(category.name)
            } else {
                Text("Selecciona una categoría")
            }
        } detail: {
            if let recipe = selectedRecipe {
                RecipeDetail(recipe: recipe)
            } else {
                Text("Selecciona una receta")
            }
        }
    }
}

Puntos clave:

  • selection: $binding en List se conecta a la selección de columna
  • Los enlaces que presentan valor actualizan la selección automáticamente
  • Se adapta a una sola pila en iPhone

Patrón 3: NavigationSplitView con Pila en el Detalle

Cuándo: Varias columnas con capacidad de profundización en el detalle

Tiempo estimado: 20-25 min

struct GridWithDrillDown: View {
    @State private var selectedCategory: Category?
    @State private var path: [Recipe] = []

    var body: some View {
        NavigationSplitView {
            List(Category.allCases, selection: $selectedCategory) { category in
                NavigationLink(category.name, value: category)
            }
            .navigationTitle("Categorías")
        } detail: {
            NavigationStack(path: $path) {
                if let category = selectedCategory {
                    RecipeGrid(category: category)
                        .navigationDestination(for: Recipe.self) { recipe in
                            RecipeDetail(recipe: recipe)
                        }
                } else {
                    Text("Selecciona una categoría")
                }
            }
        }
    }
}

Puntos clave:

  • NavigationStack dentro de la columna de detalle
  • Grid → Profundización en detalle mientras se preserva la barra lateral
  • Ruta separada para profundización, selección para barra lateral

Patrón 4: TabView con NavigationStack por Pestaña

Cuándo: Aplicación basada en pestañas donde cada pestaña tiene su propia navegación

Tiempo estimado: 15-20 min

struct TabBasedApp: View {
    var body: some View {
        TabView {
            Tab("Inicio", systemImage: "house") {
                NavigationStack {
                    HomeView()
                        .navigationDestination(for: Item.self) { item in
                            ItemDetail(item: item)
                        }
                }
            }

            Tab("Buscar", systemImage: "magnifyingglass") {
                NavigationStack {
                    SearchView()
                }
            }

            Tab("Ajustes", systemImage: "gear") {
                NavigationStack {
                    SettingsView()
                }
            }
        }
    }
}

Puntos clave:

  • Cada pestaña tiene su propio NavigationStack
  • El estado de navegación se preserva al cambiar de pestaña
  • Sintaxis de Tab en iOS 18+ con systemImage

Patrón 5: TabView Adaptable con Barra Lateral (iOS 18+)

Cuándo: Barra de pestañas en iPhone, barra lateral en iPad

Tiempo estimado: 20-25 min

struct AdaptableApp: View {
    var body: some View {
        TabView {
            Tab("Ver Ahora", systemImage: "play") {
                WatchNowView()
            }
            Tab("Biblioteca", systemImage: "books.vertical") {
                LibraryView()
            }

            TabSection("Colecciones") {
                Tab("Favoritos", systemImage: "star") {
                    FavoritesView()
                }
                Tab("Recién Añadido", systemImage: "clock") {
                    RecentView()
                }
            }

            Tab(role: .search) {
                SearchView()
            }
        }
        .tabViewStyle(.sidebarAdaptable)
    }
}

Puntos clave:

  • .tabViewStyle(.sidebarAdaptable) habilita la barra lateral en iPad
  • TabSection crea grupos colapsables en la barra lateral
  • Tab(role: .search) obtiene una ubicación especial

Patrón 6: Restauración de Estado

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