Communitygithub.com

ComeOnOliver/skillshub

Use ao depurar navegação sem resposta, pop-ups inesperados, deep links mostrando tela errada, estado perdido ao trocar de aba ou ao background, crashes em navigationDestination ou qualquer falha de navegação no SwiftUI - diagnóstico sistemático com defesa contra crises em produção.

O que é skillshub?

Esta habilidade oferece um diagnóstico sistemático e abrangente para problemas de navegação no SwiftUI, com foco em identificar rapidamente a causa raiz sem assumir defeitos do framework. Ela cobre desde verificações iniciais obrigatórias e uma árvore de decisão detalhada até padrões de diagnóstico específicos para cada sintoma, como links que não funcionam, pop-ups inesperados, falhas em deep links, perda de estado e crashes. O resumo de IA explica o princípio central de que 85% dos problemas são de gerenciamento de estado, identidade de visualização ou posicionamento incorreto de modificadores. A ferramenta é útil para qualquer desenvolvedor iOS que utilize NavigationStack ou NavigationSplitView e precise de um método rápido e estruturado para resolver falhas de navegação, suportando SwiftUI moderno e fornecendo código de exemplo, tabelas de diagnóstico e regras de interpretação obrigatórias. O funcionamento se baseia em executar verificações de log, identificar padrões através da árvore de decisão e aplicar correções uma de cada vez, evitando mudanças múltiplas ou soluções paliativas como o uso de UINavigationController.

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

Perguntar na sua IA favorita

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

Documentação

Diagnóstico de Navegação SwiftUI

Visão Geral

Princípio central 85% dos problemas de navegação vêm de erros no gerenciamento de estado do caminho, problemas de identidade de views ou erros de posicionamento — não de defeitos do SwiftUI.

O sistema de navegação do SwiftUI é usado por milhões de aplicativos e lida com padrões de navegação complexos de forma confiável. Se sua navegação está falhando, sem resposta ou se comportando inesperadamente, o problema é quase sempre em como você está gerenciando o estado da navegação, não no framework em si.

Esta habilidade fornece diagnósticos sistemáticos para identificar causas raiz em minutos, não em horas.

Bandeiras Vermelhas — Suspeite de Problema de Navegação

Se você vir QUALQUER um destes, suspeite de um problema de código, não de uma quebra do framework:

  • Tocar na navegação não faz nada (link presente, mas não empurra)

  • Botão voltar leva para a tela errada ou para a raiz

  • Deep link abre o aplicativo, mas mostra a tela errada

  • Estado de navegação perdido ao trocar de abas

  • Estado de navegação perdido quando o aplicativo vai para background

  • Mesmo NavigationLink empurra duas vezes

  • Animação de navegação travada ou irregular

  • Crash com navigationDestination no stack trace

  • ❌ PROIBIDO "A navegação do SwiftUI está quebrada, vamos usar UINavigationController"

    • NavigationStack é usado pelos próprios aplicativos da Apple
    • Usar UIKit adiciona complexidade e perde os benefícios do gerenciamento de estado do SwiftUI
    • A interoperabilidade com UIKit tem seus próprios casos extremos que você levará semanas descobrindo
    • Seu problema é quase certamente gerenciamento de caminho, não um defeito do framework

Distinção crítica O comportamento do NavigationStack é determinístico. Se não está funcionando, você está modificando o estado incorretamente, tem problemas de identidade de view ou o navigationDestination está mal posicionado.

Primeiros Passos Obrigatórios

SEMPRE execute estas verificações PRIMEIRO (antes de alterar o código):

// 1. Adicione logging do NavigationPath
NavigationStack(path: $path) {
    RootView()
        .onChange(of: path.count) { oldCount, newCount in
            print("📍 Caminho alterado: \(oldCount) → \(newCount)")
            // Se isso nunca disparar, o link não está modificando o caminho
            // Se disparar inesperadamente, outra coisa está modificando o caminho
        }
}

// 2. Verifique se navigationDestination está visível
// Coloque um print temporário no closure do destino
.navigationDestination(for: Recipe.self) { recipe in
    let _ = print("🔗 Destino para Recipe: \(recipe.name)")
    RecipeDetail(recipe: recipe)
}
// Se isso nunca imprimir, o destino não está sendo avaliado

// 3. Verifique se NavigationLink está dentro de NavigationStack
// Inspeção visual: Rastreie de NavigationLink para cima na hierarquia de views
// Deve encontrar NavigationStack, não outro contêiner primeiro

// 4. Verifique a localização do estado do caminho
// @State deve estar em uma view estável (não recriada a cada renderização)
// Deve ser @State, @StateObject ou @Observable — não uma variável local

// 5. Teste o caso básico isoladamente
// Crie uma reprodução mínima
NavigationStack {
    NavigationLink("Teste", value: "teste")
        .navigationDestination(for: String.self) { str in
            Text("Empurrado: \(str)")
        }
}
// Se isso funcionar, o problema está na sua configuração específica

O que isso lhe diz

ObservaçãoDiagnósticoPróximo Passo
onChange nunca dispara ao tocarNavigationLink não está na hierarquia NavigationStackPadrão 1a
onChange dispara, mas view não é empurradanavigationDestination não encontrado/carregadoPadrão 1b
onChange dispara, view empurra, depois pop imediatoProblema de identidade de view ou modificação de caminhoPadrão 2a
Caminho muda inesperadamente (não do toque)Código externo modificando o caminhoPadrão 2b
Deep link path.append() não navegaProblema de timing ou thread erradaPadrão 3b
Estado perdido ao trocar de abaNavigationStack compartilhado entre abasPadrão 4a
Funciona na primeira vez, falha ao retornarProblema de recriação de viewPadrão 5a

INTERPRETAÇÃO OBRIGATÓRIA

Antes de alterar QUALQUER código, identifique UM destes:

  1. Se tocar no link não faz nada E nenhum onChange → Link fora do NavigationStack (verifique a hierarquia)
  2. Se onChange dispara, mas nada empurra → navigationDestination fora do escopo (verifique o posicionamento)
  3. Se empurra e depois volta imediatamente → Mudança de identidade de view ou reinicialização do caminho (verifique a localização do @State)
  4. Se deep link falha → Problema de timing ou MainActor (verifique a thread)
  5. Se crash → Force unwrap na decodificação do caminho ou registro de tipo ausente

Se os diagnósticos forem contraditórios ou pouco claros

  • PARE. Não prossiga para os padrões ainda
  • Adicione prints em todos os pontos de modificação do caminho
  • Crie um caso de reprodução mínimo
  • Teste primeiro com valores do tipo String (caso mais simples)

Árvore de Decisão

Use isto para chegar ao padrão de diagnóstico correto em 2 minutos:

Problema de navegação?
├─ Tocar na navegação não faz nada?
│  ├─ NavigationLink dentro do NavigationStack?
│  │  ├─ Não → Padrão 1a (Link fora do Stack)
│  │  └─ Sim → Verifique navigationDestination
│  │
│  ├─ navigationDestination registrado?
│  │  ├─ Dentro de contêiner lazy? → Padrão 1b (Carregamento Lento)
│  │  ├─ Tipo incompatível? → Padrão 1c (Registro de Tipo)
│  │  └─ Bloqueado por sheet/popover? → Padrão 1d (Bloqueio Modal)
│  │
│  └─ Usando link baseado em view?
│     └─ → Padrão 1e (API Obsoleta)
│
├─ Pop inesperado ao voltar?
│  ├─ Pop imediato após empurrar?
│  │  ├─ View body recriando caminho? → Padrão 2a (Recriação de Caminho)
│  │  ├─ @State na view errada? → Padrão 2a (Localização do Estado)
│  │  └─ ForEach id mudando? → Padrão 2c (Mudança de Identidade)
│  │
│  ├─ Pop quando não deveria?
│  │  ├─ Código externo chamando removeLast? → Padrão 2b (Modificação Inesperada)
│  │  ├─ Task cancelada? → Padrão 2b (Cancelamento Assíncrono)
│  │  └─ Problema com MainActor? → Padrão 2d (Threading)
│  │
│  └─ Comportamento do botão voltar errado?
│     └─ → Padrão 2e (Corrupção do Stack)
│
├─ Deep link não funcionando?
│  ├─ URL não recebida?
│  │  ├─ onOpenURL não chamado? → Verifique esquema de URL no Info.plist
│  │  └─ Problema com Universal Links? → Verifique apple-app-site-association
│  │
│  ├─ URL recebida, caminho não atualizado?
│  │  ├─ path.append não está no MainActor? → Padrão 3a (Threading)
│  │  ├─ Problema de timing (app não pronto)? → Padrão 3b (Inicialização)
│  │  └─ NavigationStack ainda não criado? → Padrão 3b (Ciclo de Vida)
│  │
│  └─ Caminho atualizado, tela errada mostrada?
│     ├─ Ordem do caminho errada? → Padrão 3c (Construção do Caminho)
│     ├─ Tipo errado anexado? → Padrão 3c (Tipo Incompatível)
│     └─ Item não encontrado? → Padrão 3d (Resolução de Dados)
│
├─ Estado perdido?
│  ├─ Perdido ao trocar de aba?
│  │  ├─ NavigationStack compartilhado? → Padrão 4a (Estado Compartilhado)
│  │  └─ Recriação de aba? → Padrão 4a (Identidade de Aba)
│  │
│  ├─ Perdido ao ir para background/foreground?
│  │  ├─ Sem SceneStorage? → Padrão 4b (Sem Persistência)
│  │  └─ Falha na decodificação? → Padrão 4c (Erro de Decodificação)
│  │
│  └─ Perdido na rotação/mudança de tamanho?
│     └─ → Padrão 4d (Recriação de Layout)
│
├─ Problema com NavigationSplitView?
│  ├─ Sidebar não visível no iPad?
│  │  ├─ columnVisibility não definido? → Padrão 6a (Visibilidade da Coluna)
│  │  └─ Compact size class? → Padrão 6a (Adaptação Automática)
│  │
│  ├─ Detail mostra tela em branco no iPad?
│  │  ├─ Nenhuma view de detalhe padrão? → Padrão 6b (Detalhe Ausente)
│  │  └─ Selection binding nulo? → Padrão 6b (Estado da Seleção)
│  │
│  └─ Funciona no iPhone, quebrado no iPad?
│     └─ → Padrão 6c (Adaptação de Plataforma)
│
└─ Crash?
   ├─ EXC_BAD_ACCESS no código de navegação?
   │  └─ → Padrão 5a (Problema de Memória)
   │
   ├─ Erro fatal: tipo não registrado?
   │  └─ → Padrão 5b (Destino Ausente)
   │
   └─ Falha na decodificação ao restaurar?
      └─ → Padrão 5c (Crash na Restauração)

Regras de Seleção de Padrões (OBRIGATÓRIO)

Antes de prosseguir para um padrão:

  1. Tocar na navegação não faz nada → Adicione logging onChange PRIMEIRO, depois Padrão 1
  2. Pop inesperado → Descubra O QUE está modificando o caminho (logging), depois Padrão 2
  3. Falha de deep link → Verifique se a URL foi recebida (print em onOpenURL), depois Padrão 3
  4. Estado perdido → Identifique QUANDO foi perdido (troca de aba vs background), depois Padrão 4
  5. Crash → Obtenha o stack trace completo, depois Padrão 5

Aplique UM padrão de cada vez

  • Implemente a correção de um padrão
  • Teste completamente
  • Só se o problema persistir, tente o próximo padrão
  • NÃO aplique múltiplos padrões simultaneamente (não é possível isolar a causa)

PROIBIDO

  • Adivinhar soluções sem diagnóstico
  • Mudar várias coisas ao mesmo tempo
  • Usar UINavigationController "porque o SwiftUI está quebrado"
  • Adicionar atrasos/DispatchQueue.main.async sem entender o porquê
  • Mudar para NavigationLink baseado em view "para evitar problemas de caminho"

Padrões de Diagnóstico

Padrão 1a: NavigationLink Fora do NavigationStack

Custo de tempo 5-10 minutos

Sintoma

  • Tocar em NavigationLink não faz nada
  • Nenhuma navegação ocorre, nenhum erro
  • onChange(of: path) nunca dispara

Diagnóstico

// Verifique a hierarquia de views — NavigationLink deve estar DENTRO do NavigationStack

// ❌ ERRADO — Link fora do stack
struct ContentView: View {
    var body: some View {
        VStack {
            NavigationLink("Ir", value: "teste")  // Fora do stack!
            NavigationStack {
                Text("Raiz")
            }
        }
    }
}

// Verifique: Adicione cor de fundo ao NavigationStack
NavigationStack {
    Color.red  // Se o link estiver sobre o vermelho, está dentro
}

Correção

// ✅ CORRETO — Link dentro do stack
struct ContentView: View {
    var body: some View {
        NavigationStack {
            VStack {
                NavigationLink("Ir", value: "teste")  // Dentro do stack
                Text("Raiz")
            }
            .navigationDestination(for: String.self) { str in
                Text("Empurrado: \(str)")
            }
        }
    }
}

Verificação

  • Toque no link, a navegação ocorre
  • onChange(of: path) dispara ao tocar

Padrão 1b: navigationDestination em Contêiner Lazy

Custo de tempo 10-15 minutos

Sintoma

  • Tocar no NavigationLink não faz nada OU funciona intermitentemente
  • onChange dispara (caminho atualizado), mas a view não é empurrada
  • O console pode mostrar: "A navigationDestination for [Type] was not found"

Diagnóstico

// ❌ ERRADO — Destino dentro de contêiner lazy (pode não ser carregado)
ScrollView {
    LazyVStack {
        ForEach(items) { item in
            NavigationLink(item.name, value: item)
                .navigationDestination(for: Item.self) { item in
                    ItemDetail(item: item)  // Pode não ser avaliado!
                }
        }
    }
}

Correção

// ✅ CORRETO — Destino fora do contêiner lazy
ScrollView {
    LazyVStack {
        ForEach(items) { item in
            NavigationLink(item.name, value: item)
        }
    }
}
.navigationDestination(for: Item.self) { item in
    ItemDetail(item: item)  // Sempre disponível
}

Verificação

  • Adicione print no closure do destino — deve sempre imprimir na navegação
  • Funciona independentemente da posição de scroll

Padrão 1c: Incompatibilidade no Registro de Tipo

Custo de tempo 10 minutos

Sintoma

  • Tocar na navegação não faz nada
  • Nenhum navigationDestination correspondente para o tipo do valor
  • Pode funcionar para alguns links, mas não para outros

Diagnóstico

// Verifique: O tipo do valor deve CORRESPONDER EXATAMENTE ao tipo do destino

// Link usa Recipe
NavigationLink(recipe.name, value: recipe)  // value é Recipe

// Destino registrado para... Recipe.ID?
.navigationDestination(for: Recipe.ID.self) { id in  // ❌ Tipo errado!
    RecipeDetail(id: id)
}

Correção

// Corresponda os tipos exatamente
NavigationLink(recipe.name, value: recipe)  // Recipe

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

// OU altere o link para usar ID
NavigationLink(recipe.name, value: recipe.id)  // Recipe.ID

.navigationDestination(for: Recipe.ID.self) { id in  // ✅ Recipe.ID
    RecipeDetail(id: id)
}

Verificação

  • Imprima o tipo no destino: print(type(of: value))
  • Os tipos devem corresponder exatamente (sem herança)

Padrão 2a: NavigationPath Recriado a Cada Renderização

Custo de tempo 15-20 minutos

Sintoma

  • A navegação empurra e depois volta imediatamente
  • Parece "piscar" a view de destino
  • Funciona uma vez, depois falha, ou falha imediatamente

Diagnóstico

// ❌ ERRADO — Caminho criado no corpo da view (reinicializado a cada renderização)
struct ContentView: View {
    var body: some View {
        let path = NavigationPath()  // Recriado toda vez!
        NavigationStack(path: .constant(path)) {
            // ...
        }
    }
}

// ❌ ERRADO — @State em view filha que é recriada
struct ParentView: View {
    @State var showChild = true
    var body: some View {
        if showChild {
            ChildView()  // Recriada quando showChild alterna
        }
    }
}

struct ChildView: View {
    @State var path = NavigationPath()  // Perdido quando ChildView é recriada
    // ...
}

Correção

// ✅ CORRETO — @State em nível estável
struct ContentView: View {
    @State private var path = NavigationPath()  // Persiste entre renderizações

    var body: some View {
        NavigationStack(path: $path) {
            RootView()
        }
    }
}

// ✅ CORRETO — @StateObject para ObservableObject
struct ContentView: View {
    @StateObject private var navModel = NavigationModel()

    var body: some View {
        NavigationStack(path: $navModel.path) {
            RootView()
        }
    }
}

Verificação

  • Adicione logging onChange — o caminho não deve reinicializar inesperadamente
  • Navegue, espere, path.count permanece estável

Padrão 2d: Caminho Modificado Fora do MainActor

Custo de tempo 10-15 minutos

Sintoma

  • A navegação funciona algumas vezes, falha em outras
  • Avisos do Swift 6 sobre isolamento MainActor
  • Pops inesperados ou corrupção de estado

Diagnóstico

// ❌ ERRADO — Modificando o caminho de uma tarefa em background
func loadAndNavigate() async {
    let recipe = await fetchRecipe()
    path.append(recipe)  // ⚠️ Não está no MainActor!
}

// Verifique: Pesquise por path.append, path.removeLast fora do contexto @MainActor

Correção

// ✅ CORRETO — Garanta MainActor
@MainActor
func loadAndNavigate() async {
    let recipe = await fetchRecipe()
    path.append(recipe)  // ✅ Isolado no MainActor
}

// OU despache explicitamente
func loadAndNavigate() async {
    let recipe = await fetchRecipe()
    await MainActor.run {
        path.append(recipe)
    }
}

// ✅ MELHOR — Use @Observable com @

…

[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