@luanpdd/kit-mcp 1.31.0 → 1.33.0

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

package/kit/skills/ui-ritmo-espacial/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: ui-ritmo-espacial
+description: Use ao definir spacing, padding, layout, grid ou alinhamento — escala canônica em base 4 (4/8/16/24/32/48/64/96), alinhamento óptico ≠ matemático (ícones, glifos), breathing room obrigatório no viewport edge, container width via ch unit em texto, evita arbitrary values [13px] e padding cramped em interactive.
+---
+
+# UI — Ritmo Espacial
+
+## Quando usar
+
+LLM carrega esta skill quando:
+
+- "Espaçamento parece estranho / cramped / inconsistente"
+- "Alinhar elementos / grid / layout"
+- "Padding em botão / card / dialog"
+- "Container width / max-width"
+- "Optical alignment" / "está 1px off"
+- Preenchendo seção **Componentes** com spacing rules
+
+## Regras absolutas
+
+**REGRA #1 (escala base-4):** Spacing apenas em múltiplos de 4. Permitidos: `4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96, 128`. **Proibidos:** valores arbitrários `[13px]`, `[27px]`, `[1.7rem]`. Se você precisa de um, problema é de escala não documentada.
+
+**REGRA #2 (3 níveis de densidade):**
+- **Densa** (`gap-1`/`p-2`/`px-3`): tables, data grids, command palettes
+- **Padrão** (`gap-4`/`p-4`/`px-6`): cards, forms, sections
+- **Generosa** (`gap-8`/`p-8`/`px-12`): heroes, marketing, empty states
+
+Misturar densa + generosa na mesma seção = ritmo quebrado.
+
+**REGRA #3 (no edge flush):** Texto e UI sempre com padding lateral mínimo `px-4` (mobile) → `px-6` (tablet) → `px-8` (desktop). Conteúdo nunca encosta na viewport.
+
+**REGRA #4 (container width em ch):** Containers de texto têm `max-width` em `ch` unit (50-75ch body). Container de UI em `max-w-7xl` (1280px) ou `max-w-5xl` (1024px) padrão.
+
+**REGRA #5 (alinhamento óptico):** Ícones e glifos têm bounding box que ≠ shape óptico. Centralização matemática vê desalinhada. Compense: setas/triângulos shift -1 ou -2 px na direção oposta da ponta. Texto + ícone vertical alinha pela `cap-height`, não pela baseline.
+
+## Escala canônica
+
+```js
+// tailwind.config.js — restrinja explicit, esconda o resto
+module.exports = {
+  theme: {
+    spacing: {
+      '0': '0',
+      'px': '1px',
+      '0.5': '2px',  // só para borders/dividers
+      '1': '4px',
+      '2': '8px',
+      '3': '12px',
+      '4': '16px',
+      '5': '20px',
+      '6': '24px',
+      '8': '32px',
+      '10': '40px',
+      '12': '48px',
+      '16': '64px',
+      '20': '80px',
+      '24': '96px',
+      '32': '128px',
+    }
+  }
+}
+```
+
+Não inclua `7`, `9`, `11`, `14`, etc — força escolha de uma escala vizinha em vez de "tô em dúvida, vou de meio termo".
+
+## Patterns canônicos
+
+### Padding interno por componente
+
+| Componente | Padding | Notas |
+|------------|---------|-------|
+| Button (padrão) | `px-4 py-2` (h-10) | min 44px touch target |
+| Button (sm) | `px-3 py-1.5` (h-9) | minimum, densidade-tight |
+| Button (lg) | `px-6 py-3` (h-12) | CTA hero |
+| Input | `px-3 py-2` (h-10) | espaço para focus ring outside |
+| Card (padrão) | `p-6` | conteúdo respira |
+| Card (denso) | `p-4` | em lista de muitos |
+| Dialog | `p-6` (mobile) / `p-8` (desktop) | conteúdo central |
+| Badge / Chip | `px-2 py-0.5` | exceção à base-4, ok |
+| Section (vertical) | `py-16` (mobile) / `py-24` (desktop) | hero/marketing |
+| Section (vertical, produto) | `py-8` / `py-12` | denso |
+
+### Container patterns
+
+```tsx
+// Layout shell
+<div className="min-h-screen">
+  <header className="border-b">
+    <div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8 h-16 flex items-center">
+      {/* nav */}
+    </div>
+  </header>
+
+  <main>
+    {/* Marketing section */}
+    <section className="mx-auto max-w-5xl px-4 sm:px-6 lg:px-8 py-16 lg:py-24">
+      <h1 className="max-w-[18ch] text-balance text-6xl">…</h1>
+      <p className="max-w-[50ch] mt-6 text-lg text-muted-foreground">…</p>
+    </section>
+
+    {/* Produto dashboard */}
+    <section className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8 py-8">
+      <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">…</div>
+    </section>
+
+    {/* Prose article */}
+    <article className="mx-auto max-w-prose px-4 sm:px-6 py-12">
+      {/* max-w-prose = 65ch */}
+    </article>
+  </main>
+</div>
+```
+
+### Ritmo vertical em prose
+
+```tsx
+<article className="prose">
+  <h1 className="mb-8">…</h1>        {/* h1 + spacing maior abaixo */}
+  <h2 className="mt-12 mb-4">…</h2>  {/* h2 separa seções */}
+  <p className="mb-4 leading-7">…</p>{/* p body */}
+  <ul className="my-4 space-y-2">…</ul>
+</article>
+```
+
+Regra: spacing acima de heading > spacing abaixo. Senão heading "flutua" no meio.
+
+### Alinhamento óptico
+
+```tsx
+// Texto + ícone: align pelo center vertical, não baseline
+<button className="inline-flex items-center gap-2">
+  <ArrowRight className="size-4 -translate-y-px" />  {/* -1px opcional para cap-height match */}
+  <span>Próximo</span>
+</button>
+
+// Heading + ícone decorativo: ícone alinha pelo x-height, não top
+<h2 className="flex items-baseline gap-2">
+  <Sparkles className="size-5 translate-y-1" />  {/* push down to baseline-ish */}
+  <span>Feature</span>
+</h2>
+
+// Pill button: padding horizontal mais leve que vertical estaria — compense
+<button className="rounded-full px-4 py-2">  {/* px-4 não px-3 — pill rouba H */}
+  Ação
+</button>
+```
+
+## Anti-patterns
+
+### Anti-pattern 1: arbitrary values salpicados
+
+**Errado:**
+```tsx
+<div className="p-[13px] mt-[27px] gap-[18px]">…</div>
+```
+
+**Por quê:** REGRA #1 — escala se desfaz. Outro dev vê `13px` e adiciona `15px` ao lado. Em 6 meses ninguém sabe o que é "spacing default".
+
+**Certo:** `p-3 mt-6 gap-4` (12/24/16, todos na escala). Se realmente precisa de um valor fora, adicione ao theme em vez de inline.
+
+### Anti-pattern 2: padding cramped em interactive
+
+**Errado:** `<button className="px-2 py-1">Salvar</button>`
+
+**Por quê:** Q06 — touch hit area pequena + densidade desconfortável. Botão difícil de clicar.
+
+**Certo:** `px-4 py-2` mínimo. Botão denso `px-3 py-1.5` apenas em toolbar.
+
+### Anti-pattern 3: section sem padding lateral em mobile
+
+**Errado:**
+```tsx
+<section className="max-w-7xl mx-auto py-16">
+  <h1 className="text-4xl">Title</h1>  {/* encosta na borda em mobile */}
+</section>
+```
+
+**Por quê:** REGRA #3 — texto sem ar para respirar + acessibilidade em landscape narrow.
+
+**Certo:**
+```tsx
+<section className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-16">
+```
+
+### Anti-pattern 4: hero text sem max-width
+
+**Errado:**
+```tsx
+<h1 className="text-6xl">Build amazing products with our platform today</h1>
+```
+
+**Por quê:** REGRA #4 — line-length destruído em widescreen, leitura interrompida.
+
+**Certo:**
+```tsx
+<h1 className="text-6xl max-w-[18ch] text-balance leading-tight">
+  Build amazing products
+</h1>
+```
+
+### Anti-pattern 5: misturar densidades sem motivo
+
+**Errado:**
+```tsx
+<Card className="p-2">  {/* densa */}
+  <CardHeader className="p-8">  {/* generosa */}
+    <CardTitle>...</CardTitle>
+  </CardHeader>
+  <CardContent className="p-4">  {/* padrão */}
+    ...
+  </CardContent>
+</Card>
+```
+
+**Por quê:** REGRA #2 — ritmo quebrado, agente IA depois não sabe qual densidade replicar.
+
+**Certo:** uma densidade por componente. Card denso = todo o card `p-4` máximo. Card padrão = todo o card `p-6`.
+
+### Anti-pattern 6: alinhar centro com texto
+
+**Errado:**
+```tsx
+<div className="flex items-center">
+  <Icon />
+  <h2>Heading</h2>
+</div>
+```
+
+Pixel-perfect: ícone tem `cap-height` diferente do texto.
+
+**Certo:**
+```tsx
+<div className="flex items-baseline gap-2">  {/* ou items-center + ícone -translate-y-px */}
+  <Icon className="translate-y-0.5" />
+  <h2>Heading</h2>
+</div>
+```
+
+## Detecção
+
+```bash
+# Arbitrary spacing values
+grep -rnE "(p|m|gap|space)-(x|y)?-\[[0-9]+(px|rem)\]" src --include="*.tsx" 2>/dev/null
+
+# Edge flush
+grep -rnE "max-w-7xl.*mx-auto.*py-" src --include="*.tsx" 2>/dev/null | grep -v "px-"
+
+# Botão cramped
+grep -rnE "<(button|Button)[^>]*\bp[xy]?-(1|2)\b" src --include="*.tsx" 2>/dev/null
+
+# Hero sem max-w em ch
+grep -rnE "text-(5xl|6xl|7xl|8xl|9xl)" src --include="*.tsx" 2>/dev/null | grep -v "max-w-\["
+```
+
+## Ver também
+
+- [ui-anti-padroes-ia](../ui-anti-padroes-ia/SKILL.md) — Q02 (edge flush), Q06 (padding cramped)
+- [ui-tipografia](../ui-tipografia/SKILL.md) — line-length em ch
+- [ui-contexto-produto](../ui-contexto-produto/SKILL.md) — escala vai em DESIGN.json