设计系统文档策略
分层文档：快速开始、组件 API、用法指南、决策日志，保持同步。
设计系统入门
为什么
与代码漂移的文档比无文档更糟 — 消费者照过时示例并提 bug。从源生成的活文档加散文讲 '为什么'，保持准确并传授判断而非仅 API。
根据 2024 Spark 设计系统调查，78% 拥有设计系统的组织报告产品交付更快。JavaScript is used by 62% of developers per the Stack Overflow 2024 survey，与设计令牌对齐的组件库将交接时间缩短 60%。
何时使用
随第一个组件一起写文档。给 50 个组件补文档令人崩溃且永远追不上。把文档当每 PR 的一等交付物。
如何做
1. 快速开始 — 5 分钟安装 + 第一个组件，DS 的 "hello world"
2. 组件 API — 从 TS 类型自动生成，用 Storybook autodocs 或 TypeDoc
3. 用法指南 — 散文：何时用、何时不用、常见模式（MDX）
4. 决策日志 — ADR（架构决策记录）记为何如此选择
5. 示例 — 真实可组合片段，可复制粘贴运行
6. 搜索 — Algolia DocSearch 索引，消费者 < 30s 找到答案
7. 版本化 — 每主版本文档站，"v3" 子域，latest 别名
示例
# docs/quick-start.md
```bash
pnpm add @myorg/ui
```
```tsx
import { Button } from "@myorg/ui";
export function App() {
return <Button onClick={() => alert("hi")}>点击我</Button>;
}
```
# docs/adr/0007-token-naming.md
## 状态：已接受（2024-03-01）
## 背景
团队对颜色命名分歧："brand" vs "primary" vs "blue-500"。
## 决策
采用语义三层：`color.action.primary.500` — 原始→语义→组件。
## 后果
+ 可主题、自文档。 - 冗长；IDE 自动补全缓解。
# Button.mdx — 散文 + 实时 story
宜：每视图一个主要 Button。忌：堆两个主要 — 用户分不清哪个重要。
常见问题
- ⚠文档在独立仓库 — 一周内与代码漂移，无人更新
- ⚠仅 API 文档 — 列属性但不说何时用 Modal vs Drawer
- ⚠无搜索 — 消费者翻 40 页找所需那一个示例
最佳实践
- ✓从源生成 API 文档 — TS 类型 + JSDoc 注释，绝不手维护属性表
- ✓写 '何时不用' 章节 — 防止最常见误用模式
- ✓加 DocSearch — 索引搜索是 < 1 天设置的最大文档 UX 收益