Sistema de Tour de Onboarding

O que Sistema de Tour de Onboarding faz?

Propósito

O skill Sistema de Tour de Onboarding fornece uma metodologia de design abrangente para estruturar, estilizar e coordenar walkthroughs guiados de produtos em várias etapas. Ele é projetado para reduzir a carga cognitiva do usuário durante o primeiro onboarding ou lançamentos de grandes funcionalidades, isolando visualmente elementos-chave da interface, fornecendo contexto sequencial altamente relevante e guiando o usuário a um estado ativo e bem-sucedido. Este sistema evita tours confusos, caóticos ou excessivamente intrusivos, estabelecendo um ritmo previsível, acessível e controlado pelo usuário.

Casos de Uso

• Onboarding de Novo Usuário: Guiar usuários recém-registrados pelos fluxos de trabalho essenciais de uma aplicação SaaS complexa para impulsionar a ativação.
• Promoção de Novas Funcionalidades: Destacar e explicar uma nova ferramenta ou elemento de interface de alto valor recém-lançado para usuários existentes.
• Familiarização com Redesenho de UI: Ajudar usuários recorrentes a localizar ferramentas familiares após uma reformulação ou reorganização significativa da interface.
• Tours de Entrada de Dados Complexos em Etapas: Guiar um usuário por um painel multifacetado durante sua configuração inicial (por exemplo, configurando sua primeira regra de automação).

Quando NÃO Usar

• Interfaces Autoexplicativas: Se uma tarefa pode ser simplificada com layouts mais claros, rótulos melhores ou iconografia intuitiva, melhore a UI principal primeiro em vez de mascarar uma UX ruim com um tour.
• Microtarefas Altamente Repetitivas: Evite interromper fluxos de trabalho frequentes com pop-ups. Para ajuda regular, use o sistema-de-dicas-e-tooltips ou texto de ajuda inline.
• Interfaces Apenas para Dispositivos Móveis ou de Baixa Resolução: Tours com popovers ancorados em várias etapas consomem muito espaço na tela e são altamente propensos a cortes ou sobreposições em dispositivos móveis. Use cartões em tela cheia ou etapas inline dispensáveis integradas.
• Feedback de Erro Crítico ou Transacional: Para feedback instantâneo do sistema ou erros, use o sistema-de-banners-e-alertas ou sistema-de-toasts-e-snackbars.

Entradas

1. Arquitetura da Informação e Contexto: Os layouts de página específicos, seções do painel ou coordenadas de UI onde o tour será executado.
2. Inventário de Elementos Âncora: Os botões, campos de entrada, tabelas ou links de navegação específicos que precisam ser destacados em cada etapa.
3. Marcos de Onboarding (O "Porquê"): As ações-chave mínimas necessárias para concluir o onboarding e garantir a ativação.
4. Breakpoints de Dispositivo: Viewports de destino responsivas onde o tour deve ser renderizado, usando as diretrizes do sistema-de-grid-responsivo.

Saídas

1. Especificação de Máscara e Fundo: Isolar visualmente elementos de destino enquanto escurece o resto da interface para focar a atenção do usuário.
2. Especificação da Anatomia do Popover (Cartão de Tour): Blueprint estrutural detalhado da bolha de tour (setas, texto do corpo, indicadores de etapa, botões pular/próximo/voltar, controles de fechar).
3. Lógica de Sequência e Fluxo: Mapeamento de rota etapa por etapa, modelos de progressão (linear estrito vs. conduzido pelo usuário) e persistência de sessão.
4. Estratégia Responsiva e Fallbacks para Dispositivos Móveis: Regras de adaptação para telas menores onde popovers flutuantes ancorados não cabem com segurança.
5. Marcos de Acessibilidade e Especificação de Interação: Especificação ARIA completa, mapa de navegação por teclado e comportamento de captura de foco.

Fluxo de Trabalho

1. Definir a Sequência de Etapas (O Caminho Feliz)

• Limite a sequência do tour a 3 a 5 etapas (Lei de Miller). Qualquer coisa maior resulta em alta taxa de abandono.
• Foque cada etapa em um benefício ativo, não apenas em um rótulo. (Ex.: Em vez de "Este é o menu Configurações", escreva "Personalize seu espaço de trabalho para corresponder ao fluxo de trabalho da sua equipe aqui").
• Certifique-se de que a etapa final tenha uma chamada para ação (CTA) clara e acionável que deixe o usuário em um estado ativo e produtivo.

2. Projetar a Máscara de Fundo e Isolamento (Foco)

• Use uma sobreposição de fundo escura semitransparente (geralmente #000000 com opacidade de 50-70%) para silenciar o ruído de fundo e focar o olhar.
• Crie uma "Máscara de Isolamento" (usando recortes de caminho SVG ou clip-path / box-shadows CSS) ao redor do elemento âncora ativo.
• Mantenha um buffer de preenchimento de 4px a 8px ao redor da âncora destacada para evitar que a máscara fique muito próxima das bordas do elemento.

3. Construir a Hierarquia do Popover (Cartão de Tour)

• Alinhamento da Âncora: Posicione o popover dinamicamente próximo ao elemento destacado. Use uma pequena seta/ponteiro direcional para conectar visualmente o cartão à âncora.
• Anatomia do Componente:
  • Cabeçalho: Inclua um botão Fechar padrão ('X') e um indicador de progresso (ex.: "Etapa 2 de 4").
  • Corpo: Use títulos em negrito e concisos e no máximo 2 frases de texto descritivo.
  • Barra de Ações: Alinhe o link "Pular" à esquerda e os botões de navegação à direita. Certifique-se de que "Próximo" (ou "Entendi") use o estilo CTA principal, e "Voltar" use um estilo terciário de baixo contraste.

4. Codificar para Acessibilidade (Paridade com Teclado e Leitor de Tela)

• Captura de Foco: Quando uma etapa do tour estiver ativa, o foco do teclado (tecla Tab) deve ser capturado dentro do popover do tour para evitar que usuários de teclado naveguem por itens de fundo.
• Associações ARIA: Certifique-se de que o contêiner do popover use role="dialog" ou role="alertdialog" com aria-modal="false" (para que as tecnologias assistivas saibam que os elementos de fundo ainda estão presentes). Vincule o título do popover com aria-labelledby e a descrição com aria-describedby.
• Atalhos de Teclado: Suporte à navegação por teclado: Escape para dispensar/pular o tour, Seta Direita para "Próximo" e Seta Esquerda para "Voltar".

5. Mapear a Estratégia de Adaptação para Dispositivos Móveis

• Se o viewport for menor que 768px (Tablet/Móvel), faça a transição de popovers flutuantes ancorados para uma gaveta inferior ou um modal centralizado não ancorado. Isso evita que o cartão seja empurrado para fora da tela ou cubra elementos críticos.
• Certifique-se de que a máscara de fundo seja desabilitada ou simplificada em dispositivos móveis para evitar erros de corte causados pela rolagem em dispositivos móveis.

Regras de Decisão

• Tour Linear vs. Lista de Tarefas Conduzida pelo Usuário:
  • Use um Tour Linear para uma sequência de configuração inicial rígida onde a Etapa A deve preceder a Etapa B.
  • Use um Widget de Progresso Interativo (Lista de Tarefas) se as tarefas puderem ser concluídas em qualquer ordem, permitindo que os usuários selecionem as tarefas em seu próprio ritmo.
• Condição de Gatilho:
  • Acione automaticamente apenas durante a primeira execução ou após atualizações explícitas.
  • Nunca acione tours automaticamente para usuários recorrentes em visitas padrão.
• Substituição de Posição da Âncora:
  • Padrão: Posicione o popover "Centro-Inferior" ou "Centro-Direito" da âncora.
  • Regra de Colisão: Se a âncora estiver perto da borda da tela, inverta o posicionamento do popover para evitar cortes (ex.: de "Direita" para "Esquerda"). Se a âncora estiver oculta (dentro de um painel recolhido), expanda o painel programaticamente antes de renderizar o popover.
• A Opção "Pular":
  • Sempre forneça uma ação visível de "Pular Tour" ou "Dispensar" em cada etapa. Forçar os usuários a concluir um tour sem opção de saída gera frustração.

Restrições

• Acessibilidade (WCAG 2.2):
  • O contraste do texto dentro do cartão de tour deve atender ao WCAG AA (pelo menos 4,5:1).
  • Um anel de foco visual de alto contraste (outline) deve estar presente nos botões interativos.
  • Os alvos de toque para botões próximo/voltar devem ter pelo menos 44x44px (recomendado) ou atender ao mínimo de 24x24px (WCAG 2.2 SC 2.5.8).
  • As âncoras interativas dentro do recorte da máscara de fundo devem ser focalizáveis.
• Gerenciamento de Mudança de Layout:
  • O aparecimento do fundo, da máscara de recorte e do popover não deve deslocar elementos de layout existentes. Use position: absolute ou position: fixed relativo ao viewport do documento.
• Alinhamento de Z-Index:
  • O fundo e o cartão de tour devem ficar abaixo dos alertas de utilidade de nível superior, como Toasts (ex.: fundo no z-index 900, popover no z-index 910) para garantir que alertas de sistema de alta prioridade ainda possam ser exibidos.

Padrões Comuns de Falha

• A Armadilha do "Tour Infinito": Tours com mais de 5 etapas, causando desistência imediata dos usuários.
• O Conflito de "Duplo Foco": Iniciar automaticamente um tour em uma página que já possui um modal ativo, criando sobreposições empilhadas e entradas de dados capturadas.
• Destaque de Âncora Cega: Destacar um elemento que está rolado para fora da tela ou recolhido, apontando a seta para o espaço vazio.
• Ações de Fundo Inacessíveis: Exigir que o usuário digite em um elemento mascarado para prosseguir, mas bloquear sua entrada ou cliques do mouse com o fundo.
• Compressão da Bolha em Dispositivos Móveis: Permitir que bolhas ancoradas encolham para larguras ilegíveis em dispositivos móveis, fazendo com que as palavras quebrem de forma estranha.

Critérios de Validação

• O tour é estritamente limitado a 3-5 etapas.
• Cada etapa tem uma opção claramente rotulada e visível de "Pular" ou fechar.
• O foco da tecla Tab é capturado dentro do popover durante as etapas ativas.
• O foco se move suavemente para o próximo cartão de tour (ou para o elemento recém-destacado) quando "Próximo" é pressionado.
• Atributos ARIA (role="dialog", aria-modal, aria-describedby) estão configurados corretamente.
• O tratamento de colisão do popover está definido (inverte automaticamente a posição perto das bordas da tela).
• Viewports móveis fazem a transição suave de popovers ancorados para um modal centralizado ou uma gaveta inferior persistente.
• Um buffer de preenchimento de 4-8px é mantido ao redor da âncora isolada para evitar cortar as bordas.
• Estados ativo e de foco para todos os botões atendem ao WCAG AA (contraste 4,5:1).