¿Qué hace Frontend Agent Skill?
⚠️ LISTA DE VERIFICACIÓN PREVIA A LA GENERACIÓN (OBLIGATORIA)
Antes de crear CUALQUIER componente de UI, complete esta lista de verificación:
PRE_GENERATION_CHECKLIST:
1. LEER_SISTEMA_DE_DISEÑO:
- [ ] Leer /DESIGN-SYSTEM.md para patrones prohibidos
- [ ] Verificar el bloque @theme en /src/app/globals.css para tokens
- [ ] Nota: accent-500 = #ff6b35 (naranja)
2. VERIFICAR_COMPONENTES_EXISTENTES:
- [ ] Mirar primero en /src/components/ui/ (48 componentes)
- [ ] Revisar components.json para la configuración de shadcn
- [ ] Revisar patrones existentes en la página de inicio
3. REFERENCIAR_BIBLIOTECAS_UI:
- [ ] Ver /docs/UI-LIBRARY-INDEX.md para componentes premium
- [ ] Prioridad: Proyecto → StyleUI/KokonutUI/Cult UI → base shadcn
- [ ] NUNCA usar valores predeterminados de shadcn sin personalización
4. VERIFICAR_SIN_PATRONES_PROHIBIDOS:
- [ ] Sin bg-white, text-gray-600, o estados hover genéricos
- [ ] Sin diseños uniformes grid-cols-3 gap-4
- [ ] Sin <Card className="p-6"> sin estilos
- [ ] Sin iconos sin colores de marca
PATRONES DE CÓDIGO PROHIBIDOS:
// ❌ NUNCA GENERAR ESTOS
className="bg-white rounded-lg shadow p-4" // Tarjeta genérica
className="grid grid-cols-3 gap-4" // Cuadrícula uniforme
className="text-gray-600" // Silenciado predeterminado
className="hover:bg-gray-100" // Hover genérico
<Card className="p-6"> // shadcn sin estilos
PATRONES REQUERIDOS:
// ✅ USAR SIEMPRE TOKENS DE DISEÑO
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"
Descripción general
El Agente Frontend es responsable de todo el trabajo de UI/UX en la aplicación Next.js de Unite-Hub:
- Desarrollo con React 19 / Next.js 16 usando App Router
- Implementación y personalización de componentes shadcn/ui
- Estilizado con Tailwind CSS y diseño responsivo
- Creación de rutas y configuración de breadcrumbs
- Gestión de estado del lado del cliente (React Context, hooks)
- Optimización de accesibilidad y rendimiento
Cómo usar este agente
Activación
El usuario dice: "Arreglar diseño del dashboard", "Agregar nueva página de contacto", "Actualizar navegación", "Crear componente modal"
Lo que hace el agente
1. Entender la solicitud
Preguntas a realizar:
- ¿Qué página/componente necesita trabajo?
- ¿Cuál es el comportamiento deseado?
- ¿Hay referencias de diseño (capturas de pantalla, wireframes)?
- ¿Cuál es la prioridad (P0/P1/P2)?
2. Analizar la implementación actual
Paso A: Localizar archivos
# Encontrar el componente o página
find src/app -name "*.tsx" | grep -i "contacts"
find src/components -name "*.tsx" | grep -i "hotleads"
Paso B: Leer el código actual
// Usar la herramienta text_editor
text_editor.view("src/app/dashboard/contacts/page.tsx")
Paso C: Identificar dependencias
- ¿Qué componentes de shadcn/ui se utilizan?
- ¿Qué contextos se consumen (AuthContext, etc.)?
- ¿Qué rutas de API se llaman?
- ¿Qué consultas a la base de datos se realizan?
3. Implementar cambios
Paso A: Actualizaciones 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();
// Obtener leads calientes
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>
{/* Implementación de UI */}
</Card>
);
}
Paso B: Creación de rutas
Para páginas nuevas:
// src/app/dashboard/new-page/page.tsx
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Nueva Página | Unite Hub",
description: "Descripción de la nueva página"
};
export default async function NewPage() {
return (
<div className="container mx-auto py-8">
<h1 className="text-3xl font-bold">Nueva Página</h1>
{/* Contenido */}
</div>
);
}
Paso C: Componentes shadcn/ui
Instalar nuevos componentes si es necesario:
npx shadcn@latest add dialog
npx shadcn@latest add dropdown-menu
npx shadcn@latest add toast
Usar componentes siguiendo los patrones de 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>Descripción</DialogDescription>
</DialogHeader>
{/* Contenido */}
</DialogContent>
</Dialog>
4. Agregar filtrado por workspace (CRÍTICO para V1)
TODAS las consultas a la base de datos DEBEN filtrar por workspace:
// ❌ MAL - Muestra datos de todos los workspaces
const { data: contacts } = await supabase
.from("contacts")
.select("*");
// ✅ BIEN - Solo muestra datos del workspace del usuario
const { data: contacts } = await supabase
.from("contacts")
.select("*")
.eq("workspace_id", workspaceId);
Requerido para estas tablas:
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. Manejar estados de carga y error
Estado de carga:
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. Diseño responsivo
Puntos de quiebre de Tailwind:
<div className="
grid grid-cols-1 // Móvil: 1 columna
md:grid-cols-2 // Tablet: 2 columnas
lg:grid-cols-3 // Escritorio: 3 columnas
gap-4
">
{/* Tarjetas */}
</div>
Enfoque mobile-first:
- Comenzar con el diseño móvil (clases predeterminadas)
- Agregar clases
md:para tablet - Agregar clases
lg:yxl:para escritorio
7. Probar cambios
Paso A: Pruebas visuales
# Iniciar servidor de desarrollo
npm run dev
# Navegar a la página en el navegador
# Probar en viewport móvil (DevTools)
# Probar tema oscuro
Paso B: Accesibilidad
// Verificar:
// - Etiquetas ARIA adecuadas
// - Navegación por teclado
// - Estados de foco
// - Soporte para lectores de pantalla
<button aria-label="Cerrar diálogo">×</button>
<input aria-describedby="email-help" />
<div role="alert" aria-live="polite">{error}</div>
Paso C: Rendimiento
// Usar React.memo para componentes costosos
import { memo } from "react";
export const ExpensiveComponent = memo(function ExpensiveComponent({ data }) {
return <div>{/* Renderizar */}</div>;
});
// Usar importaciones dinámicas para componentes pesados
import dynamic from "next/dynamic";
const HeavyChart = dynamic(() => import("@/components/HeavyChart"), {
loading: () => <Spinner />,
ssr: false
});
Tareas comunes
Tarea 1: Corregir filtro de workspace faltante
Ejemplo: Página de resumen del dashboard mostrando todos los contactos
Pasos:
- Leer
src/app/dashboard/overview/page.tsx - Encontrar todas las consultas de Supabase
- Agregar
.eq("workspace_id", workspaceId)a cada una - Agregar verificación nula de workspaceId antes de consultar
- Probar con múltiples workspaces
Código:
// Antes
const { data: contacts } = await supabase.from("contacts").select("*");
// Después
if (!workspaceId) {
return <div>Ningún workspace seleccionado</div>;
}
const { data: contacts, error } = await supabase
.from("contacts")
.select("*")
.eq("workspace_id", workspaceId);
if (error) {
console.error("Error al obtener contactos:", error);
return <ErrorBanner />;
}
Tarea 2: Crear nueva página de dashboard
Ejemplo: Agregar página "Analytics" al dashboard
Pasos:
- Crear
src/app/dashboard/analytics/page.tsx - Agregar a la navegación en
src/app/dashboard/layout.tsx - Implementar contenido de la página con componentes shadcn/ui
- Agregar breadcrumbs
- Probar navegación
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">Sigue el rendimiento de tus campañas</p>
</div>
<div className="grid grid-cols-1 md:grid-cols-3 gap-6">
<Card>
{/* Tarjeta de estadística 1 */}
</Card>
<Card>
{/* Tarjeta de estadística 2 */}
</Card>
<Card>
{/* Tarjeta de estadística 3 */}
</Card>
</div>
</div>
);
}
// src/app/dashboard/layout.tsx - Agregar a la navegación
const navigation = [
{ name: "Dashboard", href: "/dashboard/overview", icon: HomeIcon },
{ name: "Contactos", href: "/dashboard/contacts", icon: UsersIcon },
{ name: "Campañas", href: "/dashboard/campaigns", icon: MailIcon },
{ name: "Analytics", href: "/dashboard/analytics", icon: ChartIcon }, // NUEVO
];
Tarea 3: Implementar funcionalidad de botón
Ejemplo: Botón "Enviar correo" del panel Hot Leads
Pasos:
- Leer
src/components/HotLeadsPanel.tsx - Encontrar la ubicación del botón
- Implementar el controlador onClick
- Llamar al endpoint de API adecuado
- Mostrar toast de éxito/error
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("Error al enviar el correo");
toast({
title: "Correo enviado",
description: "Tu correo ha sido encolado para envío.",
});
} catch (error) {
toast({
variant: "destructive",
title: "Error",
description: error.message,
});
}
}
return (
<Button onClick={() => handleSendEmail(contact.id)}>
Enviar Correo
</Button>
);
}
Guía de estilos
Mejores prácticas de Tailwind CSS
Usar clases utilitarias:
// ✅ Bueno
<div className="flex items-center justify-between p-4 bg-background border rounded-lg">
// ❌ Malo (CSS personalizado)
<div style={{ display: "flex", padding: "16px" }}>
Usar variables CSS del tema:
// Definido en 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%;
}
}
// Usar en componentes
<div className="bg-background text-foreground">
<div className="bg-card text-card-foreground">
<div className="bg-primary text-primary-foreground">
Diseño 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
">
Referencia de la biblioteca de componentes
Componentes shadcn/ui disponibles
accordion- Paneles de contenido colapsablesalert-dialog- Diálogos de confirmación modalesavatar- Imágenes de perfil de usuariobadge- Insignias de estadobutton- Botones interactivoscard- Contenedores de contenidocheckbox- Casillas de verificación de formulariodialog- Diálogos modalesdropdown-menu- Menús desplegablesinput- Campos de textolabel- Etiquetas de formulariopopover- Contenido flotanteprogress- Indicadores de progresoradio-group- Botones de radioselect- Listas desplegables de selecciónswitch- Interruptores de alternanciatabs- Interfaces con pestañastoast- Notificaciones toasttooltip- Información emergente al pasar el ratón
Instalar nuevos componentes:
npx shadcn@latest add [nombre-del-componente]
Patrones de manejo de errores
Errores de API
try {
const res = await fetch("/api/...");
const data = await res.json();
if (!res.ok) {
throw new Error(data.error || "Algo salió mal");
}
return data;
} catch (error) {
console.error("Error de API:", error);
toast({
variant: "destructive",
title: "Error",
description: error.message,
});
return null;
}
Errores de Supabase
const { data, error } = await supabase.from("contacts").select("*");
if (error) {
console.error("Error de Supabase:", error);
return <ErrorBanner message="Error al cargar contactos" />;
}
if (!data || data.length === 0) {
return <EmptyState message="No se encontraron contactos" />;
}
return <ContactsList contacts={data} />;
Restricciones de la Versión 1
Lo que corregimos para V1:
- ✅ Filtrado por workspace en TODAS las páginas
- ✅ Funcionalidad del botón Hot Leads
- ✅ Navegación a la página de detalle de contacto
- ✅ Tarjetas de estadísticas del dashboard
- ✅ Estados de carga y error
- ✅ Correcciones de diseño responsivo
Lo que NO construimos para V1:
- ❌ Animaciones avanzadas
- ❌ Creador de temas personalizado
- ❌ Interfaces de arrastrar y soltar
- ❌ UI de colaboración en tiempo real
- ❌ Aplicación móvil
Puntos clave
- Siempre filtrar por workspace - El aislamiento de datos es crítico
- Usar componentes shadcn/ui - No reinventar la rueda
- Seguir las convenciones de Tailwind - Enfoque utility-first
- Manejar estados de carga/error - Nunca mostrar pantallas en blanco
- Probar diseño responsivo - Móvil, tablet, escritorio
…
[truncado para traducción]