---
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

<!-- CORE-COMPONENTS-CN-START -->

**Core shared class helper:** consume the existing helper through the shared UI
boundary:

```tsx
import { cn } from "@asym/ui/lib/utils";
```

Do not create a competing local `cn` implementation or add `clsx`/`tailwind-merge`
for these recipes. The generic npm dependency examples below are retained
upstream material and are **non-operative in Core**. Current workspace manifests
and `packages/ui/lib/utils.ts` own the implementation and dependency choices.
<!-- CORE-COMPONENTS-CN-END -->

## 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.

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       | Existing hosts; passive `as` background   | `polymorphism`    |
| 9        | Render Composition | Base UI render + native semantics         | `as-child`        |
| 10       | Data Attributes    | Base UI state attributes and stable slots | `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` - Reuse the shared primitive’s state owner
- `composition-item` - Compose the existing item parts
- `composition-trigger` - Preserve interaction with Base UI render
- `composition-content` - Reuse accessible content parts
- `composition-export` - Import the existing flat shared exports

### 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` - Reuse the shared primitive’s value/defaultValue or checked/defaultChecked API.

### 7. Types

- `types-extend-html` - Inherit native host props/ref for new passive wrappers
- `types-export` - Export owned props; derive an existing part's public props
- `types-single-element` - Preserve existing DOM, non-DOM and compound host contracts

### 8. Polymorphism

- `polymorphism-host-api` - Use the existing shared action/link/render contract
- `polymorphism-passive-types` - Generic passive-wrapper typing background
- `polymorphism-defaults` - Preserve the intended native host semantics

### 9. Render Composition

- `as-child-render` - Compose Base UI parts with the existing render API
- `as-child-semantics` - Preserve the native host, forwarded props and ref

### 10. Data Attributes

- `data-attributes-state` - Read the existing Base UI part's emitted state attributes
- `data-attributes-slot` - Use `data-slot` for targeting sub-components

### 11. Styling

- `styling-cn-utility` - Consume the shared Core `cn` helper.
- `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.md
rules/accessibility.md
rules/styling.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. **Composable Parts** - Respect each part's existing DOM or non-DOM host and ownership contract
4. **Preserve Prop Contracts** - Derive existing part props; inherit native props/ref for new passive hosts
5. **Export Types** - Make prop types available to consumers
6. **Preserve State Patterns** - Use each primitive's existing controlled/uncontrolled API
7. **Intelligent Class Merging** - Import `cn` from `@asym/ui/lib/utils`.

## Authors

Co-authored by:

- **Hayden Bleasel** ([@haydenbleasel](https://x.com/haydenbleasel))
- **shadcn** ([@shadcn](https://x.com/shadcn))

Adapted as an AI skill by:

- **Jordan Gilliam** ([@nolansym](https://x.com/nolansym))

Based on the [components.build](https://components.build) specification.