# 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.