normalize

Visão geral da skill normalize

O que a normalize faz

A skill normalize audita uma funcionalidade de UI e a realinha a um design system já existente. Ela foi feita para casos em que uma página, rota ou componente se afastou dos padrões aprovados de espaçamento, tokens, hierarquia ou convenções de interação.

Quem deve usar a normalize

Use normalize se você já tem alguma direção de design e quer que um agente traga a implementação de volta ao alinhamento esperado. Ela faz sentido para times de frontend, responsáveis por design systems e product engineers que trabalham em apps maduros, onde a inconsistência custa mais do que criar uma UI nova do zero.

O trabalho real que ela resolve

Na prática, a maioria das pessoas não está pedindo “visuais mais bonitos”. O que elas precisam é que uma funcionalidade tenha a mesma aparência e o mesmo comportamento do restante do produto, sem introduzir estilos isolados novos. A normalize skill funciona melhor quando o objetivo é consistência, não ideação.

O que diferencia esta skill

Ao contrário de um prompt genérico como “melhore esta UI”, a normalize se apoia explicitamente em padrões já existentes. O repositório deixa isso claro: a skill não deve adivinhar. Ela exige primeiro a coleta de contexto de design, pede que você identifique os desvios e espera um plano antes de qualquer edição.

Cenários em que a normalize é mais indicada

• Uma funcionalidade usa espaçamento, tipografia ou color tokens de forma inconsistente
• Um componente funciona visualmente, mas não corresponde ao sistema
• Uma UI legada precisa de limpeza antes de uma refatoração maior
• Uma nova página foi entregue rapidamente e agora precisa ser alinhada ao design system
• O time quer normalizar a interface sem redesenhar a intenção do produto

Quando a normalize não é uma boa escolha

normalize for Design Systems não é a melhor primeira etapa se o seu time não tem padrões documentados, componentes reutilizáveis ou uma direção de produto/UX resolvida. Nesse cenário, a skill até pode ajudar a expor lacunas, mas não consegue inventar padrões autoritativos com segurança.

Como usar a skill normalize

Instale a normalize no seu ambiente de skills

O repositório não publica um comando de instalação dentro de SKILL.md, então quem usa diretórios de skills normalmente adiciona a skill a partir do caminho do repositório de origem usado pelo sistema de skills que já está em execução. Se o seu ambiente aceita instalação direta de skills via GitHub, use o repositório pbakaus/impeccable e selecione a skill normalize.

Se você usa um padrão de comando parecido com:
npx skills add pbakaus/impeccable --skill normalize

valide isso primeiro no seu próprio runner. O ponto importante é que a skill fica em .agents/skills/normalize.

Leia este arquivo antes do primeiro uso

Comece por:

• SKILL.md

Esta skill não traz arquivos auxiliares, scripts ou referências extras na pasta, então quase toda a orientação útil está nesse arquivo único. Isso é bom pela velocidade, mas também significa que você precisa fornecer por conta própria o contexto de projeto que estiver faltando.

Entenda a dependência obrigatória de frontend-design

O maior ponto de atrito na adoção é fácil de passar despercebido: a normalize diz que você precisa invocar /frontend-design antes. Essa skill anterior contém os princípios de design, anti-patterns e o protocolo de coleta de contexto dos quais este fluxo depende.

Ela também diz que, se ainda não existir contexto de design, você deve executar /teach-impeccable antes de continuar. Na prática, o normalize usage funciona como um fluxo encadeado, não como um prompt isolado de uma etapa só.

Saiba qual entrada a normalize espera

A dica de argumento declarada é:
[feature (page, route, component...)]

Boas entradas são unidades concretas de trabalho em UI, como:

• checkout page
• settings/billing route
• pricing card component
• mobile nav menu

Entradas fracas são alvos amplos demais, como:

• the whole app
• make the UI better
• fix styling everywhere

Transforme um objetivo vago em um prompt forte para normalize

Um pedido fraco:
Normalize the dashboard

Um pedido mais forte:
Use normalize on the analytics dashboard route. Align it to our design system by checking token usage, spacing scale, typography hierarchy, component variants, and empty-state patterns. Preserve current functionality. Flag any places where the design system is unclear instead of guessing.

Por que isso funciona:

• define claramente o limite da funcionalidade
• estabelece os critérios de normalização
• protege a funcionalidade existente
• diz ao agente o que fazer quando os padrões não estiverem claros

Reúna o contexto mínimo antes de executar a normalize

Para ter saída de alta qualidade, forneça:

• o caminho ou a rota da funcionalidade alvo
• a localização da sua biblioteca de componentes ou do design system
• as fontes de tokens, como arquivos de tema ou variáveis CSS
• diretrizes de UI relevantes ou screenshots
• quaisquer restrições de negócio marcadas como “não alterar”
• se você quer apenas o plano ou plano mais edições

Sem esse contexto, a skill consegue identificar desvios, mas não consegue escolher com confiança o padrão correto para substituição.

Siga o fluxo que a skill pressupõe

O texto do repositório sustenta esta sequência:

1. Execute /frontend-design
2. Se faltar contexto de design, execute /teach-impeccable
3. Descubra a documentação do design system, padrões de componentes e tokens
4. Analise a funcionalidade atual em busca de desvios
5. Crie um plano de normalização
6. Execute as mudanças com cautela
7. Limpe estilos isolados e inconsistências

Essa ordem importa porque a skill parte de uma posição clara: não adivinhar padrões.

O que a normalize deve inspecionar no seu codebase

O trecho de origem enfatiza:

• princípios de design e direção estética
• público-alvo e personas
• padrões e convenções de componentes
• design tokens de cor, tipografia e espaçamento
• se as inconsistências são cosméticas ou funcionais
• causas-raiz, como implementações pontuais ou falta de tokens

Isso significa que normalize install é apenas metade da decisão. A pergunta mais importante é se o seu repositório expõe sinais suficientes para um agente seguir essas decisões canônicas de UI.

Padrões de prompt que melhoram a saída da normalize

Peça diagnóstico e ação ao mesmo tempo:
Normalize the account settings page. First identify where it deviates from our system and categorize issues as token misuse, layout inconsistency, component misuse, or interaction mismatch. Then propose the minimal set of edits to align it.

Peça tratamento explícito de incerteza:
If a pattern is not documented, stop and ask rather than inventing a new one.

Peça formato de saída:
Return a brief audit, a change plan, then the implementation.

Guardrails práticos para usar a normalize em produtos reais

Para manter o uso do normalize guide seguro:

• preserve os requisitos do produto e a intenção do conteúdo
• evite mudar fluxos, a menos que eles violem claramente padrões já estabelecidos
• prefira substituir estilos customizados por primitives já existentes
• peça diffs que reduzam código pontual, e não apenas ajustes visuais
• exija que o agente aponte onde o próprio sistema está inconsistente

Uma boa execução de normalização costuma melhorar tanto a consistência da UI quanto a manutenção do código.

FAQ da skill normalize

A normalize é melhor do que um prompt comum de limpeza de UI?

Na maioria dos casos, sim, se você já tem um design system. O valor de normalize não está em um prompt “mais esperto”, e sim no fluxo obrigatório de levantar padrões primeiro, checar os desvios contra esses padrões e evitar decisões de design inventadas.

A normalize é amigável para iniciantes?

Moderadamente. A skill em si é simples, mas iniciantes muitas vezes não têm os pré-requisitos que ela espera: documentação de design, fontes de tokens e segurança para definir o que é canônico. Se você está começando, use alvos menores, como uma rota ou um componente por vez.

A normalize pode funcionar sem um design system formal?

Só parcialmente. Ela ainda consegue expor inconsistências, mas a qualidade da saída cai quando não existe uma fonte de verdade clara. A skill alerta explicitamente contra adivinhação, então a ausência de padrões vira um bloqueio visível em vez de uma suposição escondida.

O que a normalize não faz bem?

Ela não é voltada principalmente para:

• exploração visual de projetos greenfield
• grandes mudanças de estratégia de UX
• criação de marca
• refactors em toda a aplicação de uma vez

Use para alinhamento, não para um redesenho amplo do produto.

Como a normalize se encaixa em stacks de frontend?

A normalize skill é, em conceito, agnóstica de stack, porque foca em tokens, padrões e convenções. Ela é mais eficaz quando o codebase tem componentes reutilizáveis, primitives de tema e estrutura suficiente para um agente rastrear quais decisões de UI são realmente canônicas.

Quando devo evitar normalize for Design Systems?

Evite quando o problema real for escopo de produto mal resolvido, e não inconsistência visual. Também evite quando o time ainda discorda sobre o próprio design system; caso contrário, a skill pode gastar esforço normalizando em direção a um alvo em movimento.

Como melhorar a skill normalize

Dê à normalize um alvo mais estreito

O ganho de qualidade mais rápido vem do escopo. Peça que a normalize trate uma rota, funcionalidade ou grupo de componentes por vez. Escopos menores geram auditorias mais claras, menos regressões acidentais e decisões melhores de alinhamento.

Forneça a fonte de verdade real

Não diga apenas “siga nosso design system”. Aponte para:

• pastas de componentes
• URLs do Storybook ou da documentação
• arquivos de tokens
• screenshots de telas canônicas
• exemplos de padrões aprovados

Isso reduz o principal modo de falha: um alinhamento plausível, mas incorreto.

Diferencie desvio cosmético de desvio de padrão

Pedidos fortes deixam claro se você quer:

• limpeza apenas de tokens
• alinhamento de hierarquia visual
• substituição de componentes por variantes aprovadas
• normalização de interação também

Essa distinção muda bastante o plano e ajuda a evitar edições excessivas.

Diga à normalize o que não pode mudar

Um prompt melhor de normalize usage inclui restrições como:

• manter o fluxo de dados atual
• não alterar a lógica de validação
• preservar o comportamento de acessibilidade
• manter estáveis os seletores de analytics
• evitar introduzir novos componentes

Isso mantém a normalização focada na aderência ao sistema, em vez de escorregar para uma refatoração acidental.

Peça um plano antes de mudar o código

Como o repositório enfatiza planejamento, aproveite isso. Peça:

1. achados sobre o design system
2. auditoria de desvios
3. etapas propostas de normalização
4. só então a implementação

Essa é a forma mais simples de detectar suposições erradas logo no começo.

Trate padrões ausentes de forma explícita

Se o agente não conseguir encontrar uma regra para espaçamento, tipografia ou escolha de componente, instrua-o a:

• parar e perguntar
• propor opções com tradeoffs
• marcar a lacuna como um problema do design system

Esse comportamento está muito mais alinhado à intenção da skill do que forçar um palpite.

Revise pensando em manutenção, não só em screenshots

O melhor resultado de normalize guide não é apenas parecer visualmente igual. Revise se o resultado:

• substitui valores hard-coded por tokens
• remove wrappers customizados e pontuais
• reaproveita primitives aprovadas
• simplifica atualizações futuras em todo o sistema

É aí que a skill pode gerar valor duradouro para design systems.

Itere depois da primeira passada de normalize

Depois da primeira execução, faça um follow-up focado:
Re-check the implementation and list any remaining deviations from the design system, especially token usage, component variants, and spacing rhythm.

É comum que uma segunda passada encontre inconsistências mais sutis.

Melhore a qualidade da saída com exemplos de comparação

Se você tem uma tela de referência que representa o padrão ouro, diga isso:
Normalize the billing page to match the visual and structural patterns used in the account overview page.

Exemplos de referência estão entre os insumos de maior impacto para normalize for Design Systems.

Conheça os principais modos de falha

Fique atento a:

• padrões inventados quando a documentação é fraca
• correções excessivas que mudam a intenção de UX
• alinhamento visual sem limpeza de tokens
• ajustes locais que ignoram componentes compartilhados
• edições amplas de “polimento” sem justificativa no design system

Se você notar esses sinais, reduza o escopo, adicione referências e exija justificativas explícitas ligadas ao seu sistema.