@luanpdd/kit-mcp 1.32.0 → 1.33.0

package/kit/skills/ui-contexto-produto/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: ui-contexto-produto
+description: Use ANTES de qualquer trabalho de UI — carrega/gera MARCA.md (estratégia: registro marca vs produto, persona, voz, anti-referências) + DESIGN.md (visual: 6 seções canônicas Visão/Cores/Tipografia/Elevação/Componentes/Regras). Estratégia ≠ visual; arquivos separados deliberadamente. Bootstrap canônico de fluência de design para IA.
+---
+
+# UI — Contexto de Produto (MARCA.md + DESIGN.md)
+
+## Quando usar
+
+LLM carrega esta skill quando:
+
+- "Desenhe / refine / audite UI" em projeto que ainda não tem brand spec
+- "Crie um DESIGN.md / MARCA.md / docs de design system"
+- "Onboard o IA no design deste projeto"
+- "Faça o ensino / extração de design"
+- Antes de invocar agente `designer-ui` pela primeira vez
+
+## Regras absolutas
+
+**REGRA #1 (separação de preocupações):** `MARCA.md` responde **estratégia** (quem/o quê/porquê). `DESIGN.md` responde **visual** (como aparenta). Nunca coloque cor, fonte ou pixel em MARCA.md. Nunca coloque persona ou tom de voz em DESIGN.md.
+
+**REGRA #2 (registro primeiro):** Primeira pergunta sempre é registro: **marca** (marketing, hero, motion-rich) vs **produto** (dashboard, calm-clinical). Tudo deriva disso.
+
+**REGRA #3 (específico, não adjetivo):** Recuse respostas genéricas. "Moderno e limpo" → reject. "Caloroso, mecânico, opinativo" → accept. Referências por **nome próprio**: "Linear sidebar density", não "técnico e limpo".
+
+**REGRA #4 (6 seções fixas):** DESIGN.md tem exatamente 6 seções, em ordem fixa, com nomes fixos. NÃO adicione Layout, Motion ou Responsivo como top-level — eles vivem dentro de Componentes ou Regras.
+
+**REGRA #5 (ancorado no codebase):** Modo scan lê tokens reais (CSS vars, Tailwind config, shadcn preset). Nunca invente valores que o codebase não suporta — marque como `<!-- RASCUNHO -->` se vier de prompt e não de código.
+
+## Template canônico — MARCA.md
+
+```markdown
+# MARCA.md
+
+> Contexto estratégico para parceiros de design IA. Visuais vivem em DESIGN.md.
+
+## Registro
+{marca | produto | híbrido — justifique em 1 linha}
+
+## Usuários
+- Primário: {persona específica, contexto, estado de espírito}
+  Exemplo: "SRE em on-call às 3h, debugando incidente, só mobile, janela de paciência 90s"
+- Secundário: {se houver}
+
+## Propósito
+{O que o produto faz, em 1 frase de no máximo 20 palavras. Sem "platform" ou "solution"}
+
+## Personalidade
+3-5 adjetivos. Exemplo: "Calmo, clínico, opinativo, mecânico, sem hype"
+Reject: "moderno, limpo, simples, intuitivo" (genéricos)
+
+## Referências
+- {Nome próprio + URL}. Ex: "Linear app — densidade de sidebar"
+- {Nome próprio + URL}. Ex: "Vercel dashboard — empty states"
+
+## Anti-referências
+- {Nome próprio + razão}. Ex: "Templates SaaS genéricos — sobreuso de cards"
+- {Nome próprio + razão}. Ex: "Hero Stripe 2014 — era do gradiente roxo"
+
+## Voz
+- Tom: {calmo | brincalhão | clínico | caloroso | mecânico | outro}
+- Tempo verbal: {presente padrão | passado para eventos}
+- Frases banidas: {liste 3-5. Ex: "alavancar", "seamless", "incrível"}
+
+## Acessibilidade
+- WCAG: {AA | AAA}
+- Locale: {pt-BR primário | en secundário | etc}
+- Sensibilidade a motion: {respeitar prefers-reduced-motion: sim/não — default sim}
+- Daltonismo: {protanopia/deuteranopia testados via tooling}
+
+## Restrições
+- {Técnica. Ex: "shadcn/ui locked", "Tailwind v4 OKLCH tokens"}
+- {Negócio. Ex: "deve parecer sério para pitch enterprise"}
+```
+
+## Template canônico — DESIGN.md
+
+```markdown
+# DESIGN.md
+
+> Sistema visual. Agentes IA leem isto antes de gerar UI. 6 seções, ordem fixa.
+
+## Visão
+{North Star em 2-3 frases. O "feeling" do produto traduzido em direção visual.}
+Exemplo: "Quietude editorial. Preto sobre creme, accent único, espaçamento generoso, motion apenas em mudança de estado."
+
+## Cores
+- Superfície (60%): `{token | hex}` — `--background`
+- Secundária (30%): `{token | hex}` — `--muted`
+- Destaque (10%): `{token | hex}` — reservada para: {liste elementos exatos. Ex: "apenas CTA primário"}
+- Destrutiva: `{token | hex}` — reservada para: confirmação de ação irreversível
+- Foreground / contraste: AA mín 4.5:1 em cada superfície
+Modo: {claro só | escuro só | ambos com pref do sistema}
+
+## Tipografia
+- Display ({nome próprio}): h1/h2 hero
+- Body ({nome próprio}): todo o resto
+- Mono ({nome próprio}): código, dados, tempo
+
+Tamanhos (exatos, máximo 4): {ex: 14, 16, 20, 32}
+Pesos (exatos, máximo 2): {ex: 400, 600}
+Altura de linha: body 1.5, heading 1.2
+Comprimento de linha: 50-75 chars body, 30-50 hero
+
+Banidas: {liste fontes proibidas. Ex: "Inter, Geist, Space Grotesk" se quer fugir do default genérico}
+
+## Elevação
+Filosofia: {flat | sombra sutil | dramático | nenhuma}
+Tokens:
+- `elev-0`: `none` — superfície rasa
+- `elev-1`: `{shadow value}` — cards, popovers
+- `elev-2`: `{shadow value}` — modais, command palette
+Anti-pattern: glassmorphism (`backdrop-blur` em ≥ 3 camadas) PROIBIDO
+
+## Componentes
+Notas breves de caráter por padrão. Não replique docs do shadcn — declare *o que é opinativo aqui*.
+- **Button**: {raio, peso, altura, caráter}. Ex: "Raio 4px afiado, semibold, h-10, sem sombra"
+- **Card**: {quando usar, quando NÃO}. Ex: "Apenas para itens de dados em lista. Nunca envolva uma seção em card. Nunca aninhe."
+- **Input**: {caráter}. Ex: "Apenas underline, sem borda, foco = border-bottom accent"
+- **Dialog**: {motion, tamanho, dismiss}. Ex: "Slide-from-bottom em mobile, scale central em desktop, ESC sempre dismissa"
+- **Toast**: {posição, duração, caráter}
+
+## Regras (Faça / Não faça)
+FAÇA:
+- {regra brand-específica. Ex: "Use cor de destaque APENAS em CTA primário por tela"}
+- {regra. Ex: "Body copy max 70ch — wrap container em 65ch"}
+
+NÃO FAÇA:
+- {anti-pattern relevante. Ex: "Sem gradiente em texto. Nunca."}
+- {anti-pattern brand. Ex: "Sem emoji em strings de UI fora de error toasts"}
+- {anti-pattern. Ex: "Nunca envolva headings em italic serif. Display é grotesk."}
+```
+
+## Sidecar — DESIGN.json
+
+Companion machine-readable. Tokens primários extraídos do codebase:
+
+```json
+{
+  "version": "1.0",
+  "tokens": {
+    "color": {
+      "surface": "oklch(0.99 0 0)",
+      "muted": "oklch(0.94 0.005 240)",
+      "accent": "oklch(0.55 0.18 28)"
+    },
+    "typography": {
+      "display": "Söhne Breit",
+      "body": "Söhne",
+      "sizes": [14, 16, 20, 32],
+      "weights": [400, 600]
+    },
+    "spacing": [4, 8, 16, 24, 32, 48, 64],
+    "radius": { "default": 4, "pill": 9999 }
+  }
+}
+```
+
+## Workflow
+
+### Modo Scan (codebase existe)
+
+1. `Grep` por `tailwind.config.*`, `globals.css`, `:root {` para extrair tokens
+2. `Read` `components.json` (shadcn) para preset
+3. `Glob` `src/components/**` para inventário
+4. Apresentar valores detectados → pedir confirmação para Visão + notas de caráter
+5. Gerar MARCA.md (via entrevista) + DESIGN.md (via scan + confirmação)
+
+### Modo Rascunho (greenfield)
+
+1. Entrevista de 5-8 minutos. Perguntas mínimas:
+   - Registro (marca vs produto)?
+   - Usuário primário em 1 frase com contexto + estado de espírito?
+   - 3-5 adjetivos de personalidade (não-genéricos)?
+   - 2-3 referências **nomeadas** com URL?
+   - 2 anti-referências **nomeadas**?
+   - Locale + nível WCAG?
+2. Scaffold DESIGN.md com comentários `<!-- RASCUNHO -->` em valores não-extraídos
+3. Marcar para revisão pós-implementação inicial
+
+## Anti-patterns
+
+### Anti-pattern 1: misturar estratégia e visual
+
+**Errado (MARCA.md):**
+```markdown
+## Personalidade
+Moderno, limpo, com #4F46E5 primário
+```
+
+**Por quê:** REGRA #1 — cor pertence a DESIGN.md. MARCA.md fica fora de sincronia quando rebrand.
+
+**Certo:** "Personalidade: Mecânico, opinativo" em MARCA.md. "#4F46E5" em DESIGN.md > Cores > Destaque.
+
+### Anti-pattern 2: respostas adjetivais genéricas
+
+**Errado:**
+```markdown
+## Referências
+- Apps SaaS modernos
+- Design systems limpos
+```
+
+**Por quê:** REGRA #3 — sem nome próprio, IA volta ao default genérico ("dribbble médio").
+
+**Certo:**
+```markdown
+## Referências
+- [Linear](https://linear.app) — densidade de sidebar + gravidade do command palette
+- [Klim Type Foundry](https://klim.co.nz) — hero editorial quieto
+```
+
+### Anti-pattern 3: criar Layout/Motion/Responsivo como seção top-level em DESIGN.md
+
+**Errado:**
+```markdown
+## Visão
+## Cores
+## Tipografia
+## Layout            ← não!
+## Motion            ← não!
+## Responsivo        ← não!
+```
+
+**Por quê:** REGRA #4 — schema canônico tem 6 seções fixas. Layout/motion/responsivo são propriedades dos Componentes ou regras em Faça/Não faça. Agentes IA downstream esperam o schema fixo.
+
+**Certo:** Embuta em Componentes ("Dialog: slide-from-bottom em mobile, scale central em desktop") ou Regras ("FAÇA: respeitar prefers-reduced-motion").
+
+### Anti-pattern 4: MARCA.md sem anti-referências
+
+**Errado:**
+```markdown
+## Referências
+- Linear
+## Personalidade
+- Limpo
+```
+(sem anti-referências)
+
+**Por quê:** IA tende a regressão à média. Sem "NÃO se parecer com X", o output gravita para template SaaS médio mesmo com referências fortes.
+
+**Certo:** sempre 2+ anti-referências nomeadas com razão.
+
+## Ver também
+
+- [ui-anti-padroes-ia](../ui-anti-padroes-ia/SKILL.md) — catálogo de tells a evitar (alimenta seção Não faça de DESIGN.md)
+- [ui-tipografia](../ui-tipografia/SKILL.md) — preenche seção Tipografia
+- [ui-cor-estrategia](../ui-cor-estrategia/SKILL.md) — preenche seção Cores

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/