storybook

Storybook 最佳实践

你是使用 Storybook 构建和编写组件库文档的专家。创建故事、组织组件和维护设计系统时，请遵循以下指南。

项目结构

目录组织

• 将故事文件与组件文件放在一起（Component.stories.tsx）
• 为故事文件采用一致的命名规范
• 按功能或组件类型组织故事
• 保持清晰的层级结构，与组件库相匹配

文件命名

• 组件故事文件使用 PascalCase 命名
• 遵循以下模式：ComponentName.stories.tsx
• 将相关故事放在同一个文件中
• 使用能说明变体的描述性故事名称

编写故事

故事结构

import type { Meta, StoryObj } from '@storybook/react';
import { Component } from './Component';

const meta: Meta<typeof Component> = {
  title: 'Category/Component',
  component: Component,
  parameters: {
    layout: 'centered',
  },
  tags: ['autodocs'],
  argTypes: {
    // Define arg types here
  },
};

export default meta;
type Story = StoryObj<typeof meta>;

export const Default: Story = {
  args: {
    // Default props
  },
};

export const Variant: Story = {
  args: {
    variant: 'secondary',
  },
};

故事最佳实践

• 创建展示主要用法的 Default 故事
• 为每个重要变体添加故事
• 包含边界情况和错误状态
• 记录交互状态（悬停、聚焦、禁用）
• 相关时展示响应式行为

组件文档

Autodocs

• 启用 autodocs，自动生成文档
• 为组件和 props 编写清晰的 JSDoc 注释
• 记录 prop 类型、默认值和要求
• 在组件注释中提供用法示例

自定义文档

• 对于复杂的文档需求，添加 MDX 文件
• 包含设计思路和使用指南
• 记录无障碍注意事项
• 为常见用例提供代码示例

Args 和 Controls

ArgTypes 配置

argTypes: {
  variant: {
    control: 'select',
    options: ['primary', 'secondary', 'tertiary'],
    description: 'Visual style variant',
    table: {
      defaultValue: { summary: 'primary' },
    },
  },
  size: {
    control: 'radio',
    options: ['sm', 'md', 'lg'],
  },
  disabled: {
    control: 'boolean',
  },
  onClick: {
    action: 'clicked',
  },
}

Args 最佳实践

• 使用有意义的默认值
• 按逻辑对相关 args 分组
• 为复杂 props 提供说明
• 为回调 props 设置 actions

装饰器和参数

装饰器

decorators: [
  (Story) => (
    <ThemeProvider theme={defaultTheme}>
      <Story />
    </ThemeProvider>
  ),
],

• 使用装饰器为故事添加一致的包装器
• 在适当的层级应用主题提供程序
• 根据需要添加布局容器
• 保持装饰器简单且可复用

参数

parameters: {
  layout: 'centered', // or 'fullscreen', 'padded'
  backgrounds: {
    default: 'light',
    values: [
      { name: 'light', value: '#ffffff' },
      { name: 'dark', value: '#1a1a1a' },
    ],
  },
  viewport: {
    defaultViewport: 'responsive',
  },
},

使用 Storybook 进行测试

交互测试

import { within, userEvent } from '@storybook/testing-library';
import { expect } from '@storybook/jest';

export const Clickable: Story = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    const button = canvas.getByRole('button');

    await userEvent.click(button);
    await expect(button).toHaveFocus();
  },
};

视觉测试

• 配置视觉回归测试
• 在多个视口下捕获故事
• 测试主题变体（浅色／深色模式）
• 记录视觉测试覆盖范围

无障碍测试

• 启用 a11y addon 进行无障碍检查
• 解决所有无障碍违规问题
• 在故事中测试键盘导航
• 记录 ARIA 要求

Addons 和配置

必备 Addons

• @storybook/addon-essentials（docs、controls、actions、viewport）
• @storybook/addon-a11y，用于无障碍测试
• @storybook/addon-interactions，用于交互测试
• @storybook/addon-designs，用于集成设计规范

配置

// .storybook/main.ts
const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-a11y',
    '@storybook/addon-interactions',
  ],
  framework: {
    name: '@storybook/react-vite',
    options: {},
  },
};

export default config;

设计系统集成

设计令牌

• 从令牌系统导入设计令牌
• 在故事中一致地应用令牌
• 在组件文档中记录令牌的用法
• 在专门的故事中展示令牌变体

主题支持

• 在 preview.js 中配置主题提供程序
• 为每种主题变体创建故事
• 在所有受支持的主题下测试组件
• 记录特定于主题的行为

性能

构建优化

• 对大型故事集合使用延迟加载
• 优化静态资源
• 配置适当的缓存
• 监控并缩短构建时间

故事性能

• 避免在故事中进行大量计算
• 高效使用模拟数据
• 延迟加载复杂依赖项
• 对耗时较长的故事进行性能分析和优化

最佳实践总结

• 编写可作为实时文档的故事
• 集成前先独立测试组件
• 保持故事简单且重点明确
• 确保所有故事风格一致
• 组件变更时更新故事
• 使用故事进行设计评审和 QA
• 将无障碍测试纳入工作流
• 集成到 CI/CD 流水线中