BIGboss248/nextjs-wordpress

Generación de Historias Storybook CSF3 para Next.js (nextjs-storybook-story)

Flujo de trabajo especializado para generar y actualizar historias de Storybook co-ubicadas ([NombreComponente].stories.tsx) en Formato de Historia de Componente 3 (CSF3).

[!TIP] Activos Modulares:

• Implementaciones de historia de referencia: examples/
• Scripts de verificación: scripts/verify-storybook.ps1 (Windows) / scripts/verify-storybook.sh (Linux)

---

Reglas y Estándares Arquitectónicos

1. Solo Ámbito del Componente Principal (Exclusión de Micro Clientes Hoja)

• La lógica interactiva del cliente se empuja hacia abajo a pequeños componentes Cliente hoja (ej. botones de alternancia, listeners de clic).
• NO cree historias para ayudantes de micro cliente hoja internos.
• SOLO el componente principal (sección de característica principal o bloque de UI compuesto) requiere una historia de Storybook.

2. Estructura CSF3 y Controles Interactivos

• Use el Formato de Historia de Componente 3 (CSF3) con Meta<typeof NombreComponente> y StoryObj<typeof NombreComponente>.
• Incluya etiquetas: tags: ["autodocs", "ai-generated"].
• Mapee las props de TypeScript a controles interactivos (text, select, boolean, number) en meta.argTypes.
• Proporcione valores de props predeterminados realistas en args.

3. Espías de Acción (fn() de 'storybook/test')

• Para todas las props de callback y mutación (ej. onClick, onToggle, onSubmit), vincule fn() de 'storybook/test' en args por defecto para que las interacciones del usuario se registren limpiamente en el panel de Acciones de Storybook.

4. Documentación Estructurada (parameters.docs)

• Escriba documentación completa en markdown en meta.parameters.docs.description.component:
  • Resumen y Propósito: Qué es el componente y por qué existe.
  • Arquitectura y Límites: RSC vs componente Cliente hoja ("use client"), hooks, caching.
  • Interacciones Clave: Manejadores de clic, alternancias de estado y animaciones.
  • Accesibilidad y Movimiento: Roles/etiquetas ARIA y prefers-reduced-motion.
• Anote historias individuales con parameters.docs.description.story.

5. Cuatro Variantes de Historia Canónicas y Tokens de Producción (OBLIGATORIO)

• Cero Colores Hardcodeados: Bajo NINGUNA circunstancia use valores hex arbitrarios (#FAFAFA, #050505) o colores de paleta no token (border-zinc-200, text-zinc-500).
• Tokens de Producción Semánticos: Use exclusivamente tokens de tema semánticos de app/globals.css (bg-background, text-foreground, border-border, text-muted-foreground).
• Exporte estrictamente cuatro variantes de historia envueltas en tarjetas contenedoras semánticas con clases .light y .dark delimitadas:
  1. Light: Configurado con { themes: { themeOverride: "light" }, backgrounds: { default: "light" } } en una tarjeta .light bg-background text-foreground border-border etiquetada "Light Mode".
  2. Dark: Configurado con { themes: { themeOverride: "dark" }, backgrounds: { default: "dark" } } en una tarjeta .dark bg-background text-foreground border-border etiquetada "Dark Mode".
  3. SkeletonLight: render: () => <[NombreComponente]Skeleton /> en una tarjeta .light bg-background text-foreground border-border etiquetada "Skeleton (Light)".
  4. SkeletonDark: render: () => <[NombreComponente]Skeleton /> en una tarjeta .dark bg-background text-foreground border-border etiquetada "Skeleton (Dark)".

---

Pasos del Flujo de Trabajo

• Paso 1: Inspeccionar el Contrato y Props del Componente

  • Lea [NombreComponente].tsx y resuelva todas las props exportadas, manejadores de callback y estados visuales.

• Paso 2: Generar Historia Co-Ubicada ([NombreComponente].stories.tsx)

  • Coloque [NombreComponente].stories.tsx directamente junto a [NombreComponente].tsx.
  • Implemente metadatos CSF3, argTypes, espías de acción fn(), documentación markdown y las 4 variantes de historia canónicas.

• Paso 3: Verificación y Ejecución de Prueba de Humo

  • Ejecute el script de verificación para comprobar la presencia de la historia y realizar una prueba de humo de Storybook:
    • Windows (PowerShell):

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

    • Linux / macOS (Bash):

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

  • Corrija cualquier error de sintaxis o de exportación faltante.