--- name: asymmetric-al/components-build source: https://app.decimal.ai/s/asymmetric-al-components-build@1/SKILL.md source_sha256: 20e5cd2f00eb --- # 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](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.