coastdigitalgroup/coastai-skills

Sistema de Dropdown e Menu

Propósito

A skill Sistema de Dropdown e Menu fornece uma estrutura padronizada para projetar menus de ação flutuantes, menus de overflow, menus contextuais e submenus em cascata em interfaces web. Menus dropdown exibem uma lista organizada de comandos interativos, opções ou subações vinculadas a um elemento de gatilho (como um botão de ícone, botão dividido ou ação de contexto).

Projetar um sistema de menu dropdown eficaz requer equilibrar layout espacial, hierarquia visual, agrupamento de itens, semântica de navegação por teclado, tratamento de colisão (limites da viewport) e adaptação responsiva em viewports móveis baseadas em toque, sem desorientar os usuários ou violar as diretrizes de acessibilidade WCAG 2.1 AA.

Casos de Uso

• Menus de Ação e Opção: Apresentar ações secundárias de página ou linha (por exemplo, "Editar", "Duplicar", "Exportar", "Excluir") vinculadas a um botão de gatilho em tabelas de dados, cartões ou cabeçalhos de página.
• Menus de Overflow e "Mais": Abrigar ferramentas de baixa prioridade ou links de navegação quando o espaço do contêiner é limitado (por exemplo, botões "..." em barras de ferramentas ou cabeçalhos de tabela).
• Menus Popup Contextuais: Exibir comandos contextuais direcionados acionados por clique com o botão direito ou pressão longa em itens específicos da tela visual ou lista.
• Submenus em Cascata: Organizar ações aninhadas ou opções de categorias de vários níveis dentro de uma sobreposição de menu com várias camadas.
• Menus de Ação de Seleção (Itens Marcáveis e de Rádio): Alternar estados de visualização, visibilidade de colunas ou preferências de classificação dentro de painéis de ação flutuantes.

Quando NÃO Usar

• Inputs de Seleção de Formulário (Comboboxes e Selects): Para inputs de formulário onde os usuários escolhem um ou vários valores para preencher um campo (por exemplo, selecionar um país ou categoria de produto), use custom-select-and-combobox-system.
• Painéis de Navegação de Alta Densidade: Para navegação global de vários sites com colunas contendo categorias estruturadas, landing pages e promoções de marketing, use mega-menu-navigation-system.
• Grandes Modais e Espaços de Tarefa: Para subtarefas complexas, edições de vários campos ou formulários de assistente de várias etapas que exigem foco preservado, use overlay-and-dialog-system ou bottom-sheet-design-system.
• Ajuda Contextual e Dicas de Ferramenta: Para descrições de texto não interativas ao passar o mouse/foco que explicam a função de um elemento, use tooltip-and-hint-system.

Inputs

1. Componente de Gatilho e Geometria: Tipo do elemento de gatilho primário (botão padrão, botão de ícone, botão dividido ou área de destino de clique com botão direito) e posicionamento espacial.
2. Inventário de Itens do Menu e Hierarquia: Lista de ações, tipos de item (padrão, marcável, rádio, destrutivo), ícones, atalhos de teclado, separadores e rótulos de seção de grupo.
3. Tokens de Superfície e Elevação: Cores de fundo da superfície, estilos de borda, tokens de sombra (--elevation-popover) e posicionamento z-index (--z-popover) de elevation-and-depth-system e accessible-color-system.
4. Contexto de Viewport e Dispositivo: Orientação do dispositivo, ponto de interrupção de largura de tela e características de suporte a toque.

Outputs

1. Blueprint de Anatomia e Layout do Menu: Especificação estrutural CSS e HTML para dimensionamento do contêiner do menu, preenchimento, alinhamento de itens, dicas de atalho à direita e espaçamento de divisores de seção.
2. Estratégia de Posicionamento Espacial e Colisão: Regras de layout para posicionamento de âncora (superior/inferior/esquerda/direita), alinhamento, lógica dinâmica de virar/deslizar e limites de altura máxima para rolagem.
3. Modelo de Adaptação Responsiva para Dispositivos Móveis: Especificação de design que transforma popovers estreitos de desktop em action sheets inferiores (bottom-sheet-design-system) ou listas de toque de largura total em viewports móveis.
4. Especificação de Navegação por Teclado e ARIA: Regras programáticas de acessibilidade cobrindo papéis ARIA (role="menu", role="menuitem", role="menuitemcheckbox", role="menuitemradio"), estados expandidos (aria-expanded) e gerenciamento de foco com teclas de seta.

---

Fluxo de Trabalho

1. Definir Estrutura do Menu e Anatomia dos Itens

Classifique os itens dentro do menu em grupos funcionais lógicos para maximizar a escaneabilidade:

• Rótulos de Cabeçalho e Seção: Agrupe ações relacionadas usando microtipografia em maiúsculas ou cabeçalhos de seção sutis (font-size: 0.75rem, font-weight: 600, letter-spacing: 0.05em).
• Composição de Item Padrão: Alinhe elementos horizontalmente usando flexbox (gap: 0.75rem):
  • Elemento Gráfico Principal: Ícone de 16x16px ou 20x20px esclarecendo o propósito da ação.
  • Texto do Rótulo: Verbo conciso e orientado à ação (por exemplo, "Baixar PDF", "Duplicar item").
  • Dica de Atalho à Direita: Texto de atalho de teclado em fonte monoespaçada (por exemplo, ⌘E, Ctrl+D) visualmente suave (color: var(--text-tertiary)).
  • Chevron à Direita: Indica um gatilho de submenu em cascata (>).
• Tipos de Item Especializados:
  • Itens Marcáveis (role="menuitemcheckbox"): Exibem marcas de seleção à esquerda quando ativos.
  • Itens de Rádio (role="menuitemradio"): Exibem pontos de rádio quando selecionados dentro de um grupo.
  • Itens Destrutivos: Estilize ações negativas (por exemplo, "Excluir", "Remover") com tokens de cor de aviso distintos (color: var(--color-danger)), separadas de ações benignas por uma linha divisória visual.
• Divisores (role="separator"): Use regras horizontais sutis (1px solid var(--border-subtle)) para segmentar grupos distintos de ação (por exemplo, agrupar ações de visualização separadamente das ações de edição/exclusão).

2. Estabelecer Posicionamento Espacial e Tratamento de Colisão

Configure regras de layout para que o menu seja renderizado de forma limpa adjacente ao seu gatilho sem transbordar as bordas da tela:

• Alinhamento de Âncora: Posicione o popover do menu em relação ao limite do botão de gatilho:
  • Inferior-Esquerdo / Inferior-Direito: Posicionamento padrão abaixo do botão de gatilho. Alinhe à borda direita quando o gatilho estiver próximo ao limite direito da tela (por exemplo, colunas de ação de linha em tabelas de dados).
  • Superior-Esquerdo / Superior-Direito: Inverta a direção para acima do botão de gatilho quando estiver próximo à parte inferior da viewport.
• Regras de Colisão e Inversão com a Viewport:
  • Mantenha uma margem mínima de 12px das bordas da tela (viewport-margin: 12px).
  • Defina uma restrição de altura máxima (max-height: calc(100vh - 32px)) com rolagem vertical interna (overflow-y: auto) para menus longos.
• Tokens de Elevação: Aplique empilhamento de camada superior (z-index: var(--z-popover)) e sombras de queda (box-shadow: var(--shadow-popover)) para separar visualmente o menu flutuante das linhas ou cartões da tabela de fundo.

3. Configurar Interação e Dinâmica de Submenu

• Estados do Gatilho: Garanta que os botões de gatilho indiquem estado aberto ativo usando aria-expanded="true" e um estado visual pressionado sutil (background-color: var(--bg-hover)).
• Atraso de Hover e Teclado do Submenu:
  • Submenus em cascata abrem ao passar o mouse com um pequeno atraso intencional (temporizador de intenção de 150–200ms) para evitar flashes de gatilho acidentais durante o movimento do ponteiro.
  • Pressionar SetaDireita em um gatilho de submenu expande o submenu e move o foco para dentro; SetaEsquerda fecha o submenu e retorna o foco ao item de menu pai.
• Gatilhos de Dispensa: Dispensar a sobreposição do menu aberto quando:
  • O usuário clica fora do painel do menu (ouvinte de clique externo).
  • O usuário pressiona a tecla Escape.
  • Uma ação de item de menu ativo é executada (a menos que seja um item de alternância marcável).
  • O foco sai da sobreposição do menu.

4. Projetar Adaptação Responsiva para Dispositivos Móveis

Popovers flutuantes de desktop (por exemplo, caixas flutuantes de 220px) têm desempenho ruim em telas de toque móveis devido aos pequenos alvos de toque e necessidades de posicionamento preciso:

• Transformação para Toque Móvel (< 768px):
  • Transforme popovers de desktop em uma Action Sheet Inferior (bottom-sheet-design-system) ancorada na viewport inferior.
  • Aumente a altura da linha do item para um alvo de toque mínimo de 44px (de preferência 48px) com zonas de toque horizontais de largura total.
  • Forneça uma alça de arrasto visual explícita ou um botão "Cancelar" claro na parte inferior da folha para dispensa fácil com o polegar.
• Feedback de Toque: Aplique estados de fundo de toque ativo distintos (:active) para feedback tátil imediato.

5. Programar Acessibilidade e Semântica de Teclado

• Marcos ARIA e Mapeamento de Papéis:
  • Defina o botão de gatilho: aria-haspopup="menu", aria-expanded="true|false", aria-controls="menu-id".
  • Defina o contêiner do menu: role="menu", aria-labelledby="trigger-id", tabindex="-1".
  • Defina os itens do menu: role="menuitem", role="menuitemcheckbox" ou role="menuitemradio".
• Modelo de Navegação por Teclado:
  • Enter / Espaço / SetaAbaixo no gatilho: Abre o menu e foca o primeiro item do menu.
  • SetaAbaixo / SetaAcima: Navega sequencialmente pelo foco através dos itens do menu (envolvendo do topo ao fundo).
  • Home / End: Move o foco diretamente para o primeiro ou último item do menu.
  • Escape: Fecha o menu imediatamente e retorna o foco ao botão de gatilho.
  • Tab: Fecha o menu imediatamente e permite a progressão padrão do foco do documento.
  • Pesquisa de Caractere por Digitação: Pressionar uma tecla de letra (por exemplo, "D") move o foco diretamente para o próximo item do menu começando com essa letra.

---

Regras de Decisão

Seleção de Tipo de Menu e Contexto

Contexto / Objetivo	Padrão Recomendado	Estrutura ARIA	Adaptação Móvel
Ações de Linha / Cartão	Dropdown de Ação	role="menu" / role="menuitem"	Action Sheet Inferior
Overflow de Barra de Ferramentas ("...")	Menu de Overflow	role="menu" / role="menuitem"	Action Sheet Inferior
Ferramentas de Tela com Clique Direito	Menu de Contexto	role="menu" / role="menuitem"	Pressão Longa Action Sheet Inferior
Seleção de Opções de Formulário	Select Combobox	role="combobox" / role="option"	Select Nativo / Action Sheet Inferior
Alternâncias de Visualização / Filtro de Vários Níveis	Painel de Ação Marcável	role="menu" / role="menuitemcheckbox"	Action Sheet Inferior

Regras de Posicionamento e Alinhamento

• Menus de Linha de Tabela de Dados: Posicione alinhado ao canto superior direito ou inferior direito do botão de gatilho para evitar truncamento horizontal além da borda direita da viewport da tabela.
• Ações de Cabeçalho / Navegação: Posicione alinhado ao canto inferior direito ou inferior esquerdo, dependendo da proximidade com a borda da tela.
• Submenus: Abra para a direita (left: 100%) por padrão; se o espaço à direita for menor que 200px, inverta para abrir para a esquerda (right: 100%).

---

Restrições

• Acessibilidade (WCAG 2.1 AA):
  • SC 1.4.3 Contraste (Mínimo): O texto do item, ícones e dicas de teclado devem manter uma taxa de contraste de pelo menos 4,5:1 em relação ao fundo do menu.
  • SC 2.1.1 Teclado: Cada item e ação dentro do menu deve ser completamente acessível e acionável via teclado.
  • SC 2.4.7 Foco Visível: Itens do menu focados devem apresentar estados de foco visual distintos (por exemplo, mudança de cor de fundo + indicador de destaque em conformidade com contraste).
  • SC 2.5.8 Tamanho do Alvo: Itens do menu de desktop devem manter pelo menos 32px de altura; itens da action sheet móvel devem satisfazer alvos de toque de pelo menos 44x44px.
• Restrições de Limite da Viewport: Menus abertos nunca devem se estender para fora da tela ou criar barras de rolagem horizontais na página. Use inversão de colisão e rolagem vertical interna (max-height).
• Preenchimento Espacial e Densidade: Mantenha preenchimento horizontal interno consistente (por exemplo, padding: 0.5rem 0.75rem) e preenchimento vertical do contêiner (padding: 0.25rem 0).

---

Padrões Comuns de Falha

• Confusão com Combobox de Formulário: Usar role="menu" para dropdowns de seleção de formulário em vez de role="combobox" / role="listbox", confundindo leitores de tela sobre seleção de valor versus execução de comando.
• Desorientação de Foco ao Fechar: Falha ao restaurar o foco do teclado de volta ao botão de gatilho quando o menu fecha via Escape ou seleção, deixando o foco perdido em document.body.
• Armadilha do Contêiner de Corte: Colocar menus dropdown dentro de células de tabela ou contêineres com overflow: hidden, fazendo com que o menu aberto seja cortado visualmente.
• Alvos de Toque Móveis Minúsculos: Renderizar itens de dropdown de desktop minúsculos de 24px em telas de toque sem convertê-los em action sheets amigáveis ao toque.
• Dispensa Acidental de Submenu: Falta de um temporizador de intenção em submenus em cascata, fazendo com que os submenus recolham quando o mouse se move diagonalmente em direção a um subitem.

---

Critérios de Validação

• O contêiner do menu utiliza semântica ARIA apropriada (role="menu", role="menuitem", role="separator").
• A navegação por teclado suporta completamente SetaAbaixo, SetaAcima, Home, End, Escape e digitação de letras.
• Fechar o menu (via Escape ou clique em item) restaura programaticamente o foco para o elemento de gatilho.
• As regras de colisão da viewport invertem ou rolam menus longos de forma limpa sem transbordamento de tela.
• O ponto de interrupção responsivo (< 768px) transforma popovers de desktop em action sheets inferiores amigáveis ao toque.
• O texto do item, dicas de atalho e fundos do indicador de foco satisfazem o contraste WCAG AA (≥4.5:1).