lksnmnn/product-ui

Product UI

Um aplicativo é uma superfície de trabalho: as pessoas voltam a ele para realizar uma tarefa. Cada elemento merece seu lugar ao servir essa tarefa. O objetivo é a familiaridade conquistada — uma pessoa fluente em ferramentas desta categoria confia em cada controle à primeira vista, e a interface desaparece na tarefa.

Estas regras valem para qualquer aplicativo. O que é específico de um projeto — dispositivos alvo, sistema de design, componentes, direção, desvios conhecidos — vive no arquivo de projeto; construa a partir dele. Antes de declarar uma tela como pronta, execute review.md.

O arquivo de projeto

Procure-o nesta ordem: um caminho nomeado em CLAUDE.md ou AGENTS.md, depois .claude/product-ui.md. Quando nenhum existir, crie .claude/product-ui.md a partir de templates/project.md antes da primeira construção:

1. Encontre o sistema de design: arquivos de token (propriedades personalizadas CSS, um tema Tailwind, um JSON de tokens), a biblioteca de componentes (no repositório components/ui, shadcn, MUI, Radix, …), arquivos de story.
2. Liste os blocos de construção que uma tela precisa (scaffold de página, tabela, campo de formulário, estado vazio, diálogo, toast, …) com seus caminhos. Marque cada um que estiver faltando como faltando; nunca invente um caminho.
3. Anote os desvios que você viu no caminho: lugares onde o código quebra uma regra abaixo.
4. Pergunte ao usuário quais são os dispositivos alvo por aplicativo e quem é o dono da linguagem visual (uma equipe de design, ou os desenvolvedores). Sugira alvos a partir da intenção do aplicativo.

Escreva apenas o que você verificou. Aponte CLAUDE.md para o arquivo para que sessões posteriores o encontrem.

Quando o projeto não tiver direção visual e a superfície não parecer genérica, execute primeiro o skill design-direction; ele registra seu resultado no mesmo arquivo.

Propósito primeiro

Antes do layout, escreva em uma linha cada:

• o trabalho que a tela serve e a pessoa que o realiza;
• a primeira leitura: a única coisa que eles olham quando a tela abre;
• a ação principal e com que frequência eles a repetem;
• os dispositivos alvo: telefone, tablet, laptop, tela grande, a partir do arquivo de projeto.

Cada região na tela mapeia para uma dessas linhas. Uma região que não mapeia para nenhuma é cortada.

Conteúdo real

Construa e avalie com conteúdo moldado como o de produção: nomes reais de tamanho realista, o título mais longo plausível, 0, 1, 7 e 500 itens, um valor opcional ausente, uma tradução 30% mais longa que o inglês. "João Silva", "Empresa XYZ", "Lorem ipsum", "Item 1" e números redondos escondem todos os problemas de layout e são a primeira coisa que faz uma tela parecer gerada. Quando os dados do domínio forem desconhecidos, peça uma amostra ou derive uma do esquema.

Todos os tamanhos

Uma tela é otimizada para seu dispositivo principal e funciona em todos os outros breakpoints com as mesmas funcionalidades. Cada tamanho recebe o padrão que lhe cabe, não uma cópia comprimida do desktop: uma barra lateral se torna uma gaveta ou trilho de ícones, uma tabela se torna uma lista empilhada, um painel dividido se torna uma página com uma etapa de voltar, o hover se torna um controle visível, uma barra de ferramentas densa se torna um menu de estouro. Uma funcionalidade que desaparece abaixo de um breakpoint é uma constatação.

Nada rola horizontalmente em uma largura alvo: nem a página, nem uma lista dentro de seu próprio contêiner. Colunas de texto livre (nomes, títulos, e-mails, nomes de arquivo) encolhem e truncam com o texto completo ao passar o mouse; apenas uma grade genuinamente larga (uma matriz, uma linha do tempo) pode rolar, e isso é informado.

Em monitores grandes, o conteúdo mantém uma medida legível: blocos de texto ficam abaixo de ~75 caracteres por linha, formulários mantêm sua largura de coluna, e uma tabela pode crescer enquanto suas colunas de texto livre ocupam o espaço.

Navegação

• A navegação global lista as seções do aplicativo e permanece a mesma em todas as telas.
• Uma seção com suas próprias subáreas pode adicionar uma camada local (uma segunda coluna ou abas). Cada camada mostra apenas seu próprio nível: nenhuma camada repete as entradas de outra, e duas entradas nunca compartilham um rótulo.
• O escopo — qual organização, espaço de trabalho ou conta em que a tela atua — é definido por um seletor, mostrado uma vez.
• Cada página está a, no máximo, duas opções da navegação global, e a navegação local permanece visível no dispositivo principal.
• O chrome acima do primeiro controle permanece pequeno: um breadcrumb nunca repete o título da página abaixo dele.
• Um aplicativo com mais de um punhado de seções ou muitos registros oferece uma pesquisa de salto para qualquer lugar (⌘K / Ctrl+K) que encontra páginas e registros por nome ou id colado.

Densidade

• Mostre o conjunto de trabalho de uma só vez. Uma lista que uma pessoa examina ou compara é uma tabela com uma linha por item; uma grade de cartões é para poucos itens cuja imagem ou pré-visualização é o conteúdo.

• A altura da linha segue o conteúdo: linhas de uma linha com 36–44px, uma linha com uma segunda linha ou uma miniatura até 64px; o padding nunca ocupa mais altura que o conteúdo.

• O espaçamento entre itens relacionados é menor que o espaçamento entre grupos, para que o agrupamento seja lido apenas pelo espaçamento.

• Cada elemento em uma linha merece seu lugar. Teste cada um:

  • tarefa: serve para encontrar, comparar, abrir ou agir sobre o item, para o trabalho desta tela;
  • apagar: removê-lo perde algo que a pessoa precisa; caso contrário, vai, ou se move para a visão de detalhes;
  • redundância: não repete nenhuma coluna, filtro ativo ou título de página;
  • autoexplicativo: é lido sem hover, tooltip ou legenda, e um status é uma palavra, nunca cor sozinha;
  • ordem: o que identifica o item primeiro, depois os fatos que as pessoas comparam, ações por último.

  Um fato ausente também é uma constatação: quando as pessoas abrem item após item para comparar um valor, esse valor pertence à linha.

• Uma linha por linha por padrão. Fatos secundários ficam em sua própria coluna ou em uma segunda linha suave, nunca em um tooltip que a pessoa precisa passar o mouse para comparar.

• Títulos, descrições e texto de ajuda são tão curtos quanto o trabalho permite. Uma descrição de página que repete o título é cortada.

• Espaço em branco separa grupos; nunca preenche uma tela esparsa para parecer cheia.

• Uma caixa (borda, fundo, sombra) marca algo em que a pessoa atua como unidade. Apenas agrupamento é feito com espaço ou uma linha; um cartão dentro de um cartão é uma constatação.

Hierarquia

• Uma ação primária por visão, visualmente primária, no canto superior direito de seu escopo (cabeçalho da página ou cabeçalho do painel). Ações secundárias são contorno ou fantasma; as destrutivas ficam por último.
• Cada tamanho, espaço, cor e raio vêm do sistema de design da superfície e permanecem dentro dele. Um valor arbitrário (text-[10px], p-[13px], um hex bruto) é uma constatação; a correção é o passo mais próximo, ou um novo token quando nenhum passo se encaixa.
• Peso e cor carregam a hierarquia antes do tamanho.
• A cor carrega significado: o acento marca a ação primária, seleção e estado. A cor de status aparece apenas onde existe um status.
• Ícones acompanham um rótulo onde aceleram o reconhecimento (navegação, ações frequentes) e ficam sozinhos apenas para ações universais (fechar, pesquisar, mais) com um nome acessível. Um ícone em cada botão, título ou cartão é decoração.
• Um valor somente leitura é renderizado como texto, nunca como um campo de entrada.
• Um controle que a função do visualizador não pode usar fica oculto, decidido pela mesma capacidade que o servidor verifica. Quando saber que a ação existe é importante, ele é mostrado desabilitado com o motivo ("Apenas administradores podem convidar").
• O texto nomeia o que as pessoas reconhecem, não a infraestrutura por trás: nenhum nome de fornecedor ou pipeline, a menos que o público trabalhe diretamente com eles. A navegação não lista funcionalidades não construídas ou desligadas.

Texto

O texto da interface faz parte do design e é a forma mais rápida de identificar uma tela gerada.

• Um botão diz o que faz, como um verbo e seu objeto: "Convidar membro", "Exportar CSV". Nunca "Enviar", "OK", "Clique aqui", "Comece agora" dentro de um aplicativo.
• O botão de confirmação repete o verbo da pergunta: "Excluir 3 arquivos?" → "Excluir arquivos".
• Letra minúscula para cada rótulo, título e botão, com exceção de nomes próprios. Sem pontos de exclamação, sem "Ops", sem "Com sucesso", sem "Por favor".
• O feedback declara o resultado nos termos da pessoa: "Fatura enviada para financeiro@…", não "Operação concluída com sucesso".
• Um estado vazio diz o que pertence aqui e como chega aqui, em uma ou duas frases simples. Sem humor, sem preenchimento de ilustração, sem "Nada para ver aqui".
• Sem voz de marketing dentro de uma ferramenta: corte "integrado", "sem esforço", "poderoso", "desbloqueie", "acelere", "mágico", "com IA" e qualquer frase que elogie o produto.
• Um termo por conceito em todo o aplicativo; o glossário vive no arquivo de projeto.
• Números, datas e unidades seguem um formato por aplicativo; contagens usam o plural correto ("1 arquivo", "2 arquivos").

Listas e tabelas

• Números alinhados à direita com tabular-nums; texto alinhado à esquerda.
• Timestamps usam um formato fixo por aplicativo, nunca o padrão de localidade do navegador, e nunca são truncados. Telas de monitoramento emparelham tempo relativo ("3 min atrás") com o absoluto ao passar o mouse, ou o contrário.
• Cabeçalhos nomeiam a coluna em uma ou duas palavras; cabeçalhos classificáveis classificam ao clicar.
• Pesquisa, filtros, classificação, página e o item aberto vivem na URL, para que uma visão sobreviva a recarregar, voltar e um link compartilhado.
• Uma linha é um link real para seu item: a linha inteira o abre, e Cmd-click abre uma nova guia.
• Cada referência em uma linha — uma pessoa, uma organização, um trabalho, um id — linka para sua própria página.
• Ações por linha ficam no final da linha em uma coluna estável, visíveis em repouso; no mínimo, aparecem em telas sensíveis ao toque. Um controle que leva cliques enquanto invisível é um bug.
• Trabalho em lote obtém caixas de seleção, selecionar tudo e uma barra de ação em lote quando a pessoa lida com itens em lotes.
• Paginação ou windowing após ~50 linhas; a contagem está sempre visível. Um filtro que limita o conjunto (um intervalo de mês) substitui a paginação quando o limite é mostrado.
• Chips de filtro podem carregar contagens; então dobram como resumo da página.

Formulários

• Rótulos acima dos campos, uma coluna, na ordem em que a pessoa pensa sobre os dados.
• Validar ao sair do foco e ao enviar; o erro fica abaixo do seu campo e diz como corrigi-lo.
• Padrões são a resposta mais comum. Campos opcionais são marcados como opcionais, os obrigatórios não são marcados.
• O botão de enviar em um formulário de criação ou ação permanece habilitado. Enviar entrada inválida foca o primeiro campo inválido e mostra como corrigi-lo abaixo desse campo.
• Salvar em um formulário de edição pode permanecer desabilitado até que algo mude, já que nada espera para ser salvo; uma vez que algo muda, é habilitado, a regra acima se aplica, e uma dica "Alterações não salvas" ao lado mostra o estado.
• Um salvamento por visão. Sair com alterações não salvas pergunta primeiro.
• Um controle é desabilitado enquanto sua própria ação está pendente, para que não possa ser acionado duas vezes.
• Um formulário curto ou um único campo edita em linha; um diálogo é para uma tarefa focada que não deve perder seu contexto.
• Campos de entrada usam o tipo correto e autocomplete (email, tel, one-time-code, …) para que telefones mostrem o teclado correto e navegadores os preencham.
• Um gatilho de upload de arquivo é um botão focalizável que abre o seletor e também aceita arrastar e soltar.
• Uma página que configura o que outra superfície desenha (um onboarding, uma marca, um modelo) mostra uma pré-visualização dessa superfície ao lado de suas configurações.

Ações e feedback

• Uma ação com caminho de volta (restaurar, desarquivar, reativar) é executada imediatamente e oferece desfazer, sem confirmação adicional. Um toggle é seu próprio desfazer e precisa apenas de feedback imediato.
• Uma ação sem caminho de volta recebe uma confirmação que nomeia o que é perdido ("Excluir 3 documentos"). Uma ação que parece reversível mas não tem reversão é tratada como irreversível até que a reversão exista.
• Cada ação responde dentro de 100ms: atualização otimista, estado pendente no controle ou um esqueleto onde o conteúdo chegará.
• Trabalho que leva mais de alguns segundos é executado em segundo plano com progresso visível e sobrevive à navegação.
• Erros dizem o que aconteceu e o que fazer em seguida, próximo a onde aconteceu.

A matriz de estados

Cada visão entrega todos os seus estados, projetados, não padrão:

Estado	Forma
carregamento	um esqueleto no layout que o conteúdo ocupará
vazio	diz o que pertence aqui e oferece a ação para adicioná-lo
filtrado-vazio	diz que o filtro não encontrou nada e oferece para limpá-lo
parcial	as partes que carregaram renderizam; a parte com falha mostra seu próprio erro, nunca zero
sem acesso	diz quem pode ver isso e como obter acesso, e oferece um caminho adiante
erro	o que falhou, uma repetição, o resto da tela ainda utilizável
completo	o conteúdo real em volume realista, com nomes longos e muitas linhas incluídas

Cada controle interativo tem estado padrão, hover, focus-visible, ativo, desabilitado e pendente.

Em um painel, cada tile e gráfico possui seus próprios estados: uma leitura com falha mostra seu próprio erro, nunca um zero ou um gráfico vazio. Um painel abre no que precisa de atenção, não em uma linha de cartões de métrica; um número aparece apenas com a comparação que o torna significativo (meta, período anterior) e uma definição na qual a equipe concorda. Os gráficos seguem o skill dataviz quando instalado.

Acessibilidade e temas

• O texto do corpo atende 4.5:1 de contraste, texto grande e limites de controle 3:1, em cada tema. Cinza suave sobre cinza é a falha mais comum.
• O foco é sempre visível e nunca cortado; o anel de foco é projetado, não o padrão do navegador removido.
• Cada controle tem um nome acessível; um botão apenas com ícone recebe aria-label. Marcos (nav, main) e um h1 por página.
• O texto redimensiona para 200% e o layout se mantém.
• Quando o aplicativo suporta um tema escuro, ele é projetado: seus próprios passos de superfície e um acento reajustado, não cores invertidas. Revise cada tela em ambos.

Ergonomia

• A tarefa principal é concluída pelo teclado: a ordem de tabulação segue a ordem de leitura, Enter envia, Escape fecha, o foco retorna de onde veio.
• Alvos de clique têm pelo menos 24×24px, os frequentes maiores, 44px em toque; a área de clique cobre toda a linha ou rótulo, não apenas o ícone.
• Ações frequentes ficam perto do que atuam. Distância e clique são testados.

Procedimento de revisão

Veja review.md para o script de captura de tela e a lista de verificação a executar antes de considerar uma tela pronta.