Storybook天然是组件文档系统，通过DocsPage自动生成属性表与交互预览，MDX支持富文本与嵌入故事，结合Controls、Actions、Viewport实现可操作文档，并按业务逻辑结构化组织提升查找效率。
Storybook 不只是预览组件的工具，它天然就是组件文档系统。用好 DocsPage 和 MDX，能让文档和代码始终同步，团队成员点开就能看效果、改参数、抄代码，协作成本大幅下降。
启用 DocsPage 插件，一键生成基础文档
DocsPage 是 Storybook 官方推荐的文档方案，无需手写 Markdown，它会自动解析组件的 props（TypeScript 接口或 PropTypes）并生成属性表格、使用示例和交互预览。
- 在 .storybook/main.js 中启用插件：
addons: ['@storybook/addon-docs'] - 确保你的组件故事文件（如
Button.stories.tsx）导出了component字段：export default { title: 'Components/Button', component: Button }; - 启动 Storybook 后，每个组件故事页右侧会自动出现 “Docs” 标签页，内容即为自动生成文档
用 MDX 编写富文本交互文档
当默认 DocsPage 不够用时（比如需要对比用法、插入设计规范、嵌入多个故事），MDX 是更灵活的选择。它把 Markdown 的易读性和 JSX 的表现力结合在一起。
- 新建
Button.docs.mdx文件，开头声明元数据：<meta of="{ButtonStories}">（注意：of必须指向故事文件的默认导出） - 正文用标准 Markdown 写说明，用
<story of="{ButtonStories.Primary}"></story>嵌入可交互的故事 - 还能自由插入自定义组件，例如：
<dodont><do><button size="large">正确尺寸</button></do></dodont>
让文档真正“活”起来：Controls + Actions + Viewport
静态文档容易过时，而 Storybook 文档的核心优势是“可操作”。把文档变成实验沙盒，团队成员能自己调参数、点按钮、切屏幕尺寸，理解立刻加深。
-
Controls：在故事中定义
args，文档页自动生成控件面板（颜色选择器、开关、输入框等） -
Actions：添加
onSubmit或onClick等事件监听，点击后在控制台实时看到触发日志 - Viewport：在文档页顶部切换 iPhone、Tablet、Desktop 等尺寸，直接验证响应式行为
结构化组织，降低团队查找成本
文档再好，找不到也白搭。按业务逻辑或 UI 层级组织侧边栏，比堆砌文件名更有效。
- 在 story title 中使用斜杠分组，如：
'Forms/LoginForm'、'Layouts/TwoColumn' - 基础组件（Button、Input）和业务组件（UserProfileCard、OrderSummary）分开归类
- 为高频场景单独建故事，例如：
LoginForm/WithValidationErrors、Button/LoadingState
