joo6077/design-audit

Armadilhas

1. Proibido avaliar qualidade de código — Não avalie arquitetura, desempenho ou estilo de código. Julgue apenas a conformidade com princípios de design.

2. Não abuse de FAIL com "token não usado" — Em projetos sem tokens de design, não use "token não usado" como motivo de FAIL. Se não houver um sistema de tokens, recomende o uso da skill design-system com uma NOTA.

3. Categoria de Acessibilidade é obrigatória — Mesmo que pareça visualmente correto, deve-se verificar: contraste (WCAG 2.2 AA 4.5:1), alvos de toque, indicadores de foco, conexão de rótulos de formulário, novos SCs do WCAG 2.2 (Focus Not Obscured 2.4.11 AA, Dragging Movements 2.5.7 AA, Accessible Authentication Min 3.3.8 AA). Se omitir, REJEITAR.

   Padrão de alvo de toque atualizado (2026-04-11):

   • WCAG 2.2 SC 2.5.8 Target Size (Minimum) — AA = 24×24 CSS px (exceções: espaçamento suficiente / texto inline / agente do usuário / essencial)
   • WCAG 2.2 SC 2.5.5 Target Size (Enhanced) — AAA = 44×44 CSS px
   • Apple HIG 44pt = recomendação prática para dispositivos de toque (diretriz da plataforma)

   Em relatórios existentes, especificar apenas "44×44pt" pode levar o leitor a interpretar erroneamente como "requisito WCAG AA". Portanto, diferencie AA/AAA/recomendação da plataforma. Fonte: W3C WCAG 2.2 SC 2.5.8, W3C What's New in WCAG 2.2.

4. Incluir verificação de anti-padrões de IA — A categoria Autenticidade deve ser incluída obrigatoriamente. border-radius uniforme, paletas roxo-azul genéricas, repetição da mesma estrutura, efeitos decorativos sem propósito são motivos de FAIL.

5. Classificação de severidade obrigatória — Cada item FAIL deve ter uma severidade: Critical (acessibilidade, ética), Major (hierarquia, consistência), Minor (ajustes finos). Um relatório FAIL sem severidade está incompleto.

6. Proibido julgamento subjetivo — "Parece bom", "Está razoável" não podem ser justificativas. Todo PASS/FAIL deve ser baseado em princípios e critérios numéricos definidos em audit-criteria.md.

7. Incluir estados/exceções — Não inspecione apenas a tela padrão. Se estados vazio, erro, carregamento, excesso/escassez de dados existirem no código, inspecione-os também.

8. Diferenciar itens não verificáveis no código — Itens que não podem ser julgados por análise estática (como renderização em tempo real, interação real) devem ser marcados como [미검증] (não verificado) em vez de PASS/FAIL, e fornecer instruções para verificação manual.

9. Proibido confundir heurística com categoria — As 10 heurísticas de Nielsen são um quadro de perspectiva de avaliação. O julgamento real deve ser mapeado para os critérios das 10 categorias em audit-criteria.md (Tipografia, Cor, Espaçamento, Acessibilidade, Interação, Movimento, Hierarquia Visual, Layout & Grid, Design Ético, Autenticidade) e executado.

10. Auditoria Regra-por-Regra — Verificação completa das 10 categorias antes da declaração de conclusão — Antes da decisão APPROVE/REJECT, deve-se percorrer todas as 10 categorias × pontos de verificação principais de audit-criteria.md e incluir no relatório uma tabela com PASS / FAIL / [미검증] para cada item. Não agrupe algumas categorias como "não aplicável"; forneça uma justificativa. Uma auditoria que pula categorias não é uma auditoria (conforme §3.6 Rule-by-Rule Audit do skill-design-guide).

11. Binary Decidability Pre-Check — Verificar possibilidade de julgamento binário antes de iniciar a auditoria — Após definir o escopo da auditoria, verifique primeiro se cada item FAIL esperado pode ser julgado como PASS/FAIL apenas com base em código/estilo/tokens. Itens que exigem renderização em tempo real, interação real ou comparação com MCP Figma devem ser imediatamente classificados como [미검증] e não devem ser aprovados como PASS. [미검증] conta em dois contadores — invalid_evidence ([미검증:INVALID] · [미검증] sem sufixo) permite 0 julgamento normal, 1 PASS com aviso, 2 ou mais é REJECT mesmo sem FAILs individuais. [미검증:ENV] que preenche os 4 requisitos é contado separadamente como env_gaps e não conta para REJECT, mas se verified_coverage for inferior a 0.60, é BLOCKED. Esta regra tem como texto canônico a cláusula 「임계값 2 는」 ("Threshold 2") do §Canonical Unverified-Evidence Protocol em harness/docs/guides/qa-evaluation-guide.md e não é redefinida aqui. Deve ter o mesmo valor que a cópia da regra 8 do design-reviewer (conforme §3.5 Binary Decidability do agent-design-guide · reflexo na skill).

12. Evidence Validity Gate — "Há evidência" e "a evidência prova" são diferentes — Enquanto a Armadilha 11 trata de se a evidência pode ser obtida, este item trata de quando a evidência foi obtida mas não prova nada. Antes de confirmar um PASS, passe pelos 4 testes. Se algum falhar, não é PASS, é [미검증].

    #	Teste	Exemplo de falha (no contexto da auditoria)
    1	Não vazio	Citar como evidência um snapshot de 0 bytes ou um log contendo apenas erros
    2	Ativo	PASS de "sem violação de contraste" quando há 0 nós de texto para testar contraste
    3	Falseável	Usar como oráculo um grep que produz o mesmo resultado para qualquer código
    4	Fonte	Adotar como evidência um comentário do implementador ou mensagem de commit como "verificação de acessibilidade feita"

    Julgamento de 0 correspondências — grep com 0 resultados é de dois tipos. 0 intencional (contar o número de arquivos alvo, verificar que o padrão corresponde em outros lugares, e então ter 0) é a única base para PASS. 0 vazio (erro de caminho, arquivo vazio, padrão que nunca corresponde) é uma falha de medição e é [미검증]. Na frase de justificativa, inclua os três juntos no formato N arquivos alvo · validade do padrão confirmada · 0 correspondências.

    Regra especial para saída de renderização — Capturas de tela vazias, listas vazias ou com apenas placeholders não são evidência de PASS, mas sim sinais de falha de verificação. Ao usar uma captura como evidência, aponte para o elemento específico exigido pela condição. Se não puder apontar, é evidência inválida. Para cada captura, verifique a §3 da ../../references/visual-change-protocol.md (lista de verificação de captura: estouro, glifos quebrados, chips/badges e formas de linha, sobreposição de debug). Qualquer captura que falhe em um desses itens não pode ser usada como evidência de PASS. Fonte: harness/docs/guides/qa-evaluation-guide.md §Evidence Validity Gate.

13. Auditoria de contraste Antes/Depois — Mudanças em áreas não intencionadas são FAIL — Ao auditar uma alteração (com base em git diff), não olhe apenas o estado estático; compare o escopo solicitado com o escopo real da alteração. Se a solicitação pedir uma única propriedade visual específica (apenas borda, apenas cor, apenas espaçamento) mas o background / fill / radius / shadow / spacing / typography do mesmo elemento também mudou, é FAIL Major. Se houver cores aprovadas do protótipo ou do aplicativo existente, mas elas foram substituídas por tokens do projeto ou paleta padrão, é FAIL Major (violação de prioridade). O relatório de auditoria deve ser fechado com um bloco EVIDENCE (before / after / proof / área não intencionada). Detalhes: ../../references/visual-change-protocol.md.

14. Cobertura de Propagação de Decisão — Decisão confirmada aplicada apenas a algumas superfícies é FAIL Major — Se .design/decisions.yaml existir, antes da auditoria das 10 categorias, julgue a cobertura (não aumente o número de categorias — é uma verificação de pré-condição). Para cada decision_id com status: approved, percorra required_surfaces[]: (a) se não houver golden nem assertion visível pelo usuário, FAIL (b) se houver golden mas não houver assertion visible/count/height, FAIL (c) superfícies omitidas em excluded_surfaces sem justificativa são lacunas de cobertura, portanto FAIL. A severidade é Major, Critical se for decisão de acessibilidade ou ética. Decisões com status: superseded (substituídas) não julgam a posição da tela; apenas verificam se superseded_by aponta para outra decisão approved na mesma lista. Se o manifesto em si não existir, não é FAIL, mas sim NO_MANIFEST — reporte e exclua do escopo da auditoria. 0 itens alvo é diferente de passar. Esquema, regra 4, verificador executável: ../../references/visual-change-protocol.md §6 Decision Propagation Manifest.

15. Especifique o canal de evidência — Não julgue telas de aplicativo com artifact_snapshot — Anexe o nome do canal (artifact_snapshot / dom_snapshot / browser_user_visible / device_user_visible) a toda evidência citada como justificativa. Frases PASS devem conter 5 elementos: viewport · route/state · visible locator · count/height · screenshot/golden id. Se faltar algum, não é PASS, é [미검증]. Definição dos canais: ../../references/visual-change-protocol.md §7 Evidence Channels. O protocolo para quando um relatório de falha do usuário entra em conflito com a evidência própria é canonicamente definido em harness/docs/guides/skill-design-guide.md §3.8 · harness/docs/guides/agent-design-guide.md §10 e não é redefinido aqui — não refute a observação do usuário com o relatório de auditoria.

Processo

Etapa 1: Determinar escopo e modo alvo

Determine o escopo da auditoria com base no caminho e modo especificados pelo usuário:

• Caminho de arquivo → apenas aquele arquivo
• Caminho de diretório → todos os arquivos de UI abaixo
• Não especificado → arquivos de UI alterados recentemente (com base em git diff)

Modos:

• quick (padrão) — Inspeciona rapidamente todas as 10 categorias. Foco em FAILs Critical/Major.
• deep — Inspeção completa incluindo estados/exceção, breakpoints responsivos, modo escuro, detalhes de acessibilidade.

Etapa 2: Confirmar as categorias de auditoria

Inspecione as 10 categorias em ordem. Pontos de verificação principais de cada categoria:

Categoria	Ponto de verificação principal	Critério de severidade
Tipografia	Consistência da escala tipográfica, entrelinha (faixa por sistema de escrita — linha de proporção de entrelinha em references/audit-criteria.md), corpo de texto mínimo 14px (mobile)/16px (web)	Major
Cor	Contraste de texto WCAG 2.2 AA 4.5:1, uso de tokens semânticos, manutenção de contraste no modo escuro, verificação de fallback sRGB ao usar gama ampla OKLCH/P3. Referência APCA Lc (informativa): Lc 75~90 para texto do corpo, Lc 60 ou mais para não texto, Lc abaixo de 15 é invisível. APCA exige contraste diferenciado por tamanho de fonte + espessura, portanto fontes finas precisam de contraste maior. O critério de julgamento é WCAG 2.2 AA; APCA é para referência do WD WCAG 3.0	Critical (contraste) / Major (token)
Espaçamento	Consistência da escala de espaçamento, alvo de toque WCAG 2.2 SC 2.5.8 AA ≥24×24 CSS px (AAA SC 2.5.5 = 44×44), hierarquia de margem entre/dentro de grupos	Critical (toque) / Major (escala)
Acessibilidade	Não transmitir estado apenas com cor, indicador de foco, rótulos de formulário, texto alternativo, WCAG 2.2 SC 2.4.11 Focus Not Obscured (AA), SC 2.5.7 Dragging Movements (AA), SC 3.3.8 Accessible Authentication Min (AA)	Critical
Interação	Feedback de ação, indicador de carregamento, exibição de erro, caminho de cancelar/desfazer, UX exclusivo de arrasto alternativo com ponteiro único (WCAG 2.2 SC 2.5.7)	Major
Movimento	Propósito da animação, duração 200~500ms, suporte a prefers-reduced-motion	Major
Hierarquia Visual	Diferença de proporção título/corpo/legenda, ênfase de contraste do conteúdo principal, separação de margem de grupo	Major
Layout & Grid	Alinhamento de grade, consistência de gutter, estratégia responsiva para breakpoints principais, responsivo em nível de componente recomenda container-type: inline-size + @container (suporte a consultas de tamanho: Chrome 105 · Firefox 110 · Safari 16). Verificação de Container Queries: Confirme se divisões em nível de página usam media queries, divisões em nível de componente usam container queries. Recomenda-se uso de unidades cqw/cqi e definição de breakpoints com base em ponto de quebra de conteúdo (não alvo de dispositivo)	Major
Design Ético	Ausência dos 12 tipos de dark pattern, clareza do consentimento, simetria dos caminhos de inscrição/cancelamento	Critical
Autenticidade	Repetição da mesma estrutura 3 vezes ou mais, paleta genérica, decoração sem propósito, cópia genérica, inconsistência com convenções de telas existentes com a mesma função	Minor~Major

Etapa 3: Chamar o agente design-reviewer

Use a ferramenta Agent para criar um subagente design-reviewer:

Chamada de ferramenta Agent:
- subagent_type: design-reviewer
- prompt: "Avalie o(s) seguinte(s) arquivo(s) com base em princípios de design no modo [quick|deep]: [lista de arquivos alvo]"

O agente analisa (somente leitura) e retorna resultados PASS/FAIL/미검증 por categoria.

Etapa 4: Formatação do relatório

Organize o resultado do agente no formato templates/audit-report.md.

Cada item FAIL deve incluir obrigatoriamente:

• Local do arquivo:linha
• Severidade (Critical / Major / Minor)
• Princípio violado (com fonte)
• Direção concreta de melhoria (nível independente de stack)

Se houver 1 ou mais [미검증], inclua a contagem de validade no relatório (Armadilha 12):

## Validade da Evidência
- Evidências inspecionadas: {{n}}
- Julgadas inválidas: {{k}} [ID do item — Nº do teste falho — Motivo]
- Acumulado de não verificado: `invalid_evidence` {{a}} / `env_gaps` {{b}} / `verified_coverage` {{c}}

Etapa 5: Julgamento final

• FAIL 0 + invalid_evidence 0 + verified_coverage 0.60 ou mais + L3 10/10 → APPROVE (informe o número de env_gaps)
• 1 ou mais FAILs de Cobertura de Propagação de Decisão → REJECT (pré-condição separada do julgamento das 10 categorias — Armadilha 14. Ausência de manifesto não é FAIL, é relatório NO_MANIFEST)
• Código de saída 2 da verificação de propagação de decisão (SCHEMA_ERROR) significa que a entrada estava malformada e não pôde ser julgada, portanto é REJECT — mesmo que FAIL não apareça e violations=0 seja impresso, não interprete como aprovado. Código de saída 3 (NO_SURFACE · NO_DECISION) é relatado como 0 itens alvo, assim como NO_MANIFEST
• 1 ou mais FAILs Critical → REJECT (imediatamente)
• Apenas FAILs Major/Minor → REJECT + lista de melhorias por prioridade
• FAIL 0 mas invalid_evidence 2 ou mais → REJECT (limiar da Armadilha 11)
• FAIL 0, invalid_evidence menor que 2, verified_coverage = (número de itens verificados − env_gaps) / número de itens verificados < 0.60 → BLOCKED (insufficient_verified_coverage — execute um comando de re-verificação e re-audite)
• Mesmo com FAIL 0, se a cobertura L3 < 10/10 (categorias puladas das 10) → REJECT + especifique as categorias restantes (categoria pulada é FAIL — regra 11 do revisor)
• FAIL 0, invalid_evidence 1, verified_coverage 0.60 ou mais, L3 10/10 → APPROVE + especifique itens não verificados e métodos de verificação manual

Estrutura do relatório REJECT:

1. Lista de FAILs Critical (correção imediata necessária)
2. Lista de FAILs Major (corrigir antes do próximo sprint)
3. Lista de FAILs Minor (melhoria recomendada)
4. Itens [미검증] (verificação manual necessária — diferenciar [미검증:ENV] / [미검증:INVALID])

Se a auditoria for de alteração (com base em git diff), feche o relatório com um bloco EVIDENCE (Armadilha 13):

## EVIDENCE
- before: [Evidência do estado antes da alteração — arquivo:linha ou captura]
- after:  [Evidência do estado após a alteração]
- proof:  [Comando e saída que suportam o julgamento]
- Área não intencionada: [Evidência de que não houve alteração / ou item tratado como FAIL]

Referências

• references/audit-criteria.md — Critérios detalhados de auditoria por categoria
• templates/audit-report.md — Formato de saída do relatório
• ../../references/visual-change-protocol.md — Prioridade de alteração visual · Isolamento de alteração parcial · Bloco de evidência · §6 Decision Propagation Manifest · §7 Evidence Channels (SSOT)
• harness/docs/guides/skill-design-guide.md §3.8 · harness/docs/guides/agent-design-guide.md §10 — Texto canônico do protocolo de prioridade de relatório de falha do usuário
• harness/docs/guides/qa-evaluation-guide.md §Canonical Unverified-Evidence Protocol · §Evidence Validity Gate — Texto canônico do limiar de [미검증] e dos 4 testes de validade