BIGboss248/nextjs-wordpress

Generierung von Next.js Storybook CSF3 Stories (nextjs-storybook-story)

Spezialisierter Workflow zum Erstellen und Aktualisieren von co-located Storybook Stories ([ComponentName].stories.tsx) im Component Story Format 3 (CSF3).

[!TIP] Modulare Assets:

• Referenzimplementierungen für Stories: examples/
• Verifikationsskripte: scripts/verify-storybook.ps1 (Windows) / scripts/verify-storybook.sh (Linux)

---

Architekturregeln & Standards

1. Nur Hauptkomponenten-Bereich (Keine Micro-Leaf-Client-Komponenten)

• Interaktive Client-Logik wird in kleine Blatt-Komponenten (Leaf Client Components) verlagert (z.B. Toggle-Buttons, Click-Listener).
• KEINE Stories für interne Micro-Leaf-Client-Helfer erstellen.
• NUR die Hauptkomponente (primärer Feature-Bereich oder zusammengesetzter UI-Block) benötigt eine Storybook Story.

2. CSF3-Struktur & interaktive Controls

• Component Story Format 3 (CSF3) mit Meta<typeof ComponentName> und StoryObj<typeof ComponentName> verwenden.
• Tags einfügen: tags: ["autodocs", "ai-generated"].
• TypeScript-Props auf interaktive Controls abbilden (text, select, boolean, number) in meta.argTypes.
• Realistische Standard-Prop-Werte in args bereitstellen.

3. Action Spies (fn() aus 'storybook/test')

• Für alle Callback- und Mutation-Props (z.B. onClick, onToggle, onSubmit) fn() aus 'storybook/test' in den Standard-args binden, sodass Benutzerinteraktionen sauber im Storybook Actions-Panel protokolliert werden.

4. Strukturierte Dokumentation (parameters.docs)

• Umfassendes Markdown in meta.parameters.docs.description.component:
  • Überblick & Zweck: Was die Komponente ist und warum sie existiert.
  • Architektur & Grenzen: RSC vs. Leaf-Client-Komponente ("use client"), Hooks, Caching.
  • Wichtige Interaktionen: Click-Handler, Zustandswechsel und Animationen.
  • Barrierefreiheit & Bewegung: ARIA-Rollen/Labels und prefers-reduced-motion.
• Einzelne Stories mit parameters.docs.description.story annotieren.

5. Vier kanonische Story-Varianten & Produktionstokens (PFLICHT)

• Keine hartcodierten Farben: Auf KEINEN Fall beliebige Hex-Werte (#FAFAFA, #050505) oder Nicht-Token-Palettenfarben (border-zinc-200, text-zinc-500) verwenden.
• Semantische Produktionstokens: Ausschließlich semantische Theme-Tokens aus app/globals.css verwenden (bg-background, text-foreground, border-border, text-muted-foreground).
• Exakt vier Story-Varianten in semantischen Container-Karten mit abgegrenzten .light- und .dark-Klassen exportieren:
  1. Light: Konfiguriert mit { themes: { themeOverride: "light" }, backgrounds: { default: "light" } } in einer .light bg-background text-foreground border-border Karte mit der Bezeichnung "Light Mode".
  2. Dark: Konfiguriert mit { themes: { themeOverride: "dark" }, backgrounds: { default: "dark" } } in einer .dark bg-background text-foreground border-border Karte mit der Bezeichnung "Dark Mode".
  3. SkeletonLight: render: () => <[ComponentName]Skeleton /> in einer .light bg-background text-foreground border-border Karte mit der Bezeichnung "Skeleton (Light)".
  4. SkeletonDark: render: () => <[ComponentName]Skeleton /> in einer .dark bg-background text-foreground border-border Karte mit der Bezeichnung "Skeleton (Dark)".

---

Workflow-Schritte

• Schritt 1: Komponentenvertrag & Props prüfen

  • [ComponentName].tsx lesen und alle exportierten Props, Callback-Handler und visuellen Zustände auflösen.

• Schritt 2: Co-located Story generieren ([ComponentName].stories.tsx)

  • [ComponentName].stories.tsx direkt neben [ComponentName].tsx ablegen.
  • CSF3-Metadaten, argTypes, fn()-Action-Spies, Markdown-Dokumentation und die 4 kanonischen Story-Varianten implementieren.

• Schritt 3: Verifikation & Smoke-Test-Ausführung

  • Verifikationsskript ausführen, um das Vorhandensein der Story zu prüfen und einen Storybook-Smoke-Test durchzuführen:
    • Windows (PowerShell):

      pwsh .agents/skills/nextjs-storybook-story/scripts/verify-storybook.ps1 -ComponentPath <target_component_dir>
      

    • Linux / macOS (Bash):

      bash .agents/skills/nextjs-storybook-story/scripts/verify-storybook.sh <target_component_dir>
      

  • Syntaxkonflikte oder fehlende Exportfehler beheben.