Storybook 设计系统文档
Stories、MDX 文档与 addon 配置，构建活的组件文档。
设计系统进阶
为什么
静态文档（Notion、README）一周内与代码漂移。Storybook 渲染真实组件带实时属性，文档始终同步。还提供隔离开发环境 — 无需启动整个应用即可构建 Button。
何时使用
任何 5+ 组件的组件库或设计系统采用 Storybook。从不复用的应用内部组件跳过 — 内联测试足够。
如何做
1. 安装 — npx storybook@latest init，选框架（React、Vue、Astro 部分）
2. 写 stories — 每组件一个 .stories.tsx，导出 Default + 变体为命名导出
3. 加 args — 用 ArgsTable 交互式属性编辑，控件从 TS 类型自动生成
4. MDX 文档 — 导入组件，在 .mdx 写用法散文 + 实时示例，设 parameters.docs
5. addons — @storybook/addon-a11y（axe 审计）、addon-interactions（play 函数测试）
6. 组合 — 多设计系统时通过 project ID 组合到一个 Storybook
7. 发布 — Chromatic 做视觉回归 + 托管，或构建静态 + 部署 GitHub Pages
示例
// Button.stories.tsx — stories + arg 类型
import type { Meta, StoryObj } from "@storybook/react";
import { Button } from "./Button";
const meta: Meta<typeof Button> = {
title: "Components/Button",
component: Button,
tags: ["autodocs"],
argTypes: {
variant: { control: "select", options: ["primary", "secondary", "ghost"] },
size: { control: "radio", options: ["sm", "md", "lg"] },
disabled: { control: "boolean" },
},
parameters: {
docs: { description: { component: "主要 CTA。每视图用一个。" } },
},
};
export default meta;
export const Default: StoryObj<typeof Button> = {
args: { children: "点击我", variant: "primary", size: "md" },
};
export const AllVariants: StoryObj<typeof Button> = {
render: () => (
<div className="flex gap-2">
<Button variant="primary">主要</Button>
<Button variant="secondary">次要</Button>
<Button variant="ghost">幽灵</Button>
</div>
),
};
// Button.mdx — 长文文档含实时 stories
import { Meta, Story } from "@storybook/blocks";
<Meta of={Button} />
# Button
用于视图中最重要的操作。
<Story of={AllVariants} />
常见问题
- ⚠stories 不覆盖边界 — 仅“快乐路径”默认，错误/加载状态未文档化
- ⚠Storybook 配置漂移 — 加包时未更新 main.ts，stories 加载失败
- ⚠无 a11y addon — 组件通过视觉评审但有对比/键盘问题
- ⚠文档已发布但过期 — 无 CI 构建，Storybook 显示 3 个月前手动部署
最佳实践
- ✓为每个状态写 story — default、hover、focus、disabled、loading、error
- ✓加 addon-a11y，CI 违规失败 — 自动抓对比和 ARIA 问题
- ✓每 PR 在 CI 构建 Storybook — 部署预览到 Chromatic，视觉差异时阻止合并
- ✓用 CSF3 + autodocs — 简单组件无需 MDX 样板，复杂才用 MDX
常见问题解答
Storybook 和 README 文档为何选 Storybook？
README 一周就与代码漂移。Storybook 渲染真实组件带实时属性，文档始终同步。还提供隔离开发环境。
每个组件应有多少 stories？
每状态一个：default、hover、focus、disabled、loading、error。多数团队只写快乐路径默认，边界未文档化。
需要 MDX 还是 CSF 够？
CSF3 + autodocs 覆盖简单组件。仅复杂组件需长文用法指导和嵌入实时 stories 时用 MDX。
Storybook 中如何抓 a11y 问题？
加 @storybook/addon-a11y（每 story 跑 axe-core），CI 违规失败。开发时自动抓对比和 ARIA 问题。
如何防止 Storybook 文档过期？
每 PR 在 CI 构建 Storybook 并部署预览到 Chromatic。视觉差异阻止合并——每 PR 重建使过期文档不可能。