@luanpdd/kit-mcp 1.31.0 → 1.33.0

package/kit/skills/ui-cor-estrategia/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: ui-cor-estrategia
+description: Use ao definir paleta, decidir cor de elemento, ou auditar uso de cor — split 60% superfície / 30% secundária / 10% destaque, destaque reservado a elementos LISTADOS exatos, OKLCH preferido sobre HSL/HEX, contraste WCAG AA min 4.5:1, fugir da "paleta padrão IA" (roxo+mint+amarelo claro+gray uniforme), dark mode via tokens não duplicação.
+---
+
+# UI — Estratégia de Cor
+
+## Quando usar
+
+LLM carrega esta skill quando:
+
+- "Que cor usar para CTA / link / button"
+- "Definir paleta / color tokens"
+- "Audit cor / muito colorido / parece genérico"
+- "Adicionar dark mode"
+- Preenchendo seção **Cores** de DESIGN.md
+- Editando `globals.css :root` ou `tailwind.config` colors
+
+## Regras absolutas
+
+**REGRA #1 (split 60/30/10):** Superfície dominante 60%, secundária 30%, destaque 10%. Mais que 10% de destaque = ruído, sinal perde força.
+
+**REGRA #2 (lista de reserva do destaque):** A cor de destaque vai a uma lista DECLARADA de elementos. Ex: "destaque = apenas CTA primário + link de nav ativo". Tudo fora da lista vira superfície ou foreground neutro.
+
+**REGRA #3 (OKLCH preferido):** Novos tokens em `oklch()`. Lightness é perceptualmente linear (HSL não é), o que torna dark mode + variants automáticos. HEX só em integrações legacy.
+
+**REGRA #4 (AA 4.5:1 mínimo):** Contraste body em superfície ≥ 4.5:1. UI controls + interactive ≥ 3:1 (AA non-text). AAA opcional mas declare em MARCA.md.
+
+**REGRA #5 (semântico ≠ paleta):** Tokens são semânticos (`--primary`, `--destructive`, `--muted`), não nome de cor (`--blue-500`). Trocar paleta = mudar 1 lugar.
+
+## Estrutura canônica de tokens
+
+```css
+:root {
+  /* ─── Stack de superfície (60%) ─── */
+  --background: oklch(0.99 0 0);           /* canvas */
+  --card:       oklch(0.99 0 0);           /* alias to background */
+  --popover:    oklch(0.99 0 0);
+
+  /* ─── Foreground & secundária (30%) ─── */
+  --foreground: oklch(0.18 0 0);           /* body text on background */
+  --muted:      oklch(0.94 0.005 240);     /* superfície secundária */
+  --muted-foreground: oklch(0.45 0 0);     /* caption, helper text */
+  --border:     oklch(0.90 0 0);
+  --input:      oklch(0.90 0 0);
+  --ring:       oklch(0.55 0.18 28);       /* matches primary, focus ring */
+
+  /* ─── Destaque (10%) ─── */
+  --primary:    oklch(0.55 0.18 28);       /* THE brand color */
+  --primary-foreground: oklch(0.99 0 0);
+
+  /* ─── Semântico ─── */
+  --destructive: oklch(0.55 0.22 25);       /* red-ish, irreversível */
+  --destructive-foreground: oklch(0.99 0 0);
+
+  /* ─── Opcional: success/warning ───
+   * Use com parcimônia. Sucesso/aviso são UX patterns,
+   * não brand. Use cor apenas quando ícone+texto não bastarem.
+   */
+}
+
+.dark {
+  --background: oklch(0.14 0 0);
+  --card:       oklch(0.16 0 0);            /* slight lift */
+  --foreground: oklch(0.96 0 0);
+  --muted:      oklch(0.20 0.005 240);
+  --muted-foreground: oklch(0.65 0 0);
+  --border:     oklch(0.24 0 0);
+  --primary:    oklch(0.65 0.15 28);        /* shift saturation down + L up */
+}
+```
+
+## Lista de reserva do destaque — patterns
+
+Em DESIGN.md > Cores, declare a lista EXATA:
+
+```markdown
+## Cores
+- Destaque (10%) — `--primary` — reservada para:
+  - CTA primário (exatamente um por tela)
+  - Underline de link de nav ativo
+  - Estado selecionado de toggle/tab
+  - Focus ring em inputs (via `--ring`)
+  - Logo da marca
+- Destrutiva — `--destructive` — reservada para:
+  - Botão de confirmação final "Deletar X"
+  - Variante destrutiva de toast
+```
+
+Tudo FORA dessa lista usa `--foreground` ou `--muted-foreground`. Inclui:
+
+- Botões secundários → `bg-secondary` (= `--muted`) + `text-foreground`
+- Ícones de UI geral → `text-muted-foreground`
+- Links em prose → `text-foreground underline` (não destaque)
+- Badges decorativos → `bg-muted text-muted-foreground`
+
+## Padrões anti-rainbow
+
+Em produto (não marca), use **monocromático + 1 destaque**:
+- Stack de superfície: 4 tons neutros (background, card lift, muted, border)
+- Stack de foreground: 2 tons (foreground, muted-foreground)
+- Destaque: 1 cor única + sua foreground complementar
+
+Total: ~8 tokens distintos. Paleta rainbow (10+ cores) é sinal de tell T09.
+
+## Status colors — usar com parcimônia
+
+```css
+/* SOMENTE se ícone + label não bastarem */
+--success: oklch(0.55 0.15 145);      /* green */
+--warning: oklch(0.75 0.15 75);       /* amber, não yellow saturado */
+--info:    oklch(0.55 0.15 240);      /* blue */
+```
+
+Status colors quebram o split 60/30/10. Use só em:
+- Toast variants (feedback nível sistema)
+- Form inline validation (ícone + label é primário, cor é reforço)
+
+NÃO use status colors em:
+- Card backgrounds para "tipo de item" (vira card com borda lateral colorida T05)
+- Texto em botão para indicar significado (texto faz isso)
+
+## Verificação de contraste
+
+```bash
+# tooling local
+npx pa11y http://localhost:3000 --standard WCAG2AA
+
+# CSS-only check em dev: outline elements abaixo de 4.5:1
+# (snippet em CLAUDE.md ou globals.css dev)
+```
+
+Mínimos:
+- `--foreground` em `--background`: ≥ 4.5:1
+- `--muted-foreground` em `--background`: ≥ 4.5:1 (ela é caption mas é texto)
+- `--primary-foreground` em `--primary`: ≥ 4.5:1
+- Buttons disabled state: ≥ 3:1 (UI control non-text)
+
+Combo failing comum: `text-gray-400` em `bg-gray-100` → ~3.2:1, AA fail.
+
+## Anti-patterns
+
+### Anti-pattern 1: paleta IA padrão (roxo + mint + amarelo + gray)
+
+**Errado:**
+```css
+--primary: #6366F1;    /* indigo */
+--secondary: #10B981;  /* mint */
+--accent: #FBBF24;     /* yellow */
+--neutral: #64748B;    /* slate */
+```
+
+**Por quê:** T09 — esta é a paleta que aparece em Lovable, v0, Bolt, Replit default. Cliente identifica instantaneamente.
+
+**Certo:** derive de MARCA.md anti-referência. Se anti-ref é "Lovable default", adote monocromático + 1 destaque warm (terra cota, ocre, ferrugem) OU 1 destaque cool fora do espectro indigo (ciano profundo, verde-azulado oxidado).
+
+### Anti-pattern 2: usar HEX em token novo
+
+**Errado:** `--primary: #4F46E5;`
+
+**Por quê:** REGRA #3 — HSL/HEX não são perceptualmente uniformes. Lightness não corresponde a brilho percebido. Dark mode + states (hover/active) viram tentativa-e-erro.
+
+**Certo:** `--primary: oklch(0.55 0.18 270);` — agora `oklch(0.45 ...)` é "mais escuro de forma percebida".
+
+### Anti-pattern 3: rainbow status no dashboard
+
+**Errado:** cada card de stats com cor diferente — sales verde, churn vermelho, revenue azul, MRR roxo.
+
+**Por quê:** REGRA #1 quebrada — 4 destaques em 1 tela = caos. Sinal perde força.
+
+**Certo:** todos os números em foreground neutro. Apenas o número "preocupante" (churn alto) ganha destructive color. Tendências (up/down) via ícone arrow + sinal +/−, não cor.
+
+### Anti-pattern 4: dark mode duplicando tokens
+
+**Errado:**
+```css
+:root.dark {
+  --primary-dark: #818CF8;
+  --background-dark: #0F172A;
+}
+/* uso: bg-[var(--primary-dark)] em .dark, manual */
+```
+
+**Por quê:** REGRA #5 — tokens devem ser semânticos. `--primary` muda valor entre `:root` e `.dark`, não nome. Senão toda regra de CSS precisa branch.
+
+**Certo:**
+```css
+:root      { --primary: oklch(0.55 0.18 28); }
+.dark      { --primary: oklch(0.65 0.15 28); }
+/* uso único: bg-[var(--primary)] sempre */
+```
+
+### Anti-pattern 5: destaque em link de body
+
+**Errado:**
+```tsx
+<p>Leia mais em nossa <a className="text-primary">documentação</a></p>
+```
+
+**Por quê:** REGRA #2 — destaque reservado a CTA primário. Espalhado em prose vira ruído + dilui sinal de "esta é A ação".
+
+**Certo:**
+```tsx
+<p>Leia mais em nossa <a className="text-foreground underline underline-offset-4 hover:text-primary">documentação</a></p>
+```
+Hover pode revelar destaque, default fica no foreground.
+
+## Ver também
+
+- [ui-anti-padroes-ia](../ui-anti-padroes-ia/SKILL.md) — T01 (gradiente roxo), T05 (card borda lateral), T09 (paleta IA), Q04 (contraste baixo)
+- [ui-contexto-produto](../ui-contexto-produto/SKILL.md) — seção Cores do DESIGN.md
+- [ui-tipografia](../ui-tipografia/SKILL.md) — hierarquia usa peso + cor
+- OKLCH playground: https://oklch.com/

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/