Components.build Specification
Core shared class helper: consume the existing helper through the shared UI
boundary:
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.
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 first: shared primitives come from @base-ui/react via the shadcn
base-maia style in packages/ui; UI SDK fills only interactions no shared
component provides, per packages/ui/AGENTS.md. 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
- Read
docs/ai/rules/frontend.md and any nested AGENTS.md for the target package/app.
- Search existing shared components before adding a new primitive or abstraction.
- Prefer repo patterns and shadcn-compatible composition over bespoke APIs.
- Keep behavior and accessibility test coverage proportional to the component's reuse surface.
- Run focused type/lint/unit checks for touched component packages.
Checklist
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
- Composition over Configuration - Break components into composable sub-components
- Accessibility by Default - Not an afterthought, but a requirement
- Composable Parts - Respect each part's existing DOM or non-DOM host and ownership contract
- Preserve Prop Contracts - Derive existing part props; inherit native props/ref for new passive hosts
- Export Types - Make prop types available to consumers
- Preserve State Patterns - Use each primitive's existing controlled/uncontrolled API
- Intelligent Class Merging - Import
cn from @asym/ui/lib/utils.
Authors
Co-authored by:
Adapted as an AI skill by:
Based on the components.build specification.
1---2name: components-build-23description: 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.4license: MIT5metadata:6 source: https://skillmd.com/skills/asymmetric-al/components-build-27 author: components.build8 version: "1.0.0"9---1011# Components.build Specification1213<!-- CORE-COMPONENTS-CN-START -->1415**Core shared class helper:** consume the existing helper through the shared UI16boundary:1718```tsx19import { cn } from "@asym/ui/lib/utils";20```2122Do not create a competing local `cn` implementation or add `clsx`/`tailwind-merge`23for these recipes. The generic npm dependency examples below are retained24upstream material and are **non-operative in Core**. Current workspace manifests25and `packages/ui/lib/utils.ts` own the implementation and dependency choices.26<!-- CORE-COMPONENTS-CN-END -->2728## This repository (Asymmetric-al/core)2930These repo-owned sections are intentionally kept on top of the vendored31components.build skill. If upstream refreshes replace this file, reconcile this32overlay before running `bun run skills:sync`.3334**Base UI first:** shared primitives come from `@base-ui/react` via the shadcn35`base-maia` style in `packages/ui`; UI SDK fills only interactions no shared36component provides, per `packages/ui/AGENTS.md`. Where the vendored spec references Radix37or `asChild`, use Base UI's `render` prop instead and never add38`radix-ui`/`@radix-ui/*`. See `docs/ai/rules/frontend.md`.3940### Triggers4142- Creating, reviewing, or refactoring reusable React components, component APIs, slots, or composition patterns.43- Design-system work in `packages/ui/`, shadcn-compatible primitives, or shared app UI surfaces.44- Accessibility, controlled/uncontrolled state, polymorphism, or TypeScript prop contract decisions for components.4546### Workflow47481. Read `docs/ai/rules/frontend.md` and any nested `AGENTS.md` for the target package/app.492. Search existing shared components before adding a new primitive or abstraction.503. Prefer repo patterns and shadcn-compatible composition over bespoke APIs.514. Keep behavior and accessibility test coverage proportional to the component's reuse surface.525. Run focused type/lint/unit checks for touched component packages.5354### Checklist5556- [ ] Existing components and exports were checked before adding new API surface.57- [ ] Composition, keyboard, ARIA, focus, and disabled/loading states were considered.58- [ ] Props/types follow the local package's public export pattern.59- [ ] Styling uses repo tokens/utilities and avoids layout-shifting dynamic content.60- [ ] Verification covered the touched component behavior or contract.6162Comprehensive 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.6364## When to Apply6566Reference these guidelines when:6768- Creating new React components or component libraries69- Designing component APIs and prop interfaces70- Implementing accessibility features (keyboard, ARIA, focus management)71- Building composable component architectures72- Styling components with Tailwind CSS and CVA73- Publishing components to registries or npm7475## Rule Categories by Priority7677| Priority | Category | Focus | Prefix |78| -------- | ------------------ | ----------------------------------------- | ----------------- |79| 1 | Overview | Specification scope and goals | `overview` |80| 2 | Principles | Core design philosophy | `principles` |81| 3 | Definitions | Common terminology | `definitions` |82| 4 | Composition | Breaking down complex components | `composition` |83| 5 | Accessibility | Keyboard, screen readers, ARIA | `accessibility` |84| 6 | State | Controlled/uncontrolled patterns | `state` |85| 7 | Types | TypeScript props and interfaces | `types` |86| 8 | Polymorphism | Existing hosts; passive `as` background | `polymorphism` |87| 9 | Render Composition | Base UI render + native semantics | `as-child` |88| 10 | Data Attributes | Base UI state attributes and stable slots | `data-attributes` |89| 11 | Styling | Tailwind CSS, cn utility, CVA | `styling` |90| 12 | Design Tokens | CSS variables and theming | `design-tokens` |91| 13 | Documentation | Component documentation | `documentation` |92| 14 | Registry | Component registries | `registry` |93| 15 | NPM | Publishing to npm | `npm` |94| 16 | Marketplaces | Component marketplaces | `marketplaces` |9596## Quick Reference9798### 1. Overview99100- `overview` - Specification scope, goals, and philosophy101102### 2. Principles103104- `principles` - Composability, accessibility, customization, transparency105106### 3. Definitions107108- `definitions` - Common terminology (primitive, compound, headless, etc.)109110### 4. Composition111112- `composition-root` - Reuse the shared primitive’s state owner113- `composition-item` - Compose the existing item parts114- `composition-trigger` - Preserve interaction with Base UI render115- `composition-content` - Reuse accessible content parts116- `composition-export` - Import the existing flat shared exports117118### 5. Accessibility119120- `accessibility-semantic-html` - Use appropriate HTML elements121- `accessibility-keyboard` - Full keyboard navigation support122- `accessibility-aria` - Proper ARIA roles, states, and properties123- `accessibility-focus` - Focus management and restoration124- `accessibility-live-regions` - Screen reader announcements125- `accessibility-contrast` - Color contrast requirements126127### 6. State128129- `state-uncontrolled` - Internal state management130- `state-controlled` - External state delegation131- `state-controllable` - Reuse the shared primitive’s value/defaultValue or checked/defaultChecked API.132133### 7. Types134135- `types-extend-html` - Inherit native host props/ref for new passive wrappers136- `types-export` - Export owned props; derive an existing part's public props137- `types-single-element` - Preserve existing DOM, non-DOM and compound host contracts138139### 8. Polymorphism140141- `polymorphism-host-api` - Use the existing shared action/link/render contract142- `polymorphism-passive-types` - Generic passive-wrapper typing background143- `polymorphism-defaults` - Preserve the intended native host semantics144145### 9. Render Composition146147- `as-child-render` - Compose Base UI parts with the existing render API148- `as-child-semantics` - Preserve the native host, forwarded props and ref149150### 10. Data Attributes151152- `data-attributes-state` - Read the existing Base UI part's emitted state attributes153- `data-attributes-slot` - Use `data-slot` for targeting sub-components154155### 11. Styling156157- `styling-cn-utility` - Consume the shared Core `cn` helper.158- `styling-order` - Base → Variants → Conditionals → User overrides159- `styling-cva` - Class Variance Authority for variants160- `styling-css-variables` - Dynamic values with CSS variables161162### 12. Design Tokens163164- `design-tokens-css-variables` - Define tokens as CSS variables165- `design-tokens-theming` - Support light/dark modes and themes166167### 13. Documentation168169- `documentation-props` - Document all props with JSDoc170- `documentation-examples` - Provide usage examples171172### 14. Registry173174- `registry-structure` - Registry file structure175- `registry-schema` - Component metadata schema176177### 15. NPM178179- `npm-package-json` - Package configuration180- `npm-exports` - Module exports181182### 16. Marketplaces183184- `marketplaces-distribution` - Component distribution strategies185186## How to Use187188Read individual rule files for detailed explanations and code examples:189190```191rules/composition.md192rules/accessibility.md193rules/styling.md194```195196Each rule file contains:197198- Brief explanation of why it matters199- Incorrect code example with explanation200- Correct code example with explanation201- Best practices and common pitfalls202203## Full Compiled Document204205For the complete guide with all rules expanded: `AGENTS.md`206207## Key Principles2082091. **Composition over Configuration** - Break components into composable sub-components2102. **Accessibility by Default** - Not an afterthought, but a requirement2113. **Composable Parts** - Respect each part's existing DOM or non-DOM host and ownership contract2124. **Preserve Prop Contracts** - Derive existing part props; inherit native props/ref for new passive hosts2135. **Export Types** - Make prop types available to consumers2146. **Preserve State Patterns** - Use each primitive's existing controlled/uncontrolled API2157. **Intelligent Class Merging** - Import `cn` from `@asym/ui/lib/utils`.216217## Authors218219Co-authored by:220221- **Hayden Bleasel** ([@haydenbleasel](https://x.com/haydenbleasel))222- **shadcn** ([@shadcn](https://x.com/shadcn))223224Adapted as an AI skill by:225226- **Jordan Gilliam** ([@nolansym](https://x.com/nolansym))227228Based on the [components.build](https://components.build) specification.