@luanpdd/kit-mcp 1.32.0 → 1.33.0

package/kit/skills/ui-critica-auditoria/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: ui-critica-auditoria
+description: Use ao revisar UI implementada — combina crítica (Nielsen 10 heurísticas 0-4 + carga cognitiva /8 + verdict de tells-IA pass/fail) e auditoria (5 dimensões a11y/perf/theming/responsive/anti-patterns com P0-P3 severity). Produz REVISAO-UI.md scored, routes findings para endurecer/polir/otimizar. Não roda em incomplete work — só em finished pages.
+---
+
+# UI — Crítica & Auditoria
+
+## Quando usar
+
+LLM carrega esta skill quando:
+
+- "Audite design / revise UI / está bom?"
+- "Está pronto para ship?"
+- "Score this design / quão ruim é o tell de IA?"
+- Antes de release de feature visível
+- Em PR de mudança visual significativa
+
+**NÃO use em:**
+- Work-in-progress (vai pontuar mal porque incompleto, não porque ruim)
+- Componente isolado fora de página real
+- Code-only review (precisa ver rendered)
+
+## Regras absolutas
+
+**REGRA #1 (duas passadas independentes):** Rode **crítica** (LLM + heurísticas, subjetivo) E **auditoria** (5 dimensões, determinístico) **separadamente**. Não bias um pelo outro. Findings convergentes têm peso 2×.
+
+**REGRA #2 (P0-P3 severity definida):**
+- **P0** — Bloqueia release (a11y crítica, tell-IA deal-breaker, UX quebrado)
+- **P1** — Resolver neste sprint (gaps notáveis, tell parcial)
+- **P2** — Próximo ciclo (refinamento)
+- **P3** — Polimento (nice-to-have)
+
+**REGRA #3 (score antes da opinião):** Heuristic scores são numéricos (0-4), prioridade de fixes é opinião. Cliente pode discordar de prioridade, não de score.
+
+**REGRA #4 (route, don't fix):** Auditoria documenta, não corrige. Findings vão para:
+- a11y, contrast → `ui-cor-estrategia` + endurecer phase
+- tells de IA → `ui-anti-padroes-ia` patches
+- Performance → otimizar phase
+- Typography → `ui-tipografia` refactor
+
+## Passada Crítica — Nielsen 10 (0-4 cada)
+
+| # | Heurística | Como medir |
+|---|-----------|------------|
+| 1 | Visibility of system status | Loading states? Optimistic UI? Toast feedback? |
+| 2 | Match with real world | Vocabulário do domínio? Ícones reconhecíveis? Locale-aware? |
+| 3 | User control & freedom | Undo? Cancel em modais? Botão back claro? Confirm em destrutivo? |
+| 4 | Consistency & standards | Mesmo padrão de botão em todas telas? CTAs consistentes? |
+| 5 | Error prevention | Validation inline? Confirm em destrutivo? Disable em estado inválido? |
+| 6 | Recognition over recall | Labels visíveis vs precisar lembrar? Recent items? Autocomplete? |
+| 7 | Flexibility & efficiency | Keyboard shortcuts? Power-user paths? Bulk actions? |
+| 8 | Aesthetic & minimalist | Algo na tela não é essencial? Card aninhado? Decoração gratuita? |
+| 9 | Help users recognize errors | Mensagem específica + recovery action? Não "Something went wrong" genérico? |
+| 10 | Help & documentation | Inline help em fields complexos? Empty state ensina? Onboarding presente? |
+
+**Scoring:**
+- 4 — Excelente, supera expectativa
+- 3 — Bom, alguns gaps menores
+- 2 — Cumprido parcialmente, gaps notáveis
+- 1 — Falha na maioria dos cenários
+- 0 — Ausente / quebrado
+
+## Passada Crítica — Carga cognitiva (/8)
+
+Conte falhas. Para cada uma, +1 ao counter:
+
+1. Mais de 7±2 elementos competindo por atenção em viewport inicial?
+2. Hierarquia visual ambígua (qual é a ação primária)?
+3. Vocabulary mismatch (jargão técnico em UI consumer)?
+4. Decisões prematuras pedidas (escolha de plano antes de ver valor)?
+5. Estado escondido (qual aba está ativa? qual filtro aplicado?)?
+6. Confirmação ausente em destrutivo, ou excessiva em trivial?
+7. Loading sem progress signal em > 1s waits?
+8. Layout shift visível durante load (CLS > 0.1)?
+
+Score: 0-2 falhas = bom, 3-4 = preocupante, 5+ = redesign.
+
+## Passada Crítica — Verdict de Tells-IA (pass/fail)
+
+Rode o detector da skill [ui-anti-padroes-ia](../ui-anti-padroes-ia/SKILL.md). Verdict:
+
+- **PASS** — zero P0, ≤ 2 P1 com justificativa em DESIGN.md
+- **MARGINAL** — 1 P0 OU > 2 P1
+- **FAIL** — ≥ 2 P0 OU padrão sistêmico de tells
+
+Liste os tells específicos: `verdict: FAIL · gradiente-roxo · italic-serif-hero · card-aninhado`.
+
+## Passada Auditoria — 5 dimensões (0-4 cada)
+
+### D1 Accessibility (0-4)
+
+Check:
+- [ ] WCAG AA contrast pass para foreground/background pairs (`npx pa11y`)
+- [ ] Todo input tem `<label>` ou `aria-label`
+- [ ] Botão de ícone sem texto tem `aria-label`
+- [ ] Keyboard nav: Tab order lógico, focus visible
+- [ ] Semantic HTML (`<button>` não `<div onClick>`)
+- [ ] Skip-to-content em layouts longos
+
+### D2 Performance (0-4)
+
+Check:
+- [ ] LCP < 2.5s (Lighthouse mobile)
+- [ ] CLS < 0.1
+- [ ] Bundle JS first-load < 200KB gzipped
+- [ ] Imagens com `loading="lazy"` e dimensions
+- [ ] Sem layout-thrashing animations (height/width transitions)
+- [ ] Lighthouse Perf score ≥ 90
+
+### D3 Theming (0-4)
+
+Check:
+- [ ] Zero HEX/RGB hard-coded em components (use tokens)
+- [ ] Dark mode covered (se declarado em MARCA.md)
+- [ ] Tokens semânticos não nomes de cor (`--primary`, não `--blue-500`)
+- [ ] Sem `!important` em styles
+- [ ] CSS custom properties consistentes entre `:root` e `.dark`
+
+### D4 Responsive (0-4)
+
+Check:
+- [ ] Breakpoints: mobile (375), tablet (768), desktop (1024+) todos testados
+- [ ] Touch targets ≥ 44×44 em mobile
+- [ ] Horizontal scroll só em data tables (nunca em layout)
+- [ ] Texto reflow em narrow (não cortado, não overflow)
+- [ ] Hover-only interactions têm equivalente touch
+
+### D5 Anti-patterns (0-4)
+
+Rode o detector da [ui-anti-padroes-ia](../ui-anti-padroes-ia/SKILL.md). Score:
+- 4 = zero P0/P1
+- 3 = 1 P1 documentado
+- 2 = 2-3 P1 OU 1 P0 documentado
+- 1 = ≥ 2 P0
+- 0 = sistêmico
+
+## Output — REVISAO-UI.md
+
+```markdown
+# Revisão de UI — {nome da feature/página}
+
+**Revisado:** {data}
+**Revisor:** designer-ui (kit)
+**Registro:** {marca | produto}
+**Baseline:** {DESIGN.md path | abstract defaults}
+
+---
+
+## TL;DR
+
+**Verdict tells-IA:** {PASS | MARGINAL | FAIL} — {tells}
+**Crítica total:** {soma dos 10 Nielsen}/40
+**Carga cognitiva:** {N}/8 falhas
+**Auditoria total:** {soma das 5 dimensões}/20
+
+**Recomendação:** {SHIP | FIX-P0-PRIMEIRO | REWORK}
+
+---
+
+## Passada Crítica
+
+### Nielsen Heuristics
+
+| # | Heurística | Score | Key issue |
+|---|-----------|-------|-----------|
+| 1 | Visibility of status | {0-4} | {linha resumo} |
+| 2 | Match with real world | {0-4} | … |
+| 3 | User control | {0-4} | … |
+| … | … | … | … |
+
+**Subtotal:** {N}/40
+
+### Falhas de Carga Cognitiva: {N}/8
+
+{lista de falhas com referência arquivo:linha}
+
+### Tells-IA detectados
+
+{cole output do detector se houver hits}
+
+---
+
+## Passada Auditoria
+
+| Dimensão | Score | P0 | P1 | P2 | P3 |
+|-----------|-------|----|----|----|----|
+| Accessibility | {0-4} | … | … | … | … |
+| Performance | {0-4} | … | … | … | … |
+| Theming | {0-4} | … | … | … | … |
+| Responsive | {0-4} | … | … | … | … |
+| Anti-patterns | {0-4} | … | … | … | … |
+
+**Subtotal:** {N}/20
+
+---
+
+## Top 5 Priority Issues
+
+1. **[P0]** {issue} — `{file:line}` — {fix opinion (route para qual skill)}
+2. **[P0]** … — … — …
+3. **[P1]** … — … — …
+4. **[P1]** … — … — …
+5. **[P2]** … — … — …
+
+---
+
+## Perguntas Provocativas
+
+(Questões "vale responder antes de shippar")
+
+1. {ex: "Esta tela funciona em mobile com 1 mão? Você testou?"}
+2. {ex: "O empty state ensina o usuário ou só diz 'No data'?"}
+3. {ex: "Qual é a UMA ação que esta página existe para promover?"}
+
+---
+
+## Routing
+
+- P0/P1 a11y → `ui-cor-estrategia` + endurecer phase
+- P0/P1 tells → `ui-anti-padroes-ia` patches inline
+- Performance → otimizar phase
+- Typography → `ui-tipografia` audit
+- Layout → `ui-ritmo-espacial` audit
+```
+
+## Anti-patterns DESTA skill
+
+### Anti-pattern 1: review em WIP
+
+**Errado:** rodar audit em página com placeholders, lorem ipsum, estados não implementados.
+
+**Por quê:** "incomplete work scores badly because it is not done, not because it is bad". Cliente acha que tem problema de design quando é só falta acabar.
+
+**Certo:** audit apenas em features completas. Para WIP use `ui-anti-padroes-ia` detector preventivo + checklist visual sem score.
+
+### Anti-pattern 2: misturar crítica e auditoria
+
+**Errado:** rodar Nielsen + dimensões juntos, score combinado.
+
+**Por quê:** REGRA #1 — bias mútuo. LLM sabendo que tem tell-IA ajusta Nielsen down. Detector sabendo que Nielsen está alto sub-conta.
+
+**Certo:** dois reviews separados, mesclar findings no REVISAO-UI.md no fim.
+
+### Anti-pattern 3: prioridade sem evidência
+
+**Errado:** "Priority 1: fix the gradient" sem citar arquivo, sem dizer por quê P0.
+
+**Por quê:** Não acionável. Outro dev não sabe onde fixar nem se realmente é P0.
+
+**Certo:** "**[P0]** Hero gradiente roxo (`Hero.tsx:42-48`) — T01 tell-IA, ship blocker. Fix: replace `bg-gradient-to-br from-purple-500 to-pink-500` with `bg-primary` per DESIGN.md > Cores > Destaque."
+
+## Ver também
+
+- [ui-anti-padroes-ia](../ui-anti-padroes-ia/SKILL.md) — feeds verdict de tells-IA + D5
+- [ui-contexto-produto](../ui-contexto-produto/SKILL.md) — baseline para audit
+- [ui-cor-estrategia](../ui-cor-estrategia/SKILL.md) — fixes para D1/D3
+- [ui-tipografia](../ui-tipografia/SKILL.md) — fixes para typography findings
+- [ui-ritmo-espacial](../ui-ritmo-espacial/SKILL.md) — fixes para D4 responsive
+- [ui-motion-funcional](../ui-motion-funcional/SKILL.md) — motion review
+- Nielsen 10 heuristics: https://www.nngroup.com/articles/ten-usability-heuristics/

package/kit/skills/ui-motion-funcional/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: ui-motion-funcional
+description: Use ao adicionar animation, transition ou motion — princípio canônico "motion com propósito que comunica estado, não decoração". Durações 150-200ms interações / 250-400ms layout / 600ms+ celebration justificada. ease-out default, nunca ease-in para entrance, evita bounce em produto. Respeitar prefers-reduced-motion sempre. Sem auto-play, sem parallax gratuito, sem confetti exceto onboarding.
+---
+
+# UI — Motion Funcional
+
+## Quando usar
+
+LLM carrega esta skill quando:
+
+- "Adicionar animation / transition / motion"
+- "Algo parece estático / sem vida"
+- "Confetti / celebration / delight moment"
+- "Page transition / route change"
+- Preenchendo Componentes/Regras com motion rules
+
+## Regras absolutas
+
+**REGRA #1 (com propósito, não decorativo):** Motion existe para comunicar **mudança de estado** (loading → done, hidden → visible, focus, error). Decoração pura (parallax, auto-scrolling text, ambient bg motion) é proibida em produto, raramente justificada em marca.
+
+**REGRA #2 (duração por contexto):**
+- **Micro-interação** (hover, focus, button press): **100-150ms**
+- **Mudança de estado** (toggle, dropdown, popover open): **150-200ms**
+- **Layout shift** (modal open, drawer slide): **250-400ms**
+- **Page transition**: **300-400ms** max
+- **Celebration** (confetti, hero entrance): **600-800ms** com justificativa, 1 vez
+
+Duração > 500ms em interação = lento. < 100ms = imperceptível, sem valor.
+
+**REGRA #3 (easing canônico):**
+- **Padrão**: `ease-out` ou `cubic-bezier(0.2, 0.8, 0.2, 1)` (entry rápido, settle suave)
+- **Exit/dismiss**: `ease-in` aceitável para "remover do palco"
+- **Layout shifts**: `cubic-bezier(0.4, 0, 0.2, 1)` (Material standard)
+- **PROIBIDO em produto**: `bounce`, `elastic`, `back` easings — playful demais para uso funcional
+
+**REGRA #4 (prefers-reduced-motion sempre):** Toda animation tem fallback estático.
+
+**REGRA #5 (no layout thrash):** Anime apenas `transform` + `opacity`. Nunca anime `width`, `height`, `top`, `left`, `padding` em hot path. Use `transform: translate3d()` + `scale()`.
+
+## Patterns canônicos
+
+### Micro-interação (button hover)
+
+```css
+.button {
+  transition: background-color 150ms ease-out, transform 150ms ease-out;
+}
+.button:hover {
+  background-color: var(--primary-hover);
+}
+.button:active {
+  transform: translateY(1px);  /* sutil press-down */
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .button { transition: none; }
+}
+```
+
+### Dropdown / Popover open
+
+```tsx
+// Framer Motion
+<motion.div
+  initial={{ opacity: 0, y: -8 }}
+  animate={{ opacity: 1, y: 0 }}
+  exit={{ opacity: 0, y: -8 }}
+  transition={{ duration: 0.18, ease: [0.2, 0.8, 0.2, 1] }}
+>
+  {/* content */}
+</motion.div>
+
+// Tailwind / CSS only
+className="data-[state=open]:animate-in data-[state=open]:fade-in-0
+           data-[state=open]:slide-in-from-top-1
+           data-[state=closed]:animate-out data-[state=closed]:fade-out-0
+           data-[state=closed]:slide-out-to-top-1
+           duration-200 ease-out"
+```
+
+### Modal / Dialog
+
+```tsx
+// Mobile: slide-from-bottom (sheet)
+// Desktop: scale central + fade
+
+className="
+  /* mobile */
+  data-[state=open]:animate-in data-[state=open]:slide-in-from-bottom
+  data-[state=closed]:animate-out data-[state=closed]:slide-out-to-bottom
+  /* desktop */
+  sm:data-[state=open]:zoom-in-95 sm:data-[state=closed]:zoom-out-95
+  sm:data-[state=open]:fade-in-0 sm:data-[state=closed]:fade-out-0
+  /* timing */
+  duration-300 ease-out
+"
+```
+
+### Layout state transitions
+
+```tsx
+// Lista que filtra: AnimatePresence + layout
+<AnimatePresence mode="popLayout">
+  {items.map(item => (
+    <motion.div
+      key={item.id}
+      layout
+      initial={{ opacity: 0, scale: 0.95 }}
+      animate={{ opacity: 1, scale: 1 }}
+      exit={{ opacity: 0, scale: 0.95 }}
+      transition={{ duration: 0.2, ease: 'easeOut' }}
+    >
+      {item.label}
+    </motion.div>
+  ))}
+</AnimatePresence>
+```
+
+### Loading state (skeleton + transition)
+
+```tsx
+{loading ? (
+  <Skeleton className="h-24 animate-pulse" />
+) : (
+  <motion.div
+    initial={{ opacity: 0 }}
+    animate={{ opacity: 1 }}
+    transition={{ duration: 0.15 }}
+  >
+    {data}
+  </motion.div>
+)}
+```
+
+### Celebration (use 1× por flow, justificado)
+
+```tsx
+// Onboarding: primeiro check-in completado
+import confetti from 'canvas-confetti'
+
+useEffect(() => {
+  if (justCompleted) {
+    confetti({
+      particleCount: 80,
+      spread: 60,
+      origin: { y: 0.4 },
+      colors: [primaryColor, foregroundColor],  // brand-tinted, não rainbow
+      disableForReducedMotion: true,
+    })
+  }
+}, [justCompleted])
+```
+
+Critérios para usar confetti:
+1. Evento raro (não toast comum)
+2. Sucesso significativo (não "saved successfully" trivial)
+3. Cores da marca (não default rainbow)
+4. `disableForReducedMotion: true`
+5. Não bloqueia interação subsequente
+
+## Anti-patterns
+
+### Anti-pattern 1: bounce easing em produto
+
+**Errado:**
+```css
+.dropdown {
+  transition: transform 300ms cubic-bezier(0.68, -0.55, 0.265, 1.55); /* bounce */
+}
+```
+
+**Por quê:** Q08 — bounce em interação comum = playful demais, perde profissionalismo em context dashboard.
+
+**Certo:** `ease-out` ou `cubic-bezier(0.2, 0.8, 0.2, 1)`.
+
+### Anti-pattern 2: motion em decoração de bg
+
+**Errado:** SVG floating shapes orbitando hero em background, animação infinita.
+
+**Por quê:** REGRA #1 — decoração sem propósito + drena GPU + viewport battery + distrai do conteúdo.
+
+**Certo:** static. Ou movimento triggerado por scroll JÁ engajado (parallax leve, max -10% translate), nunca infinito.
+
+### Anti-pattern 3: animar `height` ou `width` em accordion
+
+**Errado:**
+```css
+.accordion-content {
+  transition: height 300ms;
+}
+.accordion-content.open { height: auto; }  /* além de quebrar transition, layout thrash */
+```
+
+**Por quê:** REGRA #5 — height/width disparam reflow + paint, queda de fps em mobile.
+
+**Certo:** anime `transform: scaleY` ou `max-height` + `clip-path`. Ou use lib (Radix Accordion) que faz right.
+
+### Anti-pattern 4: page transition longa
+
+**Errado:** route change com fade out 600ms + fade in 600ms = 1.2s de tela vazia.
+
+**Por quê:** REGRA #2 — user percebe app lento. App nativo bom = transição instantânea ou < 300ms.
+
+**Certo:** 200ms fade out + 200ms fade in, OU cross-fade overlap 250ms total.
+
+### Anti-pattern 5: ignorar prefers-reduced-motion
+
+**Errado:**
+```tsx
+<motion.div animate={{ x: [0, 100, 0] }} transition={{ repeat: Infinity }} />
+```
+
+**Por quê:** REGRA #4 — users com vestibular disorder ou enxaqueca + usuários com bateria fraca + corporate machines.
+
+**Certo:**
+```tsx
+const shouldReduceMotion = useReducedMotion()
+<motion.div
+  animate={shouldReduceMotion ? {} : { x: [0, 100, 0] }}
+  transition={{ repeat: shouldReduceMotion ? 0 : Infinity }}
+/>
+```
+
+### Anti-pattern 6: auto-play hero video sem controle
+
+**Errado:** `<video autoPlay loop muted playsInline>` em hero, 5MB+, sem botão pausar.
+
+**Por quê:** Acessibilidade + bateria + bandwidth. Tem que existir pause/control visível e respeitar prefers-reduced-motion (pausa default).
+
+**Certo:**
+```tsx
+<video
+  ref={videoRef}
+  autoPlay={!prefersReducedMotion}
+  loop muted playsInline
+  poster="/hero-static.jpg"
+/>
+<button onClick={togglePlay} aria-label="Toggle video">…</button>
+```
+
+## Detecção
+
+```bash
+# Bounce/elastic easing
+grep -rnE "bounce|cubic-bezier\(0\.68|elastic" src --include="*.css" --include="*.tsx" 2>/dev/null
+
+# Animação > 500ms em interação
+grep -rnE "duration-(700|1000|1500|2000)\b|duration:\s*(700|800|1000|1500)" src --include="*.tsx" --include="*.css" 2>/dev/null
+
+# Layout-thrashing animations
+grep -rnE "transition.*width|transition.*height|transition.*top|transition.*left|transition.*padding|transition.*margin" src --include="*.css" 2>/dev/null
+
+# Falta de prefers-reduced-motion handler
+grep -rln "framer-motion\|animate=" src --include="*.tsx" 2>/dev/null | while read f; do
+  grep -q "useReducedMotion\|prefers-reduced-motion" "$f" || echo "$f: motion sem reduce handler"
+done
+```
+
+## Ver também
+
+- [ui-anti-padroes-ia](../ui-anti-padroes-ia/SKILL.md) — Q08 (bounce easing)
+- [ui-contexto-produto](../ui-contexto-produto/SKILL.md) — sensibilidade a motion em MARCA.md
+- WCAG SC 2.3.3 Animation from Interactions: https://www.w3.org/WAI/WCAG21/Understanding/animation-from-interactions