Back to Details

storybook

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Storybook Best Practices

Storybook 最佳实践

You are an expert in building and documenting component libraries with Storybook. Apply these guidelines when creating stories, organizing components, and maintaining design systems.
你是使用Storybook构建和文档化组件库的专家。在创建stories、组织组件和维护设计系统时，请遵循以下指南。

Project Structure

项目结构

Directory Organization

目录组织

  • Place stories alongside component files (Component.stories.tsx)
  • Use consistent naming conventions for story files
  • Organize stories by feature or component type
  • Maintain a clear hierarchy matching your component library
  • 将stories与组件文件放在同一目录下（如Component.stories.tsx）
  • 为story文件使用统一的命名规范
  • 按功能或组件类型组织stories
  • 保持与组件库清晰匹配的层级结构

File Naming

文件命名

  • Use PascalCase for component story files
  • Follow pattern: 
    ComponentName.stories.tsx
  • Group related stories in the same file
  • Use descriptive story names that explain the variant
  • 组件story文件使用PascalCase命名法
  • 遵循命名模式：
    ComponentName.stories.tsx
  • 将相关stories归到同一文件中
  • 使用能说明变体的描述性story名称

Writing Stories

编写Stories

Story Structure

Story结构

typescript
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',
  },
};
typescript
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: {
    // 在此处定义参数类型
  },
};

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

export const Default: Story = {
  args: {
    // 默认属性
  },
};

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

Story Best Practices

Story最佳实践

  • Create a Default story showing primary usage
  • Add stories for each significant variant
  • Include edge cases and error states
  • Document interactive states (hover, focus, disabled)
  • Show responsive behavior when relevant
  • 创建展示主要用法的Default story
  • 为每个重要变体添加对应的story
  • 包含边缘情况和错误状态
  • 文档化交互状态（悬停、聚焦、禁用）
  • 相关时展示响应式表现

Component Documentation

组件文档化

Autodocs

自动文档（Autodocs）

  • Enable autodocs for automatic documentation generation
  • Write clear JSDoc comments for components and props
  • Document prop types, defaults, and requirements
  • Include usage examples in component comments
  • 启用autodocs以自动生成文档
  • 为组件和属性编写清晰的JSDoc注释
  • 文档化属性类型、默认值和要求
  • 在组件注释中包含使用示例

Custom Documentation

自定义文档

  • Add MDX files for complex documentation needs
  • Include design rationale and usage guidelines
  • Document accessibility considerations
  • Provide code examples for common use cases
  • 对于复杂的文档需求，添加MDX文件
  • 包含设计原理和使用指南
  • 文档化可访问性注意事项
  • 提供常见用例的代码示例

Args and Controls

参数与控件（Args and Controls）

ArgTypes Configuration

ArgTypes配置

typescript
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',
  },
}
typescript
argTypes: {
  variant: {
    control: 'select',
    options: ['primary', 'secondary', 'tertiary'],
    description: '视觉样式变体',
    table: {
      defaultValue: { summary: 'primary' },
    },
  },
  size: {
    control: 'radio',
    options: ['sm', 'md', 'lg'],
  },
  disabled: {
    control: 'boolean',
  },
  onClick: {
    action: 'clicked',
  },
}

Args Best Practices

Args最佳实践

  • Use meaningful default values
  • Group related args logically
  • Provide descriptions for complex props
  • Set up actions for callback props
  • 使用有意义的默认值
  • 按逻辑对相关参数进行分组
  • 为复杂属性提供描述
  • 为回调属性设置动作监听

Decorators and Parameters

装饰器与参数（Decorators and Parameters）

Decorators

装饰器

typescript
decorators: [
  (Story) => (
    <ThemeProvider theme={defaultTheme}>
      <Story />
    </ThemeProvider>
  ),
],
  • Use decorators for consistent story wrappers
  • Apply theme providers at the appropriate level
  • Add layout containers when needed
  • Keep decorators simple and reusable
typescript
decorators: [
  (Story) => (
    <ThemeProvider theme={defaultTheme}>
      <Story />
    </ThemeProvider>
  ),
],
  • 使用装饰器实现统一的story包装
  • 在合适层级应用主题提供者
  • 必要时添加布局容器
  • 保持装饰器简洁且可复用

Parameters

参数

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

Testing with Storybook

基于Storybook的测试

Interaction Testing

交互测试

typescript
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();
  },
};
typescript
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();
  },
};

Visual Testing

视觉测试

  • Configure visual regression testing
  • Capture stories at multiple viewports
  • Test theme variations (light/dark mode)
  • Document visual test coverage
  • 配置视觉回归测试
  • 在多个视口下捕获story
  • 测试主题变体（亮色/暗色模式）
  • 文档化视觉测试覆盖范围

Accessibility Testing

可访问性测试

  • Enable a11y addon for accessibility checks
  • Address all accessibility violations
  • Test keyboard navigation in stories
  • Document ARIA requirements
  • 启用a11y插件进行可访问性检查
  • 修复所有可访问性违规问题
  • 在stories中测试键盘导航
  • 文档化ARIA要求

Addons and Configuration

插件与配置

Essential Addons

必备插件

  • @storybook/addon-essentials (docs, controls, actions, viewport)
  • @storybook/addon-a11y for accessibility testing
  • @storybook/addon-interactions for interaction testing
  • @storybook/addon-designs for design spec integration
  • @storybook/addon-essentials（包含文档、控件、动作、视口功能）
  • @storybook/addon-a11y 用于可访问性测试
  • @storybook/addon-interactions 用于交互测试
  • @storybook/addon-designs 用于集成设计规范

Configuration

配置

typescript
// .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;
typescript
// .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;

Design System Integration

设计系统集成

Design Tokens

设计令牌

  • Import design tokens from your token system
  • Apply tokens consistently in stories
  • Document token usage in component docs
  • Show token variations in dedicated stories
  • 从令牌系统导入设计令牌
  • 在stories中一致地应用令牌
  • 在组件文档中说明令牌使用方法
  • 在专门的stories中展示令牌变体

Theme Support

主题支持

  • Configure theme provider in preview.js
  • Create stories for each theme variant
  • Test components across all supported themes
  • Document theme-specific behavior
  • 在preview.js中配置主题提供者
  • 为每个主题变体创建对应的stories
  • 在所有支持的主题下测试组件
  • 文档化主题特定行为

Performance

性能

Build Optimization

构建优化

  • Use lazy loading for large story collections
  • Optimize static assets
  • Configure proper caching
  • Monitor and improve build times
  • 对大型story集合使用懒加载
  • 优化静态资源
  • 配置合理的缓存策略
  • 监控并缩短构建时间

Story Performance

Story性能

  • Avoid heavy computations in stories
  • Use mock data efficiently
  • Lazy load complex dependencies
  • Profile and optimize slow stories
  • 避免在stories中进行大量计算
  • 高效使用模拟数据
  • 懒加载复杂依赖
  • 分析并优化加载缓慢的stories

Best Practices Summary

最佳实践总结

  • Write stories that serve as living documentation
  • Test components in isolation before integration
  • Keep stories simple and focused
  • Maintain consistency across all stories
  • Update stories when components change
  • Use stories for design review and QA
  • Make accessibility testing part of the workflow
  • Integrate with your CI/CD pipeline
  • 编写可作为活文档的stories
  • 在集成前先对组件进行隔离测试
  • 保持stories简洁且聚焦
  • 在所有stories中保持一致性
  • 组件变更时同步更新stories
  • 将stories用于设计评审和QA
  • 将可访问性测试纳入工作流
  • 与CI/CD流水线集成