feat: features 025-032 - favoritos, contatos, trabalhe-conosco, area-cliente, navbar, hero-light-dark, performance-homepage

- feat(025): favoritos locais com FavoritesContext, HeartButton, PublicFavoritesPage - feat(026): central de contatos admin (leads/contatos unificados) - feat(027): configuração da página de contato via admin - feat(028): trabalhe conosco - candidaturas com upload e admin - feat(029): UX área do cliente - visitas, comparação, perfil - feat(030): navbar UX - menu mobile, ThemeToggle, useFavorites - feat(031): hero light/dark - imagens separadas por tema, upload, preview, seed - feat(032): performance homepage - Promise.all parallel fetches, sessionStorage cache, preload hero image, loading=lazy nos cards, useInView hook, will-change carrossel, keyframes em index.css, AgentsCarousel e HomeScrollScene via props - fix: light mode HomeScrollScene - gradiente, cores de texto, scroll hint migrations: g1h2i3j4k5l6 (source em leads), h1i2j3k4l5m6 (contact_config), i1j2k3l4m5n6 (job_applications), j2k3l4m5n6o7 (hero theme images)
2026-04-22 22:35:17 -03:00 · 2026-04-22 22:35:17 -03:00 · cf5603243c
commit cf5603243c
parent 6ef5a7a17e
106 changed files with 11927 additions and 1367 deletions
--- a/specs/030-navbar-topo-ux/contracts/navbar-ui-contract.md
+++ b/specs/030-navbar-topo-ux/contracts/navbar-ui-contract.md
@ -0,0 +1,191 @@
+# UI Contract — Navbar do Topo
+
+## Objetivo
+
+Definir o comportamento observável da navbar por perfil de usuário, breakpoint e estado interativo, sem introduzir mudanças de API.
+
+---
+
+## 1. Perfis suportados
+
+### `visitor`
+
+Condição:
+- `isAuthenticated === false`
+
+Elementos obrigatórios:
+- Logo com navegação para `/`
+- Links públicos principais
+- CTA `Anunciar imóvel` para `/cadastro-residencia`
+- Ação `Entrar` para `/login`
+- Ação de favoritos públicos quando aplicável ao estado atual do produto
+
+Elementos proibidos:
+- Menu `Admin`
+- Seção `Minha Conta`
+
+### `client`
+
+Condição:
+- `isAuthenticated === true`
+- `user.role !== 'admin'`
+
+Elementos obrigatórios:
+- Tudo que continua relevante da navegação pública
+- Gatilho de conta com inicial/avatar e primeiro nome truncado
+- Entradas contextuais: `Favoritos`, `Comparar`, `Visitas`, `Minha conta`
+- Ação `Sair` separada visualmente
+
+Elementos proibidos:
+- Menu `Admin`
+- Botão `Entrar`
+
+### `admin`
+
+Condição:
+- `isAuthenticated === true`
+- `user.role === 'admin'`
+
+Elementos obrigatórios:
+- Tudo que continua relevante da navegação pública
+- Gatilho contextual `Admin`
+- Atalhos admin prioritários para módulos existentes
+- Ação `Sair`
+
+Elementos proibidos:
+- Menu padrão `Minha Conta` de cliente
+- Botão `Entrar`
+
+---
+
+## 2. Contrato desktop
+
+### Estrutura mínima
+
+```text
+[Logo]
+[Navegação pública principal]
+[Ações contextuais por perfil]
+[Theme toggle]
+[CTA principal]
+[Ação de autenticação ou logout]
+```
+
+### Regras
+
+- Devem existir no máximo 5 links públicos visíveis simultaneamente.
+- O CTA principal deve ter destaque visual acima dos links secundários.
+- Menus contextuais (`Admin` e `Conta`) não podem deslocar ou truncar a navegação principal.
+- Nomes longos de usuário devem truncar sem quebrar altura ou alinhamento.
+
+---
+
+## 3. Contrato mobile
+
+### Gatilho hambúrguer
+
+Obrigatório:
+- `aria-label` dinâmico entre abrir/fechar
+- `aria-expanded` coerente com o estado
+- `aria-controls` apontando para o painel do menu
+
+### Conteúdo do menu
+
+Obrigatório:
+- Mesmos destinos públicos principais em ordem lógica
+- CTA `Anunciar imóvel`
+- Seção `Minha Conta` apenas para cliente autenticado
+- Seção `Admin` apenas para admin
+- Logout apenas para usuário autenticado
+- `Entrar` apenas para visitante
+
+Regras:
+- Alvos tocáveis com área mínima de 44x44 px.
+- Ao navegar por qualquer item, o menu deve fechar.
+- O menu mobile não pode coexistir com dropdown contextual desktop.
+
+---
+
+## 4. Contrato de estado interativo
+
+Estados possíveis:
+
+```text
+closed
+mobile-open
+client-open
+admin-open
+```
+
+Invariantes:
+- Apenas um estado aberto por vez.
+- Abrir um contexto fecha qualquer outro.
+- Clique fora fecha o contexto aberto.
+- Mudança de rota fecha qualquer contexto aberto.
+- Logout fecha qualquer contexto aberto e restaura a visualização de visitante.
+
+---
+
+## 5. Contrato de acessibilidade
+
+Obrigatório:
+- `nav` com `aria-label` descritivo
+- foco visível em links e botões
+- acionamento por teclado em gatilhos interativos
+- contraste adequado em texto, hover, active e estados abertos nos temas suportados
+
+Não aceitável:
+- gatilhos sem nome acessível
+- estados visuais dependentes apenas de cor sem contraste suficiente
+- foco invisível ou escondido pelo backdrop da navbar
+
+---
+
+## 6. Destinos atualmente suportados
+
+### Navegação pública
+
+| Rótulo | Destino atual |
+|---|---|
+| Comprar | `/imoveis?listing_type=venda` |
+| Alugar | `/imoveis?listing_type=aluguel` |
+| Equipe | `/corretores` |
+| Sobre | `/sobre` |
+| Contato | `/contato` |
+| Anunciar imóvel | `/cadastro-residencia` |
+| Entrar | `/login` |
+
+### Navegação do cliente
+
+| Rótulo | Destino atual |
+|---|---|
+| Favoritos | `/area-do-cliente/favoritos` |
+| Comparar | `/area-do-cliente/comparar` |
+| Visitas | `/area-do-cliente/visitas` |
+| Minha conta | `/area-do-cliente/conta` |
+
+### Navegação admin
+
+| Rótulo | Destino atual |
+|---|---|
+| Imóveis | `/admin/properties` |
+| Corretores | `/admin/corretores` |
+| Clientes | `/admin/clientes` |
+| Boletos | `/admin/boletos` |
+| Visitas | `/admin/visitas` |
+| Favoritos | `/admin/favoritos` |
+| Cidades | `/admin/cidades` |
+| Amenidades | `/admin/amenidades` |
+| Analytics | `/admin/analytics` |
+| Leads | `/admin/leads` |
+| Candidaturas | `/admin/candidaturas` |
+| Conf. Contato | `/admin/contato-config` |
+
+---
+
+## 7. Fora de escopo
+
+- Alterar políticas de autorização backend
+- Criar novas rotas ou módulos administrativos
+- Persistir preferências de navegação em banco
+- Transformar a navbar em configuração dinâmica vinda da API
--- a/specs/030-navbar-topo-ux/data-model.md
+++ b/specs/030-navbar-topo-ux/data-model.md
@ -0,0 +1,165 @@
+# Data Model — 030-navbar-topo-ux
+
+> Esta feature não cria entidades de banco nem migrations. O modelo abaixo descreve dados de sessão já existentes e o estado de UI necessário para a navbar.
+
+---
+
+## 1. Entidades Existentes Consumidas
+
+### `AuthSession`
+
+Fonte: `frontend/src/contexts/AuthContext.tsx`
+
+| Campo | Tipo | Origem | Uso na navbar |
+|---|---|---|---|
+| `user` | `User | null` | contexto de autenticação | Decide exibição de avatar, primeiro nome e papel do usuário |
+| `token` | `string | null` | `localStorage` + contexto | Não renderiza UI diretamente; sustenta estado autenticado |
+| `isAuthenticated` | `boolean` | derivado do contexto | Liga/desliga ações de visitante vs cliente/admin |
+| `isLoading` | `boolean` | bootstrap da sessão | Evita flicker de ações incorretas durante hidratação |
+| `logout()` | `() => void` | contexto | Encerra sessão e força retorno visual ao estado visitante |
+
+### `UserProfile`
+
+Fonte: tipo `User` retornado pelo fluxo de auth atual.
+
+| Campo | Tipo | Regra | Uso na navbar |
+|---|---|---|---|
+| `name` | `string` | obrigatório quando `user != null` | Exibe inicial e primeiro nome truncado |
+| `role` | `string` | valor relevante nesta feature: `admin` ou não-admin | Controla presença do menu Admin e do menu Minha Conta |
+
+**Invariantes**:
+- `user === null` implica navbar de visitante.
+- `user.role === 'admin'` implica ausência do menu de cliente padrão.
+- Nome longo nunca deve quebrar layout; deve ser truncado no gatilho.
+
+---
+
+## 2. Entidades de Navegação
+
+### `NavItem`
+
+Representa um item navegável exibido em um dos grupos da navbar.
+
+```ts
+interface NavItem {
+  label: string
+  to: string
+  end?: boolean
+  visibility: 'public' | 'client' | 'admin'
+  group: 'primary' | 'contextual' | 'cta'
+}
+```
+
+**Regras**:
+- Itens `public` aparecem para todos, salvo ajustes de prioridade visual.
+- Itens `client` aparecem apenas quando `isAuthenticated === true` e `role !== 'admin'`.
+- Itens `admin` aparecem apenas quando `role === 'admin'`.
+- `group='cta'` não substitui o grupo público; ele complementa a hierarquia do topo.
+
+### `ProfileSection`
+
+Agrupa ações contextuais por perfil no mobile e no desktop.
+
+```ts
+interface ProfileSection {
+  id: 'admin' | 'client'
+  title: string
+  items: NavItem[]
+  includesLogout: boolean
+}
+```
+
+**Regras**:
+- No mobile, cada seção deve aparecer com cabeçalho próprio.
+- Logout deve permanecer visualmente separado das ações de navegação.
+
+---
+
+## 3. Estado Transitório de UI
+
+### `NavUIState`
+
+Modelo recomendado para governar interações mutuamente exclusivas.
+
+```ts
+type ActiveOverlay = 'closed' | 'mobile' | 'admin' | 'client'
+
+interface NavUIState {
+  activeOverlay: ActiveOverlay
+  isDesktop: boolean
+}
+```
+
+**Regras de transição**:
+
+| Evento | Estado atual | Próximo estado | Observação |
+|---|---|---|---|
+| Clique no hambúrguer | `closed` | `mobile` | Só em mobile |
+| Clique no hambúrguer | `mobile` | `closed` | Toggle padrão |
+| Clique no gatilho Admin | `closed` ou `client` | `admin` | Fecha qualquer outro overlay |
+| Clique no gatilho Cliente | `closed` ou `admin` | `client` | Fecha qualquer outro overlay |
+| Clique fora | `mobile` / `admin` / `client` | `closed` | Requisito FR-012 |
+| Mudança de rota | qualquer | `closed` | Requisito FR-013 |
+| Logout confirmado | qualquer | `closed` | Navbar volta ao estado visitante |
+| Escape | `mobile` / `admin` / `client` | `closed` | Recomendado para previsibilidade |
+
+**Invariantes**:
+- Apenas um contexto pode permanecer aberto por vez.
+- `mobile` não pode coexistir com `admin` ou `client`.
+- `admin` e `client` são mutuamente exclusivos.
+
+---
+
+## 4. Estados Derivados de Exibição
+
+### `NavbarVariant`
+
+```ts
+type NavbarVariant = 'visitor' | 'client' | 'admin'
+```
+
+Derivação:
+- `visitor`: `!isLoading && !isAuthenticated`
+- `client`: `isAuthenticated && user?.role !== 'admin'`
+- `admin`: `isAuthenticated && user?.role === 'admin'`
+
+### `ActiveLinkState`
+
+Estado derivado de `NavLink`/rota atual.
+
+**Regras**:
+- Links públicos devem refletir estado ativo em desktop e mobile.
+- Rotas com query string, como `/imoveis?listing_type=venda`, devem manter coerência visual com a intenção do link.
+- Itens contextuais devem fechar o menu após navegação bem-sucedida.
+
+---
+
+## 5. Regras de Validação de UX/A11y
+
+| Regra | Aplicação |
+|---|---|
+| `aria-expanded` coerente | gatilhos do menu mobile e dropdowns |
+| `aria-controls` presente | menu hambúrguer e, se aplicável, painéis contextuais |
+| foco visível | todos os links e botões interativos |
+| alvo mínimo `44x44` | hambúrguer, CTA, itens tocáveis em mobile |
+| truncamento elegante | nome do usuário e gatilhos de perfil |
+
+---
+
+## 6. Relações Entre Entidades
+
+```text
+AuthSession
+  └── UserProfile
+        ├── role ──────────────┐
+        └── name ───────┐      │
+                        │      │
+NavbarVariant <─────────┘      │
+                               │
+NavItem.visibility ────────────┘
+
+NavUIState.activeOverlay
+  ├── controls mobile menu visibility
+  ├── controls admin dropdown visibility
+  └── controls client dropdown visibility
+```
--- a/specs/030-navbar-topo-ux/plan.md
+++ b/specs/030-navbar-topo-ux/plan.md
@ -0,0 +1,123 @@
+# 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.
+
--- a/specs/030-navbar-topo-ux/quickstart.md
+++ b/specs/030-navbar-topo-ux/quickstart.md
@ -0,0 +1,105 @@
+# Quickstart — 030-navbar-topo-ux
+
+Guia curto para implementar e validar a revisão UX/UI da navbar do topo.
+
+---
+
+## Pré-requisitos
+
+- Ambiente do projeto iniciado via `./start.ps1` na raiz.
+- Frontend disponível em `http://localhost:5174`.
+- Branch de trabalho: `030-navbar-topo-ux`.
+
+Credenciais úteis encontradas no frontend atual:
+
+- Admin: `admin@demo.com` / `admin1234`
+- Usuário: `usuario@demo.com` / `demo1234`
+
+---
+
+## Superfícies de implementação
+
+Arquivos com maior probabilidade de edição:
+
+- `frontend/src/components/Navbar.tsx`
+- `frontend/src/contexts/AuthContext.tsx`
+- `frontend/src/index.css`
+- Opcionalmente `frontend/src/layouts/ClientLayout.tsx` e `frontend/src/layouts/AdminLayout.tsx` se houver ajuste fino de offset/spacing
+
+---
+
+## Ordem recomendada de trabalho
+
+### 1. Revisar a arquitetura local da navbar
+
+- Mapear os grupos de links públicos, cliente e admin.
+- Definir o modelo de estado único para overlays/contextos abertos.
+- Garantir fechamento em clique fora, troca de rota e logout.
+
+### 2. Ajustar a hierarquia visual desktop
+
+- Reequilibrar logo, links primários, CTA e ações de conta.
+- Limitar ruído visual e reforçar separação entre navegação pública e contextual.
+- Validar truncamento do nome e destaque do CTA em ambos os temas.
+
+### 3. Ajustar o comportamento mobile
+
+- Garantir ordem lógica dos destinos no menu hambúrguer.
+- Exibir seções `Minha Conta` e `Admin` apenas para os perfis corretos.
+- Validar alvo de toque, foco e estados abertos/fechados.
+
+### 4. Refinar logout e previsibilidade
+
+- Conferir se logout fecha menus e retorna imediatamente ao estado visual de visitante.
+- Se necessário, ajustar o comportamento atual de redirecionamento em `AuthContext.tsx` para evitar fricção visual desnecessária.
+
+---
+
+## Validação executável
+
+Na pasta `frontend/`:
+
+```bash
+npm run build
+```
+
+Esse é o guardrail mínimo obrigatório antes de concluir a implementação.
+
+---
+
+## Checklist manual por persona
+
+### Visitante
+
+- Desktop: links principais legíveis, CTA `Anunciar imóvel` destacado e ação `Entrar` visível.
+- Mobile: hambúrguer abre e fecha corretamente, com os mesmos destinos públicos em ordem lógica.
+- Tema claro/escuro: contraste suficiente em texto, hover e estado ativo.
+
+### Usuário autenticado
+
+- Desktop: avatar/inicial, primeiro nome truncado e dropdown `Minha conta` funcionam.
+- Dropdown: `Favoritos`, `Comparar`, `Visitas`, `Minha conta` e `Sair` fecham menu após clique.
+- Mobile: seção `Minha Conta` aparece apenas quando autenticado não-admin.
+
+### Admin
+
+- Desktop: gatilho `Admin` visível e separado da navegação pública.
+- Dropdown: atalhos admin navegam corretamente e fecham o menu.
+- Mobile: seção `Admin` aparece e não conflita com outros contextos.
+
+---
+
+## Checklist de comportamento global
+
+- Abrir dropdown admin fecha dropdown cliente.
+- Abrir dropdown cliente fecha dropdown admin.
+- Trocar de rota fecha menu mobile e dropdowns.
+- Clique fora fecha o contexto aberto.
+- `Tab`, `Enter` e `Espaço` funcionam nos gatilhos relevantes.
+- Em 320 px, 768 px, 1024 px e 1280 px não há quebra ou sobreposição.
+
+---
+
+## Risco conhecido para implementação
+
+O comportamento atual de logout em `AuthContext.tsx` usa redirecionamento forçado para `/login`. Isso é funcional, mas pode entrar em tensão com o objetivo da spec de “retornar à navbar de visitante” com mínima fricção visual. A implementação deve decidir se mantém esse fluxo por regra de produto ou se o suaviza no frontend sem alterar segurança.
--- a/specs/030-navbar-topo-ux/research.md
+++ b/specs/030-navbar-topo-ux/research.md
@ -0,0 +1,71 @@
+# Research — 030-navbar-topo-ux
+
+## Decision 1: Manter uma única Navbar compartilhada por todo o produto
+
+**Decision**: Evoluir o componente compartilhado `frontend/src/components/Navbar.tsx` em vez de criar navbars separadas para visitante, cliente e admin.
+
+**Rationale**: A navbar já é consumida por páginas públicas e layouts protegidos. Um único ponto de evolução reduz divergência visual, evita duplicação de links/rotas e facilita garantir consistência de comportamento entre desktop e mobile.
+
+**Alternatives considered**:
+- Criar três variantes independentes de navbar: rejeitado por elevar custo de manutenção e risco de regressões cruzadas.
+- Extrair uma navbar diferente para admin: rejeitado nesta fase porque a spec pede eficiência sem poluir a experiência global, não uma shell totalmente nova.
+
+---
+
+## Decision 2: Consolidar o estado transitório em um único controlador de overlay
+
+**Decision**: Planejar a navbar com um estado mutuamente exclusivo para `closed`, `mobile`, `client` e `admin`, mesmo que a implementação inicial parta do componente atual com múltiplos booleans.
+
+**Rationale**: Os requisitos FR-011, FR-012 e FR-013 pedem previsibilidade forte. Um controlador único reduz a chance de estados simultâneos, simplifica o fechamento em mudança de rota e deixa o comportamento mais testável.
+
+**Alternatives considered**:
+- Manter três `useState` independentes: rejeitado como forma final porque exige disciplina manual em todos os handlers.
+- Levar o estado para contexto global: rejeitado por excesso de complexidade para uma concern local de UI.
+
+---
+
+## Decision 3: Não introduzir novos contratos de API nem mudanças backend
+
+**Decision**: Tratar a feature como frontend/UX puro, apoiada apenas pelos dados já disponíveis em `AuthContext` e nas rotas existentes em `App.tsx`.
+
+**Rationale**: A spec descreve comportamento e hierarquia visual, não novos fluxos de domínio. `user`, `role`, `isAuthenticated` e `logout()` já cobrem as condições necessárias para as três personas.
+
+**Alternatives considered**:
+- Criar endpoint específico para navegação por perfil: rejeitado por desnecessário e contrário ao princípio de simplicidade.
+- Mover a configuração de menu para backend: rejeitado nesta fase por não haver requisito de CMS/configuração dinâmica.
+
+---
+
+## Decision 4: Derivar destinos do menu a partir das rotas reais existentes
+
+**Decision**: Basear o contrato de navegação nos destinos já disponíveis em `frontend/src/App.tsx` e na lista atual de módulos administrativos/cliente.
+
+**Rationale**: Isso evita planejar links inexistentes e mantém a feature ancorada no sistema real. Também permite priorizar atalhos admin sem inventar módulos novos.
+
+**Alternatives considered**:
+- Redesenhar a informação da navbar a partir de destinos hipotéticos: rejeitado por abrir escopo além da spec.
+- Remover rotas admin do topo nesta fase: rejeitado porque a spec exige acesso rápido para administradores.
+
+---
+
+## Decision 5: Formalizar um contrato de UI da navbar
+
+**Decision**: Criar um documento em `contracts/navbar-ui-contract.md` descrevendo comportamento por perfil, breakpoint e estado interativo.
+
+**Rationale**: Embora não exista API nova, a aplicação expõe uma interface de navegação para o usuário final. O contrato de UI serve como referência objetiva para implementação, QA e futura geração de tarefas.
+
+**Alternatives considered**:
+- Não criar contrato algum: rejeitado porque a feature é centrada em interação e estados, e isso precisa de definição explícita.
+- Modelar o contrato só dentro do plan: rejeitado para manter separação clara entre abordagem técnica e comportamento esperado.
+
+---
+
+## Decision 6: Validar principalmente com build e checklist manual responsivo
+
+**Decision**: Adotar `npm run build` como validação executável mínima e complementar com checklist manual por persona e breakpoint.
+
+**Rationale**: O frontend atual não expõe uma suíte automatizada de testes de componentes/RTL. A natureza visual/interativa da navbar exige inspeção manual em desktop/mobile além da checagem de compilação.
+
+**Alternatives considered**:
+- Introduzir Vitest/RTL apenas para esta feature: rejeitado nesta fase de planning por ampliar escopo e dependências.
+- Confiar só em validação visual manual: rejeitado porque o build ainda é o guardrail executável mínimo disponível.
--- a/specs/030-navbar-topo-ux/spec.md
+++ b/specs/030-navbar-topo-ux/spec.md
@ -0,0 +1,195 @@
+# Feature Specification: Revisão UX/UI da Navbar do Topo
+
+**Feature Branch**: `030-navbar-topo-ux`
+**Created**: 2026-04-22
+**Status**: Draft
+
+---
+
+## Objetivo
+
+Melhorar a navbar fixa do topo para oferecer uma navegação mais clara, consistente e eficiente em desktop e mobile, com comportamento específico por perfil:
+
+- Visitante (não autenticado)
+- Usuário autenticado (cliente)
+- Usuário admin
+
+A feature deve equilibrar descoberta de funcionalidades, redução de ruído visual e eficiência de navegação para tarefas críticas.
+
+---
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 — Navegação principal clara para visitantes (Priority: P1)
+
+Como visitante, quero entender rapidamente os caminhos principais do site para encontrar imóveis, equipe e contato sem confusão.
+
+**Why this priority**: A navbar é o principal ponto de orientação global da aplicação e impacta diretamente descoberta, conversão e retenção.
+
+**Independent Test**: Em páginas públicas, o visitante visualiza links principais, CTA e autenticação com hierarquia visual clara.
+
+**Acceptance Scenarios**:
+
+1. **Given** um visitante em viewport desktop, **When** a navbar é exibida, **Then** os itens principais de navegação estão visíveis e legíveis, sem truncamento.
+2. **Given** um visitante, **When** clica em um item principal (ex: Comprar, Alugar, Contato), **Then** é redirecionado ao destino correto e o estado ativo é refletido quando aplicável.
+3. **Given** um visitante, **When** interage com ações de topo, **Then** o CTA “Anunciar imóvel” e a ação “Entrar” aparecem com destaque adequado e consistente.
+4. **Given** um visitante em mobile, **When** abre o menu hambúrguer, **Then** encontra os mesmos destinos principais em ordem lógica e com alvo de toque adequado.
+
+---
+
+### User Story 2 — Menu de usuário autenticado orientado a tarefas (Priority: P1)
+
+Como usuário autenticado, quero acessar rapidamente minhas ações pessoais pela navbar para continuar minha jornada sem fricção.
+
+**Why this priority**: Usuário logado tem intenção clara; reduzir cliques e ambiguidade melhora eficiência e percepção de produto.
+
+**Independent Test**: Ao autenticar como cliente, o menu do usuário é exibido com ações pessoais e fluxo de logout confiável.
+
+**Acceptance Scenarios**:
+
+1. **Given** um cliente autenticado (não admin), **When** visualiza a navbar desktop, **Then** vê avatar/inicial, primeiro nome e um dropdown de conta.
+2. **Given** o dropdown do usuário aberto, **When** o cliente seleciona uma opção, **Then** navega para a rota correspondente e o dropdown fecha.
+3. **Given** o cliente autenticado, **When** escolhe “Sair”, **Then** a sessão é encerrada e a navbar retorna ao estado de visitante.
+4. **Given** o cliente autenticado em mobile, **When** abre o menu, **Then** encontra uma seção “Minha Conta” contendo links pessoais e logout.
+
+---
+
+### User Story 3 — Menu admin com acesso rápido e controle visual (Priority: P1)
+
+Como administrador, quero acessar módulos administrativos pela navbar sem poluir a experiência dos demais usuários.
+
+**Why this priority**: Admin precisa de eficiência operacional, mas o sistema também deve preservar clareza para perfis não-admin.
+
+**Independent Test**: Ao autenticar como admin, o menu Admin aparece; para outros perfis ele não aparece.
+
+**Acceptance Scenarios**:
+
+1. **Given** um usuário com role admin, **When** acessa o sistema, **Then** o gatilho do dropdown “Admin” é exibido na navbar desktop.
+2. **Given** o dropdown “Admin” aberto, **When** o admin escolhe um módulo, **Then** navega para o destino correto e o menu fecha.
+3. **Given** um usuário não admin, **When** navega no sistema, **Then** não vê o menu Admin em nenhum breakpoint.
+4. **Given** admin em mobile, **When** abre o menu, **Then** encontra uma seção “Admin” com os mesmos módulos prioritários da navegação desktop.
+
+---
+
+### User Story 4 — Navbar previsível, acessível e sem conflitos de estado (Priority: P2)
+
+Como usuário, quero que os menus da navbar respondam de forma previsível para não perder contexto durante a navegação.
+
+**Why this priority**: A navbar concentra múltiplos estados (menu mobile, dropdown usuário, dropdown admin), aumentando risco de comportamento inconsistente.
+
+**Independent Test**: Abrir/fechar menus mantém estados consistentes com clique externo, teclado e mudança de rota.
+
+**Acceptance Scenarios**:
+
+1. **Given** dropdown admin aberto, **When** o usuário abre dropdown do cliente, **Then** o dropdown admin fecha automaticamente.
+2. **Given** qualquer dropdown aberto, **When** ocorre clique fora, **Then** o dropdown fecha.
+3. **Given** menu mobile aberto, **When** o usuário navega para outra rota, **Then** o menu fecha automaticamente.
+4. **Given** navegação por teclado, **When** foco percorre a navbar, **Then** botões e links têm foco visível e acionamento por Enter/Espaço quando aplicável.
+
+---
+
+### User Story 5 — Hierarquia visual e responsividade premium (Priority: P2)
+
+Como usuário em desktop e mobile, quero uma navbar com equilíbrio visual e legibilidade para navegar com confiança em qualquer tamanho de tela.
+
+**Why this priority**: Qualidade visual e consistência de comportamento influenciam diretamente confiança e percepção de profissionalismo.
+
+**Independent Test**: Em breakpoints principais, navbar mantém legibilidade, contraste e espaçamento sem sobreposição de elementos.
+
+**Acceptance Scenarios**:
+
+1. **Given** telas entre 320px e 1440px+, **When** a navbar é renderizada, **Then** não há quebra de layout ou sobreposição de elementos.
+2. **Given** conteúdo de nome longo do usuário, **When** exibido no gatilho da conta, **Then** é truncado de forma elegante sem quebrar alinhamento.
+3. **Given** tema claro/escuro, **When** a navbar é exibida, **Then** contraste de texto e estados hover/active permanecem acessíveis.
+4. **Given** navegação prolongada, **When** o usuário rola e interage repetidamente, **Then** a navbar fixa mantém performance fluida sem jank perceptível.
+
+---
+
+## Edge Cases
+
+- Sessão expira com dropdown aberto: navbar deve invalidar estado autenticado e retornar ao estado visitante sem erro visual.
+- Usuário admin com nome muito longo: gatilho de conta/admin não deve deslocar links primários fora da área visível.
+- Rotas com query string (ex: listagem filtrada): estado ativo da navegação deve permanecer coerente.
+- Abertura simultânea de menu mobile e dropdown contextual: apenas um contexto de navegação deve permanecer aberto por vez.
+- Falha ao executar logout: deve mostrar feedback de erro e manter usuário autenticado até confirmação.
+
+---
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+**Arquitetura da navegação**
+
+- **FR-001**: A navbar DEVE manter uma área de navegação principal comum para todos os perfis (links públicos).
+- **FR-002**: O sistema DEVE exibir estados de navbar distintos para visitante, cliente autenticado e admin autenticado.
+- **FR-003**: O menu Admin DEVE ser exibido somente para usuários com `role=admin`.
+- **FR-004**: O menu do usuário (cliente) DEVE ser exibido somente para usuários autenticados não-admin.
+
+**Menu do usuário (cliente)**
+
+- **FR-005**: O dropdown do cliente DEVE incluir entradas para `Favoritos`, `Comparar`, `Visitas` e `Minha conta`.
+- **FR-006**: O dropdown do cliente DEVE incluir ação de `Sair` separada visualmente das ações de navegação.
+- **FR-007**: Em mobile, as ações do cliente DEVEM aparecer agrupadas sob uma seção `Minha Conta` dentro do menu principal.
+
+**Menu Admin**
+
+- **FR-008**: O dropdown Admin DEVE incluir atalhos para os módulos administrativos vigentes no sistema.
+- **FR-009**: Em mobile, os atalhos admin DEVEM ser exibidos em seção dedicada `Admin`.
+- **FR-010**: O menu Admin NÃO DEVE estar presente para visitantes nem clientes não-admin.
+
+**Comportamento de estados**
+
+- **FR-011**: Abrir um dropdown (Admin ou Cliente) DEVE fechar automaticamente o outro dropdown.
+- **FR-012**: Clique fora DEVE fechar dropdowns abertos.
+- **FR-013**: Mudança de rota DEVE fechar menu mobile e dropdowns abertos.
+- **FR-014**: O botão hambúrguer DEVE expor `aria-expanded` e `aria-controls` coerentes com o estado atual.
+
+**Acessibilidade e usabilidade**
+
+- **FR-015**: Todos os gatilhos interativos da navbar DEVEM possuir rótulos acessíveis e foco visível.
+- **FR-016**: Alvos de toque em mobile DEVEM respeitar área mínima de interação (44x44 CSS px).
+- **FR-017**: O estado ativo dos links DEVE ser visualmente distinguível em desktop e mobile.
+
+**Hierarquia visual e consistência**
+
+- **FR-018**: A navbar DEVE apresentar hierarquia clara entre links primários, menus contextuais (Admin/Conta) e CTAs.
+- **FR-019**: O CTA principal DEVE manter contraste e legibilidade adequados em tema claro e escuro.
+- **FR-020**: Nomes longos de usuário DEVEM ser truncados sem quebrar layout.
+
+### UX/UI Recommendations (Design Direction)
+
+- **UX-001**: Reduzir densidade cognitiva no topo priorizando no máximo 5 links primários visíveis no desktop.
+- **UX-002**: Reforçar separação visual entre navegação pública e navegação contextual de perfil (Admin/Conta).
+- **UX-003**: Priorizar consistência de iconografia entre desktop e mobile para ações de conta e logout.
+- **UX-004**: Padronizar microinterações (hover, active, open/close) com durações curtas e previsíveis.
+- **UX-005**: Incluir indicadores sutis de contexto de perfil (ex: badge/label admin) sem competir com CTA principal.
+
+### Key Entities
+
+- **AuthSession**: Estado de autenticação consumido pela navbar (`isAuthenticated`, `isLoading`, `user`).
+- **UserProfile**: Dados mínimos para renderização contextual (`name`, `role`).
+- **NavItem**: Item de navegação com destino e rótulo para links públicos, cliente e admin.
+- **NavUIState**: Estado transitório da navbar (`menuOpen`, `adminOpen`, `clientOpen`).
+
+---
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: 100% dos cenários de visibilidade por perfil (visitante, cliente, admin) são respeitados em desktop e mobile.
+- **SC-002**: 100% dos links de menu contextual (cliente/admin) navegam para os destinos corretos e fecham o menu após clique.
+- **SC-003**: 0 ocorrências de sobreposição/quebra da navbar nos breakpoints suportados (320px, 768px, 1024px, 1280px).
+- **SC-004**: Interações básicas de acessibilidade (foco visível, rótulos ARIA essenciais, navegação por teclado) funcionam sem bloqueios.
+- **SC-005**: Logout retorna estado visual de visitante em até 1 interação, sem necessidade de refresh manual.
+
+---
+
+## Assumptions
+
+- O fluxo de autenticação atual e o contexto de usuário (`useAuth`) permanecerão como fonte única de verdade para perfil e sessão.
+- Os módulos administrativos já existentes continuam válidos como destinos no menu Admin.
+- A navegação da Área do Cliente continuará disponível por links no menu do usuário autenticado.
+- Esta feature não altera regras de autorização backend; foca em UX/UI e comportamento de navegação no frontend.
+- Ajustes de conteúdo textual fino (copywriting) podem ser refinados durante implementação, sem alterar requisitos funcionais.
--- a/specs/030-navbar-topo-ux/tasks.md
+++ b/specs/030-navbar-topo-ux/tasks.md
@ -0,0 +1,261 @@
+# Tasks: Navbar Topo UX (030)
+
+**Input**: Design documents de `specs/030-navbar-topo-ux/`
+**Prerequisites**: plan.md ✅ · spec.md ✅ · research.md ✅ · data-model.md ✅ · quickstart.md ✅ · contracts/navbar-ui-contract.md ✅
+**Branch**: `030-navbar-topo-ux`
+
+## Format: `[ID] [P?] [Story?] Description`
+
+- **[P]**: pode ser executada em paralelo quando tocar arquivos distintos e sem dependência de tarefa incompleta
+- **[Story]**: user story correspondente (`US1`, `US2`, `US3`, `US4`, `US5`)
+- Caminhos exatos incluídos em cada tarefa
+
+**Tests**: a spec não pede suíte automatizada nova para esta feature. O guardrail executável mínimo é `npm run build` em `frontend/`, complementado pelo checklist manual de `quickstart.md`.
+
+---
+
+## Phase 1: Setup — Preparação da Navbar Compartilhada
+
+**Purpose**: estabelecer a base visual e estrutural da navbar compartilhada antes da refatoração de estados e das variações por perfil.
+
+- [X] T001 Consolidar a configuração de navegação compartilhada em `frontend/src/components/Navbar.tsx` com arrays tipados para links públicos, ações do cliente e atalhos admin, alinhados aos destinos definidos em `specs/030-navbar-topo-ux/contracts/navbar-ui-contract.md`
+
+- [X] T002 [P] Preparar tokens utilitários da navbar fixa em `frontend/src/index.css` para backdrop, foco visível, estados hover/active/open, alvo mínimo de toque e contraste consistente em tema claro/escuro
+
+**Checkpoint**: a base de navegação e os tokens visuais da navbar estão definidos sem introduzir novas dependências externas.
+
+---
+
+## Phase 2: Foundational — Estado e Shell Compartilhados
+
+**Purpose**: implementar a infraestrutura de estado e shell que bloqueia todas as user stories da navbar.
+
+**⚠️ CRÍTICO**: nenhuma user story deve avançar antes desta fase estar concluída.
+
+- [X] T003 Implementar em `frontend/src/components/Navbar.tsx` a derivação explícita de variante `visitor` / `client` / `admin` a partir de `useAuth()` e centralizar a decisão de visibilidade dos blocos públicos, contextuais e de autenticação
+
+- [X] T004 Implementar em `frontend/src/components/Navbar.tsx` um controlador único de overlay com os estados `closed`, `mobile`, `client` e `admin`, substituindo booleans soltos por handlers de abertura/fechamento mutuamente exclusivos
+
+- [X] T005 [P] Integrar em `frontend/src/components/Navbar.tsx` e `frontend/src/contexts/AuthContext.tsx` o fechamento global por mudança de rota, clique fora e logout, garantindo retorno imediato ao estado visual de visitante sem menus órfãos
+
+- [X] T006 [P] Ajustar `frontend/src/layouts/ClientLayout.tsx` e `frontend/src/layouts/AdminLayout.tsx` para respeitar a altura e o empilhamento da navbar fixa sem sobrepor o conteúdo principal após a refatoração
+
+**Checkpoint**: existe uma única fonte de verdade para os overlays da navbar, e os shells compartilham offset compatível com a barra fixa.
+
+---
+
+## Phase 3: User Story 1 — Navegação Principal Clara para Visitantes (Priority: P1) 🎯 MVP
+
+**Goal**: entregar uma navbar pública clara, legível e consistente para visitantes em desktop e mobile.
+
+**Independent Test**: em páginas públicas, o visitante vê até 5 links principais com estado ativo coerente, CTA `Anunciar imóvel`, ação `Entrar` e menu mobile com os mesmos destinos em ordem lógica.
+
+- [X] T007 [US1] Reorganizar a estrutura desktop de visitante em `frontend/src/components/Navbar.tsx` para exibir logo, navegação pública principal, favoritos públicos quando aplicável, CTA `Anunciar imóvel` e ação `Entrar` com hierarquia visual clara
+
+- [X] T008 [P] [US1] Implementar em `frontend/src/components/Navbar.tsx` a lógica de estado ativo para links públicos, incluindo correspondência coerente para rotas com query string como `/imoveis?listing_type=venda` e `/imoveis?listing_type=aluguel`
+
+- [X] T009 [US1] Implementar o menu mobile de visitante em `frontend/src/components/Navbar.tsx` com gatilho hambúrguer, mesma ordem de destinos públicos do desktop, CTA destacado e fechamento automático ao navegar
+
+- [X] T010 [P] [US1] Refinar em `frontend/src/index.css` a aparência da navegação pública desktop/mobile, do CTA principal e dos estados hover/active para manter legibilidade entre 320 px e 1440 px+
+
+**Checkpoint**: US1 fica utilizável de forma independente para visitante em desktop e mobile, com destinos públicos claros e sem truncamento indevido.
+
+---
+
+## Phase 4: User Story 2 — Menu de Usuário Autenticado Orientado a Tarefas (Priority: P1)
+
+**Goal**: permitir que o cliente autenticado acesse rapidamente ações pessoais e logout pela navbar.
+
+**Independent Test**: ao autenticar como cliente não-admin, a navbar exibe gatilho de conta com nome truncado, dropdown com `Favoritos`, `Comparar`, `Visitas`, `Minha conta` e `Sair`, além da seção `Minha Conta` no mobile.
+
+- [X] T011 [US2] Implementar em `frontend/src/components/Navbar.tsx` o gatilho de conta do cliente com inicial/avatar, primeiro nome truncado e dropdown desktop contendo `Favoritos`, `Comparar`, `Visitas`, `Minha conta` e `Sair` com separação visual do logout
+
+- [X] T012 [P] [US2] Ajustar em `frontend/src/contexts/AuthContext.tsx` a superfície consumida pela navbar para suportar renderização confiável de nome, role e logout sem flicker durante hidratação ou encerramento de sessão
+
+- [X] T013 [US2] Integrar em `frontend/src/components/Navbar.tsx` os links de `Favoritos` e `Comparar` com os contextos existentes `frontend/src/contexts/FavoritesContext.tsx` e `frontend/src/contexts/ComparisonContext.tsx` sem quebrar a navegação contextual do cliente
+
+- [X] T014 [US2] Implementar em `frontend/src/components/Navbar.tsx` a seção mobile `Minha Conta` com os mesmos destinos do dropdown desktop, logout separado visualmente e fechamento automático após clique em qualquer ação
+
+**Checkpoint**: US2 fica testável de forma independente com login de cliente, incluindo fluxo confiável de logout e paridade desktop/mobile.
+
+---
+
+## Phase 5: User Story 3 — Menu Admin com Acesso Rápido e Controle Visual (Priority: P1)
+
+**Goal**: expor atalhos administrativos apenas para admins, sem poluir a experiência de visitantes e clientes.
+
+**Independent Test**: ao autenticar como admin, a navbar exibe gatilho `Admin` com atalhos prioritários no desktop e seção `Admin` no mobile; para não-admin, nada disso aparece.
+
+- [X] T015 [US3] Implementar em `frontend/src/components/Navbar.tsx` o gatilho e dropdown desktop `Admin`, exibindo apenas para `role === 'admin'` e listando os módulos existentes definidos em `specs/030-navbar-topo-ux/contracts/navbar-ui-contract.md`
+
+- [X] T016 [US3] Implementar em `frontend/src/components/Navbar.tsx` a seção mobile `Admin` com os mesmos atalhos prioritários do desktop, mantendo exclusão do menu padrão `Minha Conta` para admins
+
+- [X] T017 [P] [US3] Validar e ajustar em `frontend/src/App.tsx` os destinos usados pela navbar admin para garantir que todos os atalhos planejados apontem para rotas já existentes no SPA sem criar rotas novas fora do escopo
+
+**Checkpoint**: US3 fica utilizável por admin sem regressão de visibilidade para visitante ou cliente autenticado.
+
+---
+
+## Phase 6: User Story 4 — Navbar Previsível, Acessível e Sem Conflitos de Estado (Priority: P2)
+
+**Goal**: garantir previsibilidade de interação, acessibilidade básica e exclusão mútua robusta entre menu mobile, dropdown do cliente e dropdown admin.
+
+**Independent Test**: abrir qualquer contexto e verificar fechamento por clique fora, Escape, mudança de rota e abertura de outro contexto; foco, labels e ARIA permanecem coerentes durante navegação por teclado.
+
+- [X] T018 [US4] Aplicar em `frontend/src/components/Navbar.tsx` `aria-label`, `aria-expanded`, `aria-controls`, ids estáveis e suporte a `Enter`, `Espaço` e `Escape` para hambúrguer, dropdown do cliente e dropdown admin
+
+- [X] T019 [P] [US4] Garantir em `frontend/src/index.css` foco visível, contraste acessível e alvo mínimo de 44x44 px para todos os gatilhos e itens clicáveis da navbar em desktop e mobile
+
+- [X] T020 [US4] Consolidar em `frontend/src/components/Navbar.tsx` o fechamento mútuo entre `mobile`, `client` e `admin`, incluindo transições corretas ao trocar rota, clicar fora e executar logout com sucesso ou erro
+
+**Checkpoint**: US4 fica validável com teclado e clique externo, sem estados simultâneos nem overlays presos.
+
+---
+
+## Phase 7: User Story 5 — Hierarquia Visual e Responsividade Premium (Priority: P2)
+
+**Goal**: elevar a qualidade visual e a responsividade da navbar compartilhada em todos os breakpoints suportados.
+
+**Independent Test**: a navbar permanece legível, sem sobreposição e com truncamento elegante de nomes longos em 320 px, 768 px, 1024 px e 1280 px+, nos dois temas.
+
+- [X] T021 [US5] Reequilibrar em `frontend/src/components/Navbar.tsx` a distribuição entre logo, links públicos, ações contextuais, `ThemeToggle` e CTA para evitar sobreposição e excesso de densidade visual nos breakpoints principais
+
+- [X] T022 [P] [US5] Ajustar em `frontend/src/index.css` truncamento elegante de nomes longos, espaçamento responsivo, microinterações curtas e separação visual entre navegação pública e contextual nos temas claro e escuro
+
+- [X] T023 [US5] Revisar em `frontend/src/layouts/ClientLayout.tsx` e `frontend/src/layouts/AdminLayout.tsx` o comportamento do conteúdo após scroll para manter a navbar fixa estável e sem jank perceptível nas áreas autenticadas
+
+**Checkpoint**: US5 fica estável visualmente nos breakpoints e temas suportados, com densidade e truncamento sob controle.
+
+---
+
+## Phase Final: Polish & Validação
+
+**Purpose**: executar o guardrail mínimo e o checklist manual completo da feature antes do merge.
+
+- [X] T024 Executar `npm run build` no diretório `frontend/` e corrigir qualquer erro de TypeScript ou compilação relacionado à navbar compartilhada
+
+- [X] T025 [P] Executar os cenários de validação por persona, tema e breakpoint descritos em `specs/030-navbar-topo-ux/quickstart.md`, cobrindo visitante, cliente, admin e os breakpoints 320 px, 768 px, 1024 px e 1280 px
+
+- [X] T026 [P] Fazer limpeza final em `frontend/src/components/Navbar.tsx` e `frontend/src/index.css`, removendo handlers, classes e estados legados substituídos pela refatoração de overlay único
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+```text
+Phase 1 (Setup)
+        │
+        └──→ Phase 2 (Foundational)
+                 │
+                 ├──→ Phase 3 (US1 — Visitante)
+                 ├──→ Phase 4 (US2 — Cliente)
+                 ├──→ Phase 5 (US3 — Admin)
+                 ├──→ Phase 6 (US4 — Acessibilidade e estado)
+                 └──→ Phase 7 (US5 — Responsividade premium)
+                               │
+                               └──→ Phase Final (Build + validação manual)
+```
+
+- **Phase 1**: sem dependências; prepara a configuração e os tokens visuais da navbar
+- **Phase 2**: depende da conclusão de Phase 1; bloqueia todas as user stories
+- **Phase 3 a Phase 7**: dependem de Phase 2; podem avançar em paralelo apenas quando não houver conflito de arquivo
+- **Phase Final**: depende das user stories desejadas concluídas
+
+### User Story Dependencies
+
+- **US1 (P1)**: pode começar após Phase 2; independente de US2 e US3 no comportamento de perfil
+- **US2 (P1)**: depende de Phase 2 e compartilha `Navbar.tsx` com US1, então a execução prática tende a ser sequencial no mesmo componente
+- **US3 (P1)**: depende de Phase 2; pode ocorrer em paralelo apenas com T017, que toca `App.tsx`
+- **US4 (P2)**: depende de T004 e T005 porque a base de overlay único e fechamento global precisa existir primeiro
+- **US5 (P2)**: depende da estrutura renderizada por US1, US2 e US3 para calibrar responsividade final com dados reais
+
+### Task-Level Notes
+
+- T002 pode rodar em paralelo com T001
+- T005 e T006 podem rodar em paralelo após T003 e T004
+- T008 e T010 podem rodar em paralelo dentro de US1
+- T012 pode rodar em paralelo com T011; T013 pode iniciar após T011
+- T017 pode rodar em paralelo com T015 e T016
+- T019 pode rodar em paralelo com T018; T020 depende da instrumentação criada em T018
+- T022 pode rodar em paralelo com T021; T023 depende do ajuste de altura/layout consolidado
+
+---
+
+## Parallel Execution Examples
+
+### User Story 1
+
+```text
+T007 → T009
+T008 || T010
+```
+
+### User Story 2
+
+```text
+T011 → T013 → T014
+T012 pode ocorrer em paralelo a T011
+```
+
+### User Story 3
+
+```text
+T015 → T016
+T017 pode ocorrer em paralelo a T015
+```
+
+### User Story 4
+
+```text
+T018 → T020
+T019 pode ocorrer em paralelo a T018
+```
+
+### User Story 5
+
+```text
+T021 → T023
+T022 pode ocorrer em paralelo a T021
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First
+
+1. Concluir Phase 1 e Phase 2
+2. Entregar US1 para visitante como primeiro incremento navegável
+3. Adicionar US2 e US3 para fechar a matriz de perfis da navbar
+4. Validar build e checklist manual antes de partir para polish visual fino
+
+### Incremental Delivery
+
+1. **Incremento 1**: Setup + Foundational
+2. **Incremento 2**: US1 — navegação pública clara em desktop/mobile
+3. **Incremento 3**: US2 + US3 — menus contextuais por perfil autenticado
+4. **Incremento 4**: US4 — previsibilidade, teclado e ARIA
+5. **Incremento 5**: US5 — acabamento responsivo premium
+
+### Suggested MVP Scope
+
+O menor recorte demonstrável é **US1** após a fase Foundational. O menor recorte funcional completo para a matriz de perfis é **US1 + US2 + US3**.
+
+---
+
+## Summary
+
+| Fase | Tarefas | Escopo |
+|------|---------|--------|
+| Phase 1 | T001–T002 | Setup da navbar compartilhada |
+| Phase 2 | T003–T006 | Estado e shell bloqueadores |
+| Phase 3 | T007–T010 | US1 — visitante |
+| Phase 4 | T011–T014 | US2 — cliente autenticado |
+| Phase 5 | T015–T017 | US3 — admin |
+| Phase 6 | T018–T020 | US4 — acessibilidade e previsibilidade |
+| Phase 7 | T021–T023 | US5 — responsividade premium |
+| Phase Final | T024–T026 | Build, validação manual e limpeza |
+| **Total** | **26 tarefas** | **5 user stories + setup/foundational/polish** |
+