什么是 Storybook？

Storybook 是一个功能强大的 UI 组件开发环境，允许开发人员在与主应用逻辑完全隔离的情况下创建、记录和测试组件。通过为 Storybook 利用 Openclaw Skills，团队可以通过组件 Story 格式 (CSF) 标准确保一致的设计模式和高质量的 UI。

此技能提供了管理组件参数 (args)、配置交互式控件以及使用 play 函数实现高级测试工作流的全面模式。它简化了从原始组件到完整文档化设计系统的过渡，确保每个边缘情况都经过视觉验证和程序化测试。

下载入口:https://github.com/openclaw/skills/tree/main/skills/ivangdavila/storybook

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

Storybook 应用场景

• 为跨团队使用记录设计系统和共享组件库。
• 隔离测试 UI 组件，以防止来自主应用的副作用错误。
• 向利益相关者展示组件变体，如加载、错误或禁用状态。
• 为复杂的 UI 行为实现自动化交互测试，无需手动刷新浏览器。
• 使用实时、可视化的文档网站在设计师和开发人员之间进行协作。

1. 使用标准 CLI 工具在项目中初始化 Storybook。
2. 使用 CSF 格式中的默认导出定义组件元数据，以建立 Story 层级。
3. 为单个 Story 创建命名导出，为每个组件状态指定唯一的 args。
4. 配置 argTypes 以定义 Storybook UI 中可用的交互式控件和操作日志。
5. 应用装饰器 (decorators)，使用必要的主题提供者、布局上下文或全局样式包装 Story。
6. 利用 play 函数自动化用户交互，并通过基于浏览器的断言验证组件行为。

Storybook 配置指南

要开始使用此技能，请在现有项目中初始化 Storybook：

npx storybook@latest init

添加用于 play 函数和交互测试的必要测试依赖项：

npm install @storybook/testing-library @storybook/test @storybook/addon-interactions --save-dev

确保您的 .storybook/main.js 已配置为指向您的组件 Story，并包含控件和操作所需的插件。

Storybook 数据架构与分类体系

该技能使用组件 Story 格式 (CSF) 组织 Storybook 数据，通常存储在 .stories.tsx 或 .stories.jsx 文件中。以下是主要的元数据分类：

name: Storybook
description: Build component stories with proper args, controls, decorators, and testing patterns.
metadata: {"clawdbot":{"emoji":"??","requires":{"bins":["npx"]},"os":["linux","darwin","win32"]}}

CSF Format (Component Story Format)

• Default export is component meta—title, component, args, decorators
• Named exports are stories—each export becomes a story in sidebar
• satisfies Meta for TypeScript type checking
• CSF3 uses object syntax, not functions—export const Primary = { args: {...} }

Args vs ArgTypes

• args are actual prop values passed to component—args: { label: 'Click me' }
• argTypes configure controls UI—argTypes: { size: { control: 'select', options: ['sm', 'lg'] } }
• Default args in meta apply to all stories—override in individual stories
• argTypes: { onClick: { action: 'clicked' } } logs events in Actions panel

Controls

• Auto-inferred from TypeScript props—boolean becomes toggle, string becomes text input
• Override control type: argTypes: { color: { control: 'color' } }
• Disable control: argTypes: { children: { control: false } }
• Options for select: control: { type: 'select' }, options: ['a', 'b', 'c']

Decorators

• Wrap stories with context—providers, layout wrappers, theme
• Component-level in meta: decorators: [(Story) => ]
• Global in .storybook/preview.js: applies to all stories
• Order matters—later decorators wrap earlier ones

Play Functions

• Interactive testing within story: play: async ({ canvasElement }) => {...}
• Use @storybook/testing-library for queries—within(canvasElement).getByRole()
• await userEvent.click(button) for interactions
• expect(element).toBeVisible() for assertions—tests run in browser

Actions

• argTypes: { onClick: { action: 'clicked' } } auto-logs to Actions panel
• Or import: import { action } from '@storybook/addon-actions'
• Use fn() from @storybook/test in Storybook 8+ for spying in play functions
• Actions help verify event handlers without manual console.log

Story Organization

• Title path creates hierarchy: title: 'Components/Forms/Button'
• Stories appear in order of export—put Primary first
• tags: ['autodocs'] generates docs page automatically
• parameters: { docs: { description: { story: 'text' } } } adds story description

Common Patterns

• Default state: export const Default = {}
• With all props: export const WithIcon = { args: { icon: } }
• Edge cases: Empty, Loading, Error, Disabled states as separate stories
• Responsive: Use viewport addon parameters per story

Render Functions

• Custom render: render: (args) =>
• Access context in render: render: (args, { globals }) => ...
• Useful when story needs different JSX structure than default
• Prefer decorators for wrapping, render for restructuring

Configuration

• .storybook/main.js: addons, framework, stories glob patterns
• .storybook/preview.js: global decorators, parameters, argTypes
• Stories glob: stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)']
• Static assets: staticDirs: ['../public'] for images/fonts

Common Mistakes

• Forgetting to install addon AND add to main.js addons array
• Using storiesOf API—deprecated, use CSF exports
• Missing component in meta—controls won't auto-generate
• Decorators returning Story without calling it: (Story) => not (Story) => Story