components-build

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Components.build Specification

Components.build 规范

Comprehensive guidelines for building modern, composable, and accessible UI components. Contains 16 rule categories covering everything from core principles to distribution, co-authored by Hayden Bleasel and shadcn.

这是构建现代化、可组合且无障碍UI组件的综合指南。包含16个规则类别，涵盖从核心原则到组件分发的所有内容，由Hayden Bleasel和shadcn联合撰写。

When to Apply

适用场景

Reference these guidelines when:

Creating new React components or component libraries
Designing component APIs and prop interfaces
Implementing accessibility features (keyboard, ARIA, focus management)
Building composable component architectures
Styling components with Tailwind CSS and CVA
Publishing components to registries or npm

在以下场景中可参考本指南：

创建新的React组件或组件库
设计组件API和属性接口
实现无障碍功能（键盘操作、ARIA、焦点管理）
构建可组合的组件架构
使用Tailwind CSS和CVA为组件设置样式
将组件发布到组件注册表或npm

Rule Categories by Priority

按优先级划分的规则类别


overview
principles
definitions
composition
accessibility
state
types
polymorphism
as-child
data-attributes
styling
design-tokens
documentation
registry
npm
marketplaces

Priority	Category	Focus	Prefix
1	Overview	Specification scope and goals	`overview`
2	Principles	Core design philosophy	`principles`
3	Definitions	Common terminology	`definitions`
4	Composition	Breaking down complex components	`composition`
5	Accessibility	Keyboard, screen readers, ARIA	`accessibility`
6	State	Controlled/uncontrolled patterns	`state`
7	Types	TypeScript props and interfaces	`types`
8	Polymorphism	Element switching with `as` prop	`polymorphism`
9	As-Child	Radix Slot composition pattern	`as-child`
10	Data Attributes	`data-state` and `data-slot`	`data-attributes`
11	Styling	Tailwind CSS, cn utility, CVA	`styling`
12	Design Tokens	CSS variables and theming	`design-tokens`
13	Documentation	Component documentation	`documentation`
14	Registry	Component registries	`registry`
15	NPM	Publishing to npm	`npm`
16	Marketplaces	Component marketplaces	`marketplaces`


overview
principles
definitions
composition
accessibility
state
types
polymorphism
as-child
data-attributes
styling
design-tokens
documentation
registry
npm
marketplaces

优先级	类别	重点	前缀
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`

Quick Reference

快速参考

1. Overview

1. 概述

```
overview
```
- Specification scope, goals, and philosophy

```
overview
```
- 规范的范围、目标与设计理念

2. Principles

2. 核心原则

```
principles
```
- Composability, accessibility, customization, transparency

```
principles
```
- 可组合性、无障碍性、可定制性、透明性

3. Definitions

3. 术语定义

```
definitions
```
- Common terminology (primitive, compound, headless, etc.)

```
definitions
```
- 通用术语（基础组件、复合组件、无头组件等）

4. Composition

4. 组件组合

```
composition-root
```
- Root component with Context for shared state
```
composition-item
```
- Item wrapper components
```
composition-trigger
```
- Interactive trigger components
```
composition-content
```
- Content display components
```
composition-export
```
- Namespace export pattern

```
composition-root
```
- 带有共享状态Context的根组件
```
composition-item
```
- 子项包装组件
```
composition-trigger
```
- 交互式触发组件
```
composition-content
```
- 内容展示组件
```
composition-export
```
- 命名空间导出模式

5. Accessibility

5. 无障碍设计

```
accessibility-semantic-html
```
- Use appropriate HTML elements
```
accessibility-keyboard
```
- Full keyboard navigation support
```
accessibility-aria
```
- Proper ARIA roles, states, and properties
```
accessibility-focus
```
- Focus management and restoration
```
accessibility-live-regions
```
- Screen reader announcements
```
accessibility-contrast
```
- Color contrast requirements

```
accessibility-semantic-html
```
- 使用合适的HTML元素
```
accessibility-keyboard
```
- 支持完整的键盘导航
```
accessibility-aria
```
- 正确使用ARIA角色、状态与属性
```
accessibility-focus
```
- 焦点管理与恢复
```
accessibility-live-regions
```
- 屏幕阅读器播报
```
accessibility-contrast
```
- 颜色对比度要求

6. State

6. 状态管理

```
state-uncontrolled
```
- Internal state management
```
state-controlled
```
- External state delegation
```
state-controllable
```
- Support both patterns with useControllableState

```
state-uncontrolled
```
- 内部状态管理
```
state-controlled
```
- 外部状态委托
```
state-controllable
```
- 使用useControllableState同时支持两种模式

7. Types

7. 类型定义

```
types-extend-html
```
- Extend native HTML attributes
```
types-export
```
- Export prop types for consumers
```
types-single-element
```
- One component wraps one element

```
types-extend-html
```
- 扩展原生HTML属性
```
types-export
```
- 向使用者导出属性类型
```
types-single-element
```
- 一个组件仅包装一个元素

8. Polymorphism

8. 多态性

```
polymorphism-as-prop
```
- Change rendered element type
```
polymorphism-typescript
```
- Type-safe polymorphic components
```
polymorphism-defaults
```
- Semantic element defaults

```
polymorphism-as-prop
```
- 更改渲染元素类型
```
polymorphism-typescript
```
- 类型安全的多态组件
```
polymorphism-defaults
```
- 语义化元素默认值

9. As-Child

9. As-Child模式

```
as-child-slot
```
- Radix Slot for prop merging
```
as-child-composition
```
- Compose with child components

```
as-child-slot
```
- 用于属性合并的Radix Slot
```
as-child-composition
```
- 与子组件组合使用

10. Data Attributes

10. 数据属性

```
data-attributes-state
```
- Use
```
data-state
```
for styling states
```
data-attributes-slot
```
- Use
```
data-slot
```
for targeting sub-components

```
data-attributes-state
```
- 使用
```
data-state
```
标记样式状态
```
data-attributes-slot
```
- 使用
```
data-slot
```
定位子组件

11. Styling

11. 样式设置

```
styling-cn-utility
```
- Combine clsx and tailwind-merge
```
styling-order
```
- Base → Variants → Conditionals → User overrides
```
styling-cva
```
- Class Variance Authority for variants
```
styling-css-variables
```
- Dynamic values with CSS variables

```
styling-cn-utility
```
- 结合clsx与tailwind-merge
```
styling-order
```
- 基础样式 → 变体样式 → 条件样式 → 用户覆盖样式
```
styling-cva
```
- 使用Class Variance Authority管理样式变体
```
styling-css-variables
```
- 通过CSS变量实现动态值

12. Design Tokens

12. 设计令牌

```
design-tokens-css-variables
```
- Define tokens as CSS variables
```
design-tokens-theming
```
- Support light/dark modes and themes

```
design-tokens-css-variables
```
- 将令牌定义为CSS变量
```
design-tokens-theming
```
- 支持明暗模式与主题定制

13. Documentation

13. 文档编写

```
documentation-props
```
- Document all props with JSDoc
```
documentation-examples
```
- Provide usage examples

```
documentation-props
```
- 使用JSDoc记录所有属性
```
documentation-examples
```
- 提供使用示例

14. Registry

14. 组件注册表

```
registry-structure
```
- Registry file structure
```
registry-schema
```
- Component metadata schema

```
registry-structure
```
- 注册表文件结构
```
registry-schema
```
- 组件元数据 schema

15. NPM

15. 发布到npm

```
npm-package-json
```
- Package configuration
```
npm-exports
```
- Module exports

```
npm-package-json
```
- 包配置
```
npm-exports
```
- 模块导出

16. Marketplaces

16. 组件市场

```
marketplaces-distribution
```
- Component distribution strategies

```
marketplaces-distribution
```
- 组件分发策略

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:

rules/composition/SKILL.md
rules/accessibility/SKILL.md
rules/styling/SKILL.md

Each rule file contains:

Brief explanation of why it matters
Incorrect code example with explanation
Correct code example with explanation
Best practices and common pitfalls

阅读单个规则文件获取详细说明与代码示例：

rules/composition/SKILL.md
rules/accessibility/SKILL.md
rules/styling/SKILL.md

每个规则文件包含：

规则重要性的简要说明
错误代码示例及问题解释
正确代码示例及说明
最佳实践与常见陷阱

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

如需查看包含所有展开规则的完整指南，请参考：

AGENTS.md

Key Principles

核心原则

Composition over Configuration - Break components into composable sub-components
Accessibility by Default - Not an afterthought, but a requirement
Single Element Wrapping - Each component wraps one HTML element
Extend HTML Attributes - Always extend native element props
Export Types - Make prop types available to consumers
Support Both State Patterns - Controlled and uncontrolled
Intelligent Class Merging - Use
```
cn()
```
utility with tailwind-merge

组合优先于配置 - 将组件拆分为可组合的子组件
默认支持无障碍 - 无障碍不是事后补充，而是必备要求
单元素包装 - 每个组件仅包装一个HTML元素
扩展HTML属性 - 始终扩展原生元素属性
导出类型定义 - 向使用者开放属性类型
支持两种状态模式 - 同时支持受控与非受控模式
智能类名合并 - 使用
```
cn()
```
工具结合tailwind-merge

Authors

作者

Co-authored by:

Hayden Bleasel (@haydenbleasel)
shadcn (@shadcn)

Adapted as an AI skill by:

Jordan Gilliam (@nolansym)

Based on the components.build specification.

联合作者：

Hayden Bleasel (@haydenbleasel)
shadcn (@shadcn)

由以下人员适配为AI技能：

Jordan Gilliam (@nolansym)

基于 components.build 规范。