Status: Approved · v3.2 · SPEC-UX-SHELL-001

depends_on: SPEC-DOMAIN-AUTH-001, SPEC-DOMAIN-PERMISSION-001, SPEC-BRAND-001

used_by: IS-ZERO-00.3, IS-MVP-02.3, IS-MVP-16.1, IS-MVP-19.29

Navegação e App Shell

O app único modular deve servir torcedores, jogadores e gestores sem transformar a navegação em um painel administrativo.

Objetivo

O app único modular deve servir torcedores, jogadores e gestores sem transformar a navegação em um painel administrativo.

Pontos de entrada

• Abertura do app autenticado ou anônimo.
• Deep links para páginas públicas e ações protegidas.
• Retorno de AuthIntent.
• Web responsiva com rotas equivalentes.

Hierarquia da tela

1. Barra inferior mobile com Início, Buscar, Jogos, Notificações e Perfil.
2. Header contextual com título, back, ações secundárias e seletor de entidade quando em gestão.
3. Conteúdo principal com safe areas e largura máxima no web.
4. Modais/bottom sheets para filtros, ações rápidas e confirmação.
5. Área Minha Gestão acessível por Perfil e card na Home para gestores.

Componentes e comportamento

Bottom Tabs

Cinco destinos fixos. Badge somente em Notificações. A aba atual deve ser identificável por ícone, label e estado acessível.

No redesign v3, a barra inferior segue a composição aprovada dos protótipos T1–T9: superfície separada por borda superior, safe area, cinco colunas equivalentes, ícone outline de 19 px e label sempre visível. O item ativo usa primary, peso visual superior e aria-current/estado nativo; os demais usam text-muted. O badge real de Notificações é numérico quando houver espaço e pode degradar para ponto no compacto, sem inventar contagem.

Web Navigation

Em desktop, navegação lateral ou header persistente preserva os mesmos destinos. Páginas públicas podem usar header institucional simplificado.

Para as rotas do app redesign v3, o padrão canônico é a sidebar do protótipo, não uma navbar horizontal genérica:

• largura expandida de 220 px e rail recolhido de 68 px;
• logo horizontal em 116 px quando expandida e símbolo em 30 px quando recolhida;
• controle explícito abaixo da marca para expandir/recolher, com nome acessível;
• itens Início, Buscar, Jogos, Notificações e Perfil com o mesmo ícone/label do mobile;
• ícone outline de 17 px, surface-alt no item ativo e badge real de Notificações;
• em largura que não comporta sidebar expandida + conteúdo mínimo de 320 px, o rail de 68 px permanece no fluxo e a expansão vira overlay com backdrop; abrir/fechar não desloca o conteúdo;
• o modo compacto inicia recolhido; mudar de largura ampla para compacta recolhe o menu antes de habilitar o overlay, evitando backdrop aberto automaticamente sobre o conteúdo;
• em largura ampla a sidebar permanece no fluxo e pode redimensionar a área de conteúdo;
• transição de 180 ms é removida com reduced motion.

O shell institucional simplificado só é permitido nas rotas explicitamente definidas pela matriz de rotas; ele não pode substituir o shell canônico da Home ou das abas autenticadas.

Matriz de aplicação do shell v3

Grupo	Web	Mobile
Home, Buscar, Jogos, Notificações, Perfil	sidebar 220/68	tabs/bottom nav
Páginas públicas T2–T9 (teams, players, detalhe de matches, championships, torcidas, fields, services, districts, neighborhoods, rankings)	sidebar 220/68	conteúdo de detalhe + bottom nav; topbar contextual continua pertencendo à feature
Auth T1 (login, register, forgot-password, reset-password, onboarding)	sem sidebar; composição T1 própria	sem bottom nav; composição T1 própria
Gestão, reports, support requests, invites e event links	preservar shell/contexto operacional existente; não inferir sidebar nova fora do escopo	Stack contextual sem bottom nav global
Fallback técnico/404	shell mínimo que não bloqueia retry/retorno	Stack sem bottom nav quando a rota não é classificável

No mobile, o root layout classifica a rota para que detalhes públicos fora de (tabs) recebam o mesmo bottom nav sem duplicá-lo dentro de (tabs). A classificação é centralizada e testada; não se envolve cada screen manualmente nem se mantém um componente sem consumidor.

Marca e iconografia

A marca usa os assets oficiais aprovados em assets/new_brand/** ou equivalentes de hash/proveniência registrados em assets/redesign-v3/**; essas fontes são imutáveis no EP e somente cópias byte-idênticas entram nos bundlers dos apps. A família canônica é Lucide (lucide-react no web e lucide-react-native no mobile, licença ISC), como no protótipo: Home, Search, CalendarDays, Bell, User e PanelLeftOpen/Close, com currentColor, stroke 1.8 inativo/2.3 ativo e tamanhos 17 px web, 19 px mobile e 16 px no toggle. Emoji, dingbat ou glifo Unicode não é substituto de produção.

O shell web expõe um único painel real Tema, fiel ao protótipo, com duas escolhas ortogonais: Escuro | Claro em Aparência e Raiz | Neutro em Cores. Ele usa o provider canônico e sua persistência; não mantém estado de tema local, fixtures ou ações mortas. Controles externos de desenvolvimento do harness continuam excluídos. A marca do shell acompanha os quatro modos com os assets oficiais brand/themeable e preserva a costura do símbolo no modo Neutro.

Context Header

Exibe entidade ativa, status e ações. Não deve esconder o contexto ao entrar em subfluxos de gestão.

Minha Gestão

Card acima do feed mostra entidades agrupadas por tipo; recolhe ao rolar. Não contém dashboard geral, pendências globais nem KPIs inventados.

Protected Action Gate

Ao tocar ação protegida, salva AuthIntent, abre login e retorna ao ponto exato.

Ações do usuário

Ação	Pré-condição	Resultado	Falha/alternativa
Trocar aba	App carregado	Preserva estado básico da aba anterior	Rota inválida volta ao destino seguro
Abrir página pública	Link válido	Página sem exigir login	404/merged/suspended usa estado específico
Entrar em gestão	Membership active	Carrega painel da entidade	Sem permission mostra 403 contextual
Executar ação protegida	Visitante	Cria AuthIntent e abre auth	Intent expirado retorna ao contexto sem ação

Estados obrigatórios

Estado	Representação	Ação disponível
Inicialização	Splash curto com o asset oficial de assets/new_brand/ e restauração de sessão	Tentar novamente/continuar anônimo
Sem conexão	Shell continua navegável com aviso	Recarregar
Sessão expirada	Modal contextual sem perder rota	Entrar novamente
Entidade não disponível	Fallback de status	Abrir destino canônico ou voltar

Autenticação e permissões

• Abas base não dependem de papel, exceto conteúdos internos.
• Minha Gestão só aparece com ao menos uma membership active.
• Painel do Jogador aparece apenas para role player.
• Botões sem permissão podem aparecer desabilitados quando ajudam descoberta, sempre com explicação.

Responsividade

• Mobile usa bottom tabs e bottom sheets.
• Tablet/web compacto usa o rail lateral de 68 px com expansão em overlay.
• Desktop usa sidebar persistente 220/68 px, largura máxima de conteúdo e painéis laterais quando úteis.
• Não ampliar cards indefinidamente; manter densidade profissional.

Acessibilidade

• Alvos de toque mínimos de 44×44.
• Labels sempre disponíveis para ícones críticos.
• Foco visível no web.
• Navegação por teclado e leitores de tela.
• Safe areas e contraste AA.

Eventos de produto e observabilidade

• app_shell_loaded
• tab_changed
• deep_link_opened
• auth_intent_started
• management_context_opened
• route_fallback_shown

Dados e endpoints

• GET /auth/me para contexto.
• GET /management/my-entities para Minha Gestão.
• GET /notifications/counts para badge.

Critérios de aceite

• Cinco abas canônicas.
• Sidebar web e bottom navigation mobile convergem visualmente com os protótipos T1–T9.
• Nenhum destino usa glifo Unicode; ícones outline, marca, badge e estados ativo/recolhido são verificáveis.
• O conteúdo não salta ao expandir a sidebar em overlay e mantém piso útil de 320 px.
• Visitante abre páginas públicas.
• Gestor acessa entidades sem app separado.
• Deep link e AuthIntent preservam contexto.
• Mobile e web compartilham estrutura sem forçar layout idêntico.

Pós-MVP

• App separado de gestão somente se uso real justificar.
• Command palette no desktop.
• Persistência avançada por aba.

Decisões registradas

• App único modular no MVP.
• Minha Gestão não é uma sexta aba.
• Home é principalmente feed.

Machine summary

spec: SPEC-UX-SHELL-001
screen_or_flow: Navegação e App Shell
required_states:
  - loading
  - success
  - empty
  - error
must_use:
  - contracts
  - service
  - hook
  - design_tokens
must_not:
  - direct_fetch
  - direct_fixture_import
  - hardcoded_brand_colors