coastdigitalgroup/coastai-skills - Sistema de Erros e Status

Sistema de Erros e Status

Propósito

O Sistema de Erros e Status fornece uma metodologia para projetar os "caminhos infelizes" de um site — os momentos em que algo dá errado em nível de sistema. Diferente de validações em nível de formulário ou banners contextuais, este sistema lida com estados de página inteira ou de todo o site. Ele garante que as falhas sejam comunicadas com clareza, empatia e um "caminho de saída" claro, evitando frustração e abandono do usuário durante problemas técnicos.

Casos de Uso

• 404 Não Encontrado: Quando um usuário navega para uma URL que não existe.
• 500 Erro de Servidor: Quando uma falha crítica no backend impede o carregamento de uma página.
• Modo de Manutenção: Quando um site é intencionalmente colocado offline para atualizações.
• Estados Offline: Quando um usuário perde a conectividade em uma aplicação web.
• Acesso Negado (403): Quando um usuário não tem permissão para visualizar um recurso específico.

Quando NÃO Usar

• Validação de Formulário: Use form-design-system para erros em nível de campo.
• Notificações Contextuais: Use banner-and-alert-system para atualizações não bloqueantes ou erros menores.
• Listas Vazias: Use empty-state-system quando uma página carrega corretamente mas não contém dados.
• Estados de Carregamento: Use skeleton-state-system para obtenção padrão de conteúdo.

Entradas

1. Tipo de Erro: É um erro de cliente (4xx), erro de servidor (5xx) ou estado do sistema (Manutenção)?
2. Contexto Técnico: O sistema consegue explicar por que falhou sem vazar dados sensíveis?
3. Caminhos de Recuperação: Quais são os prováveis próximos passos para o usuário?
4. Tom da Marca: A voz da marca é humorística, profissional ou estritamente técnica?
5. Restrições do Sistema: O estado offline precisa suportar ações específicas de primeiro local?

Saídas

1. Anatomia da Página de Status: Um layout definido para a mensagem de erro, âncora visual e ações de recuperação.
2. Hierarquia de Mensagens: Padrões para o título (o que aconteceu) e descrição (o que fazer a seguir).
3. Blueprint de Recuperação: Um mapa de links, campos de pesquisa ou recursos de ajuda adaptados ao erro específico.
4. Especificação de UI Offline: Regras de como a interface muda quando a conectividade é perdida.

Fluxo de Trabalho

1. Categorizar a Gravidade da Falha

Determine o impacto do erro:

• Baixo (404/403): Localizado a uma URL. O site está saudável. Foco em Redirecionamento.
• Alto (500): Abrangente ou quebra de página. O site está com dificuldades. Foco em Reasseguramento e Suporte.
• Sistêmico (Manutenção): Indisponibilidade intencional. Foco em Gestão de Expectativa (ex.: "De volta às 14h").
• Conectividade (Offline): Falha ambiental. Foco em Preservação de Estado (ex.: "Alterações salvas localmente").

2. Estabelecer o Caminho de Recuperação

Toda página de erro deve ter uma "Saída":

• O Botão "Início": O requisito mínimo absoluto.
• Sugestões Inteligentes: Para 404s, forneça links para páginas populares ou uma barra de pesquisa.
• O Gatilho "Atualizar": Para erros 5xx, forneça uma maneira proeminente de tentar a requisição novamente.
• Links de Suporte: Para problemas persistentes, forneça um caminho direto para uma central de ajuda ou página de status.

3. Projetar a Anatomia Visual

Aplique visual-hierarchy-system à visualização de erro:

• Âncora Visual: Use uma ilustração ou ícone alinhado à marca para suavizar o impacto da falha.
• Título Claro: Use um título "humano" (ex.: "Não encontramos essa página") em vez de apenas o código de status ("Erro 404").
• Metadados Sutis: Mantenha códigos técnicos (ex.: ID do Erro: 12345) pequenos e com baixo contraste, destinados às equipes de suporte em vez do usuário.

4. Aplicar a Regra de Mensagem "Humano em Primeiro Lugar"

Evite jargão técnico que afasta os usuários:

• Ruim: "500 Erro Interno do Servidor: Conexão redefinida pelo par."
• Bom: "Algo deu errado de nosso lado. Estamos trabalhando para consertar agora."
• Ruim: "404 Recurso não localizado."
• Bom: "Parece que esta página tomou um rumo errado."

5. Planejar a Adaptação Responsiva

• Página Inteira vs. Modal: Decida se o erro deve ocupar todo o viewport (padrão para 404/500) ou aparecer como um banner fixo (comum para estados Offline).
• Layout Centralizado: Centralizar o conteúdo é geralmente melhor para páginas de erro, pois minimiza o esforço de varredura e enfatiza a "Pausa" na jornada do usuário.

Regras de Decisão

• A Regra do "Caminho Direto": Nunca deixe uma página de erro ser um beco sem saída. Se não houver sugestões específicas, sempre inclua uma opção "Voltar ao Início" e "Pesquisar".
• Pesquisa-no-404: Se um site tiver >100 páginas, a página 404 DEVE incluir uma barra de pesquisa.
• Transparência na Manutenção: Se estiver em modo de manutenção, sempre forneça uma hora estimada de retorno ou um link para uma página de status.
• Persistência Offline: Quando offline, "acinzentar" visualmente ou desabilitar ações não funcionais (ex.: botões "Enviar") para evitar perda de dados.

Restrições

• Acessibilidade: As páginas de erro devem manter a navegação global e o rodapé do site (quando possível) para fornecer orientação familiar. Para mudanças dinâmicas de status (como ficar offline), use uma região aria-live="assertive" para anunciar a mudança imediatamente.
• Responsividade: As páginas de erro devem ser tão resilientes quanto possível. Evite ativos pesados que possam falhar ao carregar se o sistema já estiver com dificuldades.
• Marca: As páginas de erro devem parecer parte do site, não uma página genérica de navegador ou padrão do servidor.

Padrões Comuns de Falha

• O "Beco Sem Saída": Uma página 404 sem links, forçando o usuário a usar o botão "voltar" do navegador ou sair.
• A "Parede de Jargão": Exibir rastreamentos de pilha brutos ou erros de banco de dados que confundem os usuários e potencialmente vazam informações de segurança.
• O "Jogo da Culpa": Mensagens que implicam que o usuário fez algo errado (ex.: "Você digitou uma URL inválida") em vez de assumir a responsabilidade pela falha de descoberta.
• Incompatibilidade de Estilo: Uma página de erro que usa fontes/cores diferentes do resto do site, fazendo parecer quebrada ou maliciosa.

Critérios de Validação

• Todo estado de erro (404, 500, etc.) tem um título claro e legível por humanos.
• Pelo menos uma ação de recuperação primária (ex.: "Voltar ao Início") está presente.
• Para páginas 404, uma barra de pesquisa ou links populares são fornecidos para descoberta.
• Metadados técnicos (IDs de Erro) estão presentes mas subordinados na hierarquia.
• Mudanças de conectividade (Offline) são anunciadas por meio de regiões ARIA live.
• O estilo visual permanece consistente com o núcleo da marca/sistema de design.
• Páginas de manutenção fornecem um link "Retorno Esperado" ou "Página de Status".