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

| 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.

components-build

安装