文档

良好的文档对于让你的组件易于访问和使用至关重要。本指南概述了每个组件文档页面应包含的关键要素。

文档框架

为了扩展你的文档，你可以使用一个文档框架。根据你的项目语言和需求，有许多可用选项。常见选项包括：

• Fumadocs - 用于 Next.js 的快速且功能丰富的文档框架
• Nextra - 基于 Markdown 的文档，内置搜索和主题支持
• Content Collections - 用于文档的类型安全内容管理
• Docusaurus - 支持版本控制的功能丰富文档站点
• VitePress - 基于 Vue 的静态站点生成器，针对文档进行了优化

首选的框架应支持语法高亮、自定义组件并且具备良好的设计。

必要的文档章节

概述

以简短的介绍开始，说明组件的作用以及何时使用它。

演示、源代码和预览

为了给开发者留下良好的第一印象，你应包含一个展示组件实际效果的演示，以及用于创建该演示的代码。

如果你使用的是开源的 注册表，你还可以包含用于创建组件的源代码预览。

使用带语法高亮和一键复制功能的代码块。考虑使用选项卡界面在这些视图之间切换，而不会使页面混乱。

安装

包含关于如何安装组件的清晰说明。最好是一个可以复制粘贴到终端中的单行命令。

如果你在基于 shadcn/ui 构建，可以使用 shadcn CLI 来安装组件，例如：

npx shadcn@latest add <your-component-url>

如果你要发布到 市场，可以使用市场提供的 CLI 来安装组件，例如：

npx shadcn@latest add https://21st.dev/r/<your-author>/<your-component>

如果你没有使用 shadcn/ui，但正在构建一个 注册表，你可以构建你自己的 CLI 来安装组件，例如：

npx your-registry-cli@latest add <your-component-url>

最后，如果你发布到 npm，你可以使用 npm CLI 来安装组件，例如：

npm install <your-component-name>

功能

列出组件的关键功能，帮助用户快速了解其能力与优势。例如：

• 可定制 – 轻松调整样式、大小和行为以满足你的需求。
• 默认可访问 – 遵循键盘导航、ARIA 角色和屏幕阅读器支持的最佳实践。
• 可组合 – 设计为能与其他组件和模式无缝协作。
• 类型安全 – 随包附带全面的 TypeScript 类型以获得最大安全性和自动补全。
• 主题支持 – 与你的设计代币或主题系统集成。
• 轻量 – 最小依赖并针对性能进行了优化。
• 支持 SSR/SSG – 可与服务端渲染和静态渲染框架一起使用。
• 文档完善 – 包含清晰的用法示例和 API 参考。

根据你的具体组件调整该列表。强调使其独特或对开发者特别有用的点。

示例

使用实用示例展示组件的灵活性：

• 变体 - 可用的不同视觉样式或尺寸
• 状态 - 加载、禁用、错误或成功状态
• 高级用法 - 复杂场景和边缘情况
• 组合 - 组件与其他组件协作的方式
• 响应式行为 - 在不同屏幕尺寸下的适应方式

每个示例都应包含渲染输出和对应的代码。

Props 与 API 参考

记录所有可用的 props、方法和配置选项。考虑将相关的 props 分组并突出常用项。对于每个 prop，包含：

• 名称 - prop 标识符
• 类型 - TypeScript 类型定义
• 默认值 - 未指定时的默认值
• 是否必需 - prop 是否为必填
• 描述 - prop 的作用以及何时使用

可访问性

记录你的组件如何支持可访问性功能：

• 键盘导航模式
• ARIA 属性和角色
• 屏幕阅读器支持
• 焦点管理
• 色彩对比注意事项

更新日志与版本控制

在每个组件文档页面上维护更新日志可能很有用，内容包括：

• 遵循语义化版本的版本号
• 新功能和增强
• Bug 修复
• 重大变更（breaking changes）
• 主要版本更新的迁移指南

帮助用户了解版本之间的差异以及如何安全升级。对破坏性更改包含前后示例代码。

最佳实践

• 保持文档与代码变更同步
• 使用解决实际问题的真实示例
• 包含常见陷阱和故障排查提示
• 在相关情况下提供性能方面的注意事项
• 链接到相关组件和模式
• 确保所有代码示例可运行并经过测试