Checklists de revisão de CSS: arquitetura, BEM, tokens, especificidade e consistência visual

Por que usar checklists na revisão de CSS

Em projetos reais, a maior parte dos problemas de CSS não nasce de “falta de conhecimento”, mas de pequenas decisões inconsistentes acumuladas: um seletor um pouco mais específico aqui, um token ignorado ali, um componente que “resolve rápido” com um override local. Checklists transformam revisão de CSS em um processo repetível: você reduz variação entre revisores, encontra problemas antes de virarem dívida técnica e cria um padrão de qualidade que escala com o time.

Este capítulo foca em checklists práticos para revisar CSS com atenção a arquitetura, BEM, design tokens, especificidade e consistência visual. A ideia é você conseguir aplicar em pull requests, code reviews, auditorias rápidas e também em refatorações incrementais.

Como aplicar o checklist no dia a dia (passo a passo)

1) Prepare o contexto da revisão

Antes de olhar o código, entenda a intenção da mudança. Uma revisão eficiente começa com perguntas objetivas:

• Qual componente/tela foi alterado e qual comportamento visual era esperado?
• Há screenshots antes/depois, vídeo curto ou descrição de estados (hover, focus, erro, loading)?
• A mudança introduz novo padrão (novo componente, nova variação, novo token) ou apenas ajusta algo existente?

Sem esse contexto, o revisor tende a aprovar “porque parece ok” ou bloquear “porque não entendeu”, e ambos geram retrabalho.

2) Faça uma leitura em duas passadas

Uma técnica simples para reduzir falhas:

Continue em nosso aplicativo

Você poderá ouvir o audiobook com a tela desligada, ganhar gratuitamente o certificado deste curso e ainda ter acesso a outros 5.000 cursos online gratuitos.

ou continue lendo abaixo...

Baixar o aplicativo

• Passada 1 (macro): arquitetura, localização do arquivo, dependências, coerência com padrões do projeto.
• Passada 2 (micro): seletores, especificidade, tokens, estados, consistência visual e detalhes de implementação.

Isso evita que você se perca em detalhes (micro) quando o problema real é estrutural (macro).

3) Valide no navegador com um roteiro mínimo

Mesmo com bons testes, CSS é altamente visual. Um roteiro mínimo ajuda a padronizar:

• Verificar em pelo menos 2 larguras (ex.: mobile e desktop).
• Inspecionar estados: hover, focus-visible, disabled, erro/sucesso, loading (quando aplicável).
• Checar contraste e legibilidade em tema claro/escuro (se existir).
• Verificar se não houve regressão em componentes vizinhos (efeito colateral).

Checklist de arquitetura (organização, limites e impacto)

Checklist rápido

• O CSS foi adicionado no lugar certo (arquivo/camada/pasta esperada pelo projeto)?
• A mudança respeita limites do componente (não estiliza “por fora” elementos internos de outro componente)?
• Não foram criadas dependências implícitas de ordem (ex.: “funciona porque este arquivo é importado depois”)?
• Evita estilos globais para resolver problema local?
• Evita duplicar padrões já existentes (layout/objeto/utilitário)?

Sinais de alerta comuns

Alguns padrões indicam risco de escalabilidade:

• Estilo global para corrigir um caso específico: ex.: alterar button globalmente para ajustar um botão de um único componente.
• Override “misterioso”: um seletor novo aparece apenas para “ganhar” de outro, sem explicar a causa.
• CSS acoplado à estrutura do DOM: seletores dependem de hierarquia profunda e quebram com pequenas mudanças de markup.

Passo a passo para revisar a localização e o impacto

• Identifique o “dono” do estilo: é um componente, um padrão de layout, um utilitário ou um ajuste de base?
• Verifique se o arquivo alterado corresponde a esse “dono”.
• Procure por seletores que escapam do escopo (ex.: estilizar classes de outro componente).
• Simule mentalmente reutilização: se esse componente for usado em outra página, o estilo ainda faz sentido?

Checklist de BEM (clareza semântica e variações seguras)

Checklist rápido

• Classes seguem o padrão do projeto (separadores, convenções de prefixo, etc.)?
• O bloco representa um componente real e reutilizável (não um detalhe interno temporário)?
• Elementos (__) são partes do bloco e não “atalhos” para alcançar markup externo?
• Modificadores (--) representam variações (estado/tema/tamanho) e não substituem estrutura?
• Não há encadeamento desnecessário de seletores (ex.: .block .block__element sem motivo)?

Erros típicos que o checklist pega

1) Modificador usado como “novo componente”

/* Evitar: o modificador virou outro componente com estrutura diferente */
.card--profile .card__header { ... }
.card--profile .card__avatar { ... }
.card--profile .card__stats { ... }

Revisão: se a variação muda demais a estrutura e cria muitos estilos exclusivos, pode ser um novo bloco (ou composição com subcomponentes), não um modificador.

2) Elemento fora do bloco

/* Evitar: .modal__title usado dentro de outro componente */
.pageHeader .modal__title { ... }

Revisão: elemento deve existir dentro do bloco correspondente. Se é um título genérico, talvez seja outro bloco (ex.: .heading) ou um padrão tipográfico.

3) Estado implementado como seletor de atributo/estrutura

/* Evitar quando o projeto padroniza estado por classe */
.accordion details[open] .accordion__icon { transform: rotate(180deg); }

Revisão: se o time padroniza estado por classe (ex.: .accordion--open), alinhe para manter previsibilidade. Se o estado nativo for desejado, documente a exceção e garanta consistência.

Passo a passo para revisar variações

• Liste as variações introduzidas (ex.: tamanho, tom, densidade, estado).
• Confirme se cada variação está representada por modificador (ou padrão equivalente do projeto) e não por overrides ad hoc.
• Verifique se o CSS da variação altera apenas o necessário e não “redefine o componente inteiro”.
• Cheque se combinações de modificadores fazem sentido (ex.: --small com --danger), ou se há conflitos.

Checklist de design tokens (consistência, escalas e exceções)

Checklist rápido

• Valores visuais (cores, espaçamentos, tipografia, raio, sombra) usam tokens em vez de valores literais?
• Quando há valor literal, existe justificativa (exceção documentada) e ele é realmente necessário?
• Tokens usados pertencem à categoria correta (ex.: não usar token de spacing para definir font-size)?
• Há coerência de escala (ex.: espaçamentos seguem passos definidos, sem “quebrar” com 13px aleatório)?
• O componente usa tokens sem “vazar” decisões locais para o global (não cria token novo para um caso isolado)?

Heurísticas para detectar mau uso de tokens

1) Token “inventado” para resolver um único pixel

/* Sinal de alerta: token criado só para um ajuste local */
:root {
  --space-13: 13px;
}

Revisão: prefira ajustar o layout para usar a escala existente. Se o valor for realmente recorrente e fizer sentido na escala, aí sim discuta a adição do token.

2) Mistura de tokens e valores literais sem critério

.alert {
  padding: var(--space-3);
  border-radius: 6px; /* por que não token? */
}

Revisão: padronize. Se raio é tokenizado no projeto, use o token. Se não é, avalie se a mudança deve introduzir token ou manter literal de forma consistente.

3) Token correto, mas semântica errada

.badge {
  font-size: var(--space-2); /* errado: spacing não é tipografia */
}

Revisão: tokens devem expressar intenção. Tipografia deve usar tokens tipográficos (ex.: --font-size-sm), não espaçamento.

Passo a passo para revisar tokens em um PR

• Faça uma busca por valores literais comuns: # (hex), rgb, px, rem (quando o projeto exige tokens), box-shadow.
• Para cada ocorrência, pergunte: existe token equivalente? Se sim, substitua.
• Se não existe token, classifique: (a) exceção local aceitável, (b) lacuna do sistema que merece novo token, (c) problema de design que precisa de decisão.
• Valide consistência entre estados: hover/focus/disabled usam tokens de estado (ex.: cor de borda/realce) ou inventam valores?

Checklist de especificidade e robustez de seletores

Checklist rápido

• Seletores são simples e previsíveis (preferência por classe única quando possível)?
• Evita encadeamentos longos e dependência de estrutura do DOM?
• Evita IDs e !important (a menos que o projeto tenha regra explícita e justificativa)?
• Estados são aplicados de forma consistente (classe/atributo/pseudo-classe conforme padrão do projeto)?
• Não há “guerra de especificidade” (um seletor novo criado só para ganhar de outro)?

Padrões que indicam fragilidade

1) Seletor profundo e acoplado

/* Frágil: depende de estrutura e de tags */
.sidebar nav ul li a span { ... }

Revisão: prefira classe no ponto certo, reduzindo dependência estrutural.

2) Aumento de especificidade para corrigir conflito

/* Sinal de alerta: “ganhar” do estilo anterior */
.page .content .card.card--featured .card__title { ... }

Revisão: em vez de aumentar especificidade, procure a origem do conflito (ordem, escopo, responsabilidade do estilo) e ajuste no lugar correto.

3) Uso de !important como padrão

.btn { color: var(--color-text-inverse) !important; }

Revisão: !important pode ser aceitável em utilitários específicos do projeto, mas deve ser exceção controlada. Se aparece em componente, geralmente indica problema de arquitetura/escopo.

Passo a passo para revisar especificidade

• Para cada seletor novo, conte mentalmente: quantas classes? há tag? há pseudo-classe? há combinadores?
• Compare com o padrão do projeto: o seletor está “mais forte” do que deveria?
• Se houver override, pergunte: por que o estilo anterior existe? Ele está no lugar certo?
• Teste rapidamente no DevTools: desative a regra e veja o que “ganha” no lugar. Isso revela dependências ocultas.

Checklist de consistência visual (ritmo, alinhamento e estados)

Checklist rápido

• Espaçamentos seguem a escala do sistema (ritmo vertical consistente)?
• Tipografia respeita hierarquia (tamanho, peso, altura de linha) e não cria “quase iguais”?
• Bordas, raios e sombras são consistentes com o restante da UI?
• Estados interativos são completos: hover, focus-visible, active (quando aplicável), disabled?
• Mensagens de erro/sucesso/aviso seguem padrões visuais do sistema (cor, ícone, densidade)?

O que observar no DevTools

• Box model: padding/margin coerentes com tokens e com componentes similares.
• Line-height: evita cortes de texto e desalinhamento vertical.
• Alinhamento: baseline e alinhamento de ícones com texto.
• Foco: outline visível e consistente; não remover foco sem substituto.

Exemplo prático: revisão de um componente “tag/pill”

Suponha que um PR adicionou um componente de etiqueta. O checklist visual pode detectar inconsistências mesmo quando “parece ok”.

.tag {
  display: inline-flex;
  align-items: center;
  padding: 2px 10px;
  border-radius: 999px;
  font-size: 13px;
  background: #EEF2FF;
  color: #1E3A8A;
}

Pontos de revisão guiados pelo checklist:

• Tokens: substituir #EEF2FF, #1E3A8A, 13px, 2px 10px por tokens equivalentes.
• Escala: 13px é um “quase” que pode quebrar consistência; preferir passo definido (ex.: sm).
• Ritmo: padding vertical 2px pode gerar desalinhamento com outros pills; verificar padrão do sistema.
• Estados: se clicável, precisa hover/focus-visible; se apenas informativa, garantir contraste e legibilidade.

Checklist de consistência entre componentes (evitar variações invisíveis)

Um problema comum é criar microvariações: dois botões “iguais” com 1px de diferença, dois cards com sombras quase iguais, dois inputs com focus diferente. O checklist abaixo ajuda a detectar isso.

Checklist rápido

• Existe componente equivalente já implementado? Se sim, por que não reutilizar?
• As propriedades “assinatura” do componente (padding, border, radius, shadow, font) batem com o padrão?
• As variações foram implementadas como variações do componente existente (e não como novo componente duplicado)?
• O mesmo token é usado para o mesmo propósito em componentes diferentes?

Passo a passo para revisão comparativa

• Abra lado a lado o componente novo e um componente similar já existente.
• No DevTools, compare: font-size, line-height, padding, border-radius, box-shadow, cores.
• Se houver diferença, pergunte: é intencional (design) ou acidental (implementação)?
• Se for acidental, alinhe com tokens e padrões existentes.

Checklist de manutenção (legibilidade, comentários e “custo futuro”)

Checklist rápido

• O CSS é legível e fácil de modificar (ordem de propriedades consistente, agrupamentos claros)?
• Há comentários apenas quando necessário (explicando “por quê”, não “o quê”)?
• Evita números mágicos e hacks sem explicação?
• Regras não usadas foram removidas (ou justificadas)?
• O nome das classes e variáveis comunica intenção?

Exemplo: comentário útil vs. ruído

/* Ruído: descreve o óbvio */
.card { display: flex; }

/* Útil: explica a razão e o risco */
/* Mantemos min-height para evitar layout shift quando o conteúdo carrega async */
.card { min-height: 180px; }

Checklist operacional para Pull Request (copiar e colar)

Você pode usar este bloco como template de revisão. A ideia é marcar mentalmente (ou no PR) o que foi verificado.

Arquitetura

• Arquivos/camadas corretos para a mudança
• Sem dependência implícita de ordem de importação
• Sem estilos globais para resolver caso local
• Sem acoplamento a outro componente

BEM e nomenclatura

• Bloco/elemento/modificador coerentes com intenção
• Variações implementadas como modificadores (ou padrão do projeto)
• Sem seletores encadeados desnecessários

Tokens

• Cores, spacing, tipografia, raio e sombra via tokens
• Sem valores literais sem justificativa
• Escalas respeitadas (sem “quase iguais”)

Especificidade

• Seletores simples e estáveis
• Sem IDs e sem !important em componentes (exceto regra do projeto)
• Sem overrides criados só para “ganhar” de outro

Consistência visual e estados

• Ritmo de espaçamento consistente
• Hierarquia tipográfica consistente
• Estados: hover/focus-visible/disabled/erro (quando aplicável)
• Sem regressões em componentes vizinhos

Mini-auditoria: como revisar um arquivo CSS em 10 minutos

Quando o tempo é curto, um roteiro objetivo ajuda a capturar a maior parte dos problemas com alto custo futuro.

Passo a passo

• 1 minuto: localizar o arquivo e confirmar que pertence ao “dono” correto (componente/layout/utilitário/base).
• 2 minutos: varrer por valores literais (cores, px, sombras) e checar se deveriam ser tokens.
• 2 minutos: olhar seletores: profundidade, encadeamento, presença de IDs, !important.
• 2 minutos: checar variações e estados: modificadores, hover/focus-visible, disabled.
• 3 minutos: abrir no navegador e validar 2 larguras + 2 estados críticos (ex.: focus e erro).

Checklist de exceções (quando “quebrar a regra” é aceitável)

Checklists não devem virar burocracia. Algumas exceções são legítimas, desde que sejam explícitas e consistentes.

Exceções comuns e como revisar

• Hotfix visual: pode aceitar valor literal temporário, mas deve haver ticket/nota para tokenizar depois.
• Integração com conteúdo externo: às vezes exige seletor mais específico; documente o motivo e limite o escopo.
• Utilitário intencionalmente forte: alguns utilitários podem usar !important por design; confirme que está no local correto e com nome claro.

O ponto central é: exceção sem registro vira padrão acidental. Exceção com justificativa vira decisão técnica.