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.