components-build

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	As-Child	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

• 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-merge
• styling-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

核心原则

1. 组合优于配置 - 将组件拆分为可组合的子组件
2. 默认保证无障碍访问 - 这不是事后考虑的事项，而是一项要求
3. 包裹单个元素 - 每个组件只包裹一个 HTML 元素
4. 扩展 HTML 属性 - 始终扩展原生元素属性
5. 导出类型 - 让使用者能够获取属性类型
6. 支持两种状态模式 - 受控和非受控
7. 智能合并类名 - 使用 cn() 工具和 tailwind-merge

作者

共同创作：

• Hayden Bleasel (@haydenbleasel)
• shadcn (@shadcn)

由以下人员改编为 AI 技能：

• Jordan Gilliam (@nolansym)

基于 components.build 规范。