Auditoria de uma Folha de Estilo com o Project Wallace

Uma auditoria de CSS com o Project Wallace significa colar uma folha de estilo no analisador online e ler cinco números: cores únicas, font-sizes únicos, especificidade máxima de seletor (com as contagens de id e !important ao lado), a diferença entre o total de declarações e as declarações únicas, e o tamanho de arquivo não comprimido em comparação com o tamanho gzip. Cada número aponta para uma mudança diferente.

Se sua folha de estilo tem três anos, você provavelmente já suspeita que ela se desviou do rumo. O que falta é um número para colocar em um ticket. “O CSS parece bagunçado” não é priorizado; “entregamos seis tons de cinza quando o design define dois” é.

Este artigo passa uma pequena folha de estilo de exemplo pelo analisador, lê a saída métrica por métrica e associa cada descoberta à mudança concreta que ela deve desencadear. Ele cobre o diagnóstico. O artigo seguinte, How to Organize CSS in Modern Web Projects, cobre o tratamento.

Por Que uma Auditoria de CSS Encontra o Que o Build Não Encontra?

Um navegador que encontra uma declaração CSS que não consegue interpretar ou não reconhece descarta aquela declaração e continua renderizando a página, e é por isso que uma folha de estilo pode acumular erros por anos sem que um único build falhe. Essa recuperação é comportamento especificado. Sob as regras de tratamento de erros do CSS Syntax Module Level 3, a declaração construída pela metade é descartada, o parser avança até depois do próximo ponto e vírgula, e a interpretação normal continua a partir dali.

A consequência é que o dano ao CSS nunca se parece com uma falha. Parece um desvio: um quarto cinza que está dois pontos distante do terceiro, um título de 17px entre os passos de 16px e 18px, um seletor de id adicionado sob pressão de prazo e, em seguida, um !important adicionado para vencê-lo. Nada disso quebra nada. Tudo isso torna a próxima mudança mais difícil.

Como Executar o Analisador do Project Wallace?

O analisador de CSS do Project Wallace aceita entrada de três formas: uma URL de site, um arquivo enviado ou CSS colado diretamente. Quando você cola ou envia CSS, o trabalho acontece localmente: um WebWorker no seu próprio dispositivo faz a análise, e nada do que você cola é enviado para lugar algum. Esse design vem da reescrita do analisador de 2021. O modo URL necessariamente busca o site alvo pela rede antes da análise.

A página de entrada tem um botão “Prettify CSS?”, com uma nota ao lado avisando que a opção altera um pouco os números. Escolha um estado e mantenha-o fixo em todas as execuções que você pretende comparar.

Aqui está o exemplo. Três contribuidores, dois anos, um componente de header e um de card:

/* header.css — three contributors, two years */
#site-header {
  background: #f5f5f5;
  color: #333333;
  font-size: 16px;
}

#site-header .nav-link {
  color: #343434;
  font-size: 15px;
  padding: 8px 12px;
}

.nav-link:hover {
  color: #222222 !important;
}

.card {
  background: #f4f4f4;
  color: #333333;
  font-size: 1rem;
  padding: 16px;
}

.card .card-title {
  font-size: 18px;
  color: #333333;
}

.card--featured .card-title {
  font-size: 17px;
  font-weight: 700 !important;
}

.legacy-banner {
}

.footer {
  background: #f5f5f5;
  color: #444444;
  font-size: 14px;
}

O que retorna é uma página de resultados agrupada nas mesmas categorias da documentação de métricas: Stylesheet, Atrules, Rules, Selectors, Declarations, Properties e Values. São bem mais de cem métricas. As cinco abaixo são as que se transformam em um commit.

O Que Cores e Font-Sizes Únicos Revelam?

A diferença entre o total de cores e as cores únicas indica com que frequência cada cor é reutilizada, e a diferença entre as cores únicas e a paleta definida pelo seu design system indica o quanto o código se desviou do design. O analisador conta ambos e fornece a lista completa de cores únicas que encontrou; os font-sizes recebem o mesmo tratamento.

Lido manualmente, o exemplo contém seis strings hexadecimais distintas: #f5f5f5 e #f4f4f4 para superfícies, e #333333, #343434, #222222, #444444 para texto. Um design system para este componente quase certamente pretendia uma superfície e duas cores de texto. A escala tipográfica é pior: 16px, 15px, 1rem, 18px, 17px, 14px são seis valores conforme escritos, e 16px e 1rem normalmente resolvem para o mesmo tamanho em pixels de qualquer forma.

A correção é consolidação, não exclusão. Consolidar cinzas quase idênticos não significa remover regras; significa substituir cada literal pelo token mais próximo e deixar a regra continuar cumprindo seu papel:

:root {
  --color-surface: #f5f5f5;
  --color-text: #333333;
  --color-text-muted: #444444;
  --font-size-sm: 0.875rem;
  --font-size-base: 1rem;
  --font-size-lg: 1.125rem;
}

.card {
  background: var(--color-surface);
  color: var(--color-text);
  font-size: var(--font-size-base);
  padding: 16px;
}

Três tokens de cor substituem seis literais; três tokens de tamanho substituem seis. A ferramenta separada de Design Tokens do Project Wallace extrai cores e font-sizes candidatos do CSS existente, o que é um ponto de partida mais rápido do que ler a lista manualmente em uma folha de estilo real.

Especificidade: Picos Importam Mais do Que o Máximo

Um seletor de alta especificidade perto do final de uma folha de estilo é um problema local, mas um no meio força toda regra posterior que precise sobrescrevê-lo a escalar até o mesmo nível, e essa escalada é como seletores de id e flags !important se multiplicam. O gráfico de especificidade de Harry Roberts faz o mesmo argumento visualmente: a tendência deve subir suavemente em direção ao final, e qualquer pico é um custo pago por tudo que vem depois dele.

O analisador reporta a especificidade como um valor de três partes — id, class, type — através de Maximum selector specificity, Total selectors having maximum specificity e Top specificity selectors, ao lado de Total id selectors, Total !important declarations e Ratio of !important declarations.

O exemplo mostra o mecanismo em miniatura. #site-header .nav-link está em (1,1,0). O posterior .nav-link:hover em (0,2,0) não consegue vencê-lo, então um contribuidor recorreu a !important. Um seletor de id produziu uma flag !important, e a segunda flag em .card--featured .card-title vence uma regra que nunca definiu font-weight em momento algum.

A contagem de seletores de id e a contagem de !important são os dois números de especificidade que uma equipe pode reduzir um commit por vez e remedir após cada mudança. No exemplo, alterar a marcação de id="site-header" para class="site-header" achata ambas as regras do header para (0,1,0) e (0,2,0), e ambas as flags !important tornam-se desnecessárias.

Declarações Duplicadas e Regras Vazias

Uma regra vazia contribui com bytes e uma correspondência de seletor, mas não muda nada que o usuário veja, então removê-la é a única correção de auditoria que nunca precisa de verificação de regressão visual. Declarações duplicadas são diferentes: a mesma intenção escrita duas vezes é um sinal de alerta, mas deletar a cópia errada altera a cascata.

O analisador conta Total empty rules diretamente; .legacy-banner {} é a única instância do exemplo, e ela vai embora. Não existe uma métrica autônoma de declarações duplicadas. Leia Total declarations em comparação com Total unique declarations e trate a diferença como a contagem de duplicatas, tendo em mente que a documentação ainda deixa em aberto se espaços em branco ou formatação tornam duas declarações distintas.

color: #333333 aparece em três regras do exemplo. A atitude correta não é deletar duas cópias, mas rotear todas as três através de var(--color-text), o que torna a repetição visível como uma decisão compartilhada em vez de uma coincidência.

Por Que o Tamanho Gzip Esconde uma Folha de Estilo Inchada?

O gzip comprime repetição de forma eficiente, então uma folha de estilo cheia de declarações duplicadas pode apresentar um tamanho comprimido lisonjeiro enquanto seu tamanho não comprimido — os bytes que o navegador de fato interpreta — continua crescendo. O analisador reporta Uncompressed filesize, Gzip filesize e Gzip filesize compression ratio em conjunto.

Uma taxa de compressão crescente é o indício: significa que a folha de estilo está ficando mais repetitiva, não menor. O que move o tamanho não comprimido é o número de regras e declarações, e é por isso que o trabalho de consolidação acima o reduz como efeito colateral. O tamanho de arquivo é um diagnóstico a ser lido após as outras correções, não uma meta a ser otimizada isoladamente.

Acompanhando uma Folha de Estilo ao Longo das Releases

Para acompanhar uma folha de estilo ao longo das releases, salve o CSS bruto de cada release junto aos resultados do analisador e reexecute cada análise com o mesmo estado de Prettify. O visualizador CSS Diff formata duas folhas de estilo coladas e as compara linha a linha no navegador, o que mostra onde a contagem de cores únicas ou de seletores de id se moveu.

Conclusão

Uma auditoria de folha de estilo justifica o tempo investido quando cada número mapeia para uma mudança: cores e font-sizes únicos para tokens, seletores de id e flags !important para especificidade mais achatada, regras vazias para exclusão, duplicatas para declarações compartilhadas, e tamanho de arquivo para uma verificação de que o restante funcionou. Cole sua maior folha de estilo de produção no analisador, anote esses cinco números e abra um pull request por número.

Perguntas Frequentes

Posso executar o analisador do Project Wallace pela linha de comando ou em CI?

Sim. O pacote npm wallace-cli executa o mesmo analisador em um terminal: instale-o com npm install wallace-cli, depois execute wallace path/to/styles.css ou envie o CSS via stdin, e adicione a flag --json para saída legível por máquina em scripts de CI. A versão 4.x da CLI requer Node 20.12 ou superior. Para uso programático, importe a função analyze de @projectwallace/css-analyzer, um pacote somente ESM que roda tanto no Node quanto em navegadores.

Devo analisar meus arquivos-fonte Sass ou Tailwind ou o CSS compilado?

Analise o CSS compilado que seus usuários recebem, não o código-fonte Sass, Less ou Tailwind. Variáveis, mixins e @extend se expandem em tempo de build, então arquivos-fonte reportam incorretamente cores únicas, contagens de seletores e tamanho de arquivo. O próprio plugin de Stylelint do Project Wallace diz a mesma coisa sobre onde apontá-lo: direcione-o para o bundle que você entrega, porque contagens de valores únicos e as razões construídas sobre elas descrevem o arquivo entregue, e não o código-fonte. O modo URL já busca as folhas de estilo compiladas que um site serve.

Qual é a diferença entre o CSS Analyzer do Project Wallace e sua ferramenta CSS Code Quality?

O CSS Analyzer reporta métricas brutas; a ferramenta CSS Code Quality pega essa saída, executa suas próprias verificações sobre ela e resume o resultado em três pontuações de 0 a 100, para Performance, Maintainability e Complexity. Use o analisador quando precisar rastrear um número até uma regra específica, e o Code Quality quando quiser um resumo opinativo para compartilhar com a equipe. Ambos aceitam uma URL, arquivos enviados ou CSS colado.

Como evito que cores únicas ou especificidade regridam após uma auditoria?

Adicione @projectwallace/stylelint-plugin à sua configuração do Stylelint. Ele traz mais de 60 regras construídas sobre o mesmo mecanismo de análise, incluindo projectwallace/max-unique-colors, e seu preset holistic avalia o arquivo como um todo (totais, médias, razões, unicidade) em vez de verificar um nó por vez. Um preset recommended coloca você em funcionamento com uma única linha extends. Execute-o contra o bundle de CSS compilado em CI, para que um pull request que adicione um sétimo cinza falhe antes do merge.