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- Usedata-statefor styling states - •
data-attributes-slot- Usedata-slotfor 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:
code
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.