文档与样式指南集成

没有文档时，每个开发者都要重新决定约定：应该使用什么标题顺序、有哪些类名、何时使用模态框而不是抽屉。记录完善的样式指南能让正确答案易于查找，并在规模扩大后消除猜测。

Storybook、Histoire（Vue）和 Ladle 等工具会在隔离环境中渲染组件，并同时展示其文档，因此示例始终与实际代码保持同步。静态文档文件（位于维基或代码仓库中）不可避免地会逐渐偏离实际情况，而持续更新的文档不会。

为每个组件展示使用它所需的最少 HTML：<app-button variant="primary">Save</app-button>。展示各种变体（主样式、次样式、危险样式）、状态（加载中、禁用）和边界情况（长文本、带图标、全宽）。能够准确复制粘贴到真实页面中的示例，才是团队真正会使用的示例。

最好的文档会将示例渲染在源代码旁边。Storybook 原生支持这一点；mdx-deck、Docusaurus 和 Astro Starlight 支持带有实时 JSX 的 MDX。在阅读标记的同时看到真实结果，可以直接消除“这能运行吗？”的疑虑。

记录每个组件内置的无障碍行为：支持哪些键盘操作、使用哪些 ARIA 角色，以及如何管理焦点。采用组件的使用方可以免费获得完整的无障碍能力说明，审查者也能确认自己没有破坏契约。

明确展示反模式：“不要用模态框来提供重要的临时反馈——请改用提示条。”反面示例往往比正面示例更令人印象深刻。为每条应该做的建议配上清晰的不要做事项，以揭示可能的失败方式。

记录命名模式：BEM、原子化 CSS、CSS 模块、Tailwind 工具类组合。明确说明类名、自定义属性名称和文件路径的规则。统一的命名可以降低认知负担；不一致的命名则会永久消耗每位开发者的时间。

记录做出决策的原因，而不只是记录决策内容。“我们选择 React 而不是 Vue，是因为……”这样可以为未来的贡献者保留上下文。将架构决策记录以 Markdown 文件的形式放在代码旁边，是一种轻量格式，即使团队人员更替也能继续发挥作用。

新团队成员应该能够在一天内发布自己的第一个组件。清单可以包括：设置代码仓库、安装依赖项、运行 Storybook、找到正确的组件模板、编写文档、提交 PR。将首次 PR 所需时间作为指标进行跟踪；越低越好。

最好的文档应该既便于新手搜索，也便于老手查找。使用支持搜索的文档网站（Docusaurus 使用 Algolia，Starlight 使用内置搜索）。为组件添加多个别名——搜索“对话框”“弹窗”或“叠加层”时，都能找到“模态框”。

将文档与视觉回归测试结合：Chromatic 会在每个 PR 中为每个 Storybook 故事截取快照，并显示视觉差异。一个意外改变文档中按钮样式的已合并 PR 会自动阻止自身合并。这样就把文档与对设计系统的主动测试结合起来了。

记录只有维护者知道的事情：容易踩的坑、尚未完成的抽象，以及等待清理的临时方案。未来的您（或您的接任者）会感谢现在的您，在忘记这些组织知识之前将它们记录下来。

为什么更推荐与代码一起渲染的持续更新文档，而不是静态文档文件？

文档能够放大设计系统的价值。使用会导入实际组件代码的持续更新文档（Storybook、Histoire、Ladle）。展示可用的最小示例，记录无障碍行为，保留决策依据，编写应该做与不应该做的配对示例，并结合视觉回归测试。将文档视为一等交付物，而不是事后补充。