Spécification components.build
Directives complètes pour la construction de composants UI modernes, composables et accessibles. Contient 16 catégories de règles couvrant des principes fondamentaux à la distribution, coécrit par Hayden Bleasel et shadcn.
Quand appliquer
Consultez ces directives lorsque :
- Vous créez de nouveaux composants React ou des bibliothèques de composants
- Vous concevez des API de composants et des interfaces de props
- Vous implémentez des fonctionnalités d'accessibilité (clavier, ARIA, gestion du focus)
- Vous construisez des architectures de composants composables
- Vous stylisez des composants avec Tailwind CSS et CVA
- Vous publiez des composants dans des registres ou sur npm
Catégories de règles par priorité
| Priorité | Catégorie | Objectif | Préfixe |
|---|---|---|---|
| 1 | Aperçu | Portée et objectifs de la spécification | overview |
| 2 | Principes | Philosophie de conception fondamentale | principles |
| 3 | Définitions | Terminologie commune | definitions |
| 4 | Composition | Décomposition des composants complexes | composition |
| 5 | Accessibilité | Clavier, lecteurs d'écran, ARIA | accessibility |
| 6 | État | Modèles contrôlés/non contrôlés | state |
| 7 | Types | Props et interfaces TypeScript | types |
| 8 | Polymorphisme | Changement d'élément avec la prop as | polymorphism |
| 9 | As-Child | Modèle de composition Radix Slot | as-child |
| 10 | Attributs de données | data-state et data-slot | data-attributes |
| 11 | Stylisme | Tailwind CSS, utilitaire cn, CVA | styling |
| 12 | Tokens de design | Variables CSS et thèmes | design-tokens |
| 13 | Documentation | Documentation des composants | documentation |
| 14 | Registre | Registres de composants | registry |
| 15 | NPM | Publication sur npm | npm |
| 16 | Places de marché | Places de marché de composants | marketplaces |
Référence rapide
1. Aperçu
overview- Portée, objectifs et philosophie de la spécification
2. Principes
principles- Composabilité, accessibilité, personnalisation, transparence
3. Définitions
definitions- Terminologie commune (primitif, composé, headless, etc.)
4. Composition
composition-root- Composant racine avec Context pour l'état partagécomposition-item- Composants d'encapsulation d'élémentcomposition-trigger- Composants déclencheurs interactifscomposition-content- Composants d'affichage de contenucomposition-export- Modèle d'export par espace de noms
5. Accessibilité
accessibility-semantic-html- Utiliser des éléments HTML appropriésaccessibility-keyboard- Prise en charge complète de la navigation au clavieraccessibility-aria- Rôles, états et propriétés ARIA correctsaccessibility-focus- Gestion et restauration du focusaccessibility-live-regions- Annonces pour lecteurs d'écranaccessibility-contrast- Exigences de contraste des couleurs
6. État
state-uncontrolled- Gestion d'état internestate-controlled- Délégation d'état externestate-controllable- Prise en charge des deux modèles avec useControllableState
7. Types
types-extend-html- Étendre les attributs HTML natifstypes-export- Exporter les types de props pour les consommateurstypes-single-element- Un composant encapsule un élément
8. Polymorphisme
polymorphism-as-prop- Modifier le type d'élément rendupolymorphism-typescript- Composants polymorphes type-safepolymorphism-defaults- Valeurs par défaut sémantiques des éléments
9. As-Child
as-child-slot- Radix Slot pour la fusion de propsas-child-composition- Composer avec des composants enfants
10. Attributs de données
data-attributes-state- Utiliserdata-statepour le style des étatsdata-attributes-slot- Utiliserdata-slotpour cibler les sous-composants
11. Stylisme
styling-cn-utility- Combiner clsx et tailwind-mergestyling-order- Base → Variantes → Conditionnelles → Surcharges utilisateurstyling-cva- Class Variance Authority pour les variantesstyling-css-variables- Valeurs dynamiques avec variables CSS
12. Tokens de design
design-tokens-css-variables- Définir les tokens comme variables CSSdesign-tokens-theming- Prise en charge des modes clair/sombre et des thèmes
13. Documentation
documentation-props- Documenter toutes les props avec JSDocdocumentation-examples- Fournir des exemples d'utilisation
14. Registre
registry-structure- Structure des fichiers du registreregistry-schema- Schéma des métadonnées des composants
15. NPM
npm-package-json- Configuration du packagenpm-exports- Exportations de modules
16. Places de marché
marketplaces-distribution- Stratégies de distribution de composants
Comment utiliser
Lisez les fichiers de règles individuels pour des explications détaillées et des exemples de code :
rules/composition/SKILL.md
rules/accessibility/SKILL.md
rules/styling/SKILL.md
Chaque fichier de règle contient :
- Une brève explication de son importance
- Un exemple de code incorrect avec explication
- Un exemple de code correct avec explication
- Bonnes pratiques et pièges courants
Document complet compilé
Pour le guide complet avec toutes les règles développées : AGENTS.md
Principes clés
- Composition plutôt que configuration - Décomposer les composants en sous-composants composables
- Accessibilité par défaut - Pas une réflexion après coup, mais une exigence
- Encapsulation d'un seul élément - Chaque composant encapsule un élément HTML
- Étendre les attributs HTML - Toujours étendre les props des éléments natifs
- Exporter les types - Rendre les types de props disponibles pour les consommateurs
- Prendre en charge les deux modèles d'état - Contrôlé et non contrôlé
- Fusion intelligente des classes - Utiliser l'utilitaire
cn()avec tailwind-merge
Auteurs
Coécrit par :
- Hayden Bleasel (@haydenbleasel)
- shadcn (@shadcn)
Adapté en skill IA par :
- Jordan Gilliam (@nolansym)
Basé sur la spécification components.build.