Storybook组件文档生成指南：自动文档、MDX与JSDoc注释

storybook-component-documentation by thebushidocollective/han

95 周安装量

129 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/thebushidocollective/han --skill storybook-component-documentation

开发技术文档前端架构

🇨🇳中文介绍

Storybook - 组件文档

使用 Storybook 的自动文档功能、MDX 页面和 JSDoc 注释，创建全面、自动生成的组件文档。

核心概念

自动文档

从故事自动生成文档页面：

const meta = {
  title: 'Components/Button',
  component: Button,
  tags: ['autodocs'],  // 启用自动文档
  parameters: {
    docs: {
      description: {
        component: '一个具有多种变体和尺寸的多功能按钮组件。',
      },
    },
  },
} satisfies Meta<typeof Button>;

MDX 文档

创建具有完全控制权的自定义文档页面：

import { Meta, Canvas, Story, Controls } from '@storybook/blocks';
import * as ButtonStories from './Button.stories';

<Meta of={ButtonStories} />

# 按钮组件

用于用户交互的多功能按钮组件。

## 用法

<Canvas of={ButtonStories.Primary} />

## 属性

<Controls of={ButtonStories.Primary} />

JSDoc 注释

为组件属性添加文档以便自动提取：

interface ButtonProps {
  /**
   * 按钮标签文本
   */
  label: string;

  /**
   * 这是主要的操作调用吗？
   * @default false
   */
  primary?: boolean;

  /**
   * 按钮尺寸变体
   * @default 'medium'
   */
  size?: 'small' | 'medium' | 'large';
}

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

1. 启用自动文档

添加 autodocs 标签以自动生成文档：

const meta = {
  component: Button,
  tags: ['autodocs'],
  parameters: {
    docs: {
      description: {
        component: '具有主要和次要变体的按钮组件。',
      },
    },
  },
} satisfies Meta<typeof Button>;

2. 记录组件描述

提供清晰、简洁的组件描述：

const meta = {
  component: Tooltip,
  tags: ['autodocs'],
  parameters: {
    docs: {
      description: {
        component: `
工具提示在用户悬停在元素上时显示有用的信息。
支持多种位置，可以通过悬停、点击或焦点触发。

## 特性
- 多种位置选项
- 可自定义延迟
- 无障碍（符合 ARIA 标准）
- 键盘导航支持
        `.trim(),
      },
    },
  },
} satisfies Meta<typeof Tooltip>;

3. 记录故事变体

为单个故事添加描述：

export const WithIcon: Story = {
  args: {
    label: '下载',
    icon: 'download',
  },
  parameters: {
    docs: {
      description: {
        story: '按钮可以包含图标以增强视觉传达。',
      },
    },
  },
};

export const Loading: Story = {
  args: {
    loading: true,
    label: '处理中...',
  },
  parameters: {
    docs: {
      description: {
        story: '加载状态会禁用交互并显示一个旋转指示器。',
      },
    },
  },
};

4. 使用 JSDoc 进行类型文档

使用 JSDoc 记录属性以生成丰富的文档：

interface CardProps {
  /**
   * 显示在顶部的卡片标题
   */
  title: string;

  /**
   * 标题下方的可选副标题
   */
  subtitle?: string;

  /**
   * 影响视觉样式的卡片变体
   * @default 'default'
   */
  variant?: 'default' | 'outlined' | 'elevated';

  /**
   * 卡片内容
   */
  children: React.ReactNode;

  /**
   * 卡片被点击时调用
   * @param event - 点击事件
   */
  onClick?: (event: React.MouseEvent) => void;

  /**
   * 海拔级别（阴影深度）
   * @minimum 0
   * @maximum 5
   * @default 1
   */
  elevation?: number;
}

5. 创建用法示例

在 MDX 中展示实际的用法示例：

import { Meta, Canvas, Story } from '@storybook/blocks';
import * as FormStories from './Form.stories';

<Meta of={FormStories} />

# 表单组件

## 基本用法

<Canvas of={FormStories.Default} />

## 带验证

<Canvas of={FormStories.WithValidation} />

```tsx
import { Form } from './Form';

function MyForm() {
  return (
    <Form
      onSubmit={(data) => console.log(data)}
      validationSchema={schema}
    >
      <Input name="email" label="邮箱" />
      <Button type="submit">提交</Button>
    </Form>
  );
}

import { Meta, Canvas, Controls } from '@storybook/blocks';
import * as ButtonStories from './Button.stories';

<Meta of={ButtonStories} />

# 按钮

按钮在整个应用程序中触发操作和事件。

## 变体

### 主要按钮

将主要按钮用于主要的操作调用。

<Canvas of={ButtonStories.Primary} />

### 次要按钮

将次要按钮用于不太重要的操作。

<Canvas of={ButtonStories.Secondary} />

## 属性

<Controls of={ButtonStories.Primary} />

## 无障碍性

- 键盘可访问（Enter/空格键激活）
- 屏幕阅读器友好
- 焦点可见指示器
- 正确的 ARIA 标签

## 最佳实践

- 使用清晰、面向操作的标签
- 提供足够的点击目标尺寸（最小 44×44 像素）
- 每个部分不要使用超过一个主要按钮
- 为异步操作包含加载状态

const meta = {
  component: DataGrid,
  tags: ['autodocs'],
  parameters: {
    docs: {
      description: {
        component: '具有排序、过滤和分页功能的高级数据网格。',
      },
    },
  },
  argTypes: {
    data: {
      description: '要显示的数据对象数组',
      table: {
        type: { summary: 'Array<Record<string, any>>' },
      },
    },
    columns: {
      description: '列配置',
      table: {
        type: { summary: 'ColumnDef[]' },
      },
    },
    onRowClick: {
      description: '行被点击时触发的回调',
      table: {
        type: { summary: '(row: any, index: number) => void' },
      },
    },
  },
} satisfies Meta<typeof DataGrid>;

import { Meta } from '@storybook/blocks';

<Meta title="Guides/Migration/v2 to v3" />

# 迁移指南：v2 → v3

## 破坏性变更

### 按钮组件

**之前 (v2):**
```tsx
<Button type="primary">点击我</Button>

<Button variant="primary">点击我</Button>

为了保持一致性，type 属性已重命名为 variant。

<Input error="无效邮箱" />

<Input error={{ message: "无效邮箱" }} />

错误处理现在使用对象来支持额外的元数据。

按钮现在支持图标：

<Button variant="primary" icon="check">
  保存
</Button>

记录设计令牌和主题：

import { Meta, ColorPalette, ColorItem, Typeset } from '@storybook/blocks';

<Meta title="Design System/Colors" />

# 颜色调色板

## 主要颜色

<ColorPalette>
  <ColorItem
    title="主要"
    subtitle="主品牌色"
    colors={{ Primary: '#007bff' }}
  />
  <ColorItem
    title="次要"
    subtitle="辅助色"
    colors={{ Secondary: '#6c757d' }}
  />
</ColorPalette>

## 排版

<Typeset
  fontSizes={[12, 14, 16, 20, 24, 32, 40, 48]}
  fontWeight={400}
  sampleText="The quick brown fox jumps over the lazy dog"
/>

MDX 中的内联故事

import { Meta, Story } from '@storybook/blocks';
import { Button } from './Button';

<Meta title="Components/Button/Examples" component={Button} />

# 按钮示例

## 内联故事

<Story name="自定义">
  {() => {
    const [count, setCount] = React.useState(0);
    return (
      <Button onClick={() => setCount(count + 1)}>
        已点击 {count} 次
      </Button>
    );
  }}
</Story>

import { Source } from '@storybook/blocks';

<Meta title="Guides/Setup" />

# 安装

安装组件库：

<Source
  language="bash"
  code={`
npm install @company/ui-components
# 或
yarn add @company/ui-components
  `}
/>

然后导入组件：

<Source
  language="tsx"
  code={`
import { Button, Input, Form } from '@company/ui-components';

function App() {
  return (
    <Form>
      <Input label="邮箱" />
      <Button>提交</Button>
    </Form>
  );
}
  `}
/>

❌ 不要跳过组件描述

// 错误示例
const meta = {
  component: Button,
  tags: ['autodocs'],
} satisfies Meta<typeof Button>;

// 正确示例
const meta = {
  component: Button,
  tags: ['autodocs'],
  parameters: {
    docs: {
      description: {
        component: '用于用户操作的主要 UI 组件。',
      },
    },
  },
} satisfies Meta<typeof Button>;

❌ 不要使用通用的 JSDoc 注释

// 错误示例
interface ButtonProps {
  /** 标签 */
  label: string;
  /** 尺寸 */
  size?: string;
}

// 正确示例
interface ButtonProps {
  /** 按钮上显示的文本 */
  label: string;
  /**
   * 按钮的视觉尺寸
   * @default 'medium'
   */
  size?: 'small' | 'medium' | 'large';
}

❌ 不要忘记故事描述

// 错误示例
export const Disabled: Story = {
  args: { disabled: true },
};

// 正确示例
export const Disabled: Story = {
  args: { disabled: true },
  parameters: {
    docs: {
      description: {
        story: '禁用状态会阻止用户交互并使按钮视觉上变暗。',
      },
    },
  },
};

storybook-story-writing : 创建结构良好的故事
storybook-args-controls : 为属性配置交互式控件
storybook-configuration : 使用适当的文档插件设置 Storybook

🇺🇸English

Storybook - Component Documentation

Create comprehensive, auto-generated component documentation using Storybook's autodocs feature, MDX pages, and JSDoc comments.

Key Concepts

Autodocs

Automatically generate documentation pages from stories:

const meta = {
  title: 'Components/Button',
  component: Button,
  tags: ['autodocs'],  // Enable auto-documentation
  parameters: {
    docs: {
      description: {
        component: 'A versatile button component with multiple variants and sizes.',
      },
    },
  },
} satisfies Meta<typeof Button>;

MDX Documentation

Create custom documentation pages with full control:

import { Meta, Canvas, Story, Controls } from '@storybook/blocks';
import * as ButtonStories from './Button.stories';

<Meta of={ButtonStories} />

# Button Component

A versatile button component for user interactions.

## Usage

<Canvas of={ButtonStories.Primary} />

## Props

<Controls of={ButtonStories.Primary} />

JSDoc Comments

Document component props for auto-extraction:

interface ButtonProps {
  /**
   * The button label text
   */
  label: string;

  /**
   * Is this the principal call to action?
   * @default false
   */
  primary?: boolean;

  /**
   * Button size variant
   * @default 'medium'
   */
  size?: 'small' | 'medium' | 'large';
}

Best Practices

1. Enable Autodocs

Add the autodocs tag to generate documentation automatically:

const meta = {
  component: Button,
  tags: ['autodocs'],
  parameters: {
    docs: {
      description: {
        component: 'Button component with primary and secondary variants.',
      },
    },
  },
} satisfies Meta<typeof Button>;

2. Document Component Descriptions

Provide clear, concise component descriptions:

const meta = {
  component: Tooltip,
  tags: ['autodocs'],
  parameters: {
    docs: {
      description: {
        component: `
Tooltip displays helpful information when users hover over an element.
Supports multiple placements and can be triggered by hover, click, or focus.

## Features
- Multiple placement options
- Customizable delay
- Accessible (ARIA compliant)
- Keyboard navigation support
        `.trim(),
      },
    },
  },
} satisfies Meta<typeof Tooltip>;

3. Document Story Variations

Add descriptions to individual stories:

export const WithIcon: Story = {
  args: {
    label: 'Download',
    icon: 'download',
  },
  parameters: {
    docs: {
      description: {
        story: 'Buttons can include icons to enhance visual communication.',
      },
    },
  },
};

export const Loading: Story = {
  args: {
    loading: true,
    label: 'Processing...',
  },
  parameters: {
    docs: {
      description: {
        story: 'Loading state disables interaction and shows a spinner.',
      },
    },
  },
};

4. Use JSDoc for Type Documentation

Document props with JSDoc for rich documentation:

interface CardProps {
  /**
   * Card title displayed at the top
   */
  title: string;

  /**
   * Optional subtitle below the title
   */
  subtitle?: string;

  /**
   * Card variant affecting visual style
   * @default 'default'
   */
  variant?: 'default' | 'outlined' | 'elevated';

  /**
   * Card content
   */
  children: React.ReactNode;

  /**
   * Called when card is clicked
   * @param event - The click event
   */
  onClick?: (event: React.MouseEvent) => void;

  /**
   * Elevation level (shadow depth)
   * @minimum 0
   * @maximum 5
   * @default 1
   */
  elevation?: number;
}

5. Create Usage Examples

Show realistic usage examples in MDX:

import { Meta, Canvas, Story } from '@storybook/blocks';
import * as FormStories from './Form.stories';

<Meta of={FormStories} />

# Form Component

## Basic Usage

<Canvas of={FormStories.Default} />

## With Validation

<Canvas of={FormStories.WithValidation} />

```tsx
import { Form } from './Form';

function MyForm() {
  return (
    <Form
      onSubmit={(data) => console.log(data)}
      validationSchema={schema}
    >
      <Input name="email" label="Email" />
      <Button type="submit">Submit</Button>
    </Form>
  );
}



## Common Patterns

### Component Overview Page

```mdx
import { Meta, Canvas, Controls } from '@storybook/blocks';
import * as ButtonStories from './Button.stories';

<Meta of={ButtonStories} />

# Button

Buttons trigger actions and events throughout the application.

## Variants

### Primary

Use primary buttons for the main call-to-action.

<Canvas of={ButtonStories.Primary} />

### Secondary

Use secondary buttons for less important actions.

<Canvas of={ButtonStories.Secondary} />

## Props

<Controls of={ButtonStories.Primary} />

## Accessibility

- Keyboard accessible (Enter/Space to activate)
- Screen reader friendly
- Focus visible indicator
- Proper ARIA labels

## Best Practices

- Use clear, action-oriented labels
- Provide sufficient click target size (min 44×44px)
- Don't use more than one primary button per section
- Include loading states for async actions

API Documentation

const meta = {
  component: DataGrid,
  tags: ['autodocs'],
  parameters: {
    docs: {
      description: {
        component: 'Advanced data grid with sorting, filtering, and pagination.',
      },
    },
  },
  argTypes: {
    data: {
      description: 'Array of data objects to display',
      table: {
        type: { summary: 'Array<Record<string, any>>' },
      },
    },
    columns: {
      description: 'Column configuration',
      table: {
        type: { summary: 'ColumnDef[]' },
      },
    },
    onRowClick: {
      description: 'Callback fired when a row is clicked',
      table: {
        type: { summary: '(row: any, index: number) => void' },
      },
    },
  },
} satisfies Meta<typeof DataGrid>;

Migration Guides

import { Meta } from '@storybook/blocks';

<Meta title="Guides/Migration/v2 to v3" />

# Migration Guide: v2 → v3

## Breaking Changes

### Button Component

**Before (v2):**
```tsx
<Button type="primary">Click me</Button>

After (v3):

<Button variant="primary">Click me</Button>

The type prop has been renamed to variant for consistency.

Input Component

Before (v2):

<Input error="Invalid email" />

After (v3):

<Input error={{ message: "Invalid email" }} />

Error handling now uses an object to support additional metadata.

New Features

Icon Support

Buttons now support icons:

<Button variant="primary" icon="check">
  Save
</Button>



### Design Tokens

Document design tokens and theming:

```mdx
import { Meta, ColorPalette, ColorItem, Typeset } from '@storybook/blocks';

<Meta title="Design System/Colors" />

# Color Palette

## Primary Colors

<ColorPalette>
  <ColorItem
    title="Primary"
    subtitle="Main brand color"
    colors={{ Primary: '#007bff' }}
  />
  <ColorItem
    title="Secondary"
    subtitle="Supporting color"
    colors={{ Secondary: '#6c757d' }}
  />
</ColorPalette>

## Typography

<Typeset
  fontSizes={[12, 14, 16, 20, 24, 32, 40, 48]}
  fontWeight={400}
  sampleText="The quick brown fox jumps over the lazy dog"
/>

Advanced Patterns

Inline Stories in MDX

import { Meta, Story } from '@storybook/blocks';
import { Button } from './Button';

<Meta title="Components/Button/Examples" component={Button} />

# Button Examples

## Inline Story

<Story name="Custom">
  {() => {
    const [count, setCount] = React.useState(0);
    return (
      <Button onClick={() => setCount(count + 1)}>
        Clicked {count} times
      </Button>
    );
  }}
</Story>

Code Snippets

import { Source } from '@storybook/blocks';

<Meta title="Guides/Setup" />

# Installation

Install the component library:

<Source
  language="bash"
  code={`
npm install @company/ui-components
# or
yarn add @company/ui-components
  `}
/>

Then import components:

<Source
  language="tsx"
  code={`
import { Button, Input, Form } from '@company/ui-components';

function App() {
  return (
    <Form>
      <Input label="Email" />
      <Button>Submit</Button>
    </Form>
  );
}
  `}
/>

Anti-Patterns

❌ Don't Skip Component Descriptions

// Bad
const meta = {
  component: Button,
  tags: ['autodocs'],
} satisfies Meta<typeof Button>;



// Good
const meta = {
  component: Button,
  tags: ['autodocs'],
  parameters: {
    docs: {
      description: {
        component: 'Primary UI component for user actions.',
      },
    },
  },
} satisfies Meta<typeof Button>;

❌ Don't Use Generic JSDoc Comments

// Bad
interface ButtonProps {
  /** The label */
  label: string;
  /** The size */
  size?: string;
}



// Good
interface ButtonProps {
  /** Text displayed on the button */
  label: string;
  /**
   * Visual size of the button
   * @default 'medium'
   */
  size?: 'small' | 'medium' | 'large';
}

❌ Don't Forget Story Descriptions

// Bad
export const Disabled: Story = {
  args: { disabled: true },
};



// Good
export const Disabled: Story = {
  args: { disabled: true },
  parameters: {
    docs: {
      description: {
        story: 'Disabled state prevents user interaction and dims the button visually.',
      },
    },
  },
};

Related Skills

storybook-story-writing : Creating well-structured stories
storybook-args-controls : Configuring interactive controls for props
storybook-configuration : Setting up Storybook with proper documentation addons

Weekly Installs

Repository

thebushidocollective/han

GitHub Stars

129

First Seen

Jan 22, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

codex80

opencode79

gemini-cli78

github-copilot74

cursor73

kimi-cli62

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

116,600 周安装