dee0917/commercecraft-agent-skill

Vollautomatischer, hochwertiger, reiner Frontend-E-Commerce-Shop-Baukasten (Auto E-Commerce Frontend Engine)

Kernkonzept: Extreme visuelle Ästhetik, solide Engineering-Architektur, 100% Frontend-In-Experience, null externe Abhängigkeiten.

Diese Skill integriert ausgereifte DTC-E-Commerce-Modelle mit modernen Frontend-Engineering-Praktiken und konzentriert sich auf die Bereitstellung einer kommerziellen, platzhalterfreien (Zero Placeholders) und mit echtem Warenkorb- und Checkout-Zustandsautomaten ausgestatteten, modernen, reinen Frontend-E-Commerce-Erfahrung.

Ausführungssprachspezifikationen:

• Markenname, Produkttitel, Spezifikationsparameter, UI-Text → Nur Englisch (English Only), um internationale Markenqualität zu präsentieren.
• Entwicklungstagebuch, Fortschrittsberichte, technische Erläuterungen und Benutzerinteraktion → Traditionelles Chinesisch (Traditional Chinese).
• Variablen, Funktionen, Schnittstellendefinitionen im Code → Englisch in camelCase / PascalCase, Pinyin-Namensgebung ist absolut verboten.

---

🤖 Fünf virtuelle Rollen und Skill-Matrix (Agent Team Architecture)

Während der Website-Erstellung schlüpft der KI-Agent in 5 spezialisierte Rollen, die sequenziell agieren und sich gegenseitig überprüfen:

Rolle (Role)	Kernverantwortung	Kern-Skill-Tags (Skills)
1. Project Orchestrator	Markenpositionierung, Kategorieauswahl, Ausführungsplanung und phasenübergreifende Koordination	prd, brainstorming, executing-plans, writing-plans
2. Chief Creative Director	Marken-Vibe-Definition, Farbkontraste, Schriftsystem und hochwertiges Layout	ui-ux-pro-max, brand-guidelines, canvas-design, frontend-design
3. Lead Full-Stack Architect	Strikte TypeScript-Schnittstellen, Zustand-Zustandsmaschine, RWD-Komponenten und Routing-Implementierung	web-artifacts-builder, frontend-design, react-best-practices, tailwindcss
4. Content Strategist	Professionelle Produktbeschreibungen, Story-Texte, SEO-Keywords und Kundenbewertungsdesign	content-research-writer, internal-comms, brand-guidelines, doc-coauthoring
5. QA & Compliance	Zero-Placeholder-Audit, Console-Fehlerbehebung, Build-Abnahme und 7-stufige Qualitätskontrolle	verification-before-completion, webapp-testing, systematic-debugging, audit

---

🚀 Vollständiger Lebenszyklus-Ausführungsprozess (Lifecycle Phases)

Benutzer initiiert: "Erstelle mir eine E-Commerce-Website für die Kategorie [Kategorie/Stil]"

┌─ Phase 0: Null-Toleranz-Regeln und psychologische Regeln laden (P0)
│  ├─ 📖 Lese references/anti-patterns.md (18 Null-Toleranz-Regeln)
│  └─ 📖 Lese references/ux-psychology-ecommerce.md (CRO-Psychologie-Prinzipien)
│
├─ Phase 1: Kreative Saat und Designsystem-Generierung (Creative & System Generation)
│  ├─ 🎲 Bestimme Markenthema (z.B. Minimal Desk Aesthetics, Luxe Aromatherapy, Tech Gear)
│  ├─ 🎨 Führe Creative Director aus: Lege Farbpalette (60-30-10-Regel) und Schriftarten (Display / Body) fest
│  ├─ ✍️ Führe Content Strategist aus: Generiere Marken-Kernslogan und 8~12 hochrealistische Produktspezifikationsdaten
│  └─ 📝 Gib PRD-Zusammenfassung und Designentscheidungen in docs/DESIGN_DECISIONS.md aus
│
├─ Phase 2: Reines Frontend-Engineering-Setup (Vite + React + TS + Tailwind)
│  ├─ 🏗️ Initialisiere Projektgerüst (Vite React-TS)
│  ├─ 📦 Installiere Kernabhängigkeiten: zustand, react-router-dom, lucide-react, clsx, tailwind-merge, framer-motion, canvas-confetti
│  ├─ 📐 Importiere templates/ecommerce-types.ts zur Sicherstellung starker Typisierung
│  └─ 🛒 Implementiere Zustandsebene (src/store/useCartStore.ts) mit LocalStorage-Persistenz
│
├─ Phase 3: 11-seitige vollständige E-Commerce-Routenimplementierung (100% Complete Routes)
│  ├─ 🏠 Layer A (Kern-Einkaufszyklus): Home, Shop, ProductDetail, CartDrawer, Checkout, OrderSuccess
│  ├─ 👤 Layer B (Benutzervertrauenszentrum): Profile, OrderHistory
│  └─ 📜 Layer C (Compliance- und Vertrauensseiten): FAQ, ShippingPolicy, ReturnsRefunds, About
│
├─ Phase 4: CRO-Psychologie-Verstärkung und visuelle Aufwertung
│  ├─ ⏳ Injiziere Knappheitsetiketten (Scarcity: "Only 3 units left!")
│  ├─ 🚚 Implementiere Versandkostenfrei-Schwellenfortschrittsbalken ("Add $X more to unlock Free Shipping")
│  ├─ ⭐ Bette echte Kunden-Sternebewertungen und Einkaufsdynamiken ein (Social Proof)
│  ├─ 🏷️ Injiziere Schema.org (Product, Offer) JSON-LD strukturierte Daten
│  └─ 🖼️ Konfiguriere hochauflösende Unsplash-Commerce-Fotografien (verschwommene Platzhalter verboten)
│
└─ Phase 5: Qualitätsabnahme und One-Click-Lieferung (Quality & Delivery Gate)
   ├─ 🔨 Führe npm run build aus (Stelle 0 TypeScript-Fehler, 0 Build-Warnungen sicher)
   ├─ 🔍 Führe 7-stufige Qualitätsprüfung durch (Zero Mock, Zero Broken Links)
   └─ 🚀 Liefere Frontend-Vorschau und One-Click-Deployment-Anleitung für Vercel

---

📋 11-seitige vollständige Routenspezifikation (Page Requirements)

Jede generierte Website MUSS die folgenden 11 vollständigen Routen enthalten. Leere Seiten oder 404-Fehler sind absolut nicht erlaubt:

1. Startseite (/) :

   • Hero-Visual-Banner (High-Impact-Bild, starker Call-to-Action CTA "Shop The Collection").
   • Autoritätsvertrauenssiegel (Free Shipping, 30-Day Guarantee, 256-Bit SSL, Ethical Craft).
   • Ausgewählte empfohlene Produkt-Wasserfallansicht (Featured Products Grid).
   • Kategorie-Schnelleinstiege (Shop by Categories).
   • Markengeschichtsbereich (Brand Ethos).
   • Echte Kundenstimmen (Social Proof Testimonials).
   • Newsletter-Anmeldebereich (Newsletter Signup with discount incentive).

2. Produktkatalog (/shop) :

   • Mehrdimensionale Filter: Kategoriefilter, Preisspannen-Schieberegler, Tag-Filter.
   • Echtzeit-Sortierfunktion: Beliebtheit, Preis aufsteigend, Preis absteigend, neueste.
   • Echtzeit-Keyword-Suchfeld (Instant Client Search).
   • Leersuche-abwehrzustand (Empty State with reset filters button).

3. Produktdetailseite (/product/:id) :

   • Mehrwinkel-Vorschaubild-Umschaltung (Image Gallery).
   • Spezifikationsauswähler: Größe (Size), Farbe (Color), Variante (Variant).
   • Lagerknappheits-Hinweis (z.B. bernsteinfarbene Warnung bei Lagerbestand < 5).
   • Mengen-Einsteller (Plus/Minus).
   • Duale Buttons: „Add to Cart" (gleitet in Warenkorb-Drawer) und „Buy Now" (direkt zur Kasse).
   • Tab-Aufteilung: Detaillierte Spezifikationen (Specifications), Versand & Rückgabe (Shipping), Echte Kundenbewertungen (Reviews).
   • Verwandte Produktempfehlungen (Recommended Products).
   • Schema.org JSON-LD Injektion.

4. Seitlicher Warenkorb-Drawer (CartDrawer) :

   • Sanftes Hereinrutschen beim Klicken auf das Header-Warenkorbsymbol oder „Add to Cart" (Framer Motion / Transition).
   • Echtzeit-Berechnung des verbleibenden Betrags für versandkostenfreie Lieferung als Fortschrittsbalken (z.B. kostenloser Versand ab $100).
   • Produktliste: Miniaturansicht, Produktname, ausgewählte Spezifikation, Mengenänderung, Echtzeit-Löschung.
   • Rabattcode (Promo Code) Einlösefeld (integrierter Code wie WELCOME10 für 10% sofortigen Rabatt).
   • Preiszusammenfassung: Zwischensumme (Subtotal), Rabatt (Discount), geschätzte Versandkosten (Shipping), Gesamtbetrag (Total).
   • Button zur Kasse (Proceed to Checkout).

5. Checkout-Center (/checkout) :

   • 3-schrittige Checkout-UI:
     1. Kontakt- und Versandinformationen (Shipping Details): Name, E-Mail, Lieferadresse, Telefon.
     2. Versandart wählen (Shipping Method): Standard ($0 ~ $5), Express ($15).
     3. Zahlungsmethode simulieren (Payment Method): Simulierte Kreditkarteneingabe (mit automatischer Formatierung, Sicherheitssymbolen), Apple Pay / PayPal Express-Checkout-Optionen.
   • Rechte/untere Seite: Echtzeit-Bestellzusammenfassungskarte (Order Summary Sticky Card).
   • Schutz vor Doppelklicks, sofortige Formularfeldvalidierung.

6. Bestellabschlussseite (/order-success) :

   • Grüner Erfolgshaken-Animation und Konfetti-Effekt (canvas-confetti).
   • Zufällig generierte eindeutige Bestellnummer (z.B. #ORD-2026-89412).
   • Vollständige Bestellzusammenfassung, Empfängerdaten und voraussichtliches Lieferdatum.
   • „Continue Shopping" Zurück-Button.

7. Bestellverfolgung und -historie (/orders) :

   • Eingabe von Bestellnummer oder E-Mail zur Abfrage eines simulierten Bestellfortschrittsbalkens (Confirmed → Processing → Shipped → Delivered).

8. Mitgliederkonto und Favoriten (/profile) :

   • Simulierte Benutzerprofile, Wunschliste (Wishlist) Schnellansicht.

9. Häufig gestellte Fragen (/faq) :

   • Aufklappbares Akkordeon-Komponente (Accordion) mit häufig gestellten Fragen zu Bestellung, Versand, Rückgabe, Materialpflege usw.

10. Versandrichtlinie (/shipping) :

    • Enthält Inlands- und Auslandsversandkostentabelle, Lieferzeiten nach Land, Zollinformationen.

11. Rückgabe- und Umtauschrichtlinie sowie Markengeschichte (/returns & /about) :

    • Klare Darstellung der 30-tägigen Rückgabegarantie, 3-Schritte-Rückgabeprozess und Gründungsvision der Marke.

---

🧠 Pflichtimplementierungsleitfaden für E-Commerce-Psychologie und Konversionsrate (CRO)

Jede generierte Website MUSS die folgenden psychologischen Mechanismen integrieren (detaillierte Definitionen siehe references/ux-psychology-ecommerce.md):

1. Hick's Gesetz (Hick's Law) :

   • Checkout-Formular ist standardmäßig schlank gehalten, unnötige optionale Felder werden vermieden.
   • Hauptnavigation nicht mehr als 5 Elemente der ersten Ebene.

2. Ankereffekt (Anchoring Effect) :

   • Sonderangebotsprodukte zeigen parallel den durchgestrichenen Originalpreis (z.B. ~~$120.00~~ $89.00) und ein Ersparnis-Label Save $31.

3. Knappheit und Dringlichkeit (Scarcity & Urgency) :

   • Auf der Detailseite dynamisch und zufällig anzeigen: "Only 2 items left at this price".
   • Auf der Checkout-Seite anzeigen: "Reserved for your cart for 10:00 minutes" (optionaler Timer).

4. Sozialer Beweis (Social Proof) :

   • Auf der Startseite und Detailseite echtes „Verified Buyer"-Abzeichen markieren.
   • In der Produktlistenkarte die durchschnittliche Bewertung anzeigen (z.B. ★ 4.9 (128 reviews)).

5. Verlustaversion (Loss Aversion) :

   • Dynamischer Hinweis im Warenkorb-Fortschrittsbalken: „Nur noch $12 bis zum kostenlosen Versand im gesamten Store!"

---

🛠️ State-Management-Architektur-Spezifikation (Zustand + LocalStorage)

Verwende einen entkoppelten und entprellten Zustand-Store, um sicherzustellen, dass Warenkorbdaten nach einem Seitenrefresh nicht verloren gehen:

// src/store/useCartStore.ts Vorlage
import { create } from 'zustand';
import { persist } from 'zustand/middleware';
import { CartItem, Product } from '../types';

interface CartState {
  items: CartItem[];
  isOpen: boolean;
  promoCode: string | null;
  discountRate: number;
  openCart: () => void;
  closeCart: () => void;
  addItem: (product: Product, quantity?: number, selectedVariant?: string) => void;
  removeItem: (itemId: string) => void;
  updateQuantity: (itemId: string, quantity: number) => void;
  applyPromoCode: (code: string) => { success: boolean; message: string };
  clearCart: () => void;
  getSubtotal: () => number;
  getTotal: () => number;
}

---

🛡️ Qualitätssicherungsschranken der Lieferung (7-stufige Abnahmekriterien)

Vor der Übergabe der Ergebnisse an den Benutzer MUSS die QA-Rolle jeden Punkt überprüfen und bestehen:

1. 0 kaputte Bilder (Zero Broken Images) : Alle Bild-URLs müssen normal ladbar und in der Größe angepasst sein, mit loading="lazy" und alt-Attributen.
2. 0 tote Links (Zero Broken Links) : Alle Navigationen, Footer-Links und Buttons der gesamten Website müssen klickbar sein und zu den entsprechenden 11 Routen führen.
3. 0 Platzhalter (Zero Placeholders) : Das Erscheinen von Lorem Ipsum, Product 1, $0.00 oder anderen nachlässigen Texten ist verboten. Alle Texte müssen zum Marken-Ton passen.
4. Geschlossener Warenkorbkreislauf (Cart Loop Completed) : Zum Warenkorb hinzufügen → Drawer erscheint → Mengenänderung mit Preisaktualisierung → Gutschein einlösen → Checkout absenden → Weiterleitung zu Order Success mit Bestellnummer.
5. RWD (Responsives Webdesign) garantiert : Kein horizontaler Überlauf oder Layout-Brüche auf Handy (375px), Tablet (768px) und Desktop (1280px+).
6. SEO strukturiert : Produktdetailseiten geben korrektes application/ld+json (Schema.org Product) aus.
7. Produktions-Build-Validierung (Production Build) : Die Ausführung von npm run build muss fehlerfrei sein und ein dist/-Verzeichnis erzeugen.