components-build

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.

This repository (Asymmetric-al/core)

These repo-owned sections are intentionally kept on top of the vendored components.build skill. If upstream refreshes replace this file, reconcile this overlay before running bun run skills:sync.

Base UI only: shared primitives come from @base-ui/react via the shadcn base-maia style in packages/ui. Where the vendored spec references Radix or asChild, use Base UI's render prop instead and never add radix-ui/@radix-ui/*. See docs/ai/rules/frontend.md.

Triggers

• Creating, reviewing, or refactoring reusable React components, component APIs, slots, or composition patterns.
• Design-system work in packages/ui/, shadcn-compatible primitives, or shared app UI surfaces.
• Accessibility, controlled/uncontrolled state, polymorphism, or TypeScript prop contract decisions for components.

Workflow

1. Read docs/ai/rules/frontend.md and any nested AGENTS.md for the target package/app.
2. Search existing shared components before adding a new primitive or abstraction.
3. Prefer repo patterns and shadcn-compatible composition over bespoke APIs.
4. Keep behavior and accessibility test coverage proportional to the component's reuse surface.
5. Run focused type/lint/unit checks for touched component packages.

Checklist

• Existing components and exports were checked before adding new API surface.
• Composition, keyboard, ARIA, focus, and disabled/loading states were considered.
• Props/types follow the local package's public export pattern.
• Styling uses repo tokens/utilities and avoids layout-shifting dynamic content.
• Verification covered the touched component behavior or contract.

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	Slot composition (this repo: Base UI render)	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 - Slot-style prop merging (in this repo use Base UI's render prop)
• 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 - Use the shared cn() utility backed by cnfast
• 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 backed by cnfast

Authors

Co-authored by:

• Hayden Bleasel (@haydenbleasel)
• shadcn (@shadcn)

Adapted as an AI skill by:

• Jordan Gilliam (@nolansym)

Based on the components.build specification.