cf5603243c
- 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)
195 lines
11 KiB
Markdown
195 lines
11 KiB
Markdown
# 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.
|