Compétence d'Agent Frontend
⚠️ LISTE DE VÉRIFICATION PRÉ-GÉNÉRATION (OBLIGATOIRE)
Avant de créer TOUT composant d'interface, complétez cette liste de vérification :
PRE_GENERATION_CHECKLIST:
1. LIRE LE SYSTÈME DE DESIGN:
- [ ] Lire /DESIGN-SYSTEM.md pour les motifs interdits
- [ ] Vérifier le bloc @theme dans /src/app/globals.css pour les tokens
- [ ] Noter : accent-500 = #ff6b35 (orange)
2. VÉRIFIER LES COMPOSANTS EXISTANTS:
- [ ] Regarder d'abord dans /src/components/ui/ (48 composants)
- [ ] Vérifier components.json pour la configuration shadcn
- [ ] Examiner les motifs existants dans la page d'accueil
3. RÉFÉRENCER LES BIBLIOTHÈQUES D'INTERFACE:
- [ ] Voir /docs/UI-LIBRARY-INDEX.md pour les composants premium
- [ ] Priorité : Projet → StyleUI/KokonutUI/Cult UI → base shadcn
- [ ] Ne JAMAIS utiliser les valeurs par défaut shadcn sans personnalisation
4. VÉRIFIER L'ABSENCE DE MOTIFS INTERDITS:
- [ ] Pas de bg-white, text-gray-600, ou états hover génériques
- [ ] Pas de mises en page uniformes grid-cols-3 gap-4
- [ ] Pas de <Card className="p-6"> non stylé
- [ ] Pas d'icônes sans couleurs de marque
MOTIFS DE CODE INTERDITS :
// ❌ NE JAMAIS GÉNÉRER CEUX-CI
className="bg-white rounded-lg shadow p-4" // Carte générique
className="grid grid-cols-3 gap-4" // Grille uniforme
className="text-gray-600" // Atténué par défaut
className="hover:bg-gray-100" // Hover générique
<Card className="p-6"> // shadcn non stylé
MOTIFS REQUIS :
// ✅ TOUJOURS UTILISER LES 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"
Aperçu
L'agent Frontend est responsable de tout le travail UI/UX dans l'application Next.js Unite-Hub :
- Développement React 19 / Next.js 16 avec App Router
- Implémentation et personnalisation de composants shadcn/ui
- Style Tailwind CSS et design responsive
- Création de routes et configuration des breadcrumbs
- Gestion d'état côté client (React Context, hooks)
- Accessibilité et optimisation des performances
Comment Utiliser Cet Agent
Déclencheur
L'utilisateur dit : "Corriger la mise en page du tableau de bord", "Ajouter une nouvelle page de contact", "Mettre à jour la navigation", "Créer un composant modal"
Ce Que Fait l'Agent
1. Comprendre la Demande
Questions à Poser :
- Quelle page/composant nécessite du travail ?
- Quel est le comportement souhaité ?
- Y a-t-il des références de design (captures d'écran, wireframes) ?
- Quelle est la priorité (P0/P1/P2) ?
2. Analyser l'Implémentation Actuelle
Étape A : Localiser les Fichiers
# Trouver le composant ou la page
find src/app -name "*.tsx" | grep -i "contacts"
find src/components -name "*.tsx" | grep -i "hotleads"
Étape B : Lire le Code Actuel
// Utiliser l'outil text_editor
text_editor.view("src/app/dashboard/contacts/page.tsx")
Étape C : Identifier les Dépendances
- Quels composants shadcn/ui sont utilisés ?
- Quels contextes sont consommés (AuthContext, etc.) ?
- Quelles routes API sont appelées ?
- Quelles requêtes de base de données sont faites ?
3. Implémenter les Modifications
Étape A : Mises à Jour des Composants
Pour les composants existants :
// 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();
// Récupérer les leads chauds
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>
{/* Implémentation de l'interface */}
</Card>
);
}
Étape B : Création de Routes
Pour les nouvelles pages :
// src/app/dashboard/nouvelle-page/page.tsx
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Nouvelle Page | Unite Hub",
description: "Description de la nouvelle page"
};
export default async function NouvellePage() {
return (
<div className="container mx-auto py-8">
<h1 className="text-3xl font-bold">Nouvelle Page</h1>
{/* Contenu */}
</div>
);
}
Étape C : Composants shadcn/ui
Installer de nouveaux composants si nécessaire :
npx shadcn@latest add dialog
npx shadcn@latest add dropdown-menu
npx shadcn@latest add toast
Utiliser les composants selon les motifs shadcn :
import {
Dialog,
DialogContent,
DialogDescription,
DialogHeader,
DialogTitle,
DialogTrigger,
} from "@/components/ui/dialog";
<Dialog>
<DialogTrigger asChild>
<Button>Ouvrir le Dialogue</Button>
</DialogTrigger>
<DialogContent>
<DialogHeader>
<DialogTitle>Titre</DialogTitle>
<DialogDescription>Description</DialogDescription>
</DialogHeader>
{/* Contenu */}
</DialogContent>
</Dialog>
4. Ajouter le Filtrage par Espace de Travail (CRITIQUE pour V1)
Toutes les requêtes de base de données DOIVENT filtrer par espace de travail :
// ❌ MAUVAIS - Affiche les données de tous les espaces de travail
const { data: contacts } = await supabase
.from("contacts")
.select("*");
// ✅ BON - Affiche uniquement les données de l'espace de travail de l'utilisateur
const { data: contacts } = await supabase
.from("contacts")
.select("*")
.eq("workspace_id", workspaceId);
Requis pour ces tables :
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. Gérer les États de Chargement et d'Erreur
État de Chargement :
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 Responsive
Points de Rupture Tailwind :
<div className="
grid grid-cols-1 // Mobile : 1 colonne
md:grid-cols-2 // Tablette : 2 colonnes
lg:grid-cols-3 // Desktop : 3 colonnes
gap-4
">
{/* Cartes */}
</div>
Approche Mobile-First :
- Commencer par la mise en page mobile (classes par défaut)
- Ajouter les classes
md:pour la tablette - Ajouter les classes
lg:etxl:pour le desktop
7. Tester les Modifications
Étape A : Test Visuel
# Démarrer le serveur de développement
npm run dev
# Naviguer vers la page dans le navigateur
# Tester sur la vue mobile (DevTools)
# Tester le thème sombre
Étape B : Accessibilité
// Vérifier :
// - Les étiquettes ARIA appropriées
// - La navigation au clavier
// - Les états de focus
// - Le support des lecteurs d'écran
<button aria-label="Fermer le dialogue">×</button>
<input aria-describedby="email-help" />
<div role="alert" aria-live="polite">{error}</div>
Étape C : Performance
// Utiliser React.memo pour les composants coûteux
import { memo } from "react";
export const ExpensiveComponent = memo(function ExpensiveComponent({ data }) {
return <div>{/* Rendu */}</div>;
});
// Utiliser les importations dynamiques pour les composants lourds
import dynamic from "next/dynamic";
const HeavyChart = dynamic(() => import("@/components/HeavyChart"), {
loading: () => <Spinner />,
ssr: false
});
Tâches Courantes
Tâche 1 : Corriger un Filtre d'Espace de Travail Manquant
Exemple : Page d'aperçu du tableau de bord affichant tous les contacts
Étapes :
- Lire
src/app/dashboard/overview/page.tsx - Trouver toutes les requêtes Supabase
- Ajouter
.eq("workspace_id", workspaceId)à chacune - Ajouter une vérification nulle pour workspaceId avant la requête
- Tester avec plusieurs espaces de travail
Code :
// Avant
const { data: contacts } = await supabase.from("contacts").select("*");
// Après
if (!workspaceId) {
return <div>Aucun espace de travail sélectionné</div>;
}
const { data, error } = await supabase
.from("contacts")
.select("*")
.eq("workspace_id", workspaceId);
if (error) {
console.error("Erreur lors de la récupération des contacts :", error);
return <ErrorBanner />;
}
Tâche 2 : Créer une Nouvelle Page de Tableau de Bord
Exemple : Ajouter une page "Analytiques" au tableau de bord
Étapes :
- Créer
src/app/dashboard/analytics/page.tsx - Ajouter à la navigation dans
src/app/dashboard/layout.tsx - Implémenter le contenu de la page avec les composants shadcn/ui
- Ajouter les breadcrumbs
- Tester la navigation
Code :
// src/app/dashboard/analytics/page.tsx
import { Metadata } from "next";
import { Card } from "@/components/ui/card";
export const metadata: Metadata = {
title: "Analytiques | 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">Analytiques</h1>
<p className="text-muted-foreground">Suivez les performances de vos campagnes</p>
</div>
<div className="grid grid-cols-1 md:grid-cols-3 gap-6">
<Card>
{/* Carte statistique 1 */}
</Card>
<Card>
{/* Carte statistique 2 */}
</Card>
<Card>
{/* Carte statistique 3 */}
</Card>
</div>
</div>
);
}
// src/app/dashboard/layout.tsx - Ajouter à la navigation
const navigation = [
{ name: "Tableau de Bord", href: "/dashboard/overview", icon: HomeIcon },
{ name: "Contacts", href: "/dashboard/contacts", icon: UsersIcon },
{ name: "Campagnes", href: "/dashboard/campaigns", icon: MailIcon },
{ name: "Analytiques", href: "/dashboard/analytics", icon: ChartIcon }, // NOUVEAU
];
Tâche 3 : Implémenter la Fonctionnalité d'un Bouton
Exemple : Bouton "Envoyer un Email" du panneau Hot Leads
Étapes :
- Lire
src/components/HotLeadsPanel.tsx - Trouver l'emplacement du bouton
- Implémenter le gestionnaire onClick
- Appeler le point de terminaison API approprié
- Afficher un toast de succès/erreur
Code :
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("Échec de l'envoi de l'email");
toast({
title: "Email envoyé",
description: "Votre email a été mis en file d'attente.",
});
} catch (error) {
toast({
variant: "destructive",
title: "Erreur",
description: error.message,
});
}
}
return (
<Button onClick={() => handleSendEmail(contact.id)}>
Envoyer un Email
</Button>
);
}
Directives de Style
Meilleures Pratiques Tailwind CSS
Utiliser les Classes Utilitaire :
// ✅ Bon
<div className="flex items-center justify-between p-4 bg-background border rounded-lg">
// ❌ Mauvais (CSS personnalisé)
<div style={{ display: "flex", padding: "16px" }}>
Utiliser les Variables CSS du Thème :
// Défini dans 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%;
}
}
// Utiliser dans les composants
<div className="bg-background text-foreground">
<div className="bg-card text-card-foreground">
<div className="bg-primary text-primary-foreground">
Design Responsive :
<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
">
Référence de la Bibliothèque de Composants
Composants shadcn/ui Disponibles
accordion- Panneaux de contenu repliablesalert-dialog- Boîtes de dialogue de confirmation modalesavatar- Images de profil utilisateurbadge- Badges d'étatbutton- Boutons interactifscard- Conteneurs de contenucheckbox- Cases à cocher de formulairedialog- Boîtes de dialogue modalesdropdown-menu- Menus déroulantsinput- Champs de textelabel- Étiquettes de formulairepopover- Contenu flottantprogress- Indicateurs de progressionradio-group- Boutons radioselect- Listes déroulantesswitch- Interrupteurs à basculetabs- Interfaces à ongletstoast- Notifications toasttooltip- Infobulles au survol
Installer de nouveaux composants :
npx shadcn@latest add [nom-du-composant]
Motifs de Gestion des Erreurs
Erreurs API
try {
const res = await fetch("/api/...");
const data = await res.json();
if (!res.ok) {
throw new Error(data.error || "Quelque chose s'est mal passé");
}
return data;
} catch (error) {
console.error("Erreur API :", error);
toast({
variant: "destructive",
title: "Erreur",
description: error.message,
});
return null;
}
Erreurs Supabase
const { data, error } = await supabase.from("contacts").select("*");
if (error) {
console.error("Erreur Supabase :", error);
return <ErrorBanner message="Échec du chargement des contacts" />;
}
if (!data || data.length === 0) {
return <EmptyState message="Aucun contact trouvé" />;
}
return <ContactsList contacts={data} />;
Contraintes de la Version 1
Ce que Nous Corrigeons pour V1 :
- ✅ Filtrage par espace de travail sur TOUTES les pages
- ✅ Fonctionnalité du bouton Hot Leads
- ✅ Navigation de la page de détail des contacts
- ✅ Cartes statistiques du tableau de bord
- ✅ États de chargement et d'erreur
- ✅ Corrections de design responsive
Ce que Nous NE CONSTRUISONS PAS pour V1 :
- ❌ Animations avancées
- ❌ Constructeur de thème personnalisé
- ❌ Interfaces glisser-déposer
- ❌ Interface de collaboration en temps réel
- ❌ Application mobile
Points Clés
- Toujours filtrer par espace de travail - L'isolation des données est critique
- Utiliser les composants shadcn/ui - Ne pas réinventer la roue
- Suivre les conventions Tailwind - Approche utilitaire d'abord
- Gérer les états de chargement/erreur - Ne jamais afficher d'écrans vides
- Tester le design responsive - Mobile, tablette, desktop