nextjs-storybook-story

Génération d'histoires Storybook CSF3 pour Next.js (nextjs-storybook-story)

Workflow spécialisé pour générer et mettre à jour des histoires Storybook co-localisées ([NomComposant].stories.tsx) au format CSF3 (Component Story Format 3).

[!TIP] Actifs modulaires :

• Implémentations de référence d'histoires : examples/
• Scripts de vérification : scripts/verify-storybook.ps1 (Windows) / scripts/verify-storybook.sh (Linux)

---

Règles & Standards Architecturaux

1. Composant Principal Uniquement (Exclusion des Micro-Feuilles Client)

• La logique client interactive est repoussée vers de petits composants feuilles Client (ex. boutons, écouteurs de clic).
• NE PAS créer d'histoires pour les micro-feuilles client internes.
• Seul le composant principal (section fonctionnelle primaire ou bloc UI composite) nécessite une histoire Storybook.

2. Structure CSF3 & Contrôles Interactifs

• Utiliser le format CSF3 avec Meta<typeof NomComposant> et StoryObj<typeof NomComposant>.
• Inclure les tags : tags: ["autodocs", "ai-generated"].
• Mapper les props TypeScript en contrôles interactifs (text, select, boolean, number) dans meta.argTypes.
• Fournir des valeurs par défaut réalistes dans args.

3. Espions d'actions (fn() depuis 'storybook/test')

• Pour toutes les props de callback et de mutation (ex. onClick, onToggle, onSubmit), lier fn() depuis 'storybook/test' dans args par défaut afin que les interactions utilisateur s'affichent proprement dans le panneau Actions de Storybook.

4. Documentation Structurée (parameters.docs)

• Rédiger un markdown complet dans meta.parameters.docs.description.component :
  • Vue d'ensemble & objectif : Ce que fait le composant et pourquoi il existe.
  • Architecture & limites : RSC vs composant feuille Client ("use client"), hooks, mise en cache.
  • Interactions clés : Gestionnaires de clic, bascules d'état, animations.
  • Accessibilité & mouvement : Rôles/labels ARIA et prefers-reduced-motion.
• Annoter les histoires individuelles avec parameters.docs.description.story.

5. Quatre Variantes d'Histoire Canoniques & Jetons de Production (OBLIGATOIRE)

• Aucune couleur codée en dur : En aucun cas utiliser des valeurs hexadécimales arbitraires (#FAFAFA, #050505) ou des couleurs de palette non tokenisées (border-zinc-200, text-zinc-500).
• Jetons de production sémantiques : Utiliser exclusivement les jetons de thème sémantiques de app/globals.css (bg-background, text-foreground, border-border, text-muted-foreground).
• Exporter strictement quatre variantes d'histoire encapsulées dans des cartes conteneur sémantiques avec les classes .light et .dark :
  1. Light : Configurée avec { themes: { themeOverride: "light" }, backgrounds: { default: "light" } } dans une carte .light bg-background text-foreground border-border intitulée "Mode Clair".
  2. Dark : Configurée avec { themes: { themeOverride: "dark" }, backgrounds: { default: "dark" } } dans une carte .dark bg-background text-foreground border-border intitulée "Mode Sombre".
  3. SkeletonLight : render: () => <[NomComposant]Skeleton /> dans une carte .light bg-background text-foreground border-border intitulée "Squelette (Clair)".
  4. SkeletonDark : render: () => <[NomComposant]Skeleton /> dans une carte .dark bg-background text-foreground border-border intitulée "Squelette (Sombre)".

---

Étapes du Workflow

• Étape 1 : Inspecter le contrat du composant et ses props

  • Lire [NomComposant].tsx et résoudre toutes les props exportées, les gestionnaires de callback et les états visuels.

• Étape 2 : Générer l'histoire co-localisée ([NomComposant].stories.tsx)

  • Placer [NomComposant].stories.tsx directement à côté de [NomComposant].tsx.
  • Implémenter les métadonnées CSF3, argTypes, les espions fn(), la documentation markdown et les 4 variantes canoniques.

• Étape 3 : Vérification et exécution du test de non-régression

  • Exécuter le script de vérification pour contrôler la présence de l'histoire et lancer le test de non-régression Storybook :
    • Windows (PowerShell) :

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

    • Linux / macOS (Bash) :

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

  • Corriger toute collision de syntaxe ou erreur d'export manquant.