Components.build 规范
构建现代、可组合且无障碍 UI 组件的全面指南。包含 16 个规则类别,涵盖了从核心原则到分发的所有内容,由 Hayden Bleasel 和 shadcn 共同编写。
何时应用
在以下情况下参考这些指南:
- 创建新的 React 组件或组件库
- 设计组件 API 和属性接口
- 实现无障碍功能(键盘、ARIA、焦点管理)
- 构建可组合的组件架构
- 使用 Tailwind CSS 和 CVA 进行样式化
- 将组件发布到注册表或 npm
按优先级排序的规则类别
| 优先级 | 类别 | 重点 | 前缀 |
|---|---|---|---|
| 1 | 概述 | 规范范围和目标 | overview |
| 2 | 原则 | 核心设计理念 | principles |
| 3 | 定义 | 通用术语 | definitions |
| 4 | 组合 | 分解复杂组件 | composition |
| 5 | 无障碍 | 键盘、屏幕阅读器、ARIA | accessibility |
| 6 | 状态 | 受控/非受控模式 | state |
| 7 | 类型 | TypeScript 属性和接口 | types |
| 8 | 多态性 | 使用 as 属性切换元素 | polymorphism |
| 9 | 作为子元素 | Radix Slot 组合模式 | as-child |
| 10 | 数据属性 | data-state 和 data-slot | data-attributes |
| 11 | 样式化 | Tailwind CSS、cn 工具函数、CVA | styling |
| 12 | 设计令牌 | CSS 变量和主题 | design-tokens |
| 13 | 文档 | 组件文档 | documentation |
| 14 | 注册表 | 组件注册表 | registry |
| 15 | NPM | 发布到 npm | npm |
| 16 | 市场 | 组件市场 | marketplaces |
快速参考
1. 概述
overview- 规范范围、目标和理念
2. 原则
principles- 可组合性、无障碍性、可定制性、透明性
3. 定义
definitions- 通用术语(基础组件、复合组件、无头组件等)
4. 组合
composition-root- 带有 Context 的根组件,用于共享状态composition-item- 项包装组件composition-trigger- 可交互的触发器组件composition-content- 内容展示组件composition-export- 命名空间导出模式
5. 无障碍
accessibility-semantic-html- 使用合适的 HTML 元素accessibility-keyboard- 完整的键盘导航支持accessibility-aria- 正确的 ARIA 角色、状态和属性accessibility-focus- 焦点管理和恢复accessibility-live-regions- 屏幕阅读器公告accessibility-contrast- 颜色对比度要求
6. 状态
state-uncontrolled- 内部状态管理state-controlled- 外部状态委托state-controllable- 使用 useControllableState 支持两种模式
7. 类型
types-extend-html- 扩展原生 HTML 属性types-export- 导出属性类型以供消费者使用types-single-element- 一个组件包装一个元素
8. 多态性
polymorphism-as-prop- 更改渲染的元素类型polymorphism-typescript- 类型安全的多态组件polymorphism-defaults- 语义元素默认值
9. 作为子元素
as-child-slot- 使用 Radix Slot 进行属性合并as-child-composition- 与子组件组合
10. 数据属性
data-attributes-state- 使用data-state进行样式状态管理data-attributes-slot- 使用data-slot定位子组件
11. 样式化
styling-cn-utility- 组合 clsx 和 tailwind-mergestyling-order- 基础 → 变体 → 条件 → 用户覆盖styling-cva- 使用 Class Variance Authority 定义变体styling-css-variables- 使用 CSS 变量实现动态值
12. 设计令牌
design-tokens-css-variables- 将令牌定义为 CSS 变量design-tokens-theming- 支持浅色/深色模式和主题
13. 文档
documentation-props- 使用 JSDoc 记录所有属性documentation-examples- 提供使用示例
14. 注册表
registry-structure- 注册表文件结构registry-schema- 组件元数据模式
15. NPM
npm-package-json- 包配置npm-exports- 模块导出
16. 市场
marketplaces-distribution- 组件分发策略
如何使用
阅读单个规则文件以获取详细解释和代码示例:
rules/composition/SKILL.md
rules/accessibility/SKILL.md
rules/styling/SKILL.md
每个规则文件包含:
- 简要解释为什么重要
- 带解释的错误代码示例
- 带解释的正确代码示例
- 最佳实践和常见陷阱
完整编译文档
如需包含所有规则展开的完整指南:AGENTS.md
关键原则
- 组合优于配置 - 将组件分解为可组合的子组件
- 默认无障碍 - 不是事后补丁,而是硬性要求
- 单一元素包装 - 每个组件包装一个 HTML 元素
- 扩展 HTML 属性 - 始终扩展原生元素属性
- 导出类型 - 使属性类型对消费者可用
- 支持两种状态模式 - 受控和非受控
- 智能类合并 - 使用带有 tailwind-merge 的
cn()工具函数
作者
共同编写:
- Hayden Bleasel (@haydenbleasel)
- shadcn (@shadcn)
作为 AI 技能适配:
- Jordan Gilliam (@nolansym)
基于 components.build 规范。