| name | components-build |
| description | Build modern, composable, and accessible React UI components following the components.build specification. Use when creating, reviewing, or refactoring component libraries, design systems, or any reusable UI components. Triggers on tasks involving component APIs, composition patterns, accessibility, styling systems, or TypeScript props. |
| license | MIT |
| metadata | {"author":"components.build","version":"1.0.0"} |
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 statecomposition-item - Item wrapper componentscomposition-trigger - Interactive trigger componentscomposition-content - Content display componentscomposition-export - Namespace export pattern
5. Accessibility
accessibility-semantic-html - Use appropriate HTML elementsaccessibility-keyboard - Full keyboard navigation supportaccessibility-aria - Proper ARIA roles, states, and propertiesaccessibility-focus - Focus management and restorationaccessibility-live-regions - Screen reader announcementsaccessibility-contrast - Color contrast requirements
6. State
state-uncontrolled - Internal state managementstate-controlled - External state delegationstate-controllable - Support both patterns with useControllableState
7. Types
types-extend-html - Extend native HTML attributestypes-export - Export prop types for consumerstypes-single-element - One component wraps one element
8. Polymorphism
polymorphism-as-prop - Change rendered element typepolymorphism-typescript - Type-safe polymorphic componentspolymorphism-defaults - Semantic element defaults
9. As-Child
as-child-slot - Radix Slot for prop mergingas-child-composition - Compose with child components
10. Data Attributes
data-attributes-state - Use data-state for styling statesdata-attributes-slot - Use data-slot for targeting sub-components
11. Styling
styling-cn-utility - Combine clsx and tailwind-mergestyling-order - Base → Variants → Conditionals → User overridesstyling-cva - Class Variance Authority for variantsstyling-css-variables - Dynamic values with CSS variables
12. Design Tokens
design-tokens-css-variables - Define tokens as CSS variablesdesign-tokens-theming - Support light/dark modes and themes
13. Documentation
documentation-props - Document all props with JSDocdocumentation-examples - Provide usage examples
14. Registry
registry-structure - Registry file structureregistry-schema - Component metadata schema
15. NPM
npm-package-json - Package configurationnpm-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:
Adapted as an AI skill by:
Based on the components.build specification.
