Interface Review: revise diffs de UI sem culpar o código antigo

ANÁLISE EDITORIAL

Uma revisão de interface costuma dar errado antes mesmo do primeiro comentário: o avaliador olha a tela atual, encontra problemas antigos e devolve ao autor uma lista que pouco diz sobre a mudança submetida. A Interface Review parte de outra pergunta: o que este diff introduziu, regrediu ou apenas tocou sem causar? A Skill resolve o alvo, lê os dois lados da alteração, expande o impacto para consumidores diretos e entrega as evidências ao conjunto better-*, que cobre interface, tipografia, cor, acessibilidade, layout e texto de produto.

Isso faz dela uma ferramenta de revisão de mudança, não um selo automático de qualidade e nem uma auditoria completa do produto. O valor está em manter o parecer proporcional ao que foi alterado. Nesta curadoria, o repositório jakubkrehel/skills tinha 6.867 estrelas e 245 forks, consulta realizada em 18 de setembro de 2026. O pacote foi fixado no commit 267330e1adfc66a718fb65fa6918c1f06d0a689e, sob licença MIT.

O que esta Skill faz

A Interface Review organiza uma revisão de alterações de UI em quatro movimentos. Primeiro, identifica o alvo solicitado: uma branch, modificações locais, área em stage, um pull request ou um intervalo de commits. Depois, registra a base, o head, o número de commits, os arquivos incluídos e o que ficou de fora. Em seguida, procura superfícies afetadas além dos arquivos alterados, porque uma modificação em token, componente compartilhado ou texto reutilizado pode aparecer em vários lugares. Por fim, classifica cada achado como Introduced, Regression ou Pre-existing.

A diferença não é cosmética. Um controle que perdeu seu nome acessível nesta alteração é uma regressão. Um problema que já existia próximo ao trecho editado é preexistente e não deve transformar a revisão em cobrança de todo o legado. Uma nova variante sem estado de foco pode ser introduzida pelo diff. A Skill mantém essas responsabilidades separadas e encaminha os achados para a better-interface, que aplica os critérios de domínio, consolida duplicações e emite o veredito.

Ela também obriga a leitura das linhas removidas. Esse detalhe evita a revisão que enxerga somente o estado final e perde sinais apagados, como um atributo de acessibilidade, um tratamento de foco, uma opção de movimento reduzido ou uma mensagem importante. A remoção é apenas uma pista. Só vira regressão quando a mudança não oferece substituição equivalente e a Skill de domínio confirma o problema.

Para quem serve

A Skill é útil para designers que trabalham perto do código, desenvolvedores de front-end, responsáveis por design systems e revisores de pull requests com impacto visual. Ela ajuda especialmente quando o repositório tem componentes compartilhados e quando um parecer genérico sobre “a tela” seria amplo demais. Também serve para equipes que querem distinguir dívida antiga de responsabilidade da mudança atual, sem esconder riscos reais.

Ela não substitui revisão de correção funcional, testes, segurança ou desempenho. A própria instrução orienta que essas preocupações sejam nomeadas uma vez e encaminhadas ao processo geral de code review. Para uma análise ampla de uma tela já pronta, sem vínculo com um diff, a opção mais próxima no catálogo é a Open Design Critique. A Interface Review é diferente: seu objeto é a mudança e seu resultado precisa explicar causalidade.

Origem, adoção e versão

O mantenedor é Jakub Krehel. A fonte principal é a pasta skills/interface-review. O arquivo SKILL.md auditado declara invocação manual e não informa uma versão própria. Por isso, esta página não inventa um número de release: a referência reproduzível é o commit completo, datado de 29 de agosto de 2026.

As 6.867 estrelas registram a adoção do repositório inteiro no momento da consulta, não o número de usuários desta Skill isolada. A licença MIT permite redistribuição com preservação do aviso. O repositório não estava arquivado e apontava main como branch padrão durante a verificação.

Compatibilidade e pré-requisitos

O uso pressupõe um agente que entenda Skills em Markdown e tenha acesso de leitura a um repositório Git. O projeto precisa conservar histórico suficiente para calcular merge-base, comparar referências e, quando necessário, ler a versão base de um arquivo. Para revisar pull requests, o agente também precisa conseguir consultar a origem remota ou receber as referências previamente baixadas.

A Interface Review não trabalha sozinha. Ela depende da better-interface e das Skills de domínio better-ui, better-typography, better-colors, better-accessibility, better-layout e better-writing. O pacote local do Bastidores inclui essas oito pastas documentais, justamente para não oferecer um arquivo principal incapaz de concluir o fluxo. Nenhuma aplicação, runtime ou dependência foi incluída.

Instalação

O caminho documentado pelo mantenedor é executar npx skills add jakubkrehel/skills. Esse comando usa um pacote externo e pode baixar conteúdo do catálogo, portanto confira a origem do npx, o destino e os arquivos apresentados antes de confirmar. A documentação também descreve instalação como plugin do Claude Code, mas isso não transforma a Skill em recurso nativo de todos os agentes.

Para auditoria offline, use o botão “Baixar pacote auditado” nesta página. Descompacte em uma pasta de inspeção e comece por interface-review/SKILL.md. Confira depois better-interface/SKILL.md e as sete pastas de domínio. O arquivo ORIGEM.md registra commit, licença e escopo. Instalar para uso funcional é uma decisão separada da leitura do espelho.

Configuração antes do primeiro uso

Defina explicitamente o alvo. A Skill aceita branch, working, staged, pr 482 ou um intervalo Git. Se nenhum alvo for dado, ela procura primeiro commits à frente do merge-base e inclui alterações não commitadas; depois considera a árvore de trabalho suja. Se não houver mudança, deve parar e perguntar, nunca escolher HEAD~1..HEAD por conta própria.

Confirme a branch padrão e a referência base. Em repositórios com vários remotos, origin/main pode não ser o ponto certo. Defina também as exclusões esperadas, como lockfiles, snapshots, conteúdo gerado, dependências vendorizadas e binários. Essas exclusões precisam aparecer no relatório para que “cobertura completa” não esconda arquivos ignorados.

Por padrão, a expansão do raio de impacto vai um salto até importadores ou chamadores diretos. Tokens, temas e primitivas compartilhadas podem exigir um segundo salto. O limite proposto é de até cinco consumidores, ordenados por relevância; os demais devem ser contados e declarados. Essa regra protege o escopo sem fingir que um componente compartilhado termina no arquivo do diff.

Primeiro uso seguro

Comece em um repositório de teste ou em uma alteração pequena. Um pedido possível é: “use Interface Review no conjunto staged, mantenha a revisão somente leitura e marque como não verificadas as afirmações visuais sem preview”. O agente deve devolver um bloco de escopo antes dos achados, com base, head, commits, arquivos, exclusões e superfícies expandidas.

Leia esse bloco primeiro. Se o alvo não corresponder ao que você queria revisar, interrompa antes de discutir detalhes. Em seguida, confira se cada achado tem localização, situação anterior, correção sugerida, justificativa e status causal. A tabela de cobertura deve dizer “não revisado” quando o diff não contém evidência de determinado domínio, em vez de preencher lacunas com suposição.

Se o agente encontrar uma árvore limpa e nenhum commit à frente da base, o resultado correto é uma pergunta com opções: último commit identificado, alvo nomeado ou auditoria ampla do repositório. “Approve” sobre uma mudança inexistente seria um resultado enganoso.

Como o fluxo organiza o trabalho

A resolução detalhada está em scope-resolution.md. Os sinais a procurar nas linhas removidas estão em removed-signals.md. Já as escalas e os critérios finais pertencem à better-interface e às referências de UI, tipografia, cor, acessibilidade, layout e escrita.

Essa arquitetura evita duas confusões comuns. A primeira é duplicar regras de domínio na Skill de orquestração, criando critérios divergentes. A segunda é chamar todo defeito visível de “causado pelo PR”. A Interface Review mantém o status preso ao diff, enquanto as Skills especializadas decidem se a evidência constitui um problema de fato.

Resultado esperado

O relatório deve começar pelo escopo e continuar com cobertura. Depois vêm apenas achados introduzidos ou regressões acionáveis. Problemas preexistentes ficam em uma seção própria, limitada a três itens de maior severidade, e não influenciam o veredito da mudança. Quando não houver achados introduzidos nem regressões, a frase esperada é clara: “No actionable interface findings in this change.”

O veredito final é Block quando resta algum achado de alta severidade e Approve nos demais casos, seguindo as regras da better-interface. Isso não significa que todos os aspectos do produto foram testados. Significa apenas que a mudança, dentro do escopo declarado e dos domínios efetivamente revistos, não deixou bloqueadores segundo esse método.

Permissões e riscos

No fluxo padrão, a Skill lê arquivos, histórico Git, metadados do diff, mensagens de commit e, em um PR, título e descrição. Esses dados podem conter código privado, strings de clientes, caminhos internos e discussões sensíveis. Use somente em repositórios autorizados e confira para onde o agente envia contexto.

A instrução proíbe modificar a árvore de trabalho. Ela permite git fetch, que grava somente em .git, mas proíbe checkout, switch e stash durante a revisão. Para validação renderizada, o comportamento é opt-in: use um worktree isolado, não a cópia em que o autor está trabalhando. Sem preview barato ou autorização, alegações visuais e de runtime devem ser marcadas como “não verificadas”.

O relatório ainda pode errar. A seleção de consumidores é limitada, uma branch base incorreta distorce o diff e um projeto com geração de código pode ocultar a verdadeira origem de uma superfície. O parecer precisa ser revisado por uma pessoa que conhece o produto. Não trate “Approve” como certificação de acessibilidade, segurança, funcionamento ou conformidade.

Erros comuns e como corrigir

A revisão escolheu a alteração errada

Volte ao bloco de escopo. Nomeie explicitamente o PR, a branch, o stage ou o intervalo. Confirme merge-base, referência padrão e contagens separadas de commits e arquivos locais. Uma pequena edição solta não deve esconder os commits da branch.

A Skill parou depois do inventário

Verifique se better-interface e as Skills better-* estão disponíveis. A parada é intencional quando a dependência de domínio não existe: a Interface Review não deve inventar uma escala de severidade ou um veredito alternativo.

O relatório culpa o PR por código antigo

Peça confirmação contra a referência base e, quando necessário, git blame na versão base. O status depende do que o diff mudou, não da proximidade física com o hunk. Mova o item para “Pre-existing” se ele já existia.

O diff é grande demais

Divida a revisão por superfícies ou intervalos e declare cada limite. Preserve o inventário completo, as exclusões e a quantidade de consumidores não expandidos. Não reduza silenciosamente o escopo e continue chamando o parecer de completo.

O agente descreveu um problema visual sem abrir a interface

Marque a afirmação como não verificada ou autorize uma revisão renderizada em ambiente isolado. Código e diff sustentam hipóteses, mas não provam sozinho o comportamento visual no navegador, a ordem de foco ou a experiência com tecnologia assistiva.

Versão, licença e pacote auditado

• Skill: sem versão própria declarada.
• Commit: 267330e1adfc66a718fb65fa6918c1f06d0a689e.
• Licença: MIT, verificada no arquivo raiz.
• Consulta de adoção: 6.867 estrelas e 245 forks em 18/09/2026.
• SHA-256 do ZIP local: 018346976e26a9a7345783ceb77d02e377325c6870409b04b4d48479995d6815.

O ZIP reúne 47 arquivos: documentação da Interface Review, documentação das sete Skills de domínio e da orquestradora better-interface, oito referências YAML, a licença MIT e o registro ORIGEM.md. O checksum permite conferir se o download recebido corresponde ao artefato revisado nesta publicação.

Limites do pacote local

O espelho é documental. Ele não contém executáveis, binários, dependências, aplicações, repositórios de exemplo, capturas, resultados, credenciais ou dados. Ele também não instala um agente nem garante integração automática com sua ferramenta. O pacote conserva as instruções necessárias ao fluxo descrito, mas você ainda precisa colocá-las em um ambiente compatível e aprovar os acessos reais.

A ilustração de capa desta página é uma composição editorial original do Bastidores da IA. Não é captura real de produto, interface executada, relatório produzido pela Skill ou prova de resultado.

Checklist antes de usar

• Confirme que o alvo é exatamente a mudança que você pretende revisar.
• Verifique base, head, commits, arquivos, exclusões e consumidores expandidos.
• Instale ou disponibilize a better-interface e as sete Skills de domínio.
• Mantenha a árvore de trabalho somente leitura e use worktree isolado para renderização.
• Trate achados visuais sem preview como não verificados.
• Separe Introduced, Regression e Pre-existing antes do veredito.
• Revise o relatório com alguém que conheça o produto e os critérios da equipe.

Fontes oficiais consultadas

• Repositório oficial e instrução de instalação.
• Interface Review no commit auditado.
• Skill de acessibilidade incluída.
• Skill de escrita de produto incluída.
• Licença MIT do repositório.