Next.js Storybook CSF3 故事生成（nextjs-storybook-story）
專門用於生成與更新同目錄下 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 props 對應至互動控制項（text、select、boolean、number）。 - 在
args中提供實際的預設 prop 值。
3. 動作間諜（使用 'storybook/test' 的 fn()）
- 對於所有回調與突變 props（例如
onClick、onToggle、onSubmit），在預設args中綁定來自'storybook/test'的fn()，以便使用者互動能乾淨地記錄在 Storybook Actions 面板中。
4. 結構化文件（parameters.docs）
- 在
meta.parameters.docs.description.component中撰寫全面的 Markdown：- 概述與目的： 元件的用途與存在理由。
- 架構與邊界： RSC 與葉客戶端元件（
"use client"）、hook、快取。 - 關鍵互動： 點擊處理器、狀態切換與動畫。
- 無障礙與動態效果： 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 bg-background text-foreground border-border卡片中，配置{ themes: { themeOverride: "light" }, backgrounds: { default: "light" } }。Dark：在標題為"深色模式"的.dark bg-background text-foreground border-border卡片中，配置{ themes: { themeOverride: "dark" }, backgrounds: { default: "dark" } }。SkeletonLight：在標題為"骨架（淺色）"的.light bg-background text-foreground border-border卡片中，使用render: () => <[ComponentName]Skeleton />。SkeletonDark：在標題為"骨架（深色）"的.dark bg-background text-foreground border-border卡片中，使用render: () => <[ComponentName]Skeleton />。
工作流程步驟
-
步驟 1：檢查元件合約與 Props
- 讀取
[ComponentName].tsx，並解析所有匯出的 props、回調處理器與視覺狀態。
- 讀取
-
步驟 2：生成同目錄故事（
[ComponentName].stories.tsx）- 將
[ComponentName].stories.tsx直接放置在[ComponentName].tsx旁邊。 - 實作 CSF3 元資料、
argTypes、fn()動作間諜、Markdown 文件與四種標準故事變體。
- 將
-
步驟 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 冒煙測試：