Frontend-Agenten-Skill
⚠️ VOR-GENERIERUNGS-CHECKLISTE (PFLICHT)
Bevor SIE EIN UI-ELEMENT ERSTELLEN, füllen Sie diese Checkliste aus:
VOR_GENERIERUNGS_CHECKLISTE:
1. DESIGN_SYSTEM_LESEN:
- [ ] /DESIGN-SYSTEM.md auf verbotene Muster prüfen
- [ ] /src/app/globals.css @theme-Block auf Tokens prüfen
- [ ] Hinweis: accent-500 = #ff6b35 (orange)
2. VORHANDENE_KOMPONENTEN_PRÜFEN:
- [ ] Zuerst in /src/components/ui/ nachsehen (48 Komponenten)
- [ ] components.json auf shadcn-Konfiguration prüfen
- [ ] Vorhandene Muster in der Landingpage überprüfen
3. UI_BIBLIOTHEKEN_REFERENZIEREN:
- [ ] Siehe /docs/UI-LIBRARY-INDEX.md für Premium-Komponenten
- [ ] Priorität: Projekt → StyleUI/KokonutUI/Cult UI → shadcn-Basis
- [ ] NIE shadcn-Standardeinstellungen ohne Anpassung verwenden
4. KEINE_VERBOTENEN_MUSTER_SICHERSTELLEN:
- [ ] Kein bg-white, text-gray-600 oder generische Hover-Zustände
- [ ] Keine uniformen grid-cols-3 gap-4 Layouts
- [ ] Kein ungestyltes <Card className="p-6">
- [ ] Keine Icons ohne Markenfarben
VERBOTENE CODE-MUSTER:
// ❌ NIE DIESE GENERIEREN
className="bg-white rounded-lg shadow p-4" // Generische Karte
className="grid grid-cols-3 gap-4" // Uniformes Grid
className="text-gray-600" // Standard gedämpft
className="hover:bg-gray-100" // Generischer Hover
<Card className="p-6"> // Ungestyltes shadcn
ERFORDERLICHE MUSTER:
// ✅ IMMER DESIGN-TOKENS VERWENDEN
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"
Übersicht
Der Frontend-Agent ist verantwortlich für alle UI/UX-Arbeiten in der Unite-Hub Next.js-Anwendung:
- React 19 / Next.js 16 Entwicklung mit App Router
- shadcn/ui-Komponenten-Implementierung und -Anpassung
- Tailwind CSS Styling und responsives Design
- Routenerstellung und Breadcrumb-Setup
- Clientseitiges Zustandsmanagement (React Context, Hooks)
- Barrierefreiheit und Leistungsoptimierung
Wie man diesen Agenten verwendet
Auslöser
Benutzer sagt: "Dashboard-Layout reparieren", "Neue Kontaktseite hinzufügen", "Navigation aktualisieren", "Modal-Komponente erstellen"
Was der Agent tut
1. Anfrage verstehen
Zu stellende Fragen:
- Welche Seite/Komponente benötigt Arbeit?
- Was ist das gewünschte Verhalten?
- Gibt es Design-Referenzen (Screenshots, Wireframes)?
- Was ist die Priorität (P0/P1/P2)?
2. Aktuelle Implementierung analysieren
Schritt A: Dateien lokalisieren
# Die Komponente oder Seite finden
find src/app -name "*.tsx" | grep -i "contacts"
find src/components -name "*.tsx" | grep -i "hotleads"
Schritt B: Aktuellen Code lesen
// text_editor-Werkzeug verwenden
text_editor.view("src/app/dashboard/contacts/page.tsx")
Schritt C: Abhängigkeiten identifizieren
- Welche shadcn/ui-Komponenten werden verwendet?
- Welche Kontexte werden konsumiert (AuthContext usw.)?
- Welche API-Routen werden aufgerufen?
- Welche Datenbankabfragen werden gemacht?
3. Änderungen implementieren
Schritt A: Komponentenaktualisierungen
Für vorhandene Komponenten:
// 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();
// Heiße Leads abrufen
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>
{/* UI-Implementierung */}
</Card>
);
}
Schritt B: Routenerstellung
Für neue Seiten:
// src/app/dashboard/new-page/page.tsx
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Neue Seite | Unite Hub",
description: "Beschreibung der neuen Seite"
};
export default async function NeueSeite() {
return (
<div className="container mx-auto py-8">
<h1 className="text-3xl font-bold">Neue Seite</h1>
{/* Inhalt */}
</div>
);
}
Schritt C: shadcn/ui-Komponenten
Neue Komponenten bei Bedarf installieren:
npx shadcn@latest add dialog
npx shadcn@latest add dropdown-menu
npx shadcn@latest add toast
Komponenten gemäß shadcn-Mustern verwenden:
import {
Dialog,
DialogContent,
DialogDescription,
DialogHeader,
DialogTitle,
DialogTrigger,
} from "@/components/ui/dialog";
<Dialog>
<DialogTrigger asChild>
<Button>Dialog öffnen</Button>
</DialogTrigger>
<DialogContent>
<DialogHeader>
<DialogTitle>Titel</DialogTitle>
<DialogDescription>Beschreibung</DialogDescription>
</DialogHeader>
{/* Inhalt */}
</DialogContent>
</Dialog>
4. Workspace-Filterung hinzufügen (KRITISCH für V1)
ALLE Datenbankabfragen MÜSSEN nach Workspace filtern:
// ❌ SCHLECHT - Zeigt Daten aus allen Workspaces
const { data: contacts } = await supabase
.from("contacts")
.select("*");
// ✅ GUT - Zeigt nur Daten aus dem Workspace des Benutzers
const { data: contacts } = await supabase
.from("contacts")
.select("*")
.eq("workspace_id", workspaceId);
Erforderlich für diese Tabellen:
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. Lade- und Fehlerzustände behandeln
Ladezustand:
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. Responsives Design
Tailwind Breakpoints:
<div className="
grid grid-cols-1 // Mobil: 1 Spalte
md:grid-cols-2 // Tablet: 2 Spalten
lg:grid-cols-3 // Desktop: 3 Spalten
gap-4
">
{/* Karten */}
</div>
Mobile-First-Ansatz:
- Mit mobilem Layout beginnen (Standardklassen)
md:-Klassen für Tablet hinzufügenlg:- undxl:-Klassen für Desktop
7. Änderungen testen
Schritt A: Visuelles Testen
# Entwicklungsserver starten
npm run dev
# Zur Seite im Browser navigieren
# Auf mobilem Viewport testen (DevTools)
# Dunkles Theme testen
Schritt B: Barrierefreiheit
// Prüfen auf:
// - Korrekte ARIA-Labels
// - Tastaturnavigation
// - Fokus-Zustände
// - Screenreader-Unterstützung
<button aria-label="Dialog schließen">×</button>
<input aria-describedby="email-help" />
<div role="alert" aria-live="polite">{error}</div>
Schritt C: Leistung
// React.memo für teure Komponenten verwenden
import { memo } from "react";
export const TeureKomponente = memo(function TeureKomponente({ data }) {
return <div>{/* Rendern */}</div>;
});
// Dynamische Imports für schwere Komponenten verwenden
import dynamic from "next/dynamic";
const SchweresDiagramm = dynamic(() => import("@/components/SchweresDiagramm"), {
loading: () => <Spinner />,
ssr: false
});
Häufige Aufgaben
Aufgabe 1: Fehlenden Workspace-Filter korrigieren
Beispiel: Dashboard-Übersichtsseite zeigt alle Kontakte an
Schritte:
src/app/dashboard/overview/page.tsxlesen- Alle Supabase-Abfragen finden
.eq("workspace_id", workspaceId)zu jeder hinzufügen- Null-Check für workspaceId vor der Abfrage hinzufügen
- Mit mehreren Workspaces testen
Code:
// Vorher
const { data: contacts } = await supabase.from("contacts").select("*");
// Nachher
if (!workspaceId) {
return <div>Kein Workspace ausgewählt</div>;
}
const { data: contacts, error } = await supabase
.from("contacts")
.select("*")
.eq("workspace_id", workspaceId);
if (error) {
console.error("Fehler beim Abrufen der Kontakte:", error);
return <ErrorBanner />;
}
Aufgabe 2: Neue Dashboard-Seite erstellen
Beispiel: "Analytics"-Seite zum Dashboard hinzufügen
Schritte:
src/app/dashboard/analytics/page.tsxerstellen- Zur Navigation in
src/app/dashboard/layout.tsxhinzufügen - Seiteninhalt mit shadcn/ui-Komponenten implementieren
- Breadcrumbs hinzufügen
- Navigation testen
Code:
// 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">Verfolgen Sie Ihre Kampagnenleistung</p>
</div>
<div className="grid grid-cols-1 md:grid-cols-3 gap-6">
<Card>
{/* Statistik-Karte 1 */}
</Card>
<Card>
{/* Statistik-Karte 2 */}
</Card>
<Card>
{/* Statistik-Karte 3 */}
</Card>
</div>
</div>
);
}
// src/app/dashboard/layout.tsx - Zur Navigation hinzufügen
const navigation = [
{ name: "Dashboard", href: "/dashboard/overview", icon: HomeIcon },
{ name: "Kontakte", href: "/dashboard/contacts", icon: UsersIcon },
{ name: "Kampagnen", href: "/dashboard/campaigns", icon: MailIcon },
{ name: "Analytics", href: "/dashboard/analytics", icon: ChartIcon }, // NEU
];
Aufgabe 3: Button-Funktionalität implementieren
Beispiel: "E-Mail senden"-Button im Hot Leads-Panel
Schritte:
src/components/HotLeadsPanel.tsxlesen- Button-Position finden
- onClick-Handler implementieren
- Passenden API-Endpunkt aufrufen
- Erfolgs-/Fehler-Toast anzeigen
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("Fehler beim Senden der E-Mail");
toast({
title: "E-Mail gesendet",
description: "Ihre E-Mail wurde zum Versand in die Warteschlange gestellt.",
});
} catch (error) {
toast({
variant: "destructive",
title: "Fehler",
description: error.message,
});
}
}
return (
<Button onClick={() => handleSendEmail(contact.id)}>
E-Mail senden
</Button>
);
}
Styling-Richtlinien
Tailwind CSS Best Practices
Utility-Klassen verwenden:
// ✅ Gut
<div className="flex items-center justify-between p-4 bg-background border rounded-lg">
// ❌ Schlecht (eigenes CSS)
<div style={{ display: "flex", padding: "16px" }}>
CSS-Variablen aus dem Theme verwenden:
// Definiert in 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%;
}
}
// In Komponenten verwenden
<div className="bg-background text-foreground">
<div className="bg-card text-card-foreground">
<div className="bg-primary text-primary-foreground">
Responsives Design:
<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
">
Komponentenbibliotheks-Referenz
Verfügbare shadcn/ui-Komponenten
accordion- Einklappbare Inhaltsbereichealert-dialog- Modale Bestätigungsdialogeavatar- Benutzerprofilbilderbadge- Statusabzeichenbutton- Interaktive Buttonscard- Inhaltscontainercheckbox- Formular-Kontrollkästchendialog- Modale Dialogedropdown-menu- Dropdown-Menüsinput- Texteingabenlabel- Formularbeschriftungenpopover- Schwebe-Inhalteprogress- Fortschrittsanzeigenradio-group- Optionsfelderselect- Auswahl-Dropdownsswitch- Kippschaltertabs- Registerkarten-Oberflächentoast- Benachrichtigungs-Toaststooltip- Hover-Tooltips
Neue Komponenten installieren:
npx shadcn@latest add [komponenten-name]
Fehlerbehandlungsmuster
API-Fehler
try {
const res = await fetch("/api/...");
const data = await res.json();
if (!res.ok) {
throw new Error(data.error || "Etwas ist schiefgelaufen");
}
return data;
} catch (error) {
console.error("API-Fehler:", error);
toast({
variant: "destructive",
title: "Fehler",
description: error.message,
});
return null;
}
Supabase-Fehler
const { data, error } = await supabase.from("contacts").select("*");
if (error) {
console.error("Supabase-Fehler:", error);
return <ErrorBanner message="Kontakte konnten nicht geladen werden" />;
}
if (!data || data.length === 0) {
return <EmptyState message="Keine Kontakte gefunden" />;
}
return <ContactsList contacts={data} />;
Einschränkungen von Version 1
Was wir für V1 reparieren:
- ✅ Workspace-Filterung auf ALLEN Seiten
- ✅ Hot-Leads-Button-Funktionalität
- ✅ Navigation zur Kontaktdetailseite
- ✅ Dashboard-Statistik-Karten
- ✅ Lade- und Fehlerzustände
- ✅ Reparaturen des responsiven Designs
Was wir für V1 NICHT bauen:
- ❌ Erweiterte Animationen
- ❌ Eigener Theme-Builder
- ❌ Drag-and-Drop-Oberflächen
- ❌ Echtzeit-Kollaborations-UI
- ❌ Mobile App
Wichtige Punkte
- Immer nach Workspace filtern - Datenisolation ist entscheidend
- shadcn/ui-Komponenten verwenden - Das Rad nicht neu erfinden
- Tailwind-Konventionen befolgen - Utility-First-Ansatz
- Lade-/Fehlerzustände behandeln - Niemals leere Bildschirme zeigen
- Responsives Design testen - Mobil, Tablet, Desktop