UI declutter

O que UI declutter faz?

Edite uma interface para que cada palavra e ornamento nela esteja lá para a pessoa que a usa. Telas geradas tendem a se explicar: um rótulo acima do título, uma frase abaixo dele, uma dica ao lado do botão. Cada adição parece inofensiva, e juntas elas enterram as três palavras que o usuário veio buscar.

O objetivo é uma tela que sirva ao seu usuário. Não é uma tela que evite parecer gerada. A diferença importa quando uma regra e a necessidade do usuário discordam: a necessidade do usuário vence, e você diz isso no relatório.

Alvo: o arquivo, pasta ou componente que o usuário nomeou. Se não nomeou nenhum, use os arquivos de interface alterados nesta conversa. Se não houver nenhum, pergunte.

Escopo: copiar, ações, estados, conteúdo inventado, decoração e gráficos. A superfície visual (regras X1 a X4) só é incluída quando o usuário pedir, em palavras ou com --surface.

Passo 1: diga quem está nesta tela

Antes de ler uma única string, escreva uma linha:

Quem: um jogador no meio de uma missão que pressionou Esc. Fazendo: decidindo se volta, muda uma configuração ou reinicia.

Esta linha é o que você julga tudo contra. Sem ela, as regras abaixo são aplicadas como um casamento de padrões, e um casamento de padrões corta os requisitos de senha junto com o filler. Um visitante de primeira viagem em uma página de preços precisa de mais palavras do que um usuário diário de uma tabela administrativa. Um jogo pode carregar texto de sabor que um formulário de imposto não pode.

Se o código não lhe disser quem é o usuário, infira a partir do produto e declare a inferência. Pergunte apenas se duas leituras plausíveis levariam a edições diferentes.

Passo 2: o teste

Para cada pedaço de texto visível e cada elemento decorativo, pergunte:

Sem isso, essa pessoa hesitaria, cometeria um erro ou se surpreenderia com o que acontece a seguir?

• Não → corte.
• Não, mas alguém precisa disso em algum lugar → mova. Um fato para desenvolvedores vai em um comentário de código. Um fato que alguns usuários procuram vai em uma tooltip ou na documentação. Um nome que apenas a tecnologia assistiva precisa vai em aria-label.
• Sim, mas está mal dito → reescreva, usando apenas fatos que você pode encontrar no código, no conteúdo ou na conversa.
• Sim → mantenha e deixe como está.

As regras que se seguem são as formas comuns como telas geradas falham neste teste. Elas ajudam você a identificar candidatos rapidamente. Quando uma tela falha no teste de uma forma que nenhuma regra nomeia, o teste ainda se aplica. Quando uma regra sinaliza algo que passa no teste, mantenha.

Texto que merece uma frase completa

Estes passam no teste quase sempre. Não os encurte para um rótulo e não os corte:

• Restrições que o usuário deve satisfazer: regras de senha, tipos e tamanhos de arquivo aceitos, formatos de data e número, limites de caracteres.
• Consequências: o que uma ação destrutiva ou irreversível remove, o que um pagamento cobra e quando, o que uma permissão concede, quem verá algo depois de compartilhado.
• Erros: o que deu errado e o que fazer a seguir.
• Estados vazios: o que pertence aqui e como adicionar o primeiro.
• Texto de consentimento, legal e regulatório. Nunca edite seu texto. Relate se parecer errado.
• Instruções para uma tarefa que o usuário faz raramente e não pode desfazer.

Regras

Os IDs são estáveis. Cite-os no relatório.

Cópia

• C1. Rótulos de sobrancelha. Texto pequeno em maiúsculas ou com espaçamento acima de um título ("FUNCIONALIDADES", "COMO FUNCIONA", "OPERAÇÃO EM ESPERA" acima de "PAUSADO"). O título já nomeia a seção, então corte a sobrancelha. Se a sobrancelha for a linha melhor (texto de sabor em um jogo, um termo próprio do produto), promova-a para ser o título e corte o genérico. Um dos dois, nunca ambos.
• C2. Numeração decorativa. "01 02 03", "01 // Funcionalidades", prefixos "§" e "//". Corte, a menos que a ordem seja real e o usuário a siga, como em etapas de checkout ou um guia de instalação.
• C3. Reflexo de subtítulo. Uma frase abaixo de cada título, uma descrição abaixo de cada item de menu ("Configurações: Atualize suas configurações"). Mantenha apenas quando ela afirmar um fato que o título não afirma.
• C4. Narração. Texto de ajuda e legendas que descrevem o que o elemento visivelmente é ou faz ("Clique no botão abaixo para começar", "Este cartão mostra sua atividade recente"). Corte.
• C5. Notas de implementação vazadas. Texto sobre como a tela funciona internamente, ou um requisito do prompt renderizado como cópia: "Resume recaptura o mouse", "(atualiza em tempo real)", "(alimentado por IA)", "Os dados são armazenados em cache por 5 minutos". O usuário não age com base nisso. Mova para um comentário de código ou corte.
• C6. Strings de status. Fatos encadeados com "·" ou "|" ("12 itens · Atualizado há 2 min · Sincronizado · v2.1"). Mantenha o fato sobre o qual o usuário age. Coloque os outros onde são necessários ou corte.
• C7. Dicas duplicadas. Um rótulo que repete o placeholder, o ícone, o texto do botão ou o título da seção. Mantenha um. Para campos de formulário, mantenha o rótulo visível: um placeholder desaparece na entrada e não é um nome acessível.
• C8. Slogans. "Um. Grande. Negócio.", "Construído de forma diferente.", "Envie mais rápido. Pense menos." Reescreva como uma frase que nomeie a coisa e o que ela faz, se a fonte lhe der esses fatos. Caso contrário, sinalize para o proprietário.
• C9. Títulos de seção genéricos. "Por que nos escolher", "Tudo que você precisa", "Construído para equipes como a sua". Um título que poderia estar na página de qualquer produto não diz nada sobre este. Renomeie para o que a seção contém ou corte o título se o conteúdo se mantiver sem ele.
• C10. Sobrecarga de dicas. Tooltips em controles que já têm um rótulo de texto, chips de atalho de teclado em cada ação, chamadas "Dica:" e "Dica profissional", marcações de orientação em uma tela comum. Mantenha uma dica onde o controle é ambíguo (um botão apenas com ícone) ou o atalho é a principal forma de usá-lo.

Ações

• A1. Rótulos de ação vagos. "Começar", "Saiba mais", "Enviar", "Continuar", "OK", "Clique aqui". Um botão diz o que acontece quando é pressionado: um verbo, e um objeto quando o verbo sozinho é ambíguo ("Criar conta", "Exportar CSV", "Enviar convite"). "Continuar" e "Próximo" são aceitáveis dentro de um fluxo de etapas.
• A2. Uma ação, vários nomes. "Excluir" em uma tela, "Remover" na próxima e "Lixeira" no menu para a mesma operação, ou "Entrar" ao lado de "Fazer login". Escolha o termo que o projeto mais usa e aplique-o em todo o alvo. Onde dois termos nomeiam operações diferentes (remover de uma lista versus excluir permanentemente), deixe ambos.
• A3. Diálogos de confirmação. "Tem certeza?" com "OK" e "Cancelar". O título nomeia a ação e seu objeto ("Excluir 3 projetos?"), o corpo declara a consequência se houver ("Isso também remove suas 14 tarefas. Você não pode desfazer isso.") e o botão de confirmação repete o verbo ("Excluir projetos"). Uma confirmação em uma ação que é trivialmente desfeita é por si só poluição: sinalize para o proprietário.

Estados

Texto de carregamento, sucesso, vazio e erro é onde o filler se acumula, porque ninguém olha para esses estados ao revisar uma tela. Leia references/states.md antes de editar qualquer um deles: ele diz o que cada estado deve conter, que é mais do que o que cortar.

• S1. Filler de carregamento. "Aguente firme!", "Calculando os números…", "Só um momento enquanto preparamos as coisas". Nomeie o que está carregando apenas se a espera for longa o suficiente para lê-lo. Caso contrário, um spinner ou esqueleto sozinho.
• S2. Filler de sucesso. "Salvo com sucesso!", "Suas alterações foram salvas com sucesso." Declare o resultado em quantas palavras o carregarem ("Salvo", "Convite enviado para [email protected]"). Se a tela já mostra o resultado, nenhum toast.
• S3. Filler de estado vazio. "Nada aqui ainda!", "Parece que você ainda não criou nenhum projeto. Comece criando seu primeiro projeto!" Diga o que vai aqui e dê a única ação que o adiciona.
• S4. Erros vagos ou fofos. "Ops! Algo deu errado", "Ocorreu um erro. Tente novamente mais tarde." Diga o que falhou e o que o usuário pode fazer. Se o código não puder saber o que falhou, diga isso claramente e dê a opção de tentar novamente.

Conteúdo inventado

• F1. Prova inventada. Contagens de usuários, números de uptime, classificações por estrelas, depoimentos com nome e cargo, linhas de logotipo "Confiado por", "Como visto em". Se o projeto não tem fonte para isso, é uma afirmação falsa em uma página publicada. Não a reescreva em uma afirmação falsa menor. Remova-a e liste-a no relatório para que o proprietário possa fornecer a coisa real.
• F2. Dados de espaço reservado em telas publicadas. "João Silva", "Acme Corp", lorem ipsum, endereços example.com, serviços de avatar padrão. Em fixtures, testes e histórias, isso é aceitável. Em uma tela publicada, relate como uma tarefa. Você não pode fornecer dados reais.

Decoração

• D1. Badges sem estado. "NOVO", "AO VIVO", "IA", "Beta", "Pro", "Popular" adicionados por sabor. Mantenha um badge apenas quando ele refletir algo que o aplicativo rastreia.
• D2. Pontos de status. Pontos pulsantes ou coloridos ao lado do texto. Mantenha apenas quando vinculados a um status real e dê a eles um nome acessível.
• D3. Emoji e ícones decorativos. Em títulos, botões, rótulos e itens de lista. Corte. Um ícone permanece quando é o controle (um botão de ícone com um aria-label) ou quando carrega um significado que o texto não carrega.

Gráficos e painéis

• V1. Títulos que nomeiam o tipo de gráfico. "Gráfico de barras da receita mensal" torna-se "Receita mensal". Declare a descoberta ("A receita dobrou desde março") apenas se os dados à sua frente mostrarem isso.
• V2. Instruções de leitura. "Cada barra representa um mês", "Passe o mouse para detalhes". Corte.
• V3. Dizer duas vezes. Uma codificação por quantidade. Um KPI com uma seta, uma porcentagem, a palavra "acima" e uma frase reafirmando todos os três mantém o número e uma comparação.
• V4. Andaime que compete com os dados. Molduras de gráfico, linhas de grade escuras ou densas, bordas grossas de eixo, 3D, sombras e brilhos em marcadores. Corte ou afine o que deve permanecer para um traço fino. Mesmo tipo de gráfico, mesmos dados, mesmas cores de série.
• V5. Legenda onde um rótulo direto funciona. Com quatro séries ou menos e espaço para rotulá-las, nomeie cada série no final de sua linha ou ao lado de sua barra e remova a legenda.

Superfície (apenas quando solicitado)

Leia references/surface.md primeiro. Ele começa com uma verificação de intenção de design que decide se essas regras se aplicam: um jogo, uma página de marketing ou um layout editorial com tipografia de exibição deliberada não é um defeito a ser normalizado.

• X1. Gradientes e brilhos. Gradientes de matiz para matiz em superfícies e botões, texto com gradiente, brilhos coloridos, manchas de cor desfocadas.
• X2. Espaçamento fora de escala. Valores únicos como mt-[13px] ou gap: 7px onde os irmãos usam a escala.
• X3. Pesos pesados em UI em execução. 800 e 900 em texto do corpo, rótulos, células de tabela e controles. Títulos de exibição estão fora do escopo.
• X4. Movimento decorativo. transition-all, cartões que escalam ao passar o mouse, saltos e loops que não explicam nada.

Para estilo em nível de string no que você mantém ou reescreve (maiúsculas/minúsculas, pontuação, palavras de preenchimento, consistência), leia references/writing.md. Para exemplos trabalhados de antes e depois, incluindo casos onde a edição correta é manter o texto, leia references/examples.md quando não tiver certeza de até onde cortar.

Barreiras de proteção

• Nunca adicione um fato. Uma reescrita usa o que está no código, nos arquivos de conteúdo, nos dados ou na conversa. "As edições sincronizam em segundos" é uma afirmação do produto, e você não sabe que é verdade. Se a reescrita honesta precisar de um fato que você não tem, corte a linha ou liste-a como uma tarefa para o proprietário. Esta é a regra mais facilmente quebrada, porque um inventado específico parece melhor do que a linha vaga que substitui.
• Altere apenas texto visível e elementos decorativos. Deixe lógica, dados, cores, tipo e estrutura de layout em paz. As exceções são o andaime de gráfico sob V4 e as regras de superfície quando solicitado.
• Mantenha nomes acessíveis. Nunca exclua aria-label, alt, title em botões de ícone ou texto apenas para leitores de tela. Se o texto visível que você cortou era o único nome acessível, mova-o para aria-label.
• Edite o texto em sua origem. Strings de arquivos i18n, props, fixtures ou um CMS são editadas lá, ou relatadas. Não codifique uma substituição no componente. Quando você alterar uma string em um arquivo de localidade, liste as outras localidades como tarefas; não as traduza você mesmo, a menos que solicitado.
• Limpe após um corte. Remova o wrapper que agora está vazio e a margem ou gap que existia apenas para o elemento removido.
• Deixe uma tela limpa em paz. Se nada falhar no teste, não mude nada.
• Siga o projeto. Onde o projeto tem seu próprio guia de voz, glossário, tokens ou sistema de design, corrija em direção a esses e não para os padrões deste skill.

Procedimento

Acompanhe estas etapas:

- [ ] 1. Quem e fazendo: uma linha
- [ ] 2. Contagem: python3 scripts/count_tells.py <alvo>      (adicione --surface se solicitado)
- [ ] 3. Olhe: capture a tela se puder
- [ ] 4. Leia cada string visível e ornamento em cada estado; aplique o teste; marque falhas com um ID de regra
- [ ] 5. Veredito: pesado, leve ou nenhum
- [ ] 6. Edite
- [ ] 7. Conte novamente, olhe novamente
- [ ] 8. Relatório

scripts/ está na pasta deste skill. Execute o script pelo seu caminho completo.

Contagem. count_tells.py é uma passagem de regex sobre o código-fonte. Ele encontra candidatos e dá um número antes e depois para os padrões que têm uma assinatura de código. Ele não pode ver C3, C4, C5, C7, A2, V3 ou qualquer coisa que dependa de significado, e sinaliza usos legítimos. Trate sua saída como uma lista de lugares para olhar. Uma contagem que não chega a zero é aceitável quando o que resta é mantido de propósito.

Olhe. O código-fonte esconde o que o usuário vê: quais strings aparecem juntas, o que vem dos dados, o que uma exclusão faz ao layout. Se você tiver um navegador ou ferramenta de captura de tela, capture a tela antes e depois. Se não tiver nenhum, python3 scripts/screenshot.py <url-ou-arquivo-html> <out.png> faz isso onde Playwright está instalado. Verifique a imagem depois para lacunas órfãs, um título que perdeu sua hierarquia e controles que se moveram. Se você não puder renderizar a tela, diga isso no relatório.

Leia cada estado. A visualização padrão é uma fração da interface. Pesquise o alvo por branches de carregamento, vazio, erro, sucesso e desabilitado, toasts, diálogos e valida…

[truncado para tradução]