Sistema de Paleta de Comandos

O que Sistema de Paleta de Comandos faz?

Propósito

O Sistema de Paleta de Comandos fornece uma estrutura de design e espacial para menus sobrepostos globais acionados por teclado (normalmente invocados com Cmd+K ou Ctrl+K). Em aplicações web modernas, de alta densidade, plataformas de desenvolvedores e portais de documentação ricos em conteúdo, as barras de navegação padrão se tornam sobrecarregadas. Uma paleta de comandos atua como um "centro de comando", dando a usuários avançados caminhos de teclado diretos e sem atrito para pesquisar, navegar e executar ações, ao mesmo tempo que serve como um dicionário interativo de atalhos de teclado.

Este skill garante que as paletas de comando sejam espacialmente ergonômicas, visualmente estruturadas para evitar fadiga cognitiva e totalmente compatíveis com especificações de acessibilidade avançadas (WCAG 2.2 AA).

Casos de Uso

• Projetar um controlador de espaço de trabalho global orientado por atalhos para painéis SaaS.
• Estruturar portais orientados a desenvolvedores e portais de pesquisa de documentação (por exemplo, referências de API).
• Implementar painéis administrativos de ação rápida para plataformas CRM ou CMS empresariais.
• Criar interfaces de linha de comando unificadas (CLIs) dentro de produtos web complexos e multicamadas.

Quando NÃO Usar

• Páginas de Destino Estáticas: Onde a intenção do usuário é puramente exploratória e focada em conversão; uma barra de navegação global e chamadas para ação (CTAs) claras são mais eficazes.
• Sites de Informação Rasos (<15 páginas): Onde a sobrecarga de implementar e ensinar uma paleta de comandos supera qualquer benefício de orientação.
• Sites Móveis de Consumo Simples: Onde o espaço na tela é mínimo e os usuários dependem estritamente de interações de toque, sem teclados físicos externos.

Entradas

1. Inventário de Comandos e Ações: Uma taxonomia abrangente de ações, páginas, configurações e documentos pesquisáveis.
2. Regras de Mapeamento Contextual: Regras para quais comandos são globais vs. quais são específicos de contexto (por exemplo, "Excluir Projeto" aparece apenas ao visualizar um projeto).
3. Sistema de Atalhos de Teclado: Um mapeamento de ações para atalhos de teclado físicos (por exemplo, G então D para "Ir para o Painel").
4. Tokens de Design da Marca: Escalas tipográficas, cores, proporções de espaçamento e tokens de sombra (de fluid-spacing-system e fluid-typography-system).

Saídas

1. Especificações de Acesso (Trigger Affordance): Designs visuais para pontos de entrada persistentes e crachás de atalhos de teclado.
2. Arquitetura de Layout da Paleta: Estruturas de grade para o modal de sobreposição, agrupamento de resultados, navegação por categorias e rodapés de ajuda.
3. Especificações Visuais da Linha de Comando: Especificações de hierarquia para ícones, títulos de comando, crachás de categoria e anotações de atalho.
4. Especificação de Teclado e Acessibilidade: Mapeamentos exatos de eventos de teclado e especificações de estado ARIA correspondentes ao padrão ARIA APG Combobox.

---

Fluxo de Trabalho

1. Estabelecer o Acionador da Paleta e Pontos de Entrada

Como uma paleta de comandos fica oculta por padrão, você deve projetar pontos de entrada detectáveis:

• O Acionador Persistente no Cabeçalho: Um botão que imita uma barra de pesquisa no cabeçalho global, apresentando um ícone de lupa, um rótulo de texto (por exemplo, "Pesquise ou execute um comando...") e um crachá de atalho de teclado físico alinhado à direita (por exemplo, ⌘K ou Ctrl+K).
• Botão de Comando Flutuante: Para viewports com painéis intensivos ou tela cheia, coloque um botão de acionamento sutil no canto inferior direito da viewport.
• Ouvinte Global Invisível: Garanta que pressionar Cmd+K (macOS) ou Ctrl+K (Windows/Linux) em qualquer lugar do documento (a menos que o foco esteja em uma entrada de texto) abra imediatamente a paleta.

2. Projetar a Sobreposição Modal e o Fundo (Scrim)

• Fundo (Scrim): Use um fundo semitransparente de alto contraste (por exemplo, rgba(15, 23, 42, 0.4)) para escurecer a página de fundo, focando a atenção inteiramente na tarefa ativa.
• Posicionamento Vertical: Centralize o modal horizontalmente, mas ancore-o aos 10%–15% superiores da viewport, em vez de centralização vertical absoluta. Isso se alinha com o nível natural dos olhos e deixa espaço para o teclado virtual físico em telas sensíveis ao toque.
• Limites de Tamanho: Limite a largura a um envelope de digitalização confortável — idealmente entre 600px e 680px. A altura deve ser dinâmica, com um máximo de 450px a 550px para garantir que nunca ultrapasse telas de laptops pequenos.

3. Estruturar a Grade de Layout Interna

Divida a paleta de comandos em quatro zonas horizontais distintas:

1. A Zona de Pesquisa e Filtro: Um campo de entrada sem bordas e largura total com um ícone de pesquisa proeminente (mín. 20px). Use texto de espaço reservado que guie o usuário (por exemplo, "Digite um comando ou pesquise...").
2. A Barra de Filtro por Categoria (Opcional): Uma linha horizontal de chips compactos ou controles segmentados (por exemplo, "Todos", "Ações", "Páginas", "Usuários") para permitir que os usuários filtrem os resultados antes de pesquisar.
3. O Feed de Resultados (Contêiner de Rolagem): Uma listbox com rolagem contida e cabeçalhos agrupados (por exemplo, "Recentes", "Navegação", "Configurações do Sistema").
4. O Rodapé de Ajuda: Uma barra de status de baixo contraste mostrando guias de teclado (por exemplo, ↑↓ para navegar, ↵ para selecionar, esc para fechar).

+-----------------------------------------------------------+
|  [Ícone de Pesquisa]  Pesquise ou digite um comando...         [ESC] |
+-----------------------------------------------------------+
|  ( Todos )  ( Ações )  ( Páginas )  ( Membros )  ( Ajuda )   |
+-----------------------------------------------------------+
|  PESQUISAS RECENTES                                          |
|  [Ícone] Ir para Faturamento                         [ ⌘ G ] [ B ]|
|  [Ícone] Criar Nova Fatura                    [ ⌘ N ]     |
|                                                           |
|  NAVEGAÇÃO                                               |
|  [Ícone] Painel                                           |
|  [Ícone] Configurações da Equipe                [ ⌘ , ]     |
+-----------------------------------------------------------+
|  ↑↓ Navegar  |  ↵ Selecionar  |  esc Fechar  |  ? Documentos de Ajuda   |
+-----------------------------------------------------------+

4. Criar a Hierarquia Visual da Linha de Comando

Cada item na lista de resultados deve ser digitalizável em milissegundos:

• Ícone Alinhado à Esquerda: Um ícone explícito e de alto contraste que indica o tipo do item (por exemplo, um ícone de arquivo para documentos, uma engrenagem de configurações para ações, um avatar de usuário para pessoas).
• Rótulo Principal: Texto seminegrito e de cor primária do comando em si (por exemplo, "Convidar membro da equipe").
• Sub-rótulo Secundário (Opcional): Descrição esmaecida e menor abaixo ou ao lado do rótulo principal para dar contexto (por exemplo, "Configurações > Organização").
• Crachás de Atalho Alinhados à Direita: Exiba o atalho de teclado físico associado a esse comando usando crachás de tecla pequenos e de alto contraste (por exemplo, ⌥I).

5. Definir Estados Interativos e Seleção por Teclado

Uma paleta de comandos é impulsionada principalmente pelo teclado; portanto, o estado de seleção por teclado tem precedência sobre o hover do mouse:

• Estado do Item Ativo/Focado: Quando um item é navegado usando as teclas de seta, aplique uma mudança proeminente de preenchimento de fundo (usando o token de luz primário, por exemplo, var(--color-primary-light)), e um indicador de borda esquerda. O texto principal deve mudar para a cor da marca.
• Estado de Hover (Mouse): Espelhe o estado ativo do teclado. Mover o mouse sobre os itens deve atualizar a seleção do teclado para evitar estados de foco duplos.
• Estado Vazio: Quando uma pesquisa não retorna resultados, mostre um estado vazio limpo e ilustrativo sugerindo ações alternativas (por exemplo, "Nenhum comando encontrado. Tente pesquisar em nossa central de ajuda" com um link de pesquisa).
• Estado de Carregamento: Se os resultados da consulta de pesquisa forem buscados de forma assíncrona, exiba um indicador de carregamento linear sutil na base da entrada de pesquisa, evitando cartões esqueleto que causam mudanças de layout.

---

Regras de Decisão

• A Regra "Cmd+K vs Pesquisa Persistente": Se o valor principal do site é consumir conteúdo estruturado (como um catálogo de e-commerce), use uma barra de pesquisa persistente. Se o valor é fluxo de trabalho administrativo, execução de comandos ou navegação densa, use uma paleta de comandos Cmd+K.
• A Regra do Limite de Agrupamento: Nunca exiba mais de 3–4 categorias de comandos simultaneamente. Mantenha o máximo de itens visíveis em cada categoria em 5, fornecendo uma opção "Mostrar mais..." se houver mais.
• A Regra da "Contagem de Teclas": Atalhos de teclado físico exibidos ao lado dos comandos nunca devem exceder 3 teclas (por exemplo, Ctrl+Shift+P é aceitável; Ctrl+Alt+Shift+Z é complexo demais).
• A Regra do Contexto Dinâmico: Filtre comandos dinamicamente com base na rota ativa. Se um usuário está na página de faturamento, priorize "Atualizar Cartão de Crédito" ou "Baixar Fatura em PDF" no topo da lista de resultados padrão (sem digitação).

---

Restrições

1. Acessibilidade (WCAG 2.2 AA Mínimo)

• Padrão ARIA Combobox: Você deve estruturar a marcação estritamente seguindo o Guia de Práticas de Criação de ARIA (APG):
  • O contêiner de entrada deve ter role="combobox", aria-expanded="true", aria-autocomplete="list" e aria-controls="command-listbox-id".
  • A lista de resultados deve ter role="listbox", e cada linha de comando deve ter role="option".
  • Conforme o usuário pressiona as teclas de seta, a entrada deve atualizar aria-activedescendant para apontar para o ID da opção ativa, e essa opção deve ter aria-selected="true".
• Gerenciamento de Foco: Abrir a paleta deve prender o foco do teclado dentro da sobreposição. Pressionar Tab deve ser interceptado para ciclar dentro da paleta ou desabilitado completamente (preferindo teclas de seta para navegação de opções). Fechar a paleta deve retornar o foco exato ao elemento de acionamento.
• Anúncios para Leitores de Tela: Coloque uma div invisível com aria-live="polite" e aria-atomic="true" ao lado da entrada. Na pesquisa, popule dinamicamente isso com o status do resultado (por exemplo, "12 resultados encontrados, use as teclas de seta para cima e para baixo para navegar").
• Taxas de Contraste: Todo texto, crachás de atalho e indicadores de foco devem atender ao WCAG AA (4,5:1 mínimo para texto normal, 3:1 para bordas de UI e indicadores de seleção).
• O Bloqueio de Fundo: Quando a paleta está ativa, o resto da aplicação deve ser tornado inert e oculto dos leitores de tela. Use <dialog>.showModal() para conseguir o aprisionamento de foco, escurecimento de fundo e fechamento nativo com Escape.

2. Responsividade e Adaptações para Toque

• Ajuste de Viewport para Toque: Em telas móveis, a paleta de comandos deve mudar para uma sobreposição em tela cheia ou uma gaveta deslizante inferior.
• Manipulação do Teclado Virtual: Foco automático na entrada de pesquisa ao abrir, e use inputmode="search" para garantir que o dispositivo móvel exiba o botão de ação "Pesquisar" correto em seu teclado virtual.
• Ocultação de Dicas Físicas: Em dispositivos apenas com toque, oculte crachás de atalho de teclado físico (por exemplo, ⌘K ou ⌥I), pois são irrelevantes e criam poluição visual.
• Dimensionamento do Alvo de Toque: Tags removíveis, chips de categoria e linhas de lista devem ter uma altura de pelo menos 44px em telas sensíveis ao toque para acomodar toques de dedo, aderindo ao WCAG 2.2 SC 2.5.8.

---

Padrões Comuns de Falha

• A "Armadilha da Rolagem Infinita": Permitir que o feed de resultados renderize 100+ correspondências sem um contêiner de rolagem, transbordando a tela e tornando os guias de rodapé inacessíveis.
• Falta de Bloqueio de Rolagem do Fundo: Permitir que o documento de fundo role enquanto o usuário navega pela rolagem da paleta de comandos, causando desorientação de layout.
• Perda de Foco da Entrada: Clicar em um chip de categoria ou opção de resultado e perder o foco do teclado da entrada de texto, exigindo que usuários de teclado usem Tab para retornar.
• Exibição Móvel Incompreensível: Reter um pequeno modal centralizado para desktop em uma tela móvel de 320px, cortando rótulos principais e crachás de atalho.
• Falta de Espelhamento do Estado do Acionador: O botão persistente do cabeçalho não mostrar o atalho de teclado, deixando usuários de teclado sem saber que uma paleta de comandos existe.

---

Critérios de Validação

• Um botão de acionamento persistente está presente no cabeçalho com um crachá visual claro de atalho Cmd+K / Ctrl+K.
• Pressionar Cmd+K ou Ctrl+K em qualquer lugar da página abre o modal.
• O foco do teclado é imediatamente movido para a entrada de pesquisa, e a rolagem da página de fundo é bloqueada.
• A navegação das opções é impulsionada pelas teclas de seta para cima e para baixo, com um estado ativo focado altamente visível.
• As linhas de opção apresentam hierarquia estruturada: Ícone à esquerda, título da ação em negrito, hierarquia de rota contextual e crachá de atalho à direita.
• O padrão ARIA APG Combobox é totalmente especificado, incluindo role="combobox", role="listbox", role="option" e aria-activedescendant.
• Uma região aria-live="polite" está presente para anunciar mudanças na contagem de resultados de pesquisa para leitores de tela.
• Em viewports móveis, a paleta se adapta para tela cheia ou uma gaveta inferior, ocultando crachás de atalho físicos e dimensionando as linhas para uma altura mínima de 44px.
• Pressionar Escape ou clicar no fundo (scrim) fecha a paleta e retorna o foco ao botão de acionamento.