Protocolo de autodiagnostico contra os 5 problemas mais comuns da IA ao programar. Detecta overengineering, codigo duplicado, reinvencao da roda, falta de documentacao e arquivos monoliticos. Use SEMPRE antes de implementar, ao planejar mudancas, quando criar funcoes novas, ao escrever codigo, para revisar implementacoes. Palavras-chave - simples, duplicado, repetido, existe, separar, modular, documentacao, complexo, refatorar, engenharia demais, roda, reutilizar.

2026-04-100

anti-frankenstein

paulinett1508-dev/SuperCartolaManagerv5-production

Guardiao de governanca frontend. Checkpoint obrigatorio ANTES de criar ou modificar CSS, HTML, inline styles, componentes visuais ou qualquer codigo de apresentacao. Previne duplicacao, hardcoded colors, keyframes orfaos, inline styles e criacao desgovernada de arquivos. Keywords: blindar frontend, anti-frankenstein, validar CSS, checar antes de criar, governanca CSS, prevenir duplicacao, revisar criacao.

2026-04-100

api-hardening

paulinett1508-dev/SuperCartolaManagerv5-production

Especialista em Hardening de APIs - Autenticacao, Autorizacao Multi-Tenant, Validacao de Input, Security Headers, Protecao contra Injection, Session Security e Data Exposure Prevention. Adaptado para Node.js/Express/MongoDB do Super Cartola Manager. Keywords: seguranca, security, hardening, vulnerabilidade, injection, IDOR, autenticacao, autorizacao, sessao, session, OWASP, pentest, sanitizar, validar input, exposicao de dados

2026-04-100

architecture-reviewer

paulinett1508-dev/SuperCartolaManagerv5-production

Agente especialista em revisao de decisoes arquiteturais para o Super Cartola Manager. Analisa isolamento multi-tenant, sistema de modulos, integridade financeira, cache, API design e arquitetura frontend. Keywords: arquitetura, architecture, review, revisao, multi-tenant, liga_id, modulo, cache, performance, seguranca, isolamento, acoplamento, dependencia

2026-04-100

auditor-module

paulinett1508-dev/SuperCartolaManagerv5-production

Auditoria automatizada de módulos — segurança, UI/UX, performance, financeiro e regras de negócio

2026-04-100

name	ux-auditor-app
description	Auditoria completa de UI/UX, CSS, HTML e experiência do app participante (PWA Mobile)

SKILL: UX Auditor App (Auditor de Experiencia do App Participante)

Visao Geral

Auditoria completa e sistematica de UI/UX, CSS, HTML, Design e Experiencia do app do participante (PWA Mobile). Varre todas as telas, fragmentos, estilos, componentes e fluxos de navegacao do app participante para garantir consistencia visual, acessibilidade, performance e conformidade com o Design System.

Escopo: EXCLUSIVO para o app participante (/public/participante/). Para auditar admin, usar auditor-module ou code-inspector.

Diferenca das outras skills:

frontend-crafter → CRIA telas/componentes
auditor-module → Audita 1 modulo (multidimensional: seguranca, financeiro, UI, etc.)
ux-auditor-app → Audita TODA a experiencia do app participante (UI/UX/Design holistica)

Quando Usar

Revisao geral do app participante antes de release
Inconsistencias visuais reportadas por usuarios
Apos refatoracao de CSS ou HTML de multiplas telas
Onboarding de novo dev para entender o estado atual do frontend
Auditoria periodica (recomendado: mensal)

Arquitetura do App Participante

public/participante/
├── index.html              # Entry point (PWA shell)
├── manifest.json           # PWA config
├── service-worker.js       # Offline support
├── DESIGN_SYSTEM.md        # Referencia visual
│
├── css/                    # 13 arquivos CSS
│   ├── _app-tokens.css     # DESIGN TOKENS (fonte da verdade)
│   ├── participante.css    # Estilos globais
│   ├── bottom-sheet-nav.css
│   ├── splash-screen.css
│   ├── pull-refresh.css
│   ├── quick-access-bar.css
│   ├── avisos.css
│   ├── boas-vindas.css
│   ├── campinho.css
│   ├── copa-sc.css
│   ├── matchday.css
│   └── top10-destaque.css
│
├── fronts/                 # 18 fragmentos HTML (SPA)
│   ├── home.html
│   ├── ranking.html
│   ├── rodadas.html
│   ├── extrato.html
│   ├── top10.html
│   ├── melhor-mes.html
│   ├── pontos-corridos.html
│   ├── mata-mata.html
│   ├── campinho.html
│   ├── capitao.html
│   ├── artilheiro.html
│   ├── luva-ouro.html
│   ├── dicas.html
│   ├── copa-times-sc.html
│   ├── configuracoes.html
│   ├── historico.html
│   └── boas-vindas.html
│
├── js/                     # Core + 26 modulos JS
│   ├── participante-navigation.js
│   ├── participante-cache.js
│   ├── participante-auth.js
│   └── modules/            # 1 JS por tela
│
└── modules/                # Legacy (ranking)

Protocolo de Auditoria (7 Dimensoes)

DIMENSAO 1: Design Tokens & Variaveis CSS

Arquivo fonte da verdade: css/_app-tokens.css

Checklist:

Todas as cores usam variaveis var(--app-*) (NUNCA hardcoded #FF4500, #1a1a1a)
Aliases legados (--laranja, --bg-card) apontam para tokens corretos
Aliases --participante-* mapeados para --app-*
Font families usam tokens: --app-font-base, --app-font-brand, --app-font-mono
Espacamentos usam --app-space-* (nao valores px avulsos)
Border radius usam --app-radius-*
Sombras usam --app-shadow-*
Z-index respeita camadas: content(1) < header(100) < nav(200) < overlay(500) < modal(600) < toast(700) < bottom-nav(1000)

Red Flags:

Problema	Severidade	Como Detectar
Cor hardcoded em CSS/HTML	ALTO	`grep -rn "#[0-9a-fA-F]{3,6}" --include=".css" --include=".html"` excluindo `_app-tokens.css`
`font-family` inline sem token	ALTO	`grep -rn "font-family:" --include="*.css"` fora do tokens
`px` sem token em spacing	MEDIO	Inspecionar padding/margin sem `var(--app-space-*)`
`z-index` arbitrario	ALTO	`grep -rn "z-index:" --include="*.css"` comparar com tokens

DIMENSAO 2: Tipografia (3 Fontes Obrigatorias)

Regra: O app usa 3 fontes com papeis distintos:

Fonte	Token	Uso	Classe CSS
Inter	`--app-font-base`	Corpo de texto, paragrafos	(padrao, sem classe extra)
Russo One	`--app-font-brand`	Titulos, stats, badges, CTAs, nomes de destaque	`.font-brand`, `.app-brand-title`, `.app-brand-stat`
JetBrains Mono	`--app-font-mono`	Valores numericos (pontos, dinheiro, posicoes)	`.app-value-mono`, `.font-mono`

Checklist:

Google Fonts carregadas no index.html (Inter, Russo One, JetBrains Mono)
Body usa Inter como fonte base
Todos titulos de secao/modulo usam Russo One (.font-brand ou .app-brand-title)
Valores numericos (pontos, R$, posicoes) usam JetBrains Mono
Russo One NAO usa font-weight diferente de 400 (so tem 1 peso)
letter-spacing usado para ajustar Russo One (nao font-weight)
Forcadores !important em _app-tokens.css cobrem todos os seletores reais dos fragmentos
Nenhum fragmento HTML usa style="font-family:..." inline

Red Flags:

Problema	Severidade
Titulo sem Russo One	ALTO
Valor numerico sem JetBrains Mono	MEDIO
Fonte nao carregada (FOUT/FOIT)	ALTO
Uso de Lexend (legado, substituido por Inter)	MEDIO

DIMENSAO 3: Dark Theme & Cores

Principio: OLED-first. Background principal #0a0a0a, surfaces #1a1a1a.

Checklist:

Cores por Modulo (quando aplicavel):

Modulo	Cor Primaria	Variavel
Artilheiro	Verde #22c55e	`--module-artilheiro-primary`
Capitao	Roxo #8b5cf6	`--module-capitao-primary`
Luva de Ouro	Dourado #ffd700	`--module-luva-primary`

DIMENSAO 4: Responsividade & Mobile-First

Principio: App participante eh 100% mobile-first. Desktop eh bonus.

Viewports de teste:

360x640 (Android pequeno)
375x812 (iPhone X/11/12)
390x844 (iPhone 13/14)
414x896 (iPhone XR/11)
768x1024 (Tablet - bonus)

Checklist:

DIMENSAO 5: Estados Visuais (UX Completo)

Toda tela/componente DEVE ter 5 estados visuais:

Estado	Descricao	Implementacao Esperada
Loading	Dados carregando	Spinner `.app-spinner` ou skeleton
Sucesso	Dados renderizados	Tela normal com dados
Vazio	Sem dados	Mensagem amigavel + icone + CTA
Erro	Falha na API	Mensagem de erro + botao "Tentar novamente"
Offline	Sem internet	Dados do cache + indicador offline

Checklist por Fragmento (fronts/*.html):

DIMENSAO 6: Navegacao & Fluxos SPA

Checklist:

Fluxo Critico - Pre-Temporada:

Estado de pre-temporada detectado e comunicado visualmente
Telas financeiras funcionam em pre-temporada
Modulos desativados mostram mensagem (nao tela vazia)

DIMENSAO 7: PWA, Performance & Acessibilidade

PWA:

manifest.json com name, short_name, icons, theme_color, background_color
theme_color consistente com --app-bg (#0a0a0a)
Service Worker registrado e funcional
App instalavel (Add to Home Screen)
Icones em multiplas resolucoes (192px, 512px)

Performance:

CSS carrega antes do JS (ordem no <head>)
_app-tokens.css eh o PRIMEIRO CSS carregado
Nenhum @import em CSS (usar <link> no HTML)
Animacoes usam transform/opacity (nao top/left/width)
will-change em elementos animados frequentes
prefers-reduced-motion respeitado (definido em tokens)
Imagens com loading="lazy" onde aplicavel
Escudos com onerror="this.src='/escudos/default.png'" (fallback)

Acessibilidade (A11y):

Botoes com aria-label quando so tem icone
Contraste minimo 4.5:1 (WCAG AA)
Focus visible em elementos interativos
Navegacao por teclado funcional (tab order)
alt em imagens significativas
role em elementos semanticos customizados

Icones:

Usando Material Icons (material-icons ou material-symbols-outlined)
NUNCA emojis como icones (usar Material Icons)
NUNCA Font Awesome (migrado para Material Icons)
Tamanho base consistente (20-24px)

Modos de Execucao

Auditoria Completa (todas as 7 dimensoes)

auditar UX do app participante

Executa TODAS as 7 dimensoes. Gera relatorio completo.

Auditoria por Dimensao

auditar tokens do app participante
auditar tipografia do app
auditar dark mode do participante
auditar responsividade do app
auditar estados visuais do app
auditar navegacao do app
auditar PWA e acessibilidade do app

Auditoria por Tela Especifica

auditar UX da tela de ranking do participante
auditar design do extrato no app

Audita TODAS as 7 dimensoes, mas APENAS na tela especificada.

Comparacao de Telas

comparar UX do ranking com extrato no app

Compara consistencia visual entre duas telas.

🔧 AUTO-FIX MODE (NOVO)

Script de Auto-Fix

Localização: scripts/ux-auto-fix.js

Detecta e corrige automaticamente issues comuns de UX no app participante.

Issues Automatizáveis (Confidence >= 80%)

Tipo	Detecção	Fix Automático	Confidence
Cores hardcoded	`#FF5500`, `#fff`, `#0a0a0a`	→ Design tokens (`var(--app-primary)`)	95%
Z-index arbitrário	`z-index: 999`	→ Camadas semânticas (`var(--app-z-modal)`)	80-95%
Emojis como ícones	`🏆`, `⚽`, `💰`	→ Material Icons	90%
Font-family hardcoded	`font-family: Arial`	→ Tokens (`var(--app-font-base)`)	90%
Inline styles	`style="color:#fff"`	→ Extrair para CSS com tokens	85%

Uso do Script

# Preview (dry-run) - mostra issues sem aplicar
node scripts/ux-auto-fix.js

# Aplicar fixes em todos arquivos
node scripts/ux-auto-fix.js --apply

# Fix + commit automático
node scripts/ux-auto-fix.js --apply --commit

# Arquivo específico
node scripts/ux-auto-fix.js --file=css/campinho.css --apply

Safety Features

✅ Backup automático antes de aplicar mudanças (.ux-auto-fix-backup/) ✅ Git clean check - bloqueia se working directory não está limpo ✅ Confidence scoring - só aplica fixes com >= 80% confiança ✅ Dry-run mode - preview antes de aplicar

Exemplo de Output

================================================================================
🔍 UX AUTO-FIX REPORT - DRY-RUN
================================================================================

📊 RESUMO

  Cores hardcoded em CSS: 604 issue(s)
  Z-index arbitrário: 7 issue(s)
  Font-family hardcoded: 26 issue(s)
  Emoji como ícone: 2 issue(s)

  Total: 639 issue(s) detectado(s)

📝 DETALHES

  Cores hardcoded em CSS:
    css/campinho.css:8
      ❌ #0a0a0a
      ✅ var(--app-bg)
      💡 Cor hardcoded mapeada para token oficial (confidence: 95%)

    css/campinho.css:102
      ❌ #fff
      ✅ var(--app-text-primary)
      💡 Cor hardcoded mapeada para token oficial (confidence: 95%)
...

Workflow Recomendado

1. Rodar auditoria completa:
   /ux-auditor-app

2. Se encontrar issues auto-fixáveis, preview:
   node scripts/ux-auto-fix.js

3. Revisar mudanças propostas

4. Aplicar fixes:
   node scripts/ux-auto-fix.js --apply

5. Testar app manualmente

6. Commit:
   git commit -m "fix(ux): auto-fix [N] issues"

Limitações e Edge Cases

⚠️ Não corrige automaticamente:

Estados visuais (loading, empty, error)
Responsividade (overflow, touch targets)
Acessibilidade (aria-labels, focus states)
Navegação SPA (rotas, history)
Performance (animações, lazy loading)

Esses casos requerem análise e fix manual.

Workflow de Auditoria

Passo 1: Carregar Referencia

Ler: css/_app-tokens.css (fonte da verdade)
Ler: DESIGN_SYSTEM.md (referencia visual)

Passo 2: Varrer Fragmentos HTML

Para cada fronts/*.html:
  - Verificar estrutura HTML
  - Buscar classes CSS usadas
  - Detectar estilos inline
  - Verificar iconografia

Passo 3: Varrer Arquivos CSS

Para cada css/*.css:
  - Buscar cores hardcoded
  - Verificar uso de tokens
  - Analisar media queries
  - Verificar z-index

Passo 4: Varrer Modulos JS (UI)

Para cada js/modules/*.js:
  - Buscar innerHTML com estilos inline
  - Verificar estados (loading, error, empty)
  - Verificar manipulacao de classes CSS

Passo 5: Gerar Relatorio

Formato do Relatorio

# AUDITORIA UX: App Participante
**Data:** DD/MM/AAAA
**Modo:** Completa | Dimensao X | Tela Y

---

## Resumo Executivo

| Dimensao | Score | Status |
|----------|-------|--------|
| 1. Design Tokens | X/Y | Aprovado/Warnings/Critico |
| 2. Tipografia | X/Y | Aprovado/Warnings/Critico |
| 3. Dark Theme | X/Y | Aprovado/Warnings/Critico |
| 4. Responsividade | X/Y | Aprovado/Warnings/Critico |
| 5. Estados Visuais | X/Y | Aprovado/Warnings/Critico |
| 6. Navegacao SPA | X/Y | Aprovado/Warnings/Critico |
| 7. PWA/A11y | X/Y | Aprovado/Warnings/Critico |

**Score Geral:** XX/100
**Telas Auditadas:** N de 18

---

## Issues Encontrados

### CRITICOS (bloquear release)
1. [Dimensao] Arquivo:linha - Descricao - Correcao sugerida

### ALTOS (corrigir antes de producao)
1. [Dimensao] Arquivo:linha - Descricao - Correcao sugerida

### MEDIOS (corrigir no sprint)
1. [Dimensao] Arquivo:linha - Descricao - Correcao sugerida

### BAIXOS (backlog)
1. [Dimensao] Arquivo:linha - Descricao - Correcao sugerida

---

## Telas Detalhadas

### home.html
| Dimensao | Status | Observacao |
|----------|--------|------------|
| Tokens | OK/NOK | ... |
| Tipografia | OK/NOK | ... |
| ... | ... | ... |

(repetir para cada tela auditada)

---

## Acoes Recomendadas (Priorizadas)
1. ...
2. ...

---

**Auditoria realizada por:** [IA]
**Proxima auditoria recomendada:** DD/MM/AAAA

Severidades

Nivel	Criterio	Exemplos
CRITICO	Quebra visual, app inutilizavel	Overflow, texto invisivel, nav quebrada
ALTO	Inconsistencia grave, UX prejudicada	Cor hardcoded, fonte errada, sem loading state
MEDIO	Inconsistencia menor, nao impede uso	Spacing irregular, z-index fora do padrao
BAIXO	Nice to have, polimento	A11y menor, animacao faltante

Score de Conformidade

Score = (Checks Passed / Total Checks) * 100

Faixa	Classificacao
90-100%	Excelente - Pronto para release
70-89%	Bom - Corrigir warnings antes de release
50-69%	Regular - Precisa melhorias significativas
< 50%	Critico - NAO fazer release

Comandos de Busca Uteis

# Cores hardcoded em CSS (excluindo tokens)
grep -rn --include="*.css" "#[0-9a-fA-F]\{3,6\}" public/participante/css/ | grep -v "_app-tokens.css"

# Cores hardcoded em HTML
grep -rn --include="*.html" "style=.*#[0-9a-fA-F]" public/participante/fronts/

# Font-family fora dos tokens
grep -rn --include="*.css" "font-family:" public/participante/css/ | grep -v "_app-tokens.css"

# z-index fora dos tokens
grep -rn --include="*.css" "z-index:" public/participante/css/ | grep -v "_app-tokens.css"

# innerHTML com style inline em JS
grep -rn "innerHTML.*style=" public/participante/js/

# Emojis em HTML (nao deveria ter como icones)
grep -rn --include="*.html" "[^\x00-\x7F]" public/participante/fronts/

# Font Awesome residual
grep -rn "fa-\|font-awesome\|fontawesome" public/participante/

# Estados de loading nos modulos JS
grep -rn "loading\|spinner\|skeleton" public/participante/js/modules/

# Estados de erro nos modulos JS
grep -rn "error\|erro\|falha\|showError" public/participante/js/modules/

# Estados vazios nos modulos JS
grep -rn "empty\|vazio\|nenhum\|sem dados" public/participante/js/modules/

Combinacoes com Outras Skills

Cenario	Sequencia
Auditoria + correcao	`ux-auditor-app` → `frontend-crafter`
Auditoria pos-refatoracao	`Refactor-Monolith` → `ux-auditor-app`
Auditoria pre-release	`ux-auditor-app` → `cache-auditor` → `code-inspector`
Auditoria de modulo especifico (completa)	`auditor-module` (backend) + `ux-auditor-app --tela X` (frontend)

Ultima atualizacao: 06/02/2026 Versao: 1.0.0 Autor: Sistema Super Cartola Manager