maxtrigifymaxtrigify/Otto/.agents/skills/components-build/SKILL.md

components-build

Skill126 starsChanged 10 days agoApache-2.0View on GitHub

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.

1 other project uses a version of this; 1 new project in the last 4 weeks, against 0 the 4 before.

Adopted by

Surging: 1 new project took it in the last 4 weeks, none the 4 weeks before.thin data

Sep 2026Oct 2026Nov 2026

New projects taking a version of this file each week, over the 8 weeks our latest run read: only 1 in all, so this is a hint, not a trend.

Most recently taken up by

nolly-studio/cult-uiword for word, first seen Oct 8, 2026

Other versions1 project uses a version of this.
Word for word · 1
nolly-studio/cult-ui★ 6.9k100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository5 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .agents/skills/components-build/AGENTS.mdAGENTS.md
- frontend-designSkill
- otto-designSkill
- superdesignSkill

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Read individual rule files for detailed explanations and code examples:
line 138
Distinctive:
Accessibility by Default: - Not an afterthought, but a requirement
line 160
Distinctive:
Extend HTML Attributes: - Always extend native element props
line 162
Very specific:
Intelligent Class Merging: - Use cn() utility with tailwind-merge
line 165

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

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

Composition over Configuration - Break components into composable sub-components
Accessibility by Default - Not an afterthought, but a requirement
Single Element Wrapping - Each component wraps one HTML element
Extend HTML Attributes - Always extend native element props
Export Types - Make prop types available to consumers
Support Both State Patterns - Controlled and uncontrolled
Intelligent Class Merging - Use cn() utility with tailwind-merge

Authors

Co-authored by:

Hayden Bleasel (@haydenbleasel)
shadcn (@shadcn)

Adapted as an AI skill by:

Jordan Gilliam (@nolansym)

Based on the components.build specification.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free