Skip to main content
skill CX Codex

components-build — Claude Code skill for React components

components-build is a Claude Code skill for building, reviewing, and refactoring reusable React components with the components.build specification. It activates for work on component APIs, accessibility, styling, and TypeScript props.

MIT ★ 141 updated 2026-11-17

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add maxtrigify/Otto --skill components-build -a claude-code
Open on GitHub

What components-build does

components-build provides rules for React component design, covering composition, state, accessibility, and distribution. Its 16 categories include keyboard support, ARIA, polymorphism with the as prop, data-state attributes, and styling with Tailwind CSS and CVA.

The rules live in separate files with explanations, contrasting code samples, and common pitfalls. AGENTS.md contains the compiled guide; individual files include rules/composition/SKILL.md and rules/accessibility/SKILL.md. The skill also covers component documentation, registries, and npm publishing.

What it helps with

  • design a component API and its TypeScript types
  • split a complex component into composable parts
  • add keyboard navigation and ARIA support
  • align component styling with Tailwind CSS and CVA
  • prepare components for a registry or npm release

Example prompts for the agent

  • Create a compound React component with controlled and internal state.
  • Review these components for keyboard access and ARIA support.
  • Refactor this component API and its prop types to follow components.build.

How to install components-build

1Skills CLI (Vercel)

npx skills add maxtrigify/Otto --skill components-build -a claude-code

2Manually: put the files in place

~/.claude/skills/components-build/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/components-build/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about components-build

How do I install components-build in Claude Code?

Run npx skills add maxtrigify/Otto --skill components-build -a claude-code. The skill file will be at ~/.claude/skills/components-build/SKILL.md.

What does components-build do?

It supplies rules for creating, reviewing, and refactoring reusable React components. Its guidance covers composition, accessibility, state, types, styling, and component distribution.

What topics do the components-build rules cover?

They include state management, polymorphic components, the Radix Slot pattern, CSS variables for design tokens, and preparing packages for npm publishing.

Source text

SKILL.md · MIT
---
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.

## 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 | Radix Slot composition pattern | `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` - Radix Slot for prop merging
- `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` - Combine clsx and tailwind-merge
- `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 with tailwind-merge

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

© components.build · MIT · maxtrigify/Otto

Similar skills

All skills for Frontend and UI →

From the same set18

The whole set →
as-child as-child is a Claude Code rule for merging a component’s props and handlers into a custom child without an extra DOM wrapper. It applies to composable React triggers. CX Codex +1 ★ 141repo stars documentation documentation is a Claude Code rule that standardizes UI component documentation. It enforces consistent sections for props, runnable examples, and accessibility guidelines. CX Codex +1 ★ 141repo stars state state is a Claude Code rule for controlled and uncontrolled React component state. It applies while designing component APIs and state props. CX Codex +1 ★ 141repo stars accessibility accessibility is a Claude Code rule that enforces accessible frontend patterns. It triggers when generating UI components, dialogs, and navigation menus. CX Codex +1 ★ 141repo stars polymorphism polymorphism is a Claude Code rule for React components that keep their styles and behavior across element types. The as prop selects the rendered element. CX Codex +1 ★ 141repo stars styling styling is a Claude Code rule that enforces Tailwind CSS patterns. Guides the agent to combine classes with tailwind-merge, clsx, and CVA. CX Codex +1 ★ 141repo stars definitions definitions is a Claude Code rule that classifies UI artifacts and keeps names consistent across primitives, components, blocks, templates, and patterns. CX Codex +1 ★ 141repo stars otto-design otto-design is a Claude Code skill that enforces UI mockup creation in Paper before building SwiftUI views. It triggers on redesigns, mockups, or any visual changes to Otto surfaces. CX Codex +1 ★ 141repo stars

Project sponsors

Companies that keep this analytics open