Next.js Storybook CSF3 故事生成 (nextjs-storybook-story)
用于生成和更新 co-located Storybook 故事文件 ([ComponentName].stories.tsx) 的专用工作流，遵循 Component Story Format 3 (CSF3) 规范。
[!TIP] 模块化资源:
- 参考故事实现：
examples/- 验证脚本：
scripts/verify-storybook.ps1(Windows) /scripts/verify-storybook.sh(Linux)
架构规则与标准
1. 仅限主组件范围（排除微叶子客户端）
- 交互式客户端逻辑应下放到小型叶子客户端组件（例如切换按钮、点击监听器）。
- 不要为内部微叶子客户端辅助函数创建故事。
- 仅主组件（主要功能区块或复合 UI 块）需要 Storybook 故事。
2. CSF3 结构与交互式控件
- 使用 Component Story Format 3 (CSF3)，包含
Meta<typeof ComponentName>和StoryObj<typeof ComponentName>。 - 包含标签：
tags: ["autodocs", "ai-generated"]。 - 在
meta.argTypes中将 TypeScript 属性映射为交互式控件（text、select、boolean、number）。 - 在
args中提供逼真的默认属性值。
3. 操作间谍 (fn() 来自 'storybook/test')
- 对于所有回调属性和变更属性（例如
onClick、onToggle、onSubmit），在默认args中绑定来自'storybook/test'的fn()，以便用户交互清晰地记录到 Storybook Actions 面板中。
4. 结构化文档 (parameters.docs)
- 在
meta.parameters.docs.description.component中编写全面的 markdown 文档：- 概述与目的： 组件是什么以及它为何存在。
- 架构与边界： RSC 与叶子客户端组件 (
"use client")、hooks、缓存。 - 关键交互： 点击处理器、状态切换和动画。
- 无障碍与动效： ARIA 角色/标签和
prefers-reduced-motion。
- 使用
parameters.docs.description.story为单个故事添加注释。
5. 四种规范故事变体与生产 Token（强制）
- 零硬编码颜色： 在任何情况下都不得使用任意十六进制值（
#FAFAFA、#050505）或非 Token 调色板颜色（border-zinc-200、text-zinc-500）。 - 语义化生产 Token： 只能使用来自
app/globals.css的语义化主题 Token（bg-background、text-foreground、border-border、text-muted-foreground）。 - 严格导出四个故事变体，并包裹在具有作用域
.light和.dark类的语义化容器卡片中：Light：在标记为"Light Mode"的.light bg-background text-foreground border-border卡片中，配置为{ themes: { themeOverride: "light" }, backgrounds: { default: "light" } }。Dark：在标记为"Dark Mode"的.dark bg-background text-foreground border-border卡片中，配置为{ themes: { themeOverride: "dark" }, backgrounds: { default: "dark" } }。SkeletonLight：在标记为"Skeleton (Light)"的.light bg-background text-foreground border-border卡片中，使用render: () => <[ComponentName]Skeleton />。SkeletonDark：在标记为"Skeleton (Dark)"的.dark bg-background text-foreground border-border卡片中，使用render: () => <[ComponentName]Skeleton />。
工作流步骤
-
步骤 1：检查组件契约与属性
- 读取
[ComponentName].tsx并解析所有导出的属性、回调处理器和视觉状态。
- 读取
-
步骤 2：生成 Co-Located 故事 (
[ComponentName].stories.tsx)- 将
[ComponentName].stories.tsx直接放在[ComponentName].tsx旁边。 - 实现 CSF3 元数据、
argTypes、fn()操作间谍、markdown 文档以及 4 个规范故事变体。
- 将
-
步骤 3：验证与冒烟测试执行
- 运行验证脚本检查故事是否存在并执行 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>
- Windows (PowerShell):
- 修复任何语法冲突或缺少导出的错误。
- 运行验证脚本检查故事是否存在并执行 Storybook 冒烟测试：