Especificación components.build
Guía completa para construir componentes UI modernos, componibles y accesibles. Contiene 16 categorías de reglas que abarcan desde principios básicos hasta distribución, coautorada por Hayden Bleasel y shadcn.
Cuándo aplicar
Consulta estas pautas cuando:
- Creando nuevos componentes React o bibliotecas de componentes
- Diseñando APIs de componentes e interfaces de props
- Implementando funcionalidades de accesibilidad (teclado, ARIA, manejo de foco)
- Construyendo arquitecturas de componentes componibles
- Estilizando componentes con Tailwind CSS y CVA
- Publicando componentes en registros o npm
Categorías de reglas por prioridad
| Prioridad | Categoría | Enfoque | Prefijo |
|---|---|---|---|
| 1 | Visión General | Alcance y objetivos de la especificación | overview |
| 2 | Principios | Filosofía central de diseño | principles |
| 3 | Definiciones | Terminología común | definitions |
| 4 | Composición | Descomposición de componentes complejos | composition |
| 5 | Accesibilidad | Teclado, lectores de pantalla, ARIA | accessibility |
| 6 | Estado | Patrones controlados/no controlados | state |
| 7 | Tipos | Props e interfaces de TypeScript | types |
| 8 | Polimorfismo | Cambio de elemento con prop as | polymorphism |
| 9 | As-Child | Patrón de composición Radix Slot | as-child |
| 10 | Atributos de datos | data-state y data-slot | data-attributes |
| 11 | Estilizado | Tailwind CSS, utilidad cn, CVA | styling |
| 12 | Tokens de diseño | Variables CSS y tematización | design-tokens |
| 13 | Documentación | Documentación de componentes | documentation |
| 14 | Registro | Registros de componentes | registry |
| 15 | NPM | Publicación en npm | npm |
| 16 | Marketplaces | Mercados de componentes | marketplaces |
Referencia rápida
1. Visión General
overview- Alcance, objetivos y filosofía de la especificación
2. Principios
principles- Componibilidad, accesibilidad, personalización, transparencia
3. Definiciones
definitions- Terminología común (primitivo, compuesto, headless, etc.)
4. Composición
composition-root- Componente raíz con Context para estado compartidocomposition-item- Componentes envoltorio de ítemscomposition-trigger- Componentes de activación interactivoscomposition-content- Componentes de visualización de contenidocomposition-export- Patrón de exportación por espacio de nombres
5. Accesibilidad
accessibility-semantic-html- Usar elementos HTML apropiadosaccessibility-keyboard- Soporte completo de navegación por tecladoaccessibility-aria- Roles, estados y propiedades ARIA adecuadosaccessibility-focus- Manejo y restauración del focoaccessibility-live-regions- Anuncios para lectores de pantallaaccessibility-contrast- Requisitos de contraste de color
6. Estado
state-uncontrolled- Gestión de estado internostate-controlled- Delegación de estado externostate-controllable- Soporte de ambos patrones con useControllableState
7. Tipos
types-extend-html- Extender atributos HTML nativostypes-export- Exportar tipos de props para consumidorestypes-single-element- Un componente envuelve un elemento
8. Polimorfismo
polymorphism-as-prop- Cambiar el tipo de elemento renderizadopolymorphism-typescript- Componentes polimórficos con seguridad de tipospolymorphism-defaults- Valores por defecto semánticos de elementos
9. As-Child
as-child-slot- Radix Slot para fusión de propsas-child-composition- Componer con componentes hijos
10. Atributos de datos
data-attributes-state- Usardata-statepara estilizar estadosdata-attributes-slot- Usardata-slotpara apuntar a subcomponentes
11. Estilizado
styling-cn-utility- Combinar clsx y tailwind-mergestyling-order- Base → Variantes → Condicionales → Sobrescrituras de usuariostyling-cva- Class Variance Authority para variantesstyling-css-variables- Valores dinámicos con variables CSS
12. Tokens de diseño
design-tokens-css-variables- Definir tokens como variables CSSdesign-tokens-theming- Soporte de modos claro/oscuro y temas
13. Documentación
documentation-props- Documentar todas las props con JSDocdocumentation-examples- Proporcionar ejemplos de uso
14. Registro
registry-structure- Estructura de archivos del registroregistry-schema- Esquema de metadatos de componentes
15. NPM
npm-package-json- Configuración del paquetenpm-exports- Exportaciones del módulo
16. Marketplaces
marketplaces-distribution- Estrategias de distribución de componentes
Cómo usar
Lee archivos de reglas individuales para obtener explicaciones detalladas y ejemplos de código:
rules/composition/SKILL.md
rules/accessibility/SKILL.md
rules/styling/SKILL.md
Cada archivo de regla contiene:
- Breve explicación de por qué es importante
- Ejemplo de código incorrecto con explicación
- Ejemplo de código correcto con explicación
- Mejores prácticas y errores comunes
Documento completo compilado
Para la guía completa con todas las reglas expandidas: AGENTS.md
Principios clave
- Composición sobre Configuración - Descomponer componentes en subcomponentes componibles
- Accesibilidad por defecto - No es un añadido, sino un requisito
- Envoltura de elemento único - Cada componente envuelve un elemento HTML
- Extender atributos HTML - Siempre extender las props nativas de los elementos
- Exportar tipos - Hacer que los tipos de props estén disponibles para los consumidores
- Soportar ambos patrones de estado - Controlado y no controlado
- Fusión inteligente de clases - Usar la utilidad
cn()con tailwind-merge
Autores
Coautorado por:
- Hayden Bleasel (@haydenbleasel)
- shadcn (@shadcn)
Adaptado como skill de IA por:
- Jordan Gilliam (@nolansym)
Basado en la especificación components.build.