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

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

1. Composition over Configuration - Break components into composable sub-components
2. Accessibility by Default - Not an afterthought, but a requirement
3. Single Element Wrapping - Each component wraps one HTML element
4. Extend HTML Attributes - Always extend native element props
5. Export Types - Make prop types available to consumers
6. Support Both State Patterns - Controlled and uncontrolled
7. 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.