# Implementation Plan: Navbar Topo UX

**Branch**: `030-navbar-topo-ux` | **Date**: 2026-04-22 | **Spec**: [spec.md](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)

```text
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)

```text
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.