Por que a maioria dos checklists de consistência não funciona
A lista padrão faz perguntas como "o visual e a sensação da interface são consistentes?" e "os labels são usados de forma consistente?". Isso é apenas reformular o objetivo. A pessoa que executa a auditoria precisa converter cada pergunta em algo verificável, e fará isso de forma diferente a cada vez, tornando a própria auditoria inconsistente.
Uma verificação precisa de três coisas para valer a pena: algo específico para observar, uma maneira de observar e uma condição que determine aprovação ou falha. Tudo abaixo possui as três.
Etapa um: mecânica
Cinco minutos, sem necessidade de julgamento, e detecta uma parcela surpreendente de drift real. Cada uma destas deve acabar no CI assim que for aprovada; uma verificação que roda apenas durante auditorias permite que o drift se acumule entre elas.
- 1
Valores literais de cores fora do arquivo de tokens
A verificação de maior rendimento. Qualquer hex em um componente significa que a camada de tokens foi ignorada, e significa que aquela cor não pode ser alterada centralmente.
grep -rn --include='*.tsx' --include='*.css' -E '#[0-9a-fA-F]{3,8}\b' src \ | grep -v 'tokens\|globals.css' - 2
Pesos de fonte fora da sua faixa
O peso é onde a hierarquia reverte silenciosamente para os padrões do framework. Se o seu sistema define 400 e 600, qualquer coisa mais pesada é drift, independentemente da aparência.
grep -rn --include='*.tsx' -E 'font-(bold|extrabold|black)|font-weight:\s*[78]00' src - 3
Valores de espaçamento fora da escala
Saídas de escape com valores arbitrários são onde o ritmo morre. Um
p-[13px]não é nada; quarenta deles são um segundo sistema de espaçamento com o qual ninguém concordou.grep -rn --include='*.tsx' -E '\b(p|m|gap|space)-\[[0-9]+px\]' src - 4
Valores de radius
O radius sofre drift mais do que qualquer outra coisa porque cada autor de componente escolhe o que parece certo isoladamente. Conte os valores distintos em uso; mais de três ou quatro é um problema.
grep -rhoE 'rounded-[a-z0-9]+|border-radius:\s*[0-9]+px' src -r \ --include='*.tsx' --include='*.css' | sort | uniq -c | sort -rn - 5
Propriedades que seu sistema proíbe
O que quer que sua lista de proibições determine. Se ela diz que elevação nunca é uma sombra, esta verificação impõe isso. Se você não tem uma lista de proibições, esse é o problema: escreva uma primeiro.
grep -rn --include='*.tsx' --include='*.css' -E 'box-shadow|shadow-(sm|md|lg|xl)|gradient' src
Execute estas verificações antes de olhar qualquer outra coisa. Cada resultado é um problema definitivo que não requer discussão, e resolvê-los primeiro significa que a etapa comparativa focará em decisões genuínas de design, em vez de erros óbvios.
A quarta verificação tem um detalhe importante: contar valores de radius distintos informa sobre a consistência, não sobre a correção. Três valores usados deliberadamente (6px em controles, 12px em containers, full em avatares) formam um sistema. Três valores que por acaso são 6, 8 e 10 são drift que não foi notado.
Etapa dois: comparativa
Aqui está o erro de todo processo de auditoria. Revisar uma tela isoladamente diz se ela é internamente coerente. Não diz nada sobre se ela combina com as outras telas, porque você não consegue manter as outras telas na cabeça com precisão suficiente.
O drift é invisível por arquivo e óbvio na comparação. A revisão por pull-request, estruturalmente, não consegue detectá-lo.
Portanto, abra três telas finalizadas da mesma superfície lado a lado: três telas de aplicação ou três páginas de marketing, nunca uma mistura. Comparar um dashboard com uma landing page produz diferenças que deveriam estar lá.
| Analise | Falha quando | |
|---|---|---|
| Densidade | Padding de controles, altura de linha, espaçamento entre seções | Uma tela tem respiro e outra está congestionada, sem que haja motivo no conteúdo |
| Hierarquia | Como o título da página se diferencia do título de uma seção | Um usa tamanho, outro usa peso, um terceiro usa cor |
| Elevação | Como uma superfície elevada é indicada | Sombras em uma tela, bordas em outra |
| Empty states | O que acontece quando não há dados | Uma ilustração em uma tela, uma frase em outra, nada na terceira |
| Loading | O que aparece enquanto os dados estão sendo carregados | Skeletons, um spinner e um flash em branco em três telas diferentes |
| Apresentação de erros | Onde um erro aparece e qual a sua aparência | Inline em uma tela, um toast em outra, um estado de página inteira em uma terceira |
As três últimas linhas são onde o trabalho de consistência é quase sempre mais fraco, e isso não é descuido: estados de empty, loading e erro são escritos sob pressão de tempo, individualmente, por quem quer que estivesse naquele arquivo. Eles também são, desproporcionalmente, o que um usuário frustrado vê.
Se o seu design system não diz nada sobre estados de empty, loading e erro, espere que os três sejam diferentes em cada tela e que nenhuma revisão detecte isso. Esses estados precisam ser especificados tão explicitamente quanto os botões, e quase nunca são.
O checklist comparativo completo
As seis linhas acima são onde a divergência se concentra. Esta é a lista completa, agrupada para que você possa resolvê-la de uma só vez. Cada item possui uma condição de aprovação em vez de uma pergunta.
Cor
- Cada cor em cada tela resolve para um papel (role) nomeado. Falha se qualquer componente contiver um valor literal.
- A cor de destaque aparece nos mesmos tipos de elemento em todas as telas. Falha se for um botão em uma tela e um título em outra.
- Cores de status aparecem apenas para status. Falha se a cor de sucesso for usada decorativamente em qualquer lugar.
- Cada cor do modo claro tem uma contraparte no modo escuro que foi escolhida, não derivada. Falha se qualquer superfície for uma inversão direta.
Tipografia
- Cada tamanho na tela é um degrau da escala. Falha se você encontrar um tamanho que não seja.
- Os pesos permanecem dentro da faixa declarada. Falha em qualquer peso acima dela, por melhor que pareça.
- O mesmo nível semântico tem a mesma aparência em todos os lugares: cada título de página corresponde a todos os outros títulos de página. Falha se duas telas diferenciarem seus títulos de formas distintas.
- Números em colunas são tabulares e alinhados. Falha se os dígitos não estiverem alinhados entre as linhas.
Espaço e forma
- Cada valor de espaçamento é um degrau da escala. Falha em qualquer valor arbitrário.
- Os valores de raio distintos são poucos e cada um tem um propósito definido. Falha se você não conseguir explicar por que 8px existe ao lado de 6px.
- A elevação é indicada da mesma forma em todos os lugares. Falha se sombras e bordas forem usadas simultaneamente para a mesma função.
- O ritmo da seção é consistente: o espaço entre um título e seu conteúdo é o mesmo em todas as telas. Falha em qualquer variação sem justificativa.
Componentes e controles
- Uma implementação por componente. Falha se dois arquivos definirem um card.
- Ações primárias são idênticas e ocupam a mesma posição relativa. Falha se uma tela a coloca à esquerda e outra à direita.
- Ações destrutivas são visualmente distintas e consistentes. Falha se o botão de excluir for parecido com o de salvar em qualquer lugar.
- Elementos interativos possuem um estado de foco visível e idêntico em todo lugar. Falha se houver qualquer anel de foco ausente ou divergente.
- Estados desativados são visualmente distintos de conteúdos suavizados (muted). Falha se o usuário não conseguir diferenciar um controle indisponível de um texto com menos ênfase.
Os estados que ninguém especifica
- Estados vazios (empty states) usam o mesmo tratamento em todo o produto. Falha se houver uma ilustração em um lugar e apenas uma frase em outro.
- O carregamento (loading) usa um único mecanismo. Falha se houver um skeleton, um spinner e um flash em branco em três telas diferentes.
- Erros aparecem no mesmo lugar e com o mesmo tratamento. Falha se for inline em um lugar e toast em outro.
- O texto de erro explica o que deu errado e o que fazer. Falha se a mensagem apenas pedir desculpas.
- Conteúdos longos são truncados da mesma forma em todo lugar. Falha se em um lugar o texto quebrar a linha e em outro houver reticências sem uma regra definida.
Se estiver com pouco tempo, comece pelo último grupo. É o grupo com maior probabilidade de falha, menor probabilidade de estar especificado e maior probabilidade de ser visto por um usuário que já está tendo uma experiência ruim.
Conteúdo e linguagem
- O mesmo conceito tem um único nome em todo lugar. Falha se a interface disser "projeto" em um lugar e "workspace" em outro para a mesma coisa.
- Botões nomeiam a ação que executam, e a confirmação ecoa essa ação. Falha se houver um "Enviar" seguido de "Suas alterações foram salvas".
- A capitalização segue uma única regra para labels, cabeçalhos e botões. Falha se houver mistura de Title Case e Sentence Case.
- Datas, horas e números usam um único formato. Falha se houver dois formatos de data em um único produto.
O primeiro item desse grupo causa mais confusão real ao usuário do que qualquer inconsistência visual citada neste artigo. Dois nomes para um único conceito significam que o usuário mantém dois modelos mentais e não consegue saber se são a mesma coisa.
Terceira etapa: as regras em si são coerentes?
Uma vez por trimestre, audite o sistema em vez da interface. A questão não é se as pessoas seguiram as regras, mas se as regras eram passíveis de serem seguidas.
| Sinal | O que significa | |
|---|---|---|
| Uma regra com ressalvas | "Espaçamento generoso, embora tabelas possam ser mais densas" | Duas regras fingindo ser uma. Um modelo ou uma pessoa precisa escolher, e escolhem de formas diferentes |
| A mesma exceção solicitada repetidamente | Três equipes precisaram do mesmo valor fora do sistema | Falta algo na camada semântica. Promova esse valor ao sistema em vez de conceder exceções |
| Multiplicação de tokens em nível de componente | Muitos tokens com exatamente um consumidor | A saída de emergência tornou-se a estrada principal |
| Uma regra que ninguém consegue citar de memória | Todos precisam consultá-la | Ou é complexa demais ou é arbitrária. Ambos são corrigíveis |
A primeira linha é a que deve ser verificada com mais rigor, pois uma regra com ressalvas parece ser uma regra detalhada. Se a sua orientação contém ressalvas, as superfícies que essas ressalvas descrevem precisam de documentos separados: a governança cobre a versão estrutural disso.
O que muda quando um agente escreve as telas
Duas coisas, em direções opostas, e ambas mudam a forma como você deve executar este checklist.
A verificação mecânica torna-se mais importante, pois o volume de código aumentou e a capacidade de revisão não. Um agente que produz quarenta telas entre as revisões reproduzirá qualquer inconsistência quarenta vezes antes que alguém a veja. Verificações automatizadas são a única coisa que escala nesse ritmo.
A análise comparativa torna-se ainda mais importante, e por um motivo mais sutil. Um agente é extremamente consistente *dentro* de um arquivo, mas não tem memória entre sessões; portanto, seu resultado é um conjunto de telas internamente coerentes, mas que divergem entre si. Esse é precisamente o modo de falha que a revisão por arquivo não consegue detectar.
A causa raiz geralmente está na origem. Analisamos 299 arquivos DESIGN.md escritos para fornecer orientações de design aos agentes: 86% especificam cores como hexadecimais puros sem função semântica, 76% não estabelecem proibições de qualquer tipo, 69% não definem modo escuro, 57% não nomeiam motifs e 44% não contêm nenhum valor de tamanho concreto. 54% dependem de pelo menos um adjetivo vago: "clean" em 39%, "modern" em 36%.
Um arquivo assim deixa decisões de densidade, hierarquia, elevação e estados vazios em aberto, então o modelo as cria do zero em cada tela. As inconsistências encontradas diante dessa orientação são reais, e corrigi-las tela por tela não resolverá o problema. Como escrever orientações que funcionem.
Os design kits do Identity Forge eliminam essa lacuna diretamente: funções semânticas de cores para modos claro e escuro, escalas de tipografia e espaçamento, motifs e uma lista explícita de "o que fazer e o que não fazer", serializados em um DESIGN.md que o agente lê antes de escrever. Explore os kits.
A versão resumida
Se você tem vinte minutos em vez de um dia inteiro:
- Use grep para buscar valores hexadecimais fora do arquivo de tokens. Cada resultado é uma inconsistência.
- Use grep para buscar pesos de fonte acima da sua faixa permitida. Cada resultado é uma inconsistência.
- Conte os valores de raio distintos. Se houver mais de quatro, investigue o motivo.
- Abra três telas de uma mesma superfície. Compare densidade, hierarquia e elevação.
- Observe especificamente os estados vazio, de carregamento e de erro. É onde a consistência será pior.
- Verifique se a sua orientação possui uma lista de proibições. Se não tiver, essa é a correção que evita a próxima rodada de erros.
As etapas de um a três são automatizáveis hoje e nunca mais deveriam ser feitas manualmente. As etapas quatro e cinco exigem um humano e valem meia hora recorrente. A etapa seis é a que decide se você precisará fazer isso tudo de novo no próximo trimestre.
Como faço a auditoria de consistência da UI?
Em três etapas. Verificações mecânicas via grep: cores literais, pesos de fonte, espaçamentos fora da escala, dispersão de raios, propriedades proibidas. Depois, uma análise comparativa com três telas finalizadas da mesma superfície lado a lado. Por fim, trimestralmente, uma auditoria para verificar se as próprias regras são coerentes.
Por que a revisão de código não detecta a inconsistência de design?
Porque a revisão analisa um arquivo por vez, e a divergência só existe entre arquivos. Uma tela pode ser inteiramente coerente sozinha e usar uma estratégia de densidade, hierarquia e elevação diferente de todas as outras telas. Você não consegue manter as outras na memória com precisão suficiente para notar.
Quais são as partes mais comumente inconsistentes de uma interface?
Estados vazios, estados de carregamento e a apresentação de erros, por uma margem ampla. Eles são escritos individualmente sob pressão de tempo, raramente são especificados em um design system e nenhum processo de revisão os compara, apesar de serem justamente o que um usuário travado encontra.
Com que frequência devo realizar uma auditoria de consistência?
Coloque as verificações mecânicas no CI para que rodem continuamente. Faça a análise comparativa mensalmente ou após qualquer surto de novas telas. Audite as próprias regras trimestralmente. Qualquer coisa que aconteça apenas durante uma auditoria agendada permite que a divergência se acumule por um ciclo completo.
A UI gerada por IA é mais ou menos consistente?
Ambas as coisas, de uma forma que anula a revisão normal. Ela é altamente consistente dentro de um único arquivo, mas não tem memória entre sessões, então você obtém um conjunto de telas internamente coerentes que divergem entre si. Verificações automatizadas e a comparação entre telas são as duas únicas formas de detectar isso; a revisão por arquivo, estruturalmente, não consegue.