coastdigitalgroup/coastai-skills

Sistema de Toast e Snackbar

Propósito

O Sistema de Toast e Snackbar fornece uma metodologia para projetar camadas de notificação temporárias e não intrusivas. São componentes de UI breves, com descarte automático ou manual, que ficam em uma camada de tela dedicada acima da interface primária. Diferente de sobreposições modais, eles não sequestram o foco nem interrompem o fluxo do usuário; em vez disso, servem como um "loop de reconhecimento" passivo e de alta visibilidade, confirmando que uma tarefa em segundo plano ou imediata foi bem-sucedida, falhou ou requer pouca atenção. Este sistema garante que os toasts sejam visualmente unificados, posicionados para evitar bloqueio de controles vitais e totalmente acessíveis para usuários de mouse, toque e tecnologia assistiva.

Casos de Uso

• Ações Assíncronas: Confirmar que um arquivo foi enviado, um rascunho foi salvo ou um registro foi excluído em segundo plano.
• Confirmação de Micro-Compromisso: Reconhecer ações como adicionar um produto ao carrinho, copiar um link para a área de transferência ou alternar uma preferência localizada do sistema.
• Operações Destrutivas Reversíveis: Notificar um usuário que um item foi arquivado ou excluído, emparelhado com uma ação imediata "Desfazer" dentro da snackbar.
• Atualizações de Status Transitórias: Exibir alertas breves e automatizados do sistema, como a transição para um estado "Offline" ou "Online".

Quando NÃO Usar

• Bloqueios de Sistema de Alta Gravidade: Se um erro crítico exigir intervenção imediata ou impedir o usuário de prosseguir (ex.: sessão expirada, falha de pagamento); use sistema-de-sobreposicao-e-dialogo (Modal).
• Avisos de Seção Persistente: Se um aviso ou erro se relacionar especificamente a uma seção, página ou contexto de formulário inteiro e precisar permanecer visível até ser resolvido; use sistema-de-banner-e-alerta (Alerta Embutido).
• Mensagens de Validação de Formulário: Se um usuário cometer um erro em um campo de entrada específico; use sistema-de-design-de-formularios (validação no nível do campo).
• Descoberta de Conteúdo Primário: Nunca use toasts para apresentar conteúdo primário, anúncios de marketing ou opções de navegação.

Entradas

1. Gravidade/Tipo da Mensagem: Sucesso (confirmação), Informação (atualizações neutras), Aviso (preocupação não bloqueante) ou Erro (falha na operação).
2. Requisitos de Ação: O feedback é passivo (somente leitura) ou inclui uma única micro-ação (ex.: "Desfazer", "Visualizar", "Tentar Novamente")?
3. Imóvel de Tela e Classe de Dispositivo: Viewports alvo (desktop, tablet, mobile) e métodos de entrada prevalecentes (hover do mouse vs. alcance do polegar).
4. Estratégia de Z-Index e Camadas: Regras de contexto de empilhamento para evitar sobreposição com navegação de cabeçalho, rodapés fixos ou sobreposições ativas.

Saídas

1. Especificação de Anatomia: Blueprint baseado em grade do contêiner, slot de ícone, string de mensagem, CTA de ação e botão de fechamento manual.
2. Regras de Alinhamento Espacial e Posicionamento: Coordenadas adaptativas para desktop (ex.: pilha no canto superior direito ou inferior direito) e mobile (ex.: deslizamento de largura total na parte inferior).
3. Lógica de Fila e Empilhamento: Regras do sistema para lidar com alertas simultâneos, limites máximos visíveis e sequenciamento de expiração.
4. Linha do Tempo Interativa e Especificação de Expiração: Regras que governam timeouts de autodescarte, comportamentos de pausa ao passar o mouse e gestos de deslizar.
5. Blueprint de Acessibilidade/ARIA: Mapeamento semântico de regiões ativas, manipulação de foco para toasts interativos e anúncios de leitor de tela.

Fluxo de Trabalho

1. Estruturar a Anatomia do Componente

Defina uma grade de espaçamento e layout precisa para o contêiner de toast usando tokens espaciais padrão:

• Slot de Ícone: Largura fixa (ex.: 20px ou 24px) posicionada no extremo esquerdo. Use ícones de status semânticos e de alto contraste (marca de verificação para Sucesso, triângulo de exclamação para Aviso/Erro, círculo de informação para Info).
• Área de Texto: Tipografia alinhada à esquerda, com quebra de linha, consistindo em um breve título (negrito, opcional) e uma descrição. Nunca trunque o texto com reticências; quebre em até 3 linhas no máximo.
• Slot de Ação (Opcional): Um único botão de texto altamente visível (ex.: "Desfazer") colocado à direita da mensagem. Para texto longo em mobile, quebre a ação para uma nova linha alinhada à direita.
• Gatilho de Descarte: Um botão de fechamento 'X' claro colocado no extremo direito. Deve ter uma área de toque mínima de 24x24px (44x44px preferível para alvos de toque).

2. Determinar o Posicionamento Espacial por Viewport

• Posicionamento Desktop: Posicione a pilha de contêineres de toast no canto Superior Direito ou Inferior Direito da tela. Mantenha um deslocamento consistente de 24px das bordas da viewport.
  • Pilha Superior Direita: Melhor quando o fluxo de ação principal ocorre nas porções inferiores da página.
  • Pilha Inferior Direita: Melhor quando barras de navegação ou utilidades montadas no topo ocupam a margem superior, evitando sobreposição.
• Posicionamento Mobile: Transforme a pilha desktop em uma Snackbar ancorada na parte inferior, de largura total (margens de 12px a 16px das bordas esquerda, direita e inferior). Isso mantém a interação dentro da "zona de alcance do polegar" ideal.
• Regra de Z-Index: Sempre atribua um token de z-index dedicado (ex.: z-index: 5000 ou superior) que coloque os toasts acima dos cabeçalhos fixos padrão (z-index: 1000), mas abaixo das sobreposições de tela cheia ativas (z-index: 10000).

3. Estabelecer a Lógica de Empilhamento e Fila

Gerencie ambientes de alto volume de gatilhos sem induzir instabilidade de layout ou sobrecarga cognitiva:

• Limite Máximo Visível: Limite a fila ativa a um máximo de 3 toasts visíveis empilhados verticalmente.
• Direção de Empilhamento:
  • Se colocado na parte superior da tela, novos toasts deslizam de cima, empurrando os mais antigos para baixo.
  • Se colocado na parte inferior da tela, novos toasts deslizam de baixo, empurrando os mais antigos para cima.
• Buffer de Fila: Se um 4º toast for acionado enquanto 3 estão ativos, armazene o novo toast em buffer na memória. Renderize-o imediatamente assim que o toast visível mais antigo expirar naturalmente e desaparecer.

4. Codificar a Linha do Tempo de Expiração e Pausa ao Passar o Mouse

Os toasts devem existir tempo suficiente para serem lidos, mas desaparecer prontamente para limpar a tela:

• Tempo de Vida Dinâmico (TTL): Calcule a expiração com base no comprimento do conteúdo:
  • Toasts Passivos Curtos (< 40 caracteres): Descartar após 5 segundos.
  • Toasts Mais Longos ou com Ação: Descartar após 7 a 10 segundos para garantir que leitores de tela possam anunciá-los completamente e os usuários tenham tempo para ler e agir.
  • Toasts de Erro/Falha: Não descartar automaticamente. Mantenha-os visíveis até que o usuário clique manualmente no botão 'X', garantindo que o feedback crítico não seja perdido.
• A Interação "Pausar ao Passar o Mouse":
  • Se um usuário de mouse passar o cursor sobre qualquer parte da fila de toasts, congele todas as contagens regressivas TTL ativas. Redefina e retome os temporizadores somente após o mouse sair dos limites do toast.
  • Se um usuário de teclado focar em qualquer elemento dentro de um toast, congele o temporizador indefinidamente. Retome as contagens regressivas somente quando o foco mudar de volta para o documento principal.

5. Definir Comportamentos de Fechamento e Gestos

• Deslizar Toque: Em dispositivos móveis, permita que os usuários descartem snackbars individuais imediatamente deslizando-as horizontalmente para fora da tela (esquerda ou direita). Mantenha o limite de arrasto em 30% da largura da viewport.
• Animação: Use transições suaves e aceleradas por hardware (ex.: transform e opacity) com duração de 200ms a 300ms e cubic-bezier(0.16, 1, 0.3, 1) (ease-out-expo) para entrada, e simples fade-out de opacity para saída.

---

Regras de Decisão

Matriz de Alinhamento de Empilhamento

Viewport	Layout de Navegação Primária	Posicionamento Recomendado do Toast	Direção da Animação
Desktop	Sidebar Esquerda / Dashboard	Inferior Direito (mantém o trabalho principal livre)	Deslizar da esquerda para fora da tela
Desktop	Cabeçalho Fixo Superior	Inferior Direito (previne oclusão da navegação)	Deslizar da esquerda ou de cima
Desktop	Minimalista / com bastante rodapé	Superior Direito	Deslizar da esquerda ou de baixo
Mobile	Qualquer	Centralizado Inferior / Largura Total	Deslizar de baixo para cima

Matriz de Lógica de Expiração

Gravidade/Tipo do Toast	Contém Botão de Ação?	Expiração Recomendada	Tipo de Descarte
Sucesso / Info	Não	5 segundos (Fixo)	Autodescarte + Fechamento manual
Sucesso / Info	Sim ("Desfazer" / "Visualizar")	8 - 10 segundos	Autodescarte + Fechamento manual
Aviso	Não	7 segundos	Autodescarte + Fechamento manual
Erro / Falha	Sim ou Não	Infinito (Permanece persistente)	Apenas Fechamento manual

---

Restrições

• Acessibilidade (Conformidade WCAG 2.2):
  • Regiões Ativas ARIA: Mapeie toasts passivos para role="status" (que padroniza para aria-live="polite" e aria-atomic="true"). Evite usar role="alert" (assertivo) a menos que esteja comunicando uma falha do sistema (ex.: "Conexão com a internet perdida"), pois alertas assertivos interrompem imediatamente os leitores de tela no meio de uma frase.
  • Navegação por Teclado (WCAG 2.2 SC 2.1.1): Quando um toast contiver uma ação interativa (ex.: "Desfazer" ou "Visualizar"), ele deve ser acessível por teclado. Como os loops de tabulação do teclado podem ser lentos, forneça um atalho global de bypass (ex.: Escape fecha o toast ativo, ou F6 desloca o foco diretamente para o contêiner da fila de toasts) ou coloque o contêiner de toast logo após o gatilho ativo na ordem de tabulação do DOM.
  • Sem Armadilhas de Foco: Nunca prenda o foco do teclado dentro de uma fila de toasts. O usuário deve poder sair livremente do toast com Tab de volta ao conteúdo da página.
• Contraste (WCAG 2.2 SC 1.4.3):
  • Todo texto, ícones de status e botões devem atender aos mínimos de contraste em relação ao fundo do toast:
    • Texto normal: 4.5:1 de contraste mínimo.
    • Ícones e bordas de controles ativos: 3:1 de contraste mínimo.
• Responsividade:
  • Em viewports < 600px, o contêiner de toast deve abranger largura total (width: calc(100% - 32px)) com alinhamento horizontal centralizado para evitar colunas de margem estranhas.

---

Padrões Comuns de Falha

• A Armadilha da "Ação Ocluída": Colocar a fila de toasts desktop diretamente sobre elementos interativos de alta frequência, como o botão do cabeçalho do carrinho de compras ou um dropdown de filtro de tabela, fazendo com que os usuários cliquem em lugar errado.
• O Flash "Agora Você Vê, Agora Não Vê": Descartar automaticamente um erro ou aviso complexo e com várias palavras em 2-3 segundos. Isso viola os limites básicos de leitura de acessibilidade e causa pânico nos usuários que perderam o contexto.
• Silêncio do Leitor de Tela: Adicionar toasts dinamicamente ao DOM sem um wrapper de região ativa ARIA, tornando-os completamente invisíveis para usuários com deficiência visual.
• Instabilidade de Layout por Thrashing: Animar abruptamente a altura da fila de toasts na entrada, fazendo com que o conteúdo principal da página se desloque para cima e para baixo.
• Ignorância de Expiração por Hover/Foco: Deixar um toast se autodescartar enquanto um usuário está lendo com hover uma mensagem de texto densa ou passando o mouse sobre um CTA "Desfazer", fazendo com que eles cliquem em "ar morto" e acionem ações indesejadas.

---

Critérios de Validação

• Os toasts são estilizados com indicadores semânticos distintos e de alto contraste (cor + ícone único).
• No desktop, os toasts não se sobrepõem aos elementos de navegação primária ou zonas de ação global.
• No mobile, os toasts se transformam em componentes de largura total ancorados na parte inferior, facilmente alcançáveis pelo polegar.
• Os temporizadores ativos pausam instantaneamente quando o mouse passa sobre eles ou quando são focados pelo teclado.
• Toasts com ação permanecem visíveis por no mínimo 8–10 segundos; toasts de erro nunca são descartados automaticamente.
• A marcação semântica do leitor de tela (role="status" ou role="alert") é especificada corretamente.
• Usuários de teclado podem navegar até e acionar botões de ação do toast sem barreiras de armadilha de foco.
• Todos os elementos interativos (botão de fechar, CTAs) atendem ao alvo de toque mínimo WCAG 2.2 de 24x24px (44x44px preferível).