sass-imobiliaria/specs/030-navbar-topo-ux/plan.md

Implementation Plan: Navbar Topo UX

Branch: 030-navbar-topo-ux | Date: 2026-04-22 | Spec: spec.md Input: Feature specification from /specs/030-navbar-topo-ux/spec.md

Summary

Revisar e refinar a navbar fixa do topo, concentrando a implementação no frontend React para separar melhor navegação pública e contextual por perfil, melhorar a hierarquia visual em desktop/mobile, consolidar o controle de estados transitórios (menu mobile, dropdown admin, dropdown cliente) e elevar acessibilidade sem alterar contratos backend. A principal superfície técnica atual é frontend/src/components/Navbar.tsx, apoiada por AuthContext, FavoritesContext, rotas já existentes no SPA e tokens visuais já definidos em index.css.

---

Technical Context

Language/Version: TypeScript 5.5 (frontend principal) / Python 3.12 existente sem mudança funcional Primary Dependencies: React 18, react-router-dom v6, Tailwind CSS 3.4, Axios (indireto via autenticação), contexto próprio useAuth, useFavorites, ThemeToggle Storage: N/A para persistência nova; sessão e token continuam em localStorage via AuthContext Testing: npm run build no frontend + validação manual responsiva/a11y; pytest backend não deve ser impactado Target Platform: SPA React em navegadores desktop e mobile, servida por Vite/Nginx no ambiente atual Project Type: aplicação web full-stack com foco nesta feature em SPA frontend/UX Performance Goals: navegação e abertura/fechamento de menus sem jank perceptível; interações do topo percebidas em < 100 ms; zero quebra visual entre 320 px e 1440 px+ Constraints: sem alterar autorização backend; preservar rotas existentes de admin e área do cliente; respeitar DESIGN.md, tokens do projeto e suporte atual a tema claro/escuro; garantir foco visível, aria-* coerente e alvo mínimo de 44x44 px em mobile Scale/Scope: um componente navbar compartilhado entre páginas públicas, área do cliente e área admin; 3 perfis de usuário; 3 contextos interativos mutuamente exclusivos

---

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

Princípio	Status	Observação
I. Design-First	✅ PASS	A revisão mantém a navbar alinhada ao sistema visual existente, reutilizando tokens e variáveis globais em vez de introduzir paleta ad hoc. O tema claro/escuro já existe no produto e será respeitado sem romper o padrão visual.
II. Separation of Concerns	✅ PASS	A feature altera navegação e estado visual no React; não exige renderização no backend nem novo acoplamento entre Flask e SPA.
III. Spec-Driven	✅ PASS	O plano deriva diretamente de spec.md, com user stories por perfil e critérios de sucesso claros antes da implementação.
IV. Data Integrity	✅ PASS	Não há mudança de schema, payload ou persistência. A feature consome apenas dados já existentes de sessão (user, role, isAuthenticated).
V. Security	✅ PASS	O menu admin continua condicionado ao papel admin no frontend; nenhuma credencial nova será exposta e nenhuma rota protegida será aberta a outros perfis.
VI. Simplicity First	✅ PASS	O caminho proposto evita novos pacotes e favorece simplificação do estado atual da navbar, priorizando um único controlador de overlay/menu em vez de abstrações extras.

Veredicto Pré-Design: Sem violações. A feature pode prosseguir para pesquisa e desenho técnico.

Revalidação Pós-Design: Mantida como ✅ PASS após a definição do contrato de UI, do modelo de estado e do quickstart. Não surgiram dependências novas nem necessidade de mudança backend.

---

Project Structure

Documentação (esta feature)

specs/030-navbar-topo-ux/
├── spec.md                     # Especificação do produto
├── plan.md                     # Este arquivo
├── research.md                 # Decisões e tradeoffs de UX/UI e arquitetura local
├── data-model.md               # Modelo de estado e entidades da navbar
├── quickstart.md               # Fluxo recomendado de implementação e validação
├── contracts/
│   └── navbar-ui-contract.md   # Contrato de comportamento por perfil/breakpoint
└── tasks.md                    # Phase 2 — gerado por /speckit.tasks

Código-fonte (raiz do repositório)

frontend/
└── src/
    ├── components/
    │   ├── Navbar.tsx               # SUPERFÍCIE PRINCIPAL — links, dropdowns e menu mobile
    │   └── ThemeToggle.tsx          # Reutilizado no topo desktop/mobile
    ├── contexts/
    │   ├── AuthContext.tsx          # Fonte de verdade da sessão e logout
    │   └── FavoritesContext.tsx     # Badge/link de favoritos para visitante
    ├── layouts/
    │   ├── ClientLayout.tsx         # Consome Navbar na área do cliente
    │   └── AdminLayout.tsx          # Consome Navbar na área admin
    ├── pages/
    │   ├── HomePage.tsx
    │   ├── PropertiesPage.tsx
    │   ├── ContactPage.tsx
    │   └── ...                      # Demais páginas públicas que já renderizam Navbar
    ├── App.tsx                      # Rotas já existentes usadas pelo contrato de navegação
    └── index.css                    # Variáveis/tokens e acabamento visual do topo

backend/
└── app/
    └── ...                          # Sem mudanças previstas para esta feature

Structure Decision: Manter a arquitetura web existente e concentrar a implementação no frontend, com alterações localizadas em Navbar.tsx, possíveis ajustes pequenos em AuthContext.tsx para fluxo de logout/navegação e refinamentos visuais em index.css. Não há necessidade de novos módulos backend ou novos serviços HTTP.

---

Implementation Approach

1. Arquitetura de informação da navbar

• Manter até 5 links públicos primários no desktop, com prioridade para descoberta de imóveis e contato.
• Separar claramente três blocos visuais: marca/logo, navegação pública e ações contextuais de perfil/CTA.
• Tratar o menu Admin como navegação contextual especializada, não como parte da navegação pública.

2. Modelo de estado local

• Consolidar o controle de menus para garantir exclusão mútua entre mobile, admin e client.
• Fechar qualquer overlay ao trocar rota, ao clicar fora e ao iniciar logout.
• Derivar a renderização por perfil a partir do estado já disponível em useAuth().

3. Acessibilidade e previsibilidade

• Garantir rótulos e estados ARIA coerentes para gatilhos de dropdown e hambúrguer.
• Tornar foco e navegação por teclado parte do contrato da feature, inclusive nos gatilhos contextuais.
• Padronizar feedbacks de hover/active/open com transições curtas e consistentes.

4. Escopo de backend

• Nenhuma API nova.
• Nenhuma mudança em autorização.
• Nenhuma migration.

---

Complexity Tracking

Nenhuma violação constitucional identificada. Não há complexidade excepcional que exija justificativa adicional nesta fase.