Communitygithub.com

coastdigitalgroup/coastai-skills

Projete um framework sistemático para camadas de interface não persistentes (Modais, Drawers e Popovers) que equilibre foco do usuário, contexto e níveis de interrupção.

O que é coastai-skills?

Esta skill fornece uma metodologia completa para gerenciar camadas de conteúdo temporário que ficam acima da interface principal, como modais, drawers e popovers. Ela ajuda a garantir que as interrupções sejam proporcionais à tarefa do usuário, o contexto seja preservado quando possível e a interface permaneça acessível e responsiva. A skill define um fluxo de trabalho claro para categorizar o overlay por nível de interrupção (Alto: Modal, Médio: Drawer, Baixo: Popover), especificar sua anatomia (cabeçalho, corpo, rodapé), estabelecer elevação e backdrop (com recomendação do elemento nativo `<dialog>`), projetar adaptação responsiva (como Popover virar Drawer em mobile) e definir padrões de fechamento e saída. Também inclui regras de decisão práticas (como a regra 'Modal vs. Drawer' e a 'Regra do Polegar' para mobile), restrições de acessibilidade (foco gerenciado, fundo `inert`) e critérios de validação para evitar padrões de falha comuns, como 'sopa de overlays' ou perda de contexto.

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

Perguntar na sua IA favorita

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

Documentação

Sistema de Overlays e Diálogos

Propósito

A skill Sistema de Overlays e Diálogos fornece uma metodologia para gerenciar camadas temporárias de conteúdo que ficam acima da interface principal. Ela garante que as interrupções sejam proporcionais à tarefa do usuário, o contexto seja preservado onde possível e a interface permaneça acessível e responsiva ao usar Modais, Drawers ou Popovers.

Casos de Uso

  • Projetar um fluxo de confirmação para uma ação destrutiva (Modal).
  • Criar um espaço de trabalho secundário para editar detalhes complexos sem perder o contexto da página (Drawer).
  • Implementar ajuda contextual ou dicas para elementos específicos da interface (Popover).
  • Projetar uma camada de descoberta específica para mobile, como filtros ou pesquisa (Drawer).

Quando NÃO Usar

  • Navegação Principal: Não use overlays para a estrutura principal do site; use site-navigation-system.
  • Conteúdo Persistente: Se a informação é crítica para o usuário ver o tempo todo, ela deve fazer parte do layout base da página, não de um overlay.
  • Fluxos Complexos de Múltiplas Páginas: Se uma tarefa exigir mais de 2-3 passos, considere uma página dedicada em vez de um modal para evitar a desorientação do usuário.
  • Notificações Toast/Snackbar: Para feedback de status passivo e não bloqueante (ex.: "Salvo", "Copiado para a área de transferência"), use toast-and-snackbar-system — ele cobre posicionamento, empilhamento, duração e acessibilidade para essa camada em profundidade.

Entradas

  1. Volume de Conteúdo: Quanta informação precisa ser exibida?
  2. Nível de Interrupção: O usuário deve terminar esta tarefa antes de continuar, ou ela é opcional?
  3. Contexto de Gatilho: De onde o usuário está vindo e o que ele espera que aconteça?
  4. Plataforma/Viewport: É para mobile, desktop ou um híbrido responsivo?

Saídas

  1. Seleção de Padrão: Uma escolha clara entre Modal, Drawer ou Popover com base na matriz de interrupção.
  2. Especificação de Anatomia: Regiões definidas (Cabeçalho, Conteúdo, Rodapé/Ações) e sua hierarquia interna.
  3. Especificação Comportamental: Regras para comportamento do backdrop, gatilhos de fechamento e adaptação responsiva.
  4. Requisitos de Acessibilidade: Gerenciamento de foco e definições de funções ARIA.

Fluxo de Trabalho

1. Categorizar por Nível de Interrupção

Determine a "gravidade" necessária do overlay:

  • Nível 1 (Alto): Modal. Desabilita o fundo. Use para decisões críticas ou tarefas focadas.
  • Nível 2 (Médio): Drawer. Desliza pela borda. Use para subtarefas complexas que se beneficiam de ver o contexto pai.
  • Nível 3 (Baixo): Popover. Ancora a um elemento específico. Use para configurações ou informações contextuais.

Para feedback de status passivo e não bloqueante (Nível 4), consulte toast-and-snackbar-system — está fora do escopo aqui.

2. Definir a Hierarquia Interna (Anatomia)

Aplique visual-hierarchy-system ao overlay:

  • Cabeçalho: Título claro e um mecanismo de "Fechar" consistente (botão X).
  • Corpo: A área de conteúdo principal. Se o conteúdo for longo, defina o comportamento de rolagem (cabeçalho/rodapé fixo).
  • Rodapé: Ações primárias e secundárias, alinhadas consistentemente (geralmente alinhado à direita para desktop, largura total para mobile).

3. Estabelecer Elevação e Backdrop

  • Estratégia de Z-Index: Garanta que os overlays estejam no contexto de empilhamento correto. Prefira o elemento nativo <dialog> para Modais — ele gerencia seu próprio empilhamento de camada superior, fornece o pseudo-elemento ::backdrop para o scrim, e lida com Escape para fechar nativamente.
  • Backdrop (Scrim): Use para Modais e Drawers para escurecer o fundo e focar a atenção. Defina se clicar no backdrop fecha o overlay. Com <dialog>, estilize o scrim via ::backdrop em vez de uma <div> overlay renderizada manualmente.
  • Inércia do Fundo: Quando um overlay estiver aberto, o resto da página deve ser não interativo e oculto da tecnologia assistiva. <dialog>.showModal() faz isso automaticamente; para overlays personalizados (não-<dialog>), aplique o atributo inert ao conteúdo de fundo em vez de depender apenas de aria-hidden.
  • Sombras: Use profundidade para indicar a posição do overlay acima da camada base.

4. Projetar para Adaptação Responsiva

Os overlays devem se transformar com base no tamanho da tela:

  • Popover Desktop -> Drawer Mobile: Menus contextuais pequenos frequentemente se tornam drawers alinhados à parte inferior no mobile para melhor alcance do polegar.
  • Modal Desktop -> Tela Cheia Mobile: Modais grandes devem ocupar a viewport completa em telas pequenas para maximizar o espaço.
  • Comportamento do Drawer: Garanta que os drawers não excedam 90% da largura da viewport no mobile.

5. Definir Padrões de Fechamento e Saída

  • Forneça pelo menos três maneiras de sair de um overlay não crítico: botão "Fechar", tecla Escape e clicar no backdrop.
  • Para modais críticos (alerta), exija uma ação explícita (ex.: "Cancelar" ou "Confirmar").

Regras de Decisão

  • A Regra "Modal vs. Drawer": Se o usuário precisar consultar o conteúdo de fundo enquanto trabalha, use um Drawer. Se a tarefa for um momento de "pare e corrija", use um Modal.
  • A "Regra do Polegar": No mobile, priorize Drawers Inferiores para ações, mantendo-os dentro do alcance natural do polegar.
  • A "Regra dos Dois Passos": Se um overlay exigir mais de duas "visualizações" ou passos internos, provavelmente pertence a uma página própria.
  • Lógica do Backdrop: Permita "Clique fora para fechar" apenas para overlays não destrutivos. Nunca para formulários onde os dados possam ser perdidos.

Restrições

  • Acessibilidade: Deve ser navegável por teclado. Modais devem prender o foco (o elemento nativo <dialog> faz isso por padrão quando aberto via showModal()). O conteúdo de fundo deve ser tornado inert (ou equivalente) para que o foco do leitor de tela e do teclado não possa escapar para ele. Use role="dialog" ou role="alertdialog" com aria-modal="true" e aria-labelledby apontando para o título quando não estiver usando o elemento nativo.
  • Responsividade: Overlays nunca devem causar rolagem horizontal. O conteúdo interno deve ser responsivo.
  • Hierarquia: O H1/Título do overlay deve ser o elemento mais proeminente dentro do contêiner.

Padrões de Falha Comuns

  • Sopa de Overlays: Empilhar vários modais uns sobre os outros.
  • Perda de Contexto: Usar um modal que cobre exatamente a informação que o usuário precisa para completar a tarefa.
  • O "Fechar Invisível": Ocultar o botão de fechar ou torná-lo muito pequeno para toque (mínimo 44x44px).
  • Conflitos de Rolagem: Permitir que a página de fundo role enquanto um overlay está aberto (leva à desorientação).
  • Ações Inconsistentes: Trocar a posição dos botões "Cancelar" e "Confirmar" em diferentes overlays.

Critérios de Validação

  • O padrão escolhido (Modal/Drawer/Popover) corresponde ao nível de interrupção da tarefa.
  • A hierarquia interna é clara com um Título e uma Ação Primária distintos.
  • A adaptação responsiva (ex.: Popover para Drawer) está definida para mobile.
  • A lógica "Clique fora para fechar" é apropriada para o risco dos dados.
  • O gerenciamento de foco e os requisitos de acessibilidade do teclado estão especificados.
  • A elevação (sombras/backdrops) distingue a camada da página base.
  • O conteúdo de fundo é tornado inert (ou o elemento nativo <dialog> é usado) sempre que um Modal ou Drawer estiver aberto.

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