Communitygithub.com

coastdigitalgroup/coastai-skills

Projete e implemente uma central de notificações no aplicativo, centralizada, altamente acessível e com consciência de estado, para agregar atualizações do sistema, alertas do usuário e notificações acionáveis sem interromper os espaços de trabalho principais do usuário.

O que é coastai-skills?

Este skill fornece um framework de design estruturado e reutilizável para a criação de centrais de notificação in-app, feeds ou caixas de entrada. Em aplicações web modernas, especialmente em workspaces SaaS, portais comunitários e editores colaborativos, ele resolve o problema de notificações intrusivas (modais) ou transitórias (toasts) ao centralizar todas as atualizações assíncronas. O skill detalha a arquitetura completa: desde o design do ícone de disparo e emblema de contagem, passando pela escolha do layout (dropdown, gaveta lateral ou página dedicada), até a anatomia interna dos cartões de notificação e suas transições de estado (lido/não lido). Ele também inclui especificações rigorosas de acessibilidade (WCAG AA), como gerenciamento de foco de teclado, regiões âncoras para leitores de tela e tamanhos mínimos de alvos de toque, garantindo que a central seja utilizável por todos. O skill é ideal para plataformas que precisam gerenciar desde atualizações sociais e colaborativas até alertas de segurança e fluxos de trabalho assíncronos, oferecendo regras de decisão claras para escolher o padrão de layout mais adequado com base na densidade de conteúdo e interatividade necessária. Ele funciona como um guia de implementação para desenvolvedores front-end e designers de UX, definindo entradas (schema de notificação), saídas (especificações visuais e de interação) e um workflow detalhado em 6 etapas, com validação final através de critérios de aceitação.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/coastdigitalgroup/coastai-skills/tree/HEAD/website-design/notification-center-system

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Sistema de Central de Notificações

Propósito

O Sistema de Central de Notificações fornece um framework de design estruturado e reutilizável para centrais de notificação in-app, feeds ou caixas de entrada. Em aplicações web modernas, particularmente workspaces SaaS, portais comunitários, editores colaborativos e contas de e-commerce, as notificações mantêm os usuários atualizados sobre eventos assíncronos (ex.: menções, comentários, alertas do sistema, atualizações de status de workflow, conclusões de tarefas).

Sem uma central de notificações dedicada, as aplicações são forçadas a depender de sobreposições intrusivas (Modais) ou notificações transitórias e facilmente perdidas (Toasts/Banners). Este sistema centraliza essas atualizações, gerenciando sua hierarquia visual, estados interativos (lido vs. não lido), agrupamentos contextuais e adaptações responsivas, enquanto garante total acessibilidade por teclado e leitor de tela (WCAG AA).

Casos de Uso

  • Workspaces Colaborativos: Agregando comentários em documentos, pastas compartilhadas, atribuições de tarefas e menções (ex.: Slack, Notion, Figma).
  • Fluxos de Trabalho Assíncronos: Rastreando operações de longa duração como exportações de dados, relatórios em segundo plano, implantações de build ou processamento em lote.
  • Atualizações Transacionais: Rastreando atualizações de entrega de e-commerce, lembretes de renovação de assinatura ou confirmações de pagamento.
  • Feeds Sociais e Comunitários: Gerenciando curtidas, respostas, seguidores, convites para grupos e atualizações de atividades.
  • Segurança e Saúde da Conta: Informando os usuários sobre novos locais de login, alterações de senha ou avisos de cota de armazenamento.

Quando NÃO Usar

  • Bloqueios Críticos: Se um evento deve impedir o usuário de concluir sua tarefa atual (ex.: pagamento falhou, sessão expirou, envio de dados inválido), use um sistema-de-sobreposição-e-diálogo (Modal/Alertdialog).
  • Feedback Transitório de Tarefa Única: Para confirmação imediata de uma ação direta (ex.: "Link copiado", "Configurações salvas"), use um Toast (veja sistema-de-toast-e-snackbar).
  • Anúncios Globais de Indisponibilidade: Para alertas do sistema em todo o site e de alta prioridade (ex.: "Manutenção programada em 30 minutos"), use banners globais (veja sistema-de-banner-e-alerta).
  • Páginas de Destino de Conversão Independentes: Páginas de destino independentes devem minimizar links externos e distrações. Ícones de notificação globais são contraproducentes.

Entradas

  1. Arquitetura da Informação (Schema de Notificação):
    • Metadados: Avatar/iniciais do autor, fonte do evento, tipo de ação.
    • Conteúdo: Título (o que aconteceu), corpo do texto (detalhes/contexto adicionais), carimbo de data/hora.
    • Estado: Lido vs. não lido, prioridade alta/média/baixa, arquivado.
    • Ações: Link de destino principal, ações rápidas inline (ex.: "Aprovar", "Marcar como lido", "Silenciar tópico").
  2. Contexto de Exibição e Densidade: A interface é um dashboard SaaS altamente denso (precisa de itens de lista popover eficientes em espaço) ou uma plataforma espaçosa (pode utilizar uma gaveta deslizante ou página)?
  3. Iconografia do Gatilho: A âncora visual (geralmente um ícone de sino) e o design do emblema de notificação (contagens numéricas vs. um indicador de ponto simples).
  4. Layout de Ações Interativas: Ações em massa disponíveis (ex.: "Marcar todos como lidos", "Limpar tudo", "Configurações de notificação").

Saídas

  1. Anatomia do Emblema de Gatilho: Critérios de design específicos para o ícone do cabeçalho, contagem numérica do emblema e ponto indicador silencioso.
  2. Especificação do Layout do Contêiner: Dimensionamento, limites, posicionamento e comportamento do contêiner (Dropdown, Gaveta Lateral ou Página Dedicada).
  3. Anatomia do Cartão de Notificação: Layout interno explícito (avatar, corpo, carimbo de data/hora, ponto indicador de não lido, gatilhos de ação rápida).
  4. Matriz de Transição de Estado: Estilização distinta para estados lido vs. não lido, estados de foco, anéis de foco e skeletons de carregamento.
  5. Especificação de Teclado e Leitor de Tela: Parâmetros de foco retido, estrutura de tabindex móvel, definições de anúncios de região ativa e descrições aria personalizadas.

Workflow

1. Projete o Gatilho do Cabeçalho e o Indicador de Emblema

O ponto de entrada para a central de notificações está quase universalmente localizado no cabeçalho de utilitário global (lado direito).

  • O Ícone de Sino: Escolha um ícone de sino limpo.
  • O Emblema de Contagem de Não Lidos:
    • Coloque um emblema circular no quadrante superior direito do ícone de sino.
    • Limite a contagem do emblema a 99+ (ou 9+ em layouts extremamente apertados) para evitar estouro do contêiner.
    • Se a contagem for 0, o emblema deve ser removido do DOM ou ocultado usando display: none (nunca mostre 0 dentro de uma bolha vermelha).
    • Inclua um aria-label ou texto oculto do leitor de tela que declare explicitamente o número de notificações não lidas (ex.: <span class="sr-only">, 4 notificações não lidas</span>).

2. Escolha o Padrão de Layout do Contêiner

Selecione o layout com base na densidade, dispositivo alvo e quantidade de interação necessária:

  • Padrão A: Popover Dropdown (Padrão para desktop com densidade de conteúdo média)
    • Posicionado em relação ao gatilho.
    • Dimensões recomendadas: Largura mínima 320px, Largura máxima 420px. Altura restrita a 500px com um contêiner rolável (overflow-y: auto).
    • Ancore o popup usando mecânicas de popover padrão (ou API Popover nativa) para garantir que apareça no contexto de empilhamento superior.
  • Padrão B: Gaveta Lateral (Melhor para alta densidade de conteúdo ou fluxos de ação complexos)
    • Desliza da borda direita da tela, ocupando a altura total da janela de visualização.
    • Largura recomendada: 360px a 480px.
    • Escureça o fundo da página com uma sobreposição de fundo sutil (scrim).
  • Padrão C: Página de Notificação Dedicada (Fallback para viewports móveis ou gerenciamento complexo de caixa de entrada)
    • Uma visualização em tela cheia adequada para classificar, pesquisar, filtrar e gerenciar em massa arquivos profundos de notificações.

3. Estabeleça a Hierarquia e Anatomia Interna do Cartão

Cada notificação individual é um cartão (um item de lista <li> dentro de um <ol> ou <ul>). Deve seguir uma hierarquia de grade vertical e horizontal estrita:

+-------------------------------------------------------------+
| (•) [Avatar]  **João Silva** mencionou você em _Projeto X_  (x) |
|               "Por favor, revise os esboços de UI revisados."      |
|               [ há 3 horas ]  [ Aprovar ] [ Recusar ]      |
+-------------------------------------------------------------+
  • Ponto Indicador de Não Lido (Âncora Horizontal): Coloque um ponto pequeno, de alto contraste, na cor primária (ex.: azul ou roxo) na extremidade esquerda. Esta é a âncora de varredura mais rápida para itens não lidos.
  • Área do Avatar/Ícone: Coloque um avatar circular (para eventos gerados pelo usuário) ou um ícone de utilitário categorizado dentro de um fundo colorido (para eventos do sistema) próximo ao indicador.
  • Bloco de Texto (Fluxo Vertical):
    • Título/Cabeçalho: Texto em negrito destacando o ator e a ação.
    • Trecho: Texto menor e suave mostrando conteúdo secundário (ex.: texto do comentário, descrição do erro). Limite a 2 linhas de texto no máximo com CSS line-clamp.
    • Carimbo de Data/Hora: Texto pequeno e suave (ex.: 12px) mostrando a hora relativa (ex.: "há 5m", "Ontem").
  • Ações Rápidas (Gatilhos Contextuais):
    • Coloque botões de ação rápida alinhados abaixo do trecho de texto (ex.: "Aceitar Convite", "Ver Comentário").
    • Forneça um gatilho secundário sutil (ex.: um botão de menu de estouro ou um botão de marca de seleção "Marcar como lido" direto) ao passar o mouse/ao focar no canto direito.
    • O ícone de fechar/dispensar (X) deve ser posicionado no canto superior direito, medindo pelo menos 24x24px para interações de toque.

4. Crie Transições de Estado Claras

Forneça estados distintos para refletir a interação do usuário:

  • Estado Não Lido: Fundo claro, texto em negrito, ponto indicador azul visível.
  • Estado Lido: Desvanece o fundo de não lido, altera o peso do texto para normal, oculta o ponto indicador.
  • Estado de Passar o Mouse/Foco: Muda a cor de fundo ligeiramente (ex.: de branco para um cinza neutro suave) e revela gatilhos secundários inline (ex.: "Arquivar", "Marcar como lido").
  • Estado Focado: Anéis de foco de alto contraste ao redor de itens individuais quando navegados pelo teclado. Mantenha o foco visível e nítido (mínimo de contorno de 2px com deslocamento).
  • Estado Desabilitado: Se um cartão de ação está sendo processado (ex.: clicando em "Aprovar"), aplique um spinner de carregamento inline, diminua a opacidade para 0.5 e defina os atributos do botão como disabled para evitar cliques duplos.

5. Defina Operações em Massa e Estados Vazios

  • Navegação no Rodapé: Sempre forneça um link de rodapé para "Ver todas as notificações" (liga para uma página dedicada) ou "Marcar todos como lidos."
  • Estado Vazio: Quando nenhuma notificação estiver presente, ou quando todas as notificações forem limpas, exiba um estado vazio contendo um visual encorajador (ex.: uma marca de seleção ou sino), um cabeçalho neutro ("Tudo em dia!") e um link descritivo secundário para "Configurações de Notificação" (veja sistema-de-estado-vazio).

6. Implemente Gerenciamento de Foco de Teclado e Leitor de Tela

  • Alternância do Gatilho: Pressionar Enter ou Espaço no ícone de sino alterna o popover. Aplique aria-expanded="true/false" e aria-controls="id-do-painel-de-notificacao".
  • Foco Retido (para Gavetas e Popovers): Quando aberto, o foco do teclado deve se mover imediatamente para o primeiro elemento acionável dentro do painel (geralmente o botão "Marcar todos como lidos" ou o primeiro item de notificação). O foco deve ser retido dentro do painel enquanto estiver visível. Pressionar Escape deve fechar o painel e retornar o foco diretamente para o ícone de Sino.
  • Tabindex Móvel / Navegação por Lista: Se houver dezenas de itens de notificação, permita que usuários de teclado naveguem entre os cartões usando as teclas Seta para Cima e Seta para Baixo, mantendo um único ponto de tabulação (tabindex="0" para o item ativo, tabindex="-1" para os outros). Isso evita forçar usuários de teclado a percorrerem 50 links com Tab para chegar ao final da página.
  • Anúncios do Leitor de Tela: Use uma região oculta aria-live="polite" para anunciar atualizações na contagem de não lidos quando elas ocorrerem dinamicamente (ex.: "Nova notificação de Sarah").

Regras de Decisão

Regra 1: Dropdown vs. Gaveta Lateral vs. Página

Escolha a estrutura do contêiner usando esta grade de layout:

  • Escolha Popover Dropdown se: O aplicativo tem em média menos de 10-15 notificações, contém principalmente atualizações curtas e as ações são simples (como um link direto ou dispensa rápida).
  • Escolha Gaveta Lateral se: O painel de notificação inclui abas interativas (ex.: "Todas", "Menções", "Arquivo"), requer resumos de cartão de várias linhas ricos ou requer campos de formulário complexos (como entrada de texto para responder diretamente dentro da notificação).
  • Escolha Página Dedicada se: O usuário está gerenciando cargas de trabalho pesadas de notificação (ex.: caixa de entrada de revisão de PR do GitHub, tickets de suporte do Zendesk, alertas de loja Shopify) que exigem filtros de pesquisa robustos, seleções múltiplas com marca de seleção e fluxos de trabalho de arquivamento em massa.

Regra 2: Indicadores de Avatar vs. Ícone

  • Use um Avatar de Usuário (imagem ou iniciais) se a notificação for um evento social ou de colaboração direta acionado por um humano específico (ex.: "Sarah compartilhou um arquivo").
  • Use um Ícone do Sistema (com cores específicas de status: vermelho para alerta, amarelo para aviso, azul para informação) se o evento for gerado pelo sistema (ex.: "Backup do banco de dados concluído").

Regra 3: Comportamento da Ação Marcar como Lido

  • Clicar no cartão de notificação deve tanto redirecionar o usuário para o link de destino profundo quanto marcar o item como lido.
  • Forneça um ícone de marca de seleção "Marcar como lido" dedicado e visível no cartão, permitindo que os usuários marquem itens como lidos sem navegar para fora do painel.

Restrições

1. Contraste e Dimensionamento (WCAG AA)

  • Contraste de Texto: Garanta que toda a cópia da notificação atenda à taxa de contraste 4.5:1. Carimbos de data/hora e trechos suaves não devem cair abaixo de 4.5:1 (ou 3:1 para texto grande).
  • Alvos de Toque: Os alvos de toque para botões individuais (ícones de fechar, links de aceitar/recusar, marcas de seleção de marcar como lido) devem atender ao tamanho mínimo de destino da WCAG 2.2 SC 2.5.8 de 24x24px.
  • Contraste do Teclado: Os anéis de foco devem ter uma taxa de contraste mínima de 3:1 em relação ao fundo do cartão.

2. Responsividade

  • Desktop: Os painéis flutuantes devem se posicionar de forma inteligente. Se o gatilho estiver perto da borda direita da tela, o popover deve se alinhar ao seu lado direito para evitar corte.
  • Viewports Móveis (< 768px): Transforme o popover dropdown do desktop em um Painel em Tela Cheia ou em uma Folha Deslizante Alinhada na Parte Inferior para garantir acessibilidade ao alcance do polegar e evitar contêineres popover pequenos e não roláveis.

3. Empilhamento Dinâmico

  • Garanta que o z-index do popover ou gaveta esteja configurado acima dos elementos de layout padrão, mas abaixo dos gatilhos modais (ex.: --z-index-popover: 1000, --z-index-modal: 2000).

Padrões Comuns de Falha

  • A "Caixa de Entrada Inescapável": Abrir um popover dropdown de notificação no desktop, mas não fornecer um listener de tecla Escape para fechar. Os usuários são forçados a encontrar e clicar em um pequeno "X" ou clicar fora para dispensar.
  • O Loop do "Emblema Travado": Um emblema de notificação mostrando 3 itens não lidos, mas abrir o painel não destaca visualmente quais cartões estão não lidos, nem fornece uma maneira clara de marcá-los como lidos. O emblema permanece travado, causando fadiga no usuário e eventual cegueira de banner.
  • O Feed "Pia da Cozinha": Enfiar parágrafos completos de e-mails, logs brutos de banco de dados e promoções de marketing em um pequeno painel dropdown, causando estouro de layout e esmagando a hierarquia visual.
  • Mudança de Layout ao Rolar: Popovers estilizados com coordenadas de pixel estáticas que falham em permanecer presas ao ícone de sino do cabeçalho ao rolar, flutuando aleatoriamente sobre o conteúdo.
  • Contornos de Foco Duplos: Estilo de foco de camada dupla onde tanto o cartão contêiner externo quanto o botão de link interno profundo capturam o foco simultaneamente, exigindo que usuários de teclado pressionem Tab duas vezes por notificação.

Critérios de Validação

  • Comportamento da Contagem do Emblema: Se a contagem de não lidos for 0, o ponto vermelho ou indicador numérico está completamente oculto da visualização.
  • Contraste de Estado: Os cartões não lidos são claramente distinguidos visualmente dos cartões lidos (usando fundos, peso do texto e pontos indicadores).
  • Tamanhos dos Alvos: Cada botão/link clicável dentro do cartão atende ao mínimo de destino de toque de 24x24px da WCAG 2.2.
  • Transformação Responsiva: Em viewport móvel, o painel muda do posicionamento popover flutuante para um layout de sobreposição em tela cheia ou folha inferior.
  • Navegação por Teclado: Pressionar Tab move o foco para o primeiro elemento no painel, Seta para Baixo e Seta para Cima navegam por notificações individuais, e Escape fecha o painel e retorna o foco ao ícone de sino.
  • Anúncios de Leitor de Tela: Quando o conteúdo do painel muda ou novas notificações chegam, a região aria-live anuncia a alteração sem interromper a tarefa atual do usuário.

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for progressive disclosure using accordions, ensuring structural integrity, visual affordances, and accessibility across different content densities and devices.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for long-form content, managing readability, vertical rhythm, and information density to ensure a superior reading experience.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for informational elements that communicate state (Badges) and categorization (Tags) with clarity and accessibility.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for non-overlay notifications, managing global announcements and contextual inline alerts to communicate system states without interrupting the user's flow.

coastdigitalgroup/coastai-skills

Design and implement a systematic, asymmetrical bento-grid layout framework to organize diverse content types cohesively while maintaining strict visual hierarchy, logical focus order, and responsive flexibility.

coastdigitalgroup/coastai-skills

Design a responsive, mobile-first bottom navigation bar and persistent action dock system for mobile websites and web applications, establishing spatial anchors, tab bar anatomy, badge indicators, thumb-zone ergonomics, safe area inset handling, active/inactive state contrast, and desktop responsive adaptation rules.

coastdigitalgroup/coastai-skills

Design a mobile-first bottom sheet overlay system with configurable detents, drag affordances, safe area padding, responsive desktop modal/popover adaptation, and WCAG AA accessibility compliance.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for secondary navigation trails that provide orientation, context, and one-click access to parent levels in deep information architectures.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for buttons and interactive triggers, managing visual hierarchy, variant logic, and action grouping to ensure clear intent and accessible interaction.

coastdigitalgroup/coastai-skills

Design a systematic framework for date and time selection, managing calendar grids, range pickers, and scheduling interfaces to ensure precision and accessibility.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for modular content containers that maintain hierarchy, structural integrity, and action alignment across variable content and responsive viewports.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for horizontal discovery components, managing navigation affordances, scroll behavior, and accessibility to ensure effective content density without compromising usability.

coastdigitalgroup/coastai-skills

Design a systematic, highly accessible, and developer-friendly UI layout framework for code blocks, snippet showcases, multi-file code tabs, line-highlighting, diff views, and syntax token contrast in technical documentation and developer platforms.

coastdigitalgroup/coastai-skills

Design a systematic framework for global command menus (Cmd+K panels) that combines keyboard-driven navigation, command execution, and shortcut discovery into an accessible, responsive overlay.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for threaded conversations, managing nesting depths, action hierarchies, and community signaling to foster engagement and readability.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for side-by-side comparison interfaces, managing high attribute density and responsive complexity to support informed decision-making.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for user privacy, managing consent banners, preference centers, and persistent privacy controls to balance legal compliance with user trust.

coastdigitalgroup/coastai-skills

Design and implement a systematic, highly accessible, and responsive visual layout framework for conversational chat widgets, live chat boxes, and chatbot panels that ensures clear message scannability, native focus flow, and seamless mobile keyboard adaptation.

coastdigitalgroup/coastai-skills

Design a systematic, accessible, and high-conversion framework for custom select dropdowns and comboboxes, defining anatomy, states, search-filtering, and responsive mobile-adaptive patterns.

coastdigitalgroup/coastai-skills

Design and implement a systematic color palette that ensures WCAG 2.2 accessibility compliance. Trigger this skill when asked to define brand colors, create UI themes, or establish a visual system for a website.

Habilidades Relacionadas