normalize

Visão geral da skill normalize

O que a normalize faz

A skill normalize audita uma funcionalidade de UI e a realinha com um design system já existente. Ela foi pensada para casos em que uma página, rota ou componente se desviou dos padrões estabelecidos de espaçamento, tipografia, tokens, estados ou design de interação.

Quem deve instalar a normalize

A skill normalize é mais indicada para times que já têm alguma linguagem de design em uso: uma biblioteca de componentes, guia de estilo, conjunto de tokens ou padrões recorrentes no produto. Ela é especialmente útil para engenheiros frontend, design engineers e mantenedores com apoio de IA que precisam corrigir superfícies inconsistentes sem redesenhar o produto inteiro.

O trabalho real que ela resolve

Em geral, o usuário não quer simplesmente “deixar isso mais bonito”. O que ele quer é:

• identificar onde uma feature quebra as convenções do sistema
• separar inconsistência cosmética de problemas estruturais de UI
• produzir mudanças que pareçam nativas ao produto
• evitar inventar novos padrões quando os existentes já deveriam ser reutilizados

Por que a normalize é diferente de um prompt genérico

O principal diferencial é que a normalize é explicitamente um fluxo de alinhamento com design system, e não um prompt aberto de redesign de UI. A skill orienta o agente a primeiro reunir contexto do sistema, analisar os desvios e evitar suposições quando os princípios de design não estiverem claros. Ela também depende de outra skill, /frontend-design, e pode exigir /teach-impeccable antes, caso ainda não exista contexto de design.

Cenários ideais e cenários em que não encaixa

Melhor encaixe:

• uma feature parece “fora do lugar” em relação ao restante do app
• tokens, espaçamento, tipografia ou uso de componentes estão inconsistentes
• o time quer mais consistência sem partir para um redesign amplo do produto
• já existe um fluxo de Design Systems, mas ele é aplicado de forma irregular

Mau encaixe:

• design de produto greenfield, sem sistema para servir de referência
• exploração de marca ou direção visual
• fluxos que precisam de estratégia de UX antes da limpeza de UI
• times que esperam correções automáticas sem fornecer contexto do repositório

Como usar a skill normalize

Contexto de instalação da normalize

O SKILL.md de origem não publica um comando de instalação no estilo pacote, então use a skill por meio do sistema hospedeiro de skills que oferece suporte a skills baseadas em GitHub. Se o seu ambiente usa o padrão comum de CLI, a instalação base é:

npx skills add https://github.com/pbakaus/impeccable --skill normalize

Mais importante do que a instalação é configurar as dependências: a normalize exige coleta de contexto com /frontend-design, e, se esse contexto ainda não tiver sido estabelecido, a skill instrui você a executar /teach-impeccable primeiro.

Pré-requisitos obrigatórios antes do primeiro uso

Antes de chamar a normalize, confirme que você tem:

• acesso ao repositório-alvo ou aos arquivos de UI relevantes
• alguma evidência de um design system: tokens, documentação, componentes compartilhados, guias de estilo, screenshots ou convenções
• permissão para inspecionar features vizinhas em busca de padrões comparáveis
• /frontend-design disponível no mesmo ambiente de skills

Sem esse contexto, a normalize terá de adivinhar — e a orientação original diz explicitamente para não adivinhar quando os princípios não estiverem claros.

Que entrada a normalize espera

A dica de argumento é:

[feature (page, route, component...)]

Na prática, as melhores entradas nomeiam uma superfície específica e dizem onde olhar. Exemplos:

• normalize settings billing page
• normalize /dashboard/reports route
• normalize AccountMenu component and related dropdown states

Essa skill funciona melhor em uma feature bem delimitada do que no “app inteiro”.

Como formular um bom pedido para a normalize

Um pedido fraco:

• “Normalize the UI.”

Um pedido melhor:

• “Normalize the /checkout flow to match our existing design system. Focus on spacing, form field hierarchy, button treatments, error states, and component reuse. Compare against our account settings pages and shared form components before changing anything.”

Por que isso ajuda:

• define o escopo
• aponta superfícies de comparação
• traz critérios de qualidade
• reduz a chance de um redesign desnecessário

Fluxo recomendado de uso da normalize

Um fluxo prático é:

1. Execute /frontend-design e siga o protocolo de coleta de contexto.
2. Se ainda não houver contexto de design utilizável, execute /teach-impeccable.
3. Peça para a normalize analisar uma feature.
4. Revise o plano antes de qualquer alteração de código.
5. Faça o agente implementar apenas o trabalho de normalização que foi acordado.
6. Revise novamente estados e variantes adjacentes para garantir que a correção não pare no happy path.

Essa sequência importa porque a normalize foi construída em torno de primeiro entender o sistema e só depois editar.

O que a normalize deve inspecionar primeiro

Como o suporte de repositório para essa skill é mínimo, o contexto do seu próprio repo é o que mais pesa. Peça ao agente para inspecionar:

• componentes de UI compartilhados
• definições de tokens
• documentação de design system ou guia de estilo
• páginas maduras e semelhantes dentro do produto
• padrões de formulário, tabela, modal, card e navegação
• estados atuais da feature: empty, loading, error, disabled, success

Se você fornecer apenas o componente-alvo, a qualidade da saída normalmente vai parar em uma limpeza cosmética.

Primeiro arquivo do repositório para ler

Na skill upstream em si, comece por:

• SKILL.md

Esse arquivo concentra praticamente toda a orientação disponível, incluindo a etapa obrigatória de preparação e a ênfase do fluxo da normalize em descobrir o design system antes de fazer mudanças.

Padrão prático de prompt da normalize para Design Systems

Se você estiver usando a normalize para trabalho de Design Systems, dê ao agente um conjunto de comparação. Exemplo:

“Use normalize on the TeamMembers page. First study our design system tokens, the shared table component, and the settings pages. Identify where this page diverges in spacing, typography, action placement, row density, empty states, and status badges. Propose a concise plan, then update the implementation to reuse existing patterns instead of introducing new ones.”

Isso é melhor do que pedir apenas “consistência”, porque nomeia dimensões observáveis.

Restrições e tradeoffs esperados

A normalize não é um botão mágico de “deixa perfeito”. Entre os tradeoffs:

• se o seu sistema for inconsistente, a skill pode expor ambiguidades em vez de resolvê-las de forma limpa
• uma normalização visual forte pode revelar problemas de UX mais profundos para os quais ela não deve inventar soluções
• parte dos desvios vem de requisitos de produto, não de implementação ruim
• consistência estrita pode entrar em conflito com necessidades locais da feature

A skill é mais confiável quando o sistema já está maduro o suficiente para ser consultado, e não inferido.

Erros comuns ao usar a normalize

Evite estes bloqueadores de adoção:

• pular /frontend-design
• pedir uma limpeza ampla do app inteiro de uma vez
• não fornecer componentes de referência ou páginas maduras
• deixar o agente inventar tokens ou padrões
• tratar normalização visual como substituto de revisão de produto ou acessibilidade

Como é um bom resultado com a normalize

Um bom resultado da normalize deve:

• reutilizar componentes e tokens existentes
• reduzir estilos pontuais e isolados
• fazer a feature parecer nativa ao produto
• preservar a intenção da feature enquanto melhora a consistência
• explicar por que cada mudança se alinha aos padrões estabelecidos

Se a saída se resumir a trocar cores e espaçamentos sem raciocínio sobre padrões, provavelmente faltou contexto no seu input.

FAQ da skill normalize

A normalize é amigável para iniciantes?

Sim, com algumas proteções. Uma pessoa iniciante pode usar a normalize se conseguir apontar a feature-alvo e algumas boas superfícies de referência. Ela se torna menos amigável para iniciantes quando o codebase não tem um design system evidente ou quando os padrões do produto não estão documentados.

Preciso de um design system existente para usar a normalize?

Não necessariamente um site formal de design system, mas você precisa de evidências de padrões recorrentes. Componentes compartilhados, tokens, páginas estáveis e convenções visuais geralmente bastam. Se nada disso existir, a normalize deixa de ser uma boa escolha.

Qual a diferença entre a normalize e pedir para uma IA limpar a UI?

Um prompt comum costuma partir direto para as edições. A normalize é explicitamente voltada a encontrar e aplicar primeiro os padrões já existentes. Isso a torna melhor para trabalho de consistência, especialmente em produtos maiores, onde melhorias locais podem fragmentar ainda mais o sistema sem querer.

Quando não devo usar a normalize?

Não use a normalize quando você precisa de:

• uma direção visual totalmente nova
• exploração de design de produto em estágio inicial
• invenção de fluxos de UX em grande escala
• validação ampla de acessibilidade como tarefa principal
• uma estratégia completa de biblioteca de componentes do zero

Nesses casos, a normalize é estreita demais.

A normalize pode funcionar em um único componente?

Sim. Na verdade, esse costuma ser o melhor ponto de partida. Uma única seção de página, rota ou componente dá escopo suficiente para a skill raciocinar bem, mantendo as mudanças revisáveis.

A normalize serve só para polimento visual?

Não. A descrição de origem fala em padrões, tokens e convenções, o que normalmente inclui uso de componentes, hierarquia e tratamento de estados — não apenas styling superficial. Ainda assim, ela não substitui pesquisa profunda de UX.

Como melhorar a skill normalize

Dê à normalize alvos de comparação

A forma mais rápida de melhorar a saída da normalize é especificar como é o “bom” no seu app. Nomeie duas ou três páginas ou componentes de referência. Isso dá uma âncora para a skill e reduz decisões de design inventadas.

Forneça evidências do sistema, não só a feature quebrada

Entradas de alta qualidade incluem:

• arquivos de tokens
• caminhos de componentes compartilhados
• documentação de design
• screenshots de interfaces maduras
• observações sobre público ou tom de marca

Isso atende diretamente à exigência da skill de descobrir os princípios de design antes de alterar código.

Peça um plano antes da implementação

Como a normalize é orientada a alinhamento, planejar antes aumenta a confiança no resultado. Peça:

• desvios detectados
• causas-raiz
• proposta de reutilização de componentes existentes
• perguntas em aberto onde o sistema não estiver claro

Isso ajuda a barrar saídas de “polimento apenas” antes que virem código.

Divida limpezas amplas em ciclos do tamanho de uma feature

Se você quer aplicar a normalize em um produto grande, faça isso de forma incremental:

1. normalize uma rota
2. normalize uma família de componentes compartilhados
3. normalize um fluxo vizinho
4. consolide os padrões revelados pelas etapas anteriores

Isso gera consistência melhor do que um pedido amplo feito de uma vez.

Fique atento a estes modos de falha

Modos de falha comuns incluem:

• o agente adivinhar a linguagem de design
• overfitting a uma única página de referência
• introduzir novas variantes em vez de reutilizar as existentes
• corrigir os visuais do happy path e ignorar os estados
• fazer mudanças de estilo sem explicar o alinhamento com os padrões

Se você perceber isso, o problema geralmente é falta de contexto, não apenas execução fraca.

Fortaleça seus prompts de follow-up

Depois da primeira saída, melhore os resultados da normalize com prompts como:

• “Revise this to use only existing button and form patterns.”
• “Re-check empty, loading, and validation states against our settings pages.”
• “List any new patterns you introduced and replace them with existing system equivalents.”
• “Separate must-fix inconsistencies from optional polish.”

Esses follow-ups ajudam a manter o trabalho ancorado na consistência do sistema.

Use a normalize como redutora de dívida de design

A skill normalize é mais valiosa quando usada repetidamente em áreas propensas a desvio: rotas antigas, features recém-lançadas ou superfícies tocadas por muitos contribuidores. Trate-a como uma ferramenta direcionada para reduzir dívida de design, não como um embelezador de uso único.

Melhore a saída deixando claros os itens inegociáveis

Diga à skill o que precisa permanecer estável:

• restrições de layout
• lógica de negócio
• APIs de componentes
• requisitos de acessibilidade
• limites de risco de release

Isso ajuda a normalize a focar em alinhamento com o sistema sem extrapolar para refactors não relacionados.