Habilidade de Agente Frontend
⚠️ CHECKLIST PRÉ-GERAÇÃO (OBRIGATÓRIA)
Antes de criar QUALQUER componente de UI, complete esta checklist:
CHECKLIST_PRÉ_GERAÇÃO:
1. LER_SISTEMA_DE_DESIGN:
- [ ] Leia /DESIGN-SYSTEM.md para padrões proibidos
- [ ] Verifique o bloco @theme em /src/app/globals.css para tokens
- [ ] Nota: accent-500 = #ff6b35 (laranja)
2. VERIFICAR_COMPONENTES_EXISTENTES:
- [ ] Olhe em /src/components/ui/ primeiro (48 componentes)
- [ ] Verifique components.json para configuração shadcn
- [ ] Revise padrões existentes na landing page
3. REFERENCIAR_BIBLIOTECAS_DE_UI:
- [ ] Veja /docs/UI-LIBRARY-INDEX.md para componentes premium
- [ ] Prioridade: Projeto → StyleUI/KokonutUI/Cult UI → base shadcn
- [ ] NUNCA use padrões shadcn sem personalização
4. VERIFICAR_SEM_PADRÕES_PROIBIDOS:
- [ ] Sem bg-white, text-gray-600 ou estados hover genéricos
- [ ] Sem layouts uniformes grid-cols-3 gap-4
- [ ] Sem <Card className="p-6"> sem estilo
- [ ] Sem ícones sem cores da marca
PADRÕES DE CÓDIGO PROIBIDOS:
// ❌ NUNCA GERE ESTES
className="bg-white rounded-lg shadow p-4" // Card genérico
className="grid grid-cols-3 gap-4" // Grade uniforme
className="text-gray-600" // Padrão silenciado
className="hover:bg-gray-100" // Hover genérico
<Card className="p-6"> // shadcn sem estilo
PADRÕES OBRIGATÓRIOS:
// ✅ SEMPRE USE TOKENS DE DESIGN
className="bg-bg-card border border-border-base hover:border-accent-500"
className="text-text-primary"
className="text-text-secondary"
className="bg-accent-500 hover:bg-accent-400"
Visão Geral
O Agente Frontend é responsável por todo o trabalho de UI/UX na aplicação Next.js Unite-Hub:
- Desenvolvimento React 19 / Next.js 16 com App Router
- Implementação e personalização de componentes shadcn/ui
- Estilização com Tailwind CSS e design responsivo
- Criação de rotas e configuração de breadcrumbs
- Gerenciamento de estado no lado do cliente (React Context, hooks)
- Otimização de acessibilidade e desempenho
Como Usar Este Agente
Gatilho
Usuário diz: "Corrigir layout do dashboard", "Adicionar nova página de contato", "Atualizar navegação", "Criar componente modal"
O que o Agente Faz
1. Entender a Solicitação
Perguntas a Fazer:
- Qual página/componente precisa de trabalho?
- Qual é o comportamento desejado?
- Existem referências de design (capturas de tela, wireframes)?
- Qual é a prioridade (P0/P1/P2)?
2. Analisar a Implementação Atual
Passo A: Localizar Arquivos
# Encontre o componente ou página
find src/app -name "*.tsx" | grep -i "contacts"
find src/components -name "*.tsx" | grep -i "hotleads"
Passo B: Ler Código Atual
// Use a ferramenta text_editor
text_editor.view("src/app/dashboard/contacts/page.tsx")
Passo C: Identificar Dependências
- Quais componentes shadcn/ui são usados?
- Quais contextos são consumidos (AuthContext, etc.)?
- Quais rotas de API são chamadas?
- Quais consultas ao banco de dados são feitas?
3. Implementar Alterações
Passo A: Atualizações de Componentes
Para componentes existentes:
// src/components/HotLeadsPanel.tsx
import { Button } from "@/components/ui/button";
import { Card } from "@/components/ui/card";
import { useAuth } from "@/contexts/AuthContext";
export function HotLeadsPanel({ workspaceId }: { workspaceId: string }) {
const { currentOrganization } = useAuth();
// Buscar leads quentes
const [leads, setLeads] = useState([]);
useEffect(() => {
async function fetchLeads() {
const res = await fetch("/api/agents/contact-intelligence", {
method: "POST",
body: JSON.stringify({ action: "get_hot_leads", workspaceId }),
});
const data = await res.json();
setLeads(data.leads || []);
}
if (workspaceId) fetchLeads();
}, [workspaceId]);
return (
<Card>
{/* Implementação da UI */}
</Card>
);
}
Passo B: Criação de Rotas
Para novas páginas:
// src/app/dashboard/new-page/page.tsx
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Nova Página | Unite Hub",
description: "Descrição da nova página"
};
export default async function NewPage() {
return (
<div className="container mx-auto py-8">
<h1 className="text-3xl font-bold">Nova Página</h1>
{/* Conteúdo */}
</div>
);
}
Passo C: Componentes shadcn/ui
Instale novos componentes se necessário:
npx shadcn@latest add dialog
npx shadcn@latest add dropdown-menu
npx shadcn@latest add toast
Use componentes seguindo padrões shadcn:
import {
Dialog,
DialogContent,
DialogDescription,
DialogHeader,
DialogTitle,
DialogTrigger,
} from "@/components/ui/dialog";
<Dialog>
<DialogTrigger asChild>
<Button>Abrir Diálogo</Button>
</DialogTrigger>
<DialogContent>
<DialogHeader>
<DialogTitle>Título</DialogTitle>
<DialogDescription>Descrição</DialogDescription>
</DialogHeader>
{/* Conteúdo */}
</DialogContent>
</Dialog>
4. Adicionar Filtragem por Workspace (CRÍTICO para V1)
Todas as consultas ao banco de dados DEVEM filtrar por workspace:
// ❌ RUIM - Mostra dados de todos os workspaces
const { data: contacts } = await supabase
.from("contacts")
.select("*");
// ✅ BOM - Mostra apenas dados do workspace do usuário
const { data: contacts } = await supabase
.from("contacts")
.select("*")
.eq("workspace_id", workspaceId);
Obrigatório para estas tabelas:
contacts-.eq("workspace_id", workspaceId)campaigns-.eq("workspace_id", workspaceId)drip_campaigns-.eq("workspace_id", workspaceId)emails-.eq("workspace_id", workspaceId)generatedContent-.eq("workspace_id", workspaceId)
5. Gerenciar Estados de Carregamento e Erro
Estado de Carregamento:
const [isLoading, setIsLoading] = useState(true);
const [error, setError] = useState<string | null>(null);
useEffect(() => {
async function fetchData() {
try {
setIsLoading(true);
const data = await fetch("...");
setData(data);
} catch (err) {
setError(err.message);
} finally {
setIsLoading(false);
}
}
fetchData();
}, []);
if (isLoading) return <Spinner />;
if (error) return <ErrorBanner message={error} />;
return <DataDisplay data={data} />;
6. Design Responsivo
Breakpoints Tailwind:
<div className="
grid grid-cols-1 // Mobile: 1 coluna
md:grid-cols-2 // Tablet: 2 colunas
lg:grid-cols-3 // Desktop: 3 colunas
gap-4
">
{/* Cards */}
</div>
Abordagem Mobile-First:
- Comece com layout mobile (classes padrão)
- Adicione classes
md:para tablet - Adicione classes
lg:exl:para desktop
7. Testar Alterações
Passo A: Teste Visual
# Inicie o servidor de desenvolvimento
npm run dev
# Navegue até a página no navegador
# Teste no viewport mobile (DevTools)
# Teste no tema escuro
Passo B: Acessibilidade
// Verifique:
// - Rótulos ARIA adequados
// - Navegação por teclado
// - Estados de foco
// - Suporte a leitores de tela
<button aria-label="Fechar diálogo">×</button>
<input aria-describedby="email-help" />
<div role="alert" aria-live="polite">{error}</div>
Passo C: Desempenho
// Use React.memo para componentes caros
import { memo } from "react";
export const ExpensiveComponent = memo(function ExpensiveComponent({ data }) {
return <div>{/* Renderizar */}</div>;
});
// Use imports dinâmicos para componentes pesados
import dynamic from "next/dynamic";
const HeavyChart = dynamic(() => import("@/components/HeavyChart"), {
loading: () => <Spinner />,
ssr: false
});
Tarefas Comuns
Tarefa 1: Corrigir Filtro de Workspace Ausente
Exemplo: Página do Dashboard Overview mostrando todos os contatos
Passos:
- Leia
src/app/dashboard/overview/page.tsx - Encontre todas as consultas Supabase
- Adicione
.eq("workspace_id", workspaceId)a cada uma - Adicione verificação nula para workspaceId antes de consultar
- Teste com múltiplos workspaces
Código:
// Antes
const { data: contacts } = await supabase.from("contacts").select("*");
// Depois
if (!workspaceId) {
return <div>Nenhum workspace selecionado</div>;
}
const { data: contacts, error } = await supabase
.from("contacts")
.select("*")
.eq("workspace_id", workspaceId);
if (error) {
console.error("Erro ao buscar contatos:", error);
return <ErrorBanner />;
}
Tarefa 2: Criar Nova Página do Dashboard
Exemplo: Adicionar página "Analytics" ao dashboard
Passos:
- Crie
src/app/dashboard/analytics/page.tsx - Adicione à navegação em
src/app/dashboard/layout.tsx - Implemente o conteúdo da página com componentes shadcn/ui
- Adicione breadcrumbs
- Teste a navegação
Código:
// src/app/dashboard/analytics/page.tsx
import { Metadata } from "next";
import { Card } from "@/components/ui/card";
export const metadata: Metadata = {
title: "Analytics | Unite Hub",
};
export default async function AnalyticsPage() {
return (
<div className="container mx-auto py-8 space-y-6">
<div>
<h1 className="text-3xl font-bold">Analytics</h1>
<p className="text-muted-foreground">Acompanhe o desempenho de suas campanhas</p>
</div>
<div className="grid grid-cols-1 md:grid-cols-3 gap-6">
<Card>
{/* Card de estatística 1 */}
</Card>
<Card>
{/* Card de estatística 2 */}
</Card>
<Card>
{/* Card de estatística 3 */}
</Card>
</div>
</div>
);
}
// src/app/dashboard/layout.tsx - Adicionar à navegação
const navigation = [
{ name: "Dashboard", href: "/dashboard/overview", icon: HomeIcon },
{ name: "Contatos", href: "/dashboard/contacts", icon: UsersIcon },
{ name: "Campanhas", href: "/dashboard/campaigns", icon: MailIcon },
{ name: "Analytics", href: "/dashboard/analytics", icon: ChartIcon }, // NOVO
];
Tarefa 3: Implementar Funcionalidade de Botão
Exemplo: Botão "Enviar Email" no painel Hot Leads
Passos:
- Leia
src/components/HotLeadsPanel.tsx - Encontre a localização do botão
- Implemente o manipulador onClick
- Chame o endpoint de API apropriado
- Mostre toast de sucesso/erro
Código:
import { useToast } from "@/components/ui/use-toast";
function HotLeadsPanel() {
const { toast } = useToast();
async function handleSendEmail(contactId: string) {
try {
const res = await fetch("/api/emails/send", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ contactId, templateType: "followup" }),
});
if (!res.ok) throw new Error("Falha ao enviar email");
toast({
title: "Email enviado",
description: "Seu email foi colocado na fila para envio.",
});
} catch (error) {
toast({
variant: "destructive",
title: "Erro",
description: error.message,
});
}
}
return (
<Button onClick={() => handleSendEmail(contact.id)}>
Enviar Email
</Button>
);
}
Diretrizes de Estilização
Melhores Práticas Tailwind CSS
Use Classes Utilitárias:
// ✅ Bom
<div className="flex items-center justify-between p-4 bg-background border rounded-lg">
// ❌ Ruim (CSS personalizado)
<div style={{ display: "flex", padding: "16px" }}>
Use Variáveis CSS do Tema:
// Definido em globals.css
@layer base {
:root {
--background: 0 0% 100%;
--foreground: 222.2 84% 4.9%;
--card: 0 0% 100%;
--primary: 222.2 47.4% 11.2%;
}
}
// Use em componentes
<div className="bg-background text-foreground">
<div className="bg-card text-card-foreground">
<div className="bg-primary text-primary-foreground">
Design Responsivo:
<div className="
text-sm md:text-base lg:text-lg
p-2 md:p-4 lg:p-6
grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3
">
Referência da Biblioteca de Componentes
Componentes shadcn/ui Disponíveis
accordion- Painéis de conteúdo recolhíveisalert-dialog- Diálogos de confirmação modaisavatar- Imagens de perfil do usuáriobadge- Selos de statusbutton- Botões interativoscard- Contêineres de conteúdocheckbox- Caixas de seleção de formuláriodialog- Diálogos modaisdropdown-menu- Menus suspensosinput- Campos de textolabel- Rótulos de formuláriopopover- Conteúdo flutuanteprogress- Indicadores de progressoradio-group- Botões de rádioselect- Listas suspensas de seleçãoswitch- Interruptores de alternânciatabs- Interfaces com abastoast- Notificações toasttooltip- Tooltips de hover
Instale novos componentes:
npx shadcn@latest add [nome-do-componente]
Padrões de Tratamento de Erros
Erros de API
try {
const res = await fetch("/api/...");
const data = await res.json();
if (!res.ok) {
throw new Error(data.error || "Algo deu errado");
}
return data;
} catch (error) {
console.error("Erro de API:", error);
toast({
variant: "destructive",
title: "Erro",
description: error.message,
});
return null;
}
Erros do Supabase
const { data, error } = await supabase.from("contacts").select("*");
if (error) {
console.error("Erro do Supabase:", error);
return <ErrorBanner message="Falha ao carregar contatos" />;
}
if (!data || data.length === 0) {
return <EmptyState message="Nenhum contato encontrado" />;
}
return <ContactsList contacts={data} />;
Restrições da Versão 1
O que Corrigimos na V1:
- ✅ Filtragem por workspace em TODAS as páginas
- ✅ Funcionalidade do botão Hot Leads
- ✅ Navegação da página de detalhes do contato
- ✅ Cards de estatísticas do dashboard
- ✅ Estados de carregamento e erro
- ✅ Correções de design responsivo
O que NÃO Construímos na V1:
- ❌ Animações avançadas
- ❌ Construtor de temas personalizado
- ❌ Interfaces de arrastar e soltar
- ❌ UI de colaboração em tempo real
- ❌ Aplicativo mobile
Pontos-Chave
- Sempre filtre por workspace - O isolamento de dados é crítico
- Use componentes shadcn/ui - Não reinvente a roda
- Siga as convenções Tailwind - Abordagem utilitária primeiro
- Gerencie estados de carregamento/erro - Nunca mostre telas em branco
- Teste o design responsivo - Mobile, tablet, desktop