coastdigitalgroup/coastai-skills

Sistema de Banner e Alerta

Propósito

O Sistema de Banner e Alerta fornece uma metodologia para projetar camadas de comunicação não persistentes e sem sobreposição. Diferente de modais que param o usuário, banners e alertas fornecem informações críticas (atualizações de status, avisos ou anúncios) enquanto permitem que o usuário continue sua tarefa atual. Este sistema garante que as notificações sejam visualmente distintas, apropriadamente priorizadas e acessíveis.

Casos de Uso

• Comunicar anúncios em todo o site (ex.: "Manutenção programada em 2 horas").
• Fornecer feedback contextual dentro de um formulário (ex.: "Alterações salvas com sucesso").
• Avisar usuários sobre problemas na conta (ex.: "Assinatura expira em 3 dias").
• Notificar usuários sobre erros sistêmicos que não bloqueiam todo o aplicativo, mas afetam a funcionalidade (ex.: "Sincronização bancária está indisponível no momento").
• Exibir "Banners de Marketing" para promoções ou lançamentos de novos recursos.

Quando NÃO Usar

• Bloqueios Críticos: Se o usuário deve agir antes de prosseguir, use overlay-and-dialog-system (Modal).
• Feedback Passivo: Para atualizações de status curtas e de baixa prioridade (ex.: "Link copiado"), use Toasts (veja overlay-and-dialog-system).
• Rótulos de Dados: Para indicadores de status simples em um único item, use badge-and-tag-system.
• Navegação: Não use banners para links de navegação primária ou secundária; use site-navigation-system.

Entradas

1. Gravidade da Mensagem: É uma mensagem de Erro, Aviso, Sucesso ou Informação?
2. Escopo: É Global (todo o site) ou Embutido (específico de uma seção/página)?
3. Capacidade de Dispensar: O usuário pode ocultar esta mensagem, ou ela deve permanecer visível?
4. Exigência de Ação: A mensagem requer uma ação de acompanhamento (ex.: "Atualizar Faturamento")?
5. Paleta da Marca: Cores padrão para estados de status (Vermelho de Perigo, Âmbar de Aviso, etc.).

Saídas

1. Especificação de Anatomia do Alerta: Definição do ícone, hierarquia de texto e posicionamento da ação.
2. Lógica Espacial: Regras para onde os banners aparecem (Topo da viewport, Acima do conteúdo ou Dentro de uma seção).
3. Matriz de Estados: Tratamentos visuais para diferentes gravidades de mensagem.
4. Plano de Acessibilidade: Papéis ARIA e regras de gerenciamento de foco para alertas interativos.

Fluxo de Trabalho

1. Determine o Nível do Alerta (Gravidade)

Atribua um estado com base na intenção:

• Erro (Alta Prioridade): Problemas críticos que exigem atenção, mas não quebram a visualização.
• Aviso (Prioridade Média): Problemas potenciais ou prazos futuros.
• Sucesso (Baixa Prioridade): Confirmação de uma ação concluída.
• Informação/Anúncio: Informações neutras ou atualizações de marketing.

2. Escolha o Padrão de Posicionamento

• Banner Global (Barra Superior): Fica no topo da viewport. Melhor para anúncios de alta prioridade em todo o site.
• Banner de Página: Fica abaixo do cabeçalho global, mas acima do conteúdo da página. Melhor para notificações específicas de página.
• Alerta Embutido: Fica diretamente dentro de uma seção ou ao lado de um componente relevante (ex.: dentro de um formulário). Melhor para feedback contextual.

3. Projete a Anatomia do Componente

Cada alerta deve seguir uma hierarquia interna consistente:

• Ícone: Uma abreviação visual da gravidade (ex.: marca de verificação para sucesso).
• Título (Opcional): Um cabeçalho em negrito para alertas mais longos.
• Descrição: A mensagem principal. Mantenha-a concisa.
• Ação: Um botão ou link para o próximo passo.
• Gatilho de Dispensar: Um botão 'X' se o alerta não for crítico.

4. Estabeleça Regras de Interação

• Persistência: Determine se o alerta desaparece após uma ação, após um tempo limite (não recomendado para banners), ou apenas quando dispensado manualmente.
• Gerenciamento de Mudança de Layout: Garanta que banners ao aparecer não causem mudanças bruscas de layout (CLS). Use espaço reservado ou transições suaves.

5. Defina o Comportamento Responsivo

• Empilhamento: Em dispositivos móveis, as ações devem se mover para baixo do texto se não couberem horizontalmente.
• Largura: Banners globais têm largura total; alertas embutidos seguem a largura do contêiner.

Regras de Decisão

• A Regra "Um de Cada Vez": Nunca empilhe mais de dois banners globais. Se você tiver vários anúncios, consolide-os em uma "Central de Notificações" ou um carrossel.
• Cor + Ícone: Nunca confie apenas na cor para comunicar o estado do alerta. Sempre inclua um ícone para acessibilidade.
• Posicionamento por Contexto: Se o alerta for causado por uma ação do usuário (ex.: clicar em "Salvar"), coloque o alerta perto do ponto de ação (Embutido). Se for um estado do sistema, coloque-o no topo (Global).
• Lógica de Dispensar: Sempre permita que os usuários dispensem banners "Informação" e "Sucesso". Banners "Erro" e "Aviso" só devem ser dispensados se o problema subjacente for resolvido.

Restrições

• Acessibilidade: Use role="alert" para erros de alta prioridade e role="status" para atualizações de menor prioridade. Garanta uma taxa de contraste de 4.5:1 para texto. Se um banner global for fixo/sticky, verifique se ele nunca obscurece permanentemente um elemento focado conforme o conteúdo rola (WCAG 2.2 SC 2.4.11).
• Tipografia: Use um tamanho de fonte claro (mín. 14px) e evite CAIXA ALTA para descrições longas.
• Alcance em Dispositivos Móveis: Garanta que os botões de dispensar atendam ao mínimo de 24x24px do WCAG 2.2 SC 2.5.8, aumentados para 44x44px onde o layout permitir.

Padrões Comuns de Falha

• O "Erro Ignorável": Usar estilo "Informação" para um erro crítico, fazendo com que o usuário perca avisos importantes.
• Marketing Intrusivo: Usar banners globais para promoções de baixo valor que irritam os usuários e desvalorizam o espaço de "Alerta".
• Ações Ausentes: Dizer ao usuário que algo está errado (ex.: "Pagamento falhou") sem fornecer um link direto para corrigir.
• Travamento de Layout: Banners que "aparecem" e empurram todo o conteúdo da página para baixo, fazendo com que os usuários cliquem no lugar errado.

Critérios de Validação

• Cada alerta usa uma combinação de ícone e cor que corresponde à sua gravidade.
• Banners globais são posicionados no topo da hierarquia.
• Alertas embutidos são colocados próximos ao seu conteúdo relacionado.
• Todos os elementos interativos (Fechar, CTA) atendem ao alvo de toque mínimo de 24x24px do WCAG 2.2 (2.5.8).
• Alertas de alta prioridade usam papéis ARIA apropriados (alert).
• Banners dispensáveis lembram seu estado (ou têm uma lógica para quando reaparecer).