UI Audit Skill

Descrição: Audita componentes UI do frontend seguindo as regras específicas do NEXO Design System.

Comando: /ui-audit

Contexto obrigatório:

•.github/instructions/frontend-ui.instructions.md
•frontend/src/app/globals.css
•Componente/arquivo alvo

Objetivo

Analisar código de componente UI e identificar violações das regras do Design System NEXO, sugerindo correções específicas.

Regras de Auditoria

1. Typography & Readability (Anti-Slop)

Headings

Verificar:

• h1..h3 usam tracking-tight
• Font weight é font-weight-[550] ou semibold
• Multiline usa text-balance

❌ Violações comuns:

tsx

// INCORRETO
<h1 className="text-xl">Título</h1>
<h2 className="text-lg font-normal">Subtítulo</h2>
<h3 className="text-base">Item</h3>

✅ Correção:

tsx

// CORRETO
<h1 className="text-2xl font-semibold tracking-tight text-balance">Título</h1>
<h2 className="text-xl font-semibold tracking-tight">Subtítulo</h2>
<h3 className="text-lg font-semibold tracking-tight">Item</h3>

Body

Verificar:

• Dashboards usam text-sm (não text-base)
• Texto secundário usa text-muted-foreground (não text-gray-500)
• Parágrafos usam leading-relaxed
• Labels usam leading-none

❌ Violações comuns:

tsx

// INCORRETO
<p className="text-base text-gray-600">Descrição</p>
<span className="text-sm text-gray-500">Label</span>

✅ Correção:

tsx

// CORRETO
<p className="text-sm text-muted-foreground leading-relaxed">Descrição</p>
<span className="text-sm text-muted-foreground leading-none">Label</span>

2. Spacing & Layout

Fluidity

Verificar:

• Evita larguras fixas (w-[300px])
• Usa max-w-md, max-w-lg, etc.
• Page wrappers usam container + mx-auto

❌ Violações comuns:

tsx

// INCORRETO
<div className="w-[400px]">Conteúdo</div>
<div className="w-full px-4">Página</div>

✅ Correção:

tsx

// CORRETO
<div className="max-w-md">Conteúdo</div>
<div className="container mx-auto">Página</div>

Vertical Rhythm

Verificar:

❌ Violações comuns:

tsx

// INCORRETO - gap-4 em tudo (AI Slop)
<div className="flex gap-4">...</div>
<div className="space-y-4">...</div>

✅ Correção:

tsx

// CORRETO - spacing intencional
<div className="flex gap-3">...</div>        {/* Small */}
<div className="space-y-6">...</div>         {/* Medium */}
<div className="flex flex-col gap-12">...</div> {/* Section */}

3. Visuals & Depth

Borders

Verificar:

• Usa border (não border-gray-300)
• Separação sutil usa bg-muted ou bg-sidebar-border

❌ Violações comuns:

tsx

// INCORRETO
<div className="border-gray-200">...</div>
<div className="border-[#E5E7EB]">...</div>

✅ Correção:

tsx

// CORRETO
<div className="border">...</div>
<div className="bg-muted">...</div>

Shadows

Verificar:

• Cards usam shadow-sm (não shadow-md)
• Popovers usam shadow-lg
• Inputs usam inner shadows customizados

❌ Violações comuns:

tsx

// INCORRETO
<div className="shadow-md">Card</div>
<div className="shadow-xl">Popover</div>

✅ Correção:

tsx

// CORRETO
<div className="shadow-sm">Card</div>
<div className="shadow-lg">Popover</div>
<input className="shadow-[inset_0_1px_2px_rgba(0,0,0,0.05)]" />

Radius

Verificar:

• Usa var(--radius) via classes Tailwind
• Nested items usam rounded-[calc(var(--radius)-2px)]

❌ Violações comuns:

tsx

// INCORRETO
<div className="rounded-lg">...</div>
<div className="rounded-md">...</div>

✅ Correção:

tsx

// CORRETO
<div className="rounded-[var(--radius)]">...</div>
<div className="rounded-[calc(var(--radius)-2px)]">...</div>

4. Components (shadcn/ui)

Buttons

Verificar:

• Standard: h-9 ou h-10
• Small: h-8 px-3 text-xs
• Micro-interaction: active:scale-95

❌ Violações comuns:

tsx

// INCORRETO
<button className="py-2 px-4">Salvar</button>
<Button className="h-12">Grande</Button>

✅ Correção:

tsx

// CORRETO
<Button className="h-9 active:scale-95">Salvar</Button>
<Button className="h-8 px-3 text-xs active:scale-95">Pequeno</Button>

Cards

Verificar:

• Borderless style para dados densos
• Background: bg-card ou bg-muted

❌ Violações comuns:

tsx

// INCORRETO
<div className="border rounded-lg p-4 bg-white">...</div>

✅ Correção:

tsx

// CORRETO
<div className="p-4 bg-card">...</div>
<div className="p-4 bg-muted">...</div>

5. Colors (OKLCH System)

Verificar:

• Usa tokens CSS (não hex/rgb)
• CTAs: bg-primary text-primary-foreground
• Secondary: bg-secondary text-secondary-foreground
• Danger: bg-destructive text-destructive-foreground
• Hints: text-muted-foreground

❌ Violações comuns:

tsx

// INCORRETO - Cores hardcoded
<button className="bg-[#3B82F6] text-white">CTA</button>
<p className="text-gray-500">Hint</p>
<div className="bg-red-500">Erro</div>

✅ Correção:

tsx

// CORRETO - Tokens CSS
<Button className="bg-primary text-primary-foreground">CTA</Button>
<p className="text-muted-foreground">Hint</p>
<div className="bg-destructive text-destructive-foreground">Erro</div>

6. Motion (Framer Motion + Tailwind)

Hover

Verificar:

• Transições usam transition-all duration-200 ease-in-out

❌ Violações comuns:

tsx

// INCORRETO
<button className="hover:bg-blue-600">...</button>
<div className="transition">...</div>

✅ Correção:

tsx

// CORRETO
<Button className="transition-all duration-200 ease-in-out hover:bg-primary/90">...</Button>

Enter/Exit

Verificar:

• Usa animate-in fade-in zoom-in-95

❌ Violações comuns:

tsx

// INCORRETO
<motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }}>...</motion.div>

✅ Correção:

tsx

// CORRETO
<div className="animate-in fade-in zoom-in-95 duration-200">...</div>

Lists

Verificar:

• Reordering usa layout prop do Framer Motion

7. Accessibility (Requirements)

Verificar:

• Elementos interativos têm focus-visible:ring-2
• Cores usam variáveis OKLCH (contraste garantido)
• Tags semânticas: section, article, nav

❌ Violações comuns:

tsx

// INCORRETO
<button onClick={handleClick}>
  <X />
</button>
<div className="cursor-pointer" onClick={...}>...</div>

✅ Correção:

tsx

// CORRETO
<Button
  onClick={handleClick}
  aria-label="Fechar modal"
  className="focus-visible:ring-2"
>
  <X />
</Button>
<button className="cursor-pointer focus-visible:ring-2" onClick={...}>...</button>

Processo de Auditoria

•Leia o componente fornecido pelo usuário
•Identifique violações em cada categoria
•Liste violações com código atual
•Sugira correções com código corrigido
•
Priorize por impacto:
- •🔴 P0 (Crítico): Cores hardcoded, sem acessibilidade
- •🟡 P1 (Alto): AI Slop (gap-4, rounded-md genérico)
- •🟢 P2 (Médio): Otimizações (micro-interações, shadows)

Template de Relatório

markdown

# UI Audit Report: {ComponentName}

## Resumo
- **Arquivo:** `{path}`
- **Violações encontradas:** {count}
- **Prioridade:** P0: {n} | P1: {n} | P2: {n}

---

## 🔴 P0 - Violações Críticas

### 1. Cores Hardcoded
**Linha:** {line}
**Atual:**
```tsx
{código com violação}

Correção:

tsx

{código corrigido}

🟡 P1 - AI Slop

1. Spacing Genérico

Linha: {line} Atual:

tsx

{código com violação}

Correção:

tsx

{código corrigido}

🟢 P2 - Otimizações

1. Micro-interações Ausentes

Linha: {line} Atual:

tsx

{código com violação}

Correção:

tsx

{código corrigido}

✅ Checklist de Correção

• Corrigir cores hardcoded (P0)
• Adicionar acessibilidade (P0)
• Corrigir spacing genérico (P1)
• Corrigir tipografia (P1)
• Adicionar micro-interações (P2)
• Otimizar shadows (P2)

Próximos Passos

•Aplicar correções P0 imediatamente
•Aplicar correções P1 antes de merge
•Aplicar correções P2 se houver tempo

code


---

## Uso

```bash
# Auditar componente específico
/ui-audit frontend/src/components/customers/customer-table.tsx

# Auditar página
/ui-audit frontend/src/app/(dashboard)/clientes/page.tsx

# Auditar múltiplos arquivos
/ui-audit frontend/src/components/customers/*.tsx

Referências

•.github/instructions/frontend-ui.instructions.md - Regras completas
•frontend/src/app/globals.css - Tokens CSS
•frontend/src/components/ui/ - Componentes shadcn/ui