Components.build 规范：构建现代化、可组合、无障碍 React UI 组件库的完整指南

components-build by nolly-studio/components-build-skill

115 周安装量

47 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/nolly-studio/components-build-skill --skill components-build

UI组件库 React 代码规范

🇨🇳中文介绍

Components.build 规范

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

何时应用

在以下情况下参考本指南：

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

按优先级划分的规则类别

优先级	类别	重点	前缀
1	概述	规范范围与目标	`overview`
2	原则	核心设计理念	`principles`
3	定义	常用术语

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

代码审查最佳实践指南：完整流程、安全与性能审查清单

12,400 周安装

UI组件模式实战指南：构建可复用React组件库与设计系统

10,700 周安装

React视图过渡API使用指南：实现原生浏览器动画与状态管理

5,700 周安装

Tailwind CSS v4 + shadcn/ui 生产级技术栈配置指南与最佳实践

2,600 周安装

overview - 规范范围、目标与理念

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

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

composition-root - 根组件，使用 Context 共享状态
composition-item - 项目包装组件
composition-trigger - 交互式触发器组件
composition-content - 内容显示组件
composition-export - 命名空间导出模式

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

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

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

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

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

data-attributes-state - 使用 data-state 表示样式状态
data-attributes-slot - 使用 data-slot 定位子组件

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

design-tokens-css-variables - 将设计令牌定义为 CSS 变量
design-tokens-theming - 支持浅色/深色模式和主题

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

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

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

marketplaces-distribution - 组件分发策略

阅读单个规则文件以获取详细解释和代码示例：

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

每个规则文件包含：

简要说明其重要性
错误的代码示例及解释
正确的代码示例及解释
最佳实践和常见陷阱

获取包含所有扩展规则的完整指南：AGENTS.md

组合优于配置 - 将组件分解为可组合的子组件
默认无障碍 - 不是事后考虑，而是基本要求
单元素包装 - 每个组件包装一个 HTML 元素
扩展 HTML 属性 - 始终扩展原生元素属性
导出类型 - 向使用者提供属性类型
支持两种状态模式 - 受控和非受控
智能类合并 - 使用 cn() 工具函数结合 tailwind-merge

Hayden Bleasel (@haydenbleasel)
shadcn (@shadcn)

改编为 AI 技能：

Jordan Gilliam (@nolansym)

基于 components.build 规范。

2026 年 1 月 28 日

🇺🇸English

Components.build Specification

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.

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

Rule Categories by Priority

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`

Quick Reference

1. Overview

overview - Specification scope, goals, and philosophy

2. Principles

principles - Composability, accessibility, customization, transparency

3. Definitions

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

4. Composition

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

5. Accessibility

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

6. State

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

7. Types

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

8. Polymorphism

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

9. As-Child

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

10. Data Attributes

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

11. Styling

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

12. Design Tokens

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

13. Documentation

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

14. Registry

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

15. NPM

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

16. Marketplaces

marketplaces-distribution - Component distribution strategies

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

Full Compiled Document

For the complete guide with all rules expanded: 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

Authors

Co-authored by:

Hayden Bleasel (@haydenbleasel)
shadcn (@shadcn)

Adapted as an AI skill by:

Jordan Gilliam (@nolansym)

Based on the components.build specification.

Weekly Installs

111

Repository

nolly-studio/co…ld-skill

GitHub Stars

First Seen

Jan 28, 2026

Security Audits

Gen Agent Trust HubWarn SocketPass SnykWarn

Installed on

claude-code80

opencode71

codex69

cursor68

gemini-cli61

github-copilot60

TanStack Query v5 完全指南：React 数据管理、乐观更新、离线支持

2,500 周安装

Components.build 规范：构建现代化、可组合、无障碍 React UI 组件库的完整指南

🇨🇳中文介绍

Components.build 规范

何时应用

按优先级划分的规则类别

相关 Skills

快速参考

1. 概述

2. 原则

3. 定义

4. 组合

5. 无障碍

6. 状态

7. 类型

8. 多态性

9. As-Child

10. 数据属性

11. 样式

12. 设计令牌

13. 文档

14. 注册表

15. NPM

16. 市场

如何使用

完整编译文档

核心原则

作者

🇺🇸English

Components.build Specification

When to Apply

Rule Categories by Priority

Quick Reference

1. Overview

2. Principles

3. Definitions

4. Composition

5. Accessibility

6. State

7. Types

8. Polymorphism

9. As-Child

10. Data Attributes

11. Styling

12. Design Tokens

13. Documentation

14. Registry

15. NPM

16. Marketplaces

How to Use

Full Compiled Document

Key Principles

Authors

最新 Skills