Geração de Histórias Storybook CSF3 para Next.js

Geração de Histórias Storybook CSF3 para Next.js (nextjs-storybook-story)

Workflow especializado para gerar e atualizar histórias Storybook co-localizadas ([ComponentName].stories.tsx) no Component Story Format 3 (CSF3).

[!TIP] Ativos Modulares:

• Implementações de referência: examples/
• Scripts de verificação: scripts/verify-storybook.ps1 (Windows) / scripts/verify-storybook.sh (Linux)

---

Regras e Padrões Arquiteturais

1. Apenas Componente Principal (Exclusão de Micro Leaf Client)

• A lógica interativa do cliente é delegada a pequenos componentes folha (Client Components), como botões de alternância e listeners de clique.
• NÃO crie histórias para componentes auxiliares micro leaf internos.
• APENAS o componente principal (seção de recurso principal ou bloco de UI composto) requer uma história Storybook.

2. Estrutura CSF3 e Controles Interativos

• Use o Component Story Format 3 (CSF3) com Meta<typeof ComponentName> e StoryObj<typeof ComponentName>.
• Inclua as tags: tags: ["autodocs", "ai-generated"].
• Mapeie as props TypeScript para controles interativos (text, select, boolean, number) em meta.argTypes.
• Forneça valores padrão realistas para as props em args.

3. Espiões de Ação (fn() de 'storybook/test')

• Para todas as props de callback e mutação (ex.: onClick, onToggle, onSubmit), associe fn() de 'storybook/test' nos args padrão para que as interações do usuário sejam registradas de forma limpa no painel Actions do Storybook.

4. Documentação Estruturada (parameters.docs)

• Escreva markdown abrangente em meta.parameters.docs.description.component:
  • Visão Geral e Propósito: O que o componente é e por que existe.
  • Arquitetura e Limites: RSC vs. Client Component ("use client"), hooks, cache.
  • Interações Principais: Manipuladores de clique, alternâncias de estado e animações.
  • Acessibilidade e Movimento: Funções/labels ARIA e prefers-reduced-motion.
• Anote histórias individuais com parameters.docs.description.story.

5. Quatro Variantes Canônicas de História e Tokens de Produção (OBRIGATÓRIO)

• Zero Cores Hardcoded: Em NENHUMA circunstância use valores hexadecimais arbitrários (#FAFAFA, #050505) ou cores de paleta não tokenizadas (border-zinc-200, text-zinc-500).
• Tokens de Produção Semânticos: Use exclusivamente tokens de tema semântico de app/globals.css (bg-background, text-foreground, border-border, text-muted-foreground).
• Exporte estritamente quatro variantes de história encapsuladas em cartões de contêiner semântico com classes .light e .dark de escopo:
  1. Light: Configurada com { themes: { themeOverride: "light" }, backgrounds: { default: "light" } } em um cartão .light bg-background text-foreground border-border rotulado como "Light Mode".
  2. Dark: Configurada com { themes: { themeOverride: "dark" }, backgrounds: { default: "dark" } } em um cartão .dark bg-background text-foreground border-border rotulado como "Dark Mode".
  3. SkeletonLight: render: () => <[ComponentName]Skeleton /> em um cartão .light bg-background text-foreground border-border rotulado como "Skeleton (Light)".
  4. SkeletonDark: render: () => <[ComponentName]Skeleton /> em um cartão .dark bg-background text-foreground border-border rotulado como "Skeleton (Dark)".

---

Etapas do Workflow

• Passo 1: Inspecionar o Contrato e as Props do Componente

  • Leia [ComponentName].tsx e resolva todas as props exportadas, manipuladores de callback e estados visuais.

• Passo 2: Gerar História Co-Localizada ([ComponentName].stories.tsx)

  • Coloque [ComponentName].stories.tsx diretamente ao lado de [ComponentName].tsx.
  • Implemente metadados CSF3, argTypes, espiões de ação fn(), documentação markdown e as 4 variantes canônicas de história.

• Passo 3: Execução de Verificação e Teste Smoke

  • Execute o script de verificação para verificar a presença da história e executar o teste smoke do Storybook:
    • 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>
      

  • Corrija quaisquer colisões de sintaxe ou erros de exportação ausentes.