Polimento de UI

O que Polimento de UI faz?

Uma tela pode estar bem organizada e ainda assim parecer inacabada: duas colunas de campos que ficam 17px fora de alinhamento, caixas de 88px em um telefone de 390px, uma palavra de unidade arrastando cada campo, um link que você não consegue tocar com o polegar. As pessoas sentem isso instantaneamente; modelos que revisam screenshots raramente veem. Este skill mede primeiro, julga depois, e só considera um defeito corrigido quando a medição diz que sim.

Entradas

Peça apenas o que está faltando.

1. Alvo. Uma URL, ou um arquivo HTML, ou o componente em um repositório mais uma URL onde ele renderiza. Você precisa de uma forma de renderizá-lo; se não conseguir renderizar nada, diga isso e recorra apenas à rubrica, marcando cada verificação medida como "não medido".
2. Escopo (opcional). Um seletor CSS para a parte da página a ser polida, por exemplo, o formulário ou main. Padrão: main, senão body.
3. Referência (opcional). Uma tela que o usuário considera melhor (uma URL, arquivo ou screenshot). Meça-a também e use-a como direção para a aparência; nunca copie sua marca, conteúdo ou alegações.

Fluxo de Trabalho

1. Meça a tela atual

Execute o script incluso (precisa de Node e Playwright com Chromium; instale com npm i -D playwright && npx playwright install chromium se o projeto não tiver):

node <skill-dir>/scripts/measure.cjs <arquivo-ou-url> --out ui-polish/before [--scope "<seletor>"] [--primary "<seletor>"] [--hide "<seletor>,…"] [--profile form|content]

• Ele renderiza em telefone (390×844) e desktop (1366×900) (código de saída 1 enquanto houver achados de erro, 2 em erros de uso, 3 quando a execução falha), escreve measure.json em --out (resolvido em relação ao diretório atual) com duas screenshots por viewport, <viewport>.png (a primeira tela) e <viewport>-scope.png (todo o escopo, incluindo qualquer coisa abaixo da dobra), e imprime cada achado com um seletor. Elementos que compartilham uma causa são um único achado com uma contagem e seletores de exemplo, e um achado que é o mesmo no telefone e no desktop é impresso uma vez, com ambos em viewports (use viewports, não viewport, ao filtrar um achado mesclado por viewport).
• Scripts estão desligados por padrão para que o layout estático seja medido; adicione --js para páginas que só renderizam com JavaScript. --offline bloqueia toda requisição de rede exceto a página alvo (hermético); --assets-only também permite o carregamento de fontes, folhas de estilo e imagens remotas, para cópias salvas que precisam de suas fontes, e entra em contato com esses hosts.
• --hide define display: none em sobreposições como um banner de cookies ou um lançador de chat antes de medir e capturar, para que não cubram as screenshots nem adicionem achados. Um seletor --hide que não corresponde a nada imprime um aviso.
• --profile content é para artigos e outras páginas de texto longo: ele pula as verificações construídas para etapas de formulário (type-scale, action-distance, action-below-fold, dead-space). O padrão é form.
• Vários alvos em uma única execução (measure.cjs <pagina1> <pagina2> … --out dir) vão cada um para dir/<slug>/, e dir/summary.json mescla um achado que se repete em várias páginas em uma linha listando as páginas; corrija um componente compartilhado uma vez. Compare página por página (--compare before/<slug>/measure.json after/<slug>/measure.json).
• Verificações e limites, e a correção usual para cada um, estão em reference/checks.md. Erros falham a execução; avisos precisam de uma correção ou de uma razão declarada.
• Declare uma razão uma vez, não a cada execução: um ui-polish.config.json no diretório atual (ou --config <arquivo>) lista decisões aceitas, por exemplo, { "ignore": [{ "check": "text-size", "selector": ".eyebrow", "reason": "rótulos de kicker da marca" }] }. Achados correspondentes vão para accepted com a razão, são impressos em sua própria seção e não afetam o código de saída. Apenas registre uma decisão que o proprietário tomou; nunca adicione uma para fazer os números passarem.

Se uma referência foi fornecida, meça-a da mesma forma em ui-polish/reference.

2. Observe

Abra as screenshots (as -scope.png mostram todo o escopo) e percorra todos os dez pontos de reference/rubric.md. Escreva uma tabela de veredito com uma linha por ponto (e uma linha por subverificação do ponto 10): passa, falha ou n/a, o problema localizado e a correção. Julgue apenas o que está na tela. As medições são evidência para a rubrica, não um substituto para ela: uma tela com zero achados medidos ainda pode falhar em hierarquia, rótulos e unidades, agrupamento ou confiança, e essas são geralmente as falhas que as pessoas notam primeiro.

3. Planeje as correções

Liste cada achado medido e cada ponto da rubrica que falhou com sua correção, agrupados pelo elemento que tocam. Prefira correções estruturais que removam vários achados de uma vez (por exemplo, rótulos acima de campos em uma grade de duas colunas corrige alinhamento, larguras iguais, preenchimento de campo, posicionamento de rótulo e nomes acessíveis juntos) em vez de corrigir cada achado individualmente. Ordene por impacto na pessoa que usa a tela.

4. Aplique as correções na fonte

Edite a fonte real: o componente e seus estilos em um repositório, ou o arquivo HTML. Regras:

• Mantenha o trabalho e o conteúdo. Mesmas perguntas, mesmas entradas e unidades, mesmas ações, mesma marca. Não remova recursos para fazer uma verificação passar.
• Não invente nada. Não adicione fatos que a tela não declarou em palavras: contagens de etapas, tempos, preços, alegações clínicas, legais ou de privacidade. Um valor que você calculou a partir do código (um aria-valuenow de barra de progresso, uma largura CSS, um nome de rota) ainda não foi declarado; coloque-o entre colchetes também. Se o design precisar de tal texto, use um placeholder entre colchetes (Pergunta [n] de [N], [~3] minutos, [Por que perguntamos: …]) e liste-o para o proprietário preencher.
• Use o sistema que existe. Reutilize os tokens, componentes e escala de espaçamento do projeto; adicione novos valores apenas quando nenhum servir.
• Mantenha funcionando. Cada controle ainda deve fazer o que fazia (e, onde estava quebrado, funcionar). Mantenha o foco do teclado visível.

5. Remeça até passar

node <skill-dir>/scripts/measure.cjs <arquivo-ou-url> --out ui-polish/after [mesmas opções]
node <skill-dir>/scripts/measure.cjs --compare ui-polish/before/measure.json ui-polish/after/measure.json

A etapa de comparação também lista cada pedaço de novo texto para o proprietário revisar e falha com invented-number quando o novo texto contém um número fora de [colchetes] (por exemplo, "Passo 2 de [5]": o 2 nunca foi declarado).

Repita as etapas 4–5 até que não haja erros, todo aviso restante seja corrigido ou tenha uma razão declarada, e todo ponto da rubrica que falhou seja corrigido ou tenha uma razão declarada, no máximo três rodadas. Repercorra a rubrica nas novas screenshots a cada rodada. Zero erros não é suficiente: avisos como alvos de toque de 36px ou rótulos finais são exatamente os detalhes para os quais este skill existe para finalizar. Abra as novas screenshots a cada rodada: uma verificação pode passar enquanto a tela parece pior, e isso conta como uma regressão.

6. Relate

• Screenshots de antes e depois no telefone e desktop.
• A saída da comparação: corrigido, restante (com a razão), novo e aceito (com a razão do config).
• A tabela de veredito da rubrica antes e depois, com o porquê de qualquer coisa ainda falhando.
• Cada placeholder entre colchetes que o proprietário precisa preencher.
• Qualquer coisa que precise de uma decisão de produto em vez de polimento (encaminhe para design-review ou o proprietário).

Pegadinhas

• Screenshots escondem geometria. Um deslocamento de coluna de 17px ou um campo de 88px em uma tela de 390px é óbvio para uma pessoa e invisível em uma screenshot reduzida. Confie nos números para geometria e em seus olhos para equilíbrio e hierarquia.
• Uma palavra de unidade no final é a causa usual de colunas desalinhadas. "Pés" e "Quilos" têm larguras diferentes, então tudo depois delas muda. Coloque rótulos acima dos campos.
• Edições pequenas em arquivos grandes permanecem pequenas. Quando a fonte é um arquivo grande gerado, edite a marcação e os estilos do formulário como um bloco em vez de corrigir atributo por atributo, ou o layout nunca mudará.
• Parar quando os números passam é a falha clássica. Geometria é apenas metade do polimento; a outra metade é a rubrica (um cabeçalho real, uma alternância de modo em vez de um link por campo, uma razão para perguntas sensíveis, orientação).
• Um token, muitos achados. Um achado de texto pequeno ou alvo de toque que se repete em cada página geralmente vem de um token de sistema de design ou componente. Corrija lá, ou registre a decisão do proprietário em ui-polish.config.json, em vez de triar página por página.
• Verificações passando não é o objetivo. Uma tela focada com um cabeçalho claro, campos agrupados e uma ação primária próxima é. Use as verificações para provar que você chegou lá.

---

Construído por aictrl.dev. Este skill ensina o fluxo de trabalho; aictrl operacionaliza — fundamentado no seu backlog, padrões de equipe e grafo de conhecimento do código. Veja como →