agent-engineering-skills 1.0.0

package/skills/frontend/animation-review/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: animation-review
+description: Evaluates purpose, timing, easing, hierarchy, continuity, interruption, accessibility, and reduced motion compliance of every animation in the interface.
+category: frontend
+triggers:
+  - "audit animations"
+  - "review motion and transitions"
+  - "check timing and easing"
+  - "verify reduced motion"
+  - "animation hierarchy and interruption"
+priority: high
+---
+
+# Animation Review
+
+## Objective
+
+Ensinar o agente a avaliar animações contra princípios de motion design: propósito,
+timing, easing, hierarquia, continuidade, interrupção, acessibilidade, e reduced
+motion. Toda animação deve ter uma razão de existir; se não serve à função, é ruído.
+
+## When to Use
+
+* Em qualquer interface com animações, transições, micro-interações, parallax,
+  loaders, ou motion.
+* Quando o pedido menciona "animation", "motion", "transitions", "easing", "timing",
+  "reduced motion", "parallax".
+* **Composição:** roda com `interaction-design` (transições e feedback de estado),
+  `accessibility-review` (reduced motion, vestibular), e `ux-review` (animação que
+  informa vs distrai). Consulta `references/frontend.yaml` (Animate UI, Impeccable,
+  Interfaces).
+
+## Mental Model
+
+Animação não é decoração — é **comunicação**. Toda animação deve responder a uma
+pergunta do usuário (o que aconteceu? para onde vai? o que mudou?). Se não responde,
+é ruído visual.
+
+Os eixos (do `plan.md` §10):
+
+```text
+purpose          — a animação comunica algo? (mudança de estado, navegação, feedback)
+timing           — duração correta para o que comunica (muito rápida = imperceptível;
+                   muito lenta = frustrante)
+easing           — a curva de aceleração é natural? (ease-out para entrada, ease-in
+                   para saída, spring para interação)
+hierarchy        — animações mais importantes são mais rápidas/notáveis que as menos
+                   importantes
+continuity       — elementos não teleportam; o movimento é contínuo entre estados
+interruption    — a animação pode ser interrompida? (se o usuário clica de novo, o
+                   que acontece?)
+accessibility    — a animação respeita `prefers-reduced-motion`?
+reduced motion   — cores e transições não causam desconforto visual (vestibular,
+                   epilepsy)
+```
+
+## Investigation Procedure
+
+1. **Inventariar animações** — carregamento, transição de página, hover, expansão,
+   entrada/saída, loader, parallax, scroll-triggered.
+2. **Para cada, avaliar propósito** — comunica uma mudança de estado, direção, hierarquia?
+   Ou é decorativa sem função? ("animation for its own sake")
+3. **Avaliar timing** — durações consistentes? (50-100ms para feedback, 200-300ms para
+   transição de página, > 500ms só para storytelling). Todas as animações similares
+   têm a mesma duração?
+4. **Avaliar easing** — a curva de aceleração é natural? (ease-out para entrada de
+   objetos, ease-in para saída, spring para interação tátil). Ou é linear (robótica)?
+5. **Avaliar hierarchy** — a animação principal é mais rápida que as secundárias? Ou
+   tudo anima junto no mesmo tempo?
+6. **Avaliar continuity** — elementos teleportam entre estados? (não: movimento
+   contínuo é esperado). Exemplo: modal abre sem transição, item some sem fade.
+7. **Avaliar interruption** — se o usuário clica de novo, a animação reinicia ou
+   inverte suavemente? Ou trava/empilha?
+8. **Avaliar reduced motion** — `@media (prefers-reduced-motion: reduce)` é respeitado?
+   Animações sensíveis (parallax, scroll, flutuação) são desligadas? Há botão de
+   desligar motion no app?
+9. **Avaliar desconforto** — parallax acentuado, flutuação constante, scroll-triggered
+   que compete com scroll, loading animation que vibra. Causa desconforto vestibular?
+10. **Sintetizar** — referenciar `references/frontend.yaml` (Animate UI, Impeccable)
+    quando apropriado.
+
+## Questions to Ask
+
+* Esta animação tem propósito? (comunica algo, ou só "enfeita"?)
+* Duração é apropriada? (feedback rápido, transição suave, storytelling lento?)
+* Easing é natural (ease-out/spring) ou linear (robótica)?
+* Animações similares têm a mesma duração e easing? (consistência)
+* A animação mais importante é mais rápida que as secundárias? (hierarchy)
+* Elementos teleportam ou se movem continuamente? (continuity)
+* Se o usuário clica de novo, a animação interrompe suavemente? (interruption)
+* `prefers-reduced-motion` é respeitado? (accessibility)
+* Alguma animação causa desconforto visual? (parallax/scroll não-controlado)
+
+## Attack Patterns
+
+```text
+purpose absent
+    entrada de sidebar com fade+slide quando o conteúdo não mudou → por quê?
+    (animação decorativa sem função comunicativa)
+
+timing wrong
+    hover de botão: 300ms (muito longo para feedback que deve ser < 100ms)
+    transição de página: 100ms (muito rápido, não comunica navegação)
+    loader: 10s (nunca deve; se > 10s, erro)
+
+easing linear
+    todas as animações usam `ease` ou `linear`
+    → movimento robótico, sem naturalidade; falta spring/ease-out
+
+hierarchy inverted
+    micro-interação de ícone (secundária) anima 300ms
+    transição de página (principal) anima 100ms
+    → hierarquia invertida; o principal parece menos importante
+
+continuity broken
+    modal aparece sem transição (teleport)
+    item some antes de sair da tela (corte abrupto)
+    → desorientação, perda de contexto
+
+interruption broken
+    clique em botão → animação de 300ms
+    clique de novo no meio → animação reinicia do início (trava) ou empilha (2×)
+    → deveria interromper e inverter suavemente
+
+reduced motion ignored
+    parallax no hero com `prefers-reduced-motion: reduce`
+    → ainda anima, causa desconforto vestibular
+
+vestibular risk
+    paralaxe acentuado em background de scroll-triggered
+    flutuação constante de CTA (sobe e desce para sempre)
+    loading spinner com rotação rápida + contraste alto
+```
+
+## Evidence Requirements
+
+* **Nomear a animação e o eixo** (propósito/timing/easing/hierarchy/continuity/
+  interruption/accessibility/reduced motion).
+* **Mostrar os valores exatos** (timing em ms, easing function, CSS/JS da animação).
+* **Escalar confiança (Animation Review):**
+  * `CONFIRMED` — animação sem propósito, timing errado, easing linear, hierarchy
+    invertida, continuity quebrada, reduced motion não respeitado.
+  * `HIGH CONFIDENCE` — violação clara de princípio.
+  * `POSSIBLE` — questão de nuance (timing marginalmente longo).
+  * `SPECULATIVE` — preferência pessoal.
+
+## False Positives
+
+* **Animação de marca com propósito** — animações de marca (logo, loading) podem ser
+  mais longas e expressivas por design. Avaliar se servem à identidade ou são ruído.
+* **Timing varia por plataforma** — mobile vs desktop podem ter durações diferentes.
+  Não reportar "inconsistência" entre plataformas sem considerar o contexto.
+* **Reduced motion parcial** — se o app respeita reduced motion para as animações
+  principais, omitir de micro-interações pode ser aceitável. Marcar como melhoria.
+* **Parallax com fallback** — se parallax desliga em reduced motion, é aceitável.
+  Confirmar o fallback.
+* **Easing linear intencional** — progress bar, skeleton, ou loader podem ser lineares
+  intencionalmente. Não reportar como erro.
+
+## Output Format
+
+Para cada animação que viola um princípio, um finding via `templates/audit-report.md`.
+Em **Affected component**, nomeie a animação. Em **Reproduction**, descreva o que o
+usuário vê vs o esperado (timing, easing, continuity, etc.). Em **Root cause**, aponte
+o eixo violado. Em **Recommendation**, dê a correção (timing, easing, respectar
+reduced motion, adicionar continuity, interrompção suave, remover animação sem
+propósito).
+
+Apresente por eixo. Reduced motion e vestibular (acessibilidade/desconforto) primeiro;
+purpose e continuity depois; timing/easing/hierarchy em seguida; interruption por
+último.

package/skills/frontend/interaction-design/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: interaction-design
+description: Evaluates hover, focus, pressed, disabled, loading, transitions, feedback, and micro-interactions to verify every state of every interactive element is intentionally designed.
+category: frontend
+triggers:
+  - "audit interaction design"
+  - "check hover focus pressed disabled states"
+  - "review micro-interactions"
+  - "loading and transition feedback"
+  - "every interactive state designed"
+priority: high
+---
+
+# Interaction Design
+
+## Objective
+
+Ensinar o agente a avaliar **cada estado de cada elemento interativo**: hover, focus,
+pressed, disabled, loading, transitions, feedback, e micro-interações. A pergunta
+central: *todo estado que o usuário pode ver está intencionalmente desenhado, ou há
+estados acidentais (sem feedback, sem affordance, sem contraste)?*
+
+## When to Use
+
+* Em qualquer tela com elementos interativos (botões, links, inputs, dropdowns, cards
+  clicáveis, toggles).
+* Quando o pedido menciona "interaction", "micro-interactions", "hover state",
+  "focus state", "disabled state", "loading state".
+* Em revisões de frontend onde UX e visual são complementares à interação.
+* **Composição:** roda com `ux-review` (a interação serve à UX), `visual-quality-review`
+  (estados são visuais), `animation-review` (transições/motion são interação), e
+  `accessibility-review` (focus/keyboard são acessibilidade E interação).
+
+## Mental Model
+
+Todo elemento interativo é uma **máquina de estados**: default, hover, focus, pressed,
+disabled, loading, selected, error. O bug de interação é um **estado não-desenhado** —
+o usuário paira, foca, pressiona, desabilita, e nada comunica a mudança. O sistema
+"funciona" mas não *reage*.
+
+O modelo de estados canônicos (do `plan.md` §10):
+
+```text
+hover      — indica que o elemento é interativo (mudança de fundo/borda/elevação)
+focus      — indica posição de teclado/assistivo (ring, outline, não removido!)
+pressed    — confirma o pressionamento (escala, escurece, "estou sendo clicado")
+disabled   — comunica indisponibilidade com causa (não só "cinza morto")
+loading    — comunica trabalho em progresso (não congelar sem feedback)
+transitions — mudanças de estado são suaves e legíveis, não teleportadas
+feedback   — resultado da interação é comunicado (não só no DOM)
+micro-interactions — detalhe que encanta e informa (efeito sutil e significativo)
+```
+
+## Investigation Procedure
+
+1. **Listar elementos interativos** — botões, links, inputs, selects, toggles, cards,
+   tabs, dropdowns, modais, checkboxes.
+2. **Para cada elemento, percorrer os estados:**
+   * **default** — comunica a função? (affordance)
+   * **hover** — muda algo? O que? É distinto o suficiente?
+   * **focus** — há focus ring/outline? Foi removido (culpado — acessibilidade)?
+   * **pressed** — dá feedback de pressionamento? Ou fica estático?
+   * **disabled** — comunica por quê? Ou é indistinguível de erro?
+   * **loading** — durante a ação, o elemento mostra progresso? (spinner/skeleton/
+     mudança de label) ou congela?
+   * **selected/active** — o estado selecionado é visível e distinto?
+   * **error** — a interação que falha comunica o erro?
+3. **Avaliar transitions** — mudanças de estado são suaves? (ou teleportam?) São
+   rápidas demais para perceber ou lentas demais para tolerar?
+4. **Avaliar micro-interactions** — há detalhe que informa (ex: input com check de
+   validação, botão com confirmação)? Algum é *excessivo* (ruído)?
+5. **Verificar focus sequence** — interagir só com teclado funciona? (parcialmente
+   aqui, completo em `accessibility-review`).
+6. **Sintetizar** com o formato de saída.
+
+## Questions to Ask
+
+* Cada elemento interativo comunica sua função no default? (affordance)
+* O hover muda o estado de forma perceptível? (fundo/borda/elevação)
+* O focus tem ring/outline visível? Foi removido com `outline: none`?
+* O pressed dá feedback de pressionamento? (escala/escurece)
+* O disabled comunica a causa ("unavailable — upgrade to pro") ou é um cinza mudo?
+* Durante uma ação, o elemento mostra loading? Ou congela até o fim?
+* O estado selecionado (active/tab/selected) é visível e distinto?
+* Transições são suaves? (ou teleportam entre estados?)
+* Micro-interações informam ou só enfeitam? (alguma é excessiva/ruído?)
+* A interação com teclado completa o fluxo? (focus sequence funciona?)
+
+## Attack Patterns
+
+```text
+hover without affordance change
+    botão muda cor no hover, mas links/ícones não — o que é clicável é inconsistente
+
+focus removed
+    `:focus { outline: none }` sem substituto
+    → teclado/assistivo não sabe onde está. Acessibilidade E interação quebrada.
+
+pressed feedback absent
+    botão não reage ao clique (sem escala, sem mudança)
+    → usuário não sabe se o clique foi registrado
+
+disabled without cause
+    botão cinza sem tooltip/legenda de "por quê"
+    → usuário pensa que está bugado (ver também `error-flow-audit`)
+
+loading frozen
+    ação disparada, botão congela 3s sem feedback
+    → usuário clica de novo (duplo submit), ou acha que quebrou
+
+selected state invisible
+    tab selecionada e não-selecionada têm o mesmo peso visual
+    → usuário não sabe em que página está
+
+transition too fast/slow
+    0ms (teleport) → desorientado
+    800ms em card grid → frustrante, lento
+
+micro-interaction excessive
+    animação em cada hover de ícone de 24px → ruído visual, distração
+    (ver `animation-review`)
+
+feedback after action absent
+    toggle flip sem "salvo" (o toggle é otimistic e o servidor falhou — ver
+    `state-consistency-audit` — ou a mudança não é comunicada)
+```
+
+## Evidence Requirements
+
+* **Nomear o elemento e o estado** (ex: "botão Save: estado disabled sem explicação").
+* **Mostrar o estado observado** vs o estado esperado (sem focus ring, sem feedback de
+  pressed, congelado em loading).
+* **Escalar confiança (Interaction Design):**
+  * `CONFIRMED` — estado não-desenhado observado (ex: `outline: none` sem substituto,
+    botão congela sem loading).
+  * `HIGH CONFIDENCE` — código/estilo confirma a ausência de estado.
+  * `POSSIBLE` — interação marginalmente inconsistente.
+  * `SPECULATIVE` — preferência pessoal sobre micro-interação.
+
+## False Positives
+
+* **Plataforma usa padrão diferente** — hover em touch não existe; em desktop touch
+  não aplica. Avaliar por plataforma/dispositivo.
+* **Micro-interação é parte da marca** — animações de marca podem ser mais presentes;
+  avaliar se servem a identidade ou são ruído.
+* **Focus via outro sinal** — focus ring removido mas substituído por outra indicação
+  visível (border, background) em todos os estados. Confirmar antes de reportar.
+* **Disabled com tooltip intencional** — se o disabled tem tooltip/legend explicando
+  causa, não é "cinza mudo". Confirmar.
+* **Loading indireto** — skeleton no lugar do conteúdo é loading válido. Não exigir
+  spinner no botão se o skeleton comunica.
+
+## Output Format
+
+Para cada estado não-desenhado, um finding via `templates/audit-report.md`. Em
+**Affected component**, nomeie o elemento e o estado. Em **Reproduction**, descreva o
+que o usuário vê vs o que deveria ver (paira/foca/pressiona e nada muda). Em **Root
+cause**, aponte o estado ausente. Em **Recommendation**, dê a correção (adicionar focus
+ring, feedback de pressed, disabled com causa, loading state, selected state).
+
+Apresente por elemento × estado. Focus e feedback (impacto direto em uso) primeiro;
+hover/pressed/disabled depois; transitions e micro-interactions por último.

package/skills/frontend/ux-review/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: ux-review
+description: Evaluates clarity, hierarchy, cognitive load, feedback, affordances, consistency, navigation, empty states, errors, loading, and progress indicators in a user interface against established UX principles.
+category: frontend
+triggers:
+  - "review ux"
+  - "audit usability"
+  - "evaluate clarity and cognitive load"
+  - "check empty states and errors"
+  - "review navigation and feedback"
+priority: high
+---
+
+# UX Review
+
+## Objective
+
+Ensinar o agente a avaliar a experiência do usuário de uma interface contra princípios
+estabelecidos: clareza, hierarquia, carga cognitiva, feedback, affordances,
+consistência, navegação, estados vazios, erros, e loading.
+
+## When to Use
+
+* Antes de lançar ou revisar uma tela/fluxo que o usuário vê.
+* Quando o pedido menciona "UX", "usability", "user experience", "confusing",
+  "unclear", "clarity", "feedback".
+* Em qualquer revisão de frontend que não seja puramente visual (ver
+  `visual-quality-review` para o visual).
+* **Composição:** roda com todas as frontend skills (especialmente `visual-quality-review` e `interaction-design`). Pareia também com `user-flow-audit` (fluxos) e
+  `reference-research` (referências de UX de `references/ux.yaml`).
+
+## Mental Model
+
+UX não é sobre beleza — é sobre **reduzir a distância entre a intenção do usuário e o
+efeito no sistema**. Toda ambiguidade, pausa, ou descoberta é atrito.
+
+Seis princípios base:
+
+1. **Clareza** — o usuário entende o que está vendo, o que pode fazer, e o que cada
+   ação faz.
+2. **Hierarquia** — o layout comunica importância relativa: mais importante = maior,
+   mais perto do topo, mais contraste.
+3. **Carga cognitiva** — quanta informação o usuário precisa reter para agir. Quanto
+   menos, melhor.
+4. **Feedback** — toda ação deve ter resposta visível em < 100ms (imediata) ou
+   indicador de progresso (se > 1s). O estado do sistema é sempre visível.
+5. **Affordances** — elementos comunicam sua função. Botões parecem clicáveis, inputs
+   parecem editáveis, items não-clicáveis não parecem botões.
+6. **Consistência** — o mesmo padrão visual/comportamental resolve o mesmo problema em
+   toda a interface. Modais não variam; botões primários não alternam cor.
+
+## Investigation Procedure
+
+1. **Capturar / revisar a tela** — lista de componentes, fluxo, estados.
+2. **Avaliar clareza** — o título/heading explica o que é esta página? A ação primária
+   é óbvia? Labels são descritivas?
+3. **Avaliar hierarquia** — o elemento mais importante é o mais proeminente? Há
+   hierarquia visual (tamanho, peso, cor, espaçamento) ou é tudo igual?
+4. **Avaliar carga cognitiva** — quantos elementos o usuário precisa processar antes
+   de agir? Há informação redundante? Há campos desnecessários?
+5. **Avaliar feedback** — ações têm resposta imediata? Loading states existem? O
+   sistema mostra o estado atual após cada ação? Erros são comunicados perto do campo?
+6. **Avaliar affordances** — botões parecem clicáveis? Links parecem links?
+   Inputs parecem editáveis? Texto pleno parece clicável? (se sim, affordance falsa)
+7. **Avaliar consistência** — o mesmo tipo de ação usa o mesmo componente em toda a
+   interface? (todos os "salvar" são iguais? todos os "cancelar" são iguais?)
+8. **Avaliar navegação** — o usuário sabe onde está? Sabe como voltar? Sabe onde
+   encontrar ações importantes? Há breadcrumbs/back consistentes?
+9. **Avaliar estados vazios** — o que aparece quando não há dados? Guia, instrução, ou
+   espaço vazio? (empty state deve ser útil, não confuso)
+10. **Avaliar erros e loading** — erros são legíveis e acionáveis? Loading é visível e
+    não bloqueia para sempre? (ver `error-flow-audit` para erros server-side)
+11. **Sintetizar** com o formato de saída, referenciando `references/ux.yaml` quando
+    apropriado.
+
+## Questions to Ask
+
+* O usuário entende o que esta página/tela faz sem ler um tutorial?
+* Qual é a ação primária? Ela é a mais proeminente visualmente?
+* Quantos elementos competem pela atenção do usuário ao mesmo tempo?
+* Toda ação dá feedback imediato? (visual, não só console.log)
+* O estado do sistema (salvo, carregando, erro) é visível sem o usuário precisar
+  adivinhar?
+* Botões parecem clicáveis? Inputs parecem editáveis? Texto pleno parece link?
+* O mesmo padrão repete para o mesmo problema? (botões, modais, notificações, menus)
+* O usuário sabe onde está e como voltar? (navegação, breadcrumbs, back)
+* O que aparece quando não há dados? (empty state: útil ou vazio?)
+* Erros são legíveis ("Campo obrigatório" vs "Error 500 — contact support")?
+* Loading é visível e não bloqueia para sempre? (skeleton, spinner, ou tela branca?)
+
+## Attack Patterns
+
+```text
+clarity failure
+    título "Dashboard" → dashboard de quê? de quem? sem contexto
+    botão "Submit" → submit o quê? para onde? o que acontece depois?
+
+hierarchy flattened
+    ação primária (salvar) e secundária (cancelar) têm o mesmo peso visual
+    → usuário hesita, erra, ou ignora a primária
+
+cognitive overload
+    form com 20 campos, 3 seções, 2 tipos de validação
+    → taxa de abandono alta, erros frequentes
+
+feedback absent
+    "Save" → sem loading, sem confirmação, sem erro
+    → usuário clica de novo (duplo submit) ou não sabe se salvou
+
+affordance false
+    card de perfil clicável leva ao perfil (não parece clicável)
+    → usuário não descobre que pode editar clicando
+
+consistency broken
+    modal de confirmação: "Save" verde / "Cancel" cinza
+    mesma ação em outra tela: "Save" azul / "Cancel" vermelho
+    → confiança no padrão quebrada
+
+navigation lost
+    sem breadcrumbs, sem back button consistente, sem título de página
+    → usuário não sabe onde está após 3 cliques
+
+empty state useless
+    empty: "No data" — e agora? O que o usuário deve fazer?
+    (correto: "No posts yet. Create your first post!" com link)
+
+error not actionable
+    "Something went wrong" — qual problema? o que o usuário faz?
+    (correto: "Connection lost. Check your internet and retry.")
+```
+
+## Evidence Requirements
+
+* **Nomear o princípio violado** (clareza/hierarquia/carga cognitiva/feedback/
+  affordance/consistência/navegação/empty state/error).
+* **Mostrar o elemento exato** e o porquê da violação (ex: "Dois botões primários",
+  "Título vago", "Estado vazio sem ação").
+* **Referenciar a fonte de UX** (Laws of UX, Interfaces, etc.) como suporte quando
+  relevante — mas não é evidência, é fundamentação.
+* **Escalar confiança (UX Review):**
+  * `CONFIRMED` — padrão observado, princípio violado, e o impacto é demonstrável
+    (ex: usuário hesita, clica errado, abandona).
+  * `HIGH CONFIDENCE` — padrão observado, princípio violado, impacto plausível.
+  * `POSSIBLE` — violação marginal ou subjetiva.
+  * `SPECULATIVE` — preferência pessoal sem fundamento em princípio.
+
+## False Positives
+
+* **Padrão de plataforma** — iOS HIG e Material Design diferem; um padrão "diferente" é
+  correto se consistente com a plataforma.
+* **Público específico** — alta densidade de informação pode ser intencional para
+  power users. Avaliar pelo público-alvo.
+* **Empty state com propósito** — "sem dados" pode ser deliberado (ex: não há
+  conteúdo e o estado não pede ação). Verificar intenção.
+* **Feedback não-visual intencional** — haptic/audio feedback pode substituir visual.
+  Não reportar se o feedback existe em outra modalidade.
+* **Consistência com design system** — se o design system define o padrão, a variação
+  está errada. Verificar contra o design system antes de reportar.
+* **Preferência pessoal** — "eu não gosto" não é finding de UX. Toda crítica deve ser
+  fundamentada em princípio, não em gosto.
+
+## Output Format
+
+Para cada violação de princípio, um finding via `templates/audit-report.md`. Em
+**Affected component**, nomeie o componente/tela. Em **Reproduction**, descreva o que
+o usuário vê e o que deveria ver. Em **Root cause**, aponte o princípio violado. Em
+**Recommendation**, dê a correção concreta de UX (título, realce da ação primária,
+empty state guiado, feedback adicionado, affordance corrigida, consistência de padrão).
+
+Apresente por princípio violado. Impacto em fluxo (navegação perdida, erro não
+acionável) primeiro; clareza e hierarquia depois; affordance/consistência/empty state
+em seguida.

package/skills/frontend/visual-quality-review/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: visual-quality-review
+description: Evaluates typography, spacing, hierarchy, density, contrast, composition, consistency, visual noise, and generic AI slop patterns against a high craft bar.
+category: frontend
+triggers:
+  - "audit visual quality"
+  - "review typography spacing hierarchy"
+  - "check contrast and density"
+  - "detect AI slop"
+  - "evaluate visual craft"
+priority: high
+---
+
+# Visual Quality Review
+
+## Objective
+
+Ensinar o agente a avaliar a **qualidade de execução visual** de uma interface contra
+um bar padrão de craft: tipografia, spacing, hierarquia, densidade, contraste,
+composição, consistência, ruído visual, e padrões genéricos de AI slop.
+
+## When to Use
+
+* Em qualquer revisão de frontend que não seja só de UX ou interação.
+* Quando uma interface parece "genérica", "feia", "amadora", ou "feita por IA".
+* Quando o pedido menciona "visual quality", "craft", "polish", "typography",
+  "spacing", "hierarchy", "AI slop", "generic", "boring".
+* **Composição:** roda com `ux-review` (UX + visual são complementares) e
+  `interaction-design` (visual + interação = experiência completa). Consulta
+  `references/frontend.yaml` (Impeccable, Impeccable Slop, Dribbble, Interfaces).
+
+## Mental Model
+
+Qualidade visual não é subjetiva — é uma execução de princípios de design. Os eixos
+são mensuráveis:
+
+| Eixo | O que avaliar |
+|---|---|
+| **Tipografia** | hierarchy consistente, escala, line-height, legibilidade, contraste de fonte |
+| **Spacing** | sistema de ritmo, padding interno vs externo, alinhamento vertical/horizontal |
+| **Hierarchy** | peso visual que comunica importância relativa, não só tamanho |
+| **Density** | informação compactada ou espaçada demais? |
+| **Contrast** | texto vs fundo, componentes vs background, modo escuro/claro |
+| **Composition** | balance, grid, alinhamento, margens, corners |
+| **Consistency** | o mesmo padrão visual resolve o mesmo problema em toda a interface |
+| **Visual noise** | elementos decorativos sem função, bordas desnecessárias, cores demais |
+| **AI slop** | padrões genéricos que indicam output de IA sem revisão |
+
+## Investigation Procedure
+
+1. **Avaliar tipografia** — há escala consistente? (h1 > h2 > h3 > body > caption)
+   O line-height é legível? O contraste de fonte é suficiente? A fonte é apropriada
+   para o contexto?
+2. **Avaliar spacing** — há um sistema de ritmo (4px nem sempre, mas consistente)?
+   Elementos relacionados estão próximos? Elementos diferentes estão separados?
+3. **Avaliar hierarchy** — a ação primária é a mais proeminente? Informações de mesmo
+   nível têm o mesmo peso visual? A hierarquia é comunicada por mais de um sinal
+   (tamanho + peso + cor + espaçamento)?
+4. **Avaliar density** — o conteúdo é denso demais? (exaustivo) ou esparso demais?
+   (precisa scroll infinito para ver nada)
+5. **Avaliar contrast** — texto body tem ≥ 4.5:1? O contraste de componentes é
+   suficiente? Modo escuro recalculou cores ou só inverteu?
+6. **Avaliar composition** — grid consistente? Alinhamento vertical/horizontal correto?
+   Margens e paddings consistentes? Corners uniformes?
+7. **Avaliar visual noise** — há elementos decorativos que não servem à função
+   (bordas, ícones, cores, gradientes, sombras)? Há informações redundantes?
+8. **Avaliar AI slop** — padrões genéricos: ícones Lucide sem personalidade, ondas
+   SVG repetitivas, "Build Something Amazing", "Empower Your Team", roxo-azul
+   gradiente, cartões sem conteúdo real, avatares genéricos.
+9. **Sintetizar** — referenciar `references/frontend.yaml` (Impeccable, Impeccable
+   Slop, Interfaces) quando apropriado.
+
+## Questions to Ask
+
+* A tipografia tem escala consistente? A fonte é legível no tamanho usado?
+* O spacing é consistente ou parece aleatório? (padding varia sem motivo)
+* A hierarquia visual comunica o que é importante? (ou tudo parece igual)
+* A densidade é apropriada para o conteúdo? (informação compactada vs perdida)
+* O contraste de texto é suficiente (≥ 4.5:1)? O modo escuro recalcula ou é acidental?
+* O grid é consistente? Alinhamentos estão corretos?
+* Há elementos decorativos sem função? (visual noise)
+* A interface parece "genérica"? (mesmo gradiente, mesmo ícone, mesmo "Build
+  Something" — AI slop)
+
+## Attack Patterns
+
+```text
+typography broken
+    h1 = 32px, h2 = 28px, h3 = 18px  (escala inconsistente — gap de 2px vs 10px)
+    body = 14px com line-height 1.2 (ilegível)
+    fonte display para body text (cansativa)
+
+spacing random
+    padding: 24px em um card, 16px em outro (mesmo tipo)
+    elementos relacionados com 40px de gap; unrelated com 8px
+
+hierarchy flat
+    preço (importante) e "em até 3x sem juros" (secundário) têm mesmo size/weight
+    → usuário não sabe o que é o valor principal
+
+density wrong
+    form com 3 campos + 2 botões ocupando 100% da viewport (esparso demais)
+    tabela com 10 colunas sem scroll horizontal (denso demais)
+
+contrast insufficient
+    gray-400 (#9CA3AF) em gray-50 (#F9FAFB) — 1.8:1, invisível
+    placeholder cinza claro em fundo branco
+
+composition broken
+    margem esquerda 24px, direita 16px (não centrado)
+    grid com gutter inconsistente
+
+AI slop detected
+    "Build Something Amazing" como headline
+    gradiente azul-roxo padrão
+    ondas SVG decorativas sem sentido
+    avatares de usuário genéricos (UI Avatars sem personalização)
+    "Lorem ipsum" em produção
+    tooltip genérico "This is a tooltip"
+    "Empower Your Workflow" como subheading
+```
+
+## Evidence Requirements
+
+* **Nomear o eixo** (tipografia/spacing/hierarchy/density/contrast/composition/
+  noise/slop).
+* **Mostrar o elemento exato** e a violação do princípio (ex: "h1=32px, h2=28px no
+  header, mas h2=20px no card — inconsistência de escala").
+* **Referenciar o padrão esperado** (escala, sistema de spacing, grid, WCAG contrast).
+* **Escalar confiança (Visual Quality):**
+  * `CONFIRMED` — violação mensurável (ex: contraste 2.1:1, escala inconsistente, grid
+    quebrado, AI slop identificável).
+  * `HIGH CONFIDENCE` — violação clara de princípio.
+  * `POSSIBLE` — subjetivo, pode ser questão de gosto.
+  * `SPECULATIVE` — preferência pessoal não fundamentada.
+
+## False Positives
+
+* **Design system define o padrão** — se o design system tem uma escala de tipografia
+  e a interface segue, "inconsistência" é entre a interface e o sistema, não um erro
+  da interface. Reportar como desvio do design system, não como erro visual.
+* **Modo escuro é propositalmente diferente** — algumas cores são intencionalmente
+  diferentes no modo escuro (não-simples inversão). Verificar decisão de design.
+* **AI slop é intencional e não há budget para refinar** — reportar como nota, não
+  como defeito. Marcar `POSSIBLE` e contextualizar.
+* **Density é intencional** — landing pages são esparsas por design; dashboards são
+  densas por design. Avaliar contra o propósito da tela, não contra um padrão absoluto.
+* **Visual noise tem função** — decoração que comunica identidade de marca não é noise.
+  Avaliar se serve a marca ou é só poluição.
+
+## Output Format
+
+Para cada violação, um finding via `templates/audit-report.md`. Em **Affected
+component**, nomeie o componente/tela. Em **Reproduction**, mostre o elemento e a
+violação (incluindo valor de contraste, tamanhos, gap). Em **Root cause**, aponte o
+eixo. Em **Recommendation**, dê a correção concreta (escala de fonte, sistema de
+spacing, cor de contraste, remoção de AI slop, grid consistente).
+
+Apresente por eixo. Contrast e typography (impacto direto em legibilidade) primeiro;
+spacing e hierarchy depois; composition e noise/slop em seguida.