gitadmin/sass-imobiliaria
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
sass-imobiliaria/specs/030-navbar-topo-ux/spec.md
MatheusAlves96 cf5603243c
Some checks failed
CI/CD → Deploy via SSH / Build & Push Docker Images (push) Successful in 1m0s
Details
CI/CD → Deploy via SSH / Deploy via SSH (push) Successful in 4m35s
Details
CI/CD → Deploy via SSH / Validate HTTPS & Endpoints (push) Failing after 46s
Details
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

11 KiB
Raw Blame History

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.