Criar uma command palette com Claude Code

Defina primeiro o limite do problema

Criar uma command palette com Claude Code não é pedir ao Claude Code uma UI bonita e solta. O objetivo é melhorar interação, layout, acessibilidade, mobile e conversão na mesma checklist. Em produção, textos longos, blocos de código, anúncios, CTA, teclado, erros e estados vazios importam.

Leia também claude code keyboard shortcuts, claude code accessibility, claude code search functionality. Referências oficiais: React useDeferredValue, React useMemo, WAI-ARIA practices. O pedido precisa conter objetivo, escopo proibido, regras visuais, use case e pitfall.

O que é uma command palette

Uma command palette é uma pequena janela de comando que abre com Cmd+K ou Ctrl+K e permite, enquanto você busca, navegar, criar, mudar configurações e executar ações. É comum em produtos como VS Code, Linear, Slack e Notion. Como o usuário digita diretamente “o que quer fazer”, sem percorrer menus com o mouse, quem já tem prática trabalha mais rápido.

Mas copiar só a aparência costuma dar errado. Um modal que apenas faz busca não basta. Uma command palette útil em produção precisa de navegação por teclado, controle de foco, ARIA para leitores de tela, um design em que o campo não trava mesmo com busca pesada e uma proteção para não executar por engano ações perigosas. Pense em ARIA como “o conjunto de atributos que comunica o significado da UI às tecnologias assistivas” e em combobox como “o componente que combina um campo de entrada com uma lista de candidatos”.

Prompt recomendado

Implemente esta melhoria UI com a menor mudança segura.
Mantenha rotas, componentes, design tokens e CTA principal.
Retorne código copiável, use case, pitfall, revisão mobile e rollback.
Finalize com review checklist para humanos.

Requisitos da implementação

Ao pedir ao Claude Code, não basta dizer “crie uma command palette”. Liste antes as responsabilidades que o componente precisa cobrir, para a IA não parar só no visual.

Requisito	Ponto de implementação
Abertura	Atalho global Cmd+K / Ctrl+K
Busca	Filtrar por label, category, description e keywords
Velocidade	useDeferredValue prioriza a digitação e useMemo memoiza o cálculo dos candidatos
Teclado	Definir o tratamento de setas, Home, End, Enter, Escape e Tab
ARIA	dialog, combobox, listbox, option e aria-activedescendant
Segurança	Ações destrutivas exigem confirmação ou checagem de permissão no próprio comando

Use case checklist

1. Conteúdo: busca, artigos relacionados, consulta e download fáceis de encontrar.
2. SaaS: menos passos sem perder teclado, mobile e estados de erro.
3. Produto: preço, compra, anúncios e formulários continuam prioritários.
4. Time: Claude Code entrega código e checklist de revisão.

Código de implementação

import { useDeferredValue, useMemo, useState } from "react";

type Command = {
  id: string;
  label: string;
  keywords: string[];
  run: () => void;
};

export function CommandPalette({ commands }: { commands: Command[] }) {
  const [open, setOpen] = useState(false);
  const [query, setQuery] = useState("");
  const deferredQuery = useDeferredValue(query);

  const results = useMemo(() => {
    const text = deferredQuery.trim().toLowerCase();
    if (!text) return commands.slice(0, 8);
    return commands
      .filter((command) =>
        [command.label, ...command.keywords].some((value) => value.toLowerCase().includes(text)),
      )
      .slice(0, 8);
  }, [commands, deferredQuery]);

  function onKeyDown(event: React.KeyboardEvent) {
    if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k") {
      event.preventDefault();
      setOpen((value) => !value);
    }
    if (event.key === "Escape") setOpen(false);
  }

  return (
    <div onKeyDown={onKeyDown}>
      <button type="button" aria-haspopup="dialog" aria-expanded={open} onClick={() => setOpen(true)}>
        Open commands
      </button>
      {open ? (
        <div role="dialog" aria-modal="true" aria-label="Command palette" className="palette">
          <input
            autoFocus
            value={query}
            onChange={(event) => setQuery(event.target.value)}
            aria-label="Search commands"
            placeholder="Search actions..."
          />
          <ul role="listbox" aria-label="Available commands">
            {results.map((command) => (
              <li key={command.id}>
                <button type="button" onClick={() => { command.run(); setOpen(false); }}>
                  {command.label}
                </button>
              </li>
            ))}
          </ul>
        </div>
      ) : null}
    </div>
  );
}

.palette {
  position: fixed;
  inset: 1rem;
  max-width: 40rem;
  margin: auto;
  padding: 1rem;
  background: canvas;
  color: canvastext;
  border: 1px solid color-mix(in srgb, canvastext 20%, transparent);
}

Pitfall checklist

• Não otimize só para screenshot.
• Verifique textos longos, code blocks e tabelas no mobile.
• Não comunique estado apenas por cor.
• Evite mudanças em arquivos sem relação.
• Teste 375px, teclado, rede lenta e erros.

A armadilha do IME e da lista vazia

Os erros mais comuns aparecem em dois pontos. O primeiro é o Enter disparar durante a digitação com IME: quando o usuário ainda está compondo o texto (por exemplo, confirmando um candidato), um Enter prematuro executa um comando errado. A solução é ignorar a tecla quando event.nativeEvent.isComposing for verdadeiro. O segundo é o índice ativo apontar para uma posição inexistente quando há zero resultados, gerando um acesso equivalente a filtered[-1]. Sempre limite o índice ao tamanho atual da lista e trate o caso vazio com uma mensagem clara.

Há ainda um terceiro ponto, muitas vezes esquecido: o leitor de tela precisa saber qual candidato está selecionado agora. Use aria-activedescendant apontando para o id da opção ativa e marque a lista com role="listbox" e cada item com role="option". Sem isso, a navegação por teclado funciona visualmente, mas quem depende de tecnologia assistiva fica perdido.

Verificação

Rode build e revise mobile. Confirme ausência de overflow, rolagem de code block, CTA, formulários e anúncios visíveis. Peça uma segunda review a Claude Code com arquivos alterados, riscos, código removível e rollback.

Monetização

Esse tema afeta anúncios, consulta, cards de produto, preços e formulários. Para transformar em processo, use treinamento e consultoria Claude Code.

Revisão adicional

Antes de publicar, reúna screenshots, teclado, largura mobile, rede lenta, erros e CTA em uma checklist. Assim Claude Code gera uma melhoria conectada ao negócio, não apenas código. Complexidade que pode ser removida também é ganho.

Nota prática

Testei separando implementação e review. O diff ficou menor e problemas de layout apareceram antes do deploy. Na primeira geração, o visual estava bom, mas o Enter disparava durante a digitação com IME e o leitor de tela não anunciava o candidato selecionado; só depois de adicionar a guarda de composição e o aria-activedescendant a palette ficou realmente utilizável.