Modèles d'interface Astro et bibliothèque de composants portables
Ce guide définit le catalogue standardisé de composants d'interface portables et prêts à l'emploi pour les sites Astro.
Les exemples autonomes utilisent le Modèle de composant portable : zéro dépendance npm externe, zéro runtime de framework client (pas de React/Vue), jetons CSS avec espaces de noms et valeurs de repli intégrées, et amélioration progressive. Dans les projets avec framework, conservez les exigences sémantiques et d'interaction tout en adaptant la composition et le style au contrat sélectionné. Vérifiez l'accessibilité dans le projet rendu ; un modèle seul ne garantit pas la conformité WCAG.
Contrats de comportement et composition du framework
Pour un composant dans l'index ci-dessous, utilisez son contrat sémantique et d'interaction : prise en charge du clavier, gestion du focus, éléments natifs, noms accessibles, mises à jour d'état et amélioration progressive. Le contrat du projet/framework sélectionné régit le style, les jetons, les importations et la composition du composant. Les instructions de l'utilisateur restent faisant autorité.
Les exemples utilisent le modèle de composant portable autonome ci-dessous. Utilisez-le lors de l'ajout d'un composant indépendant sans contrat de composition de framework. Lorsqu'un projet possède une bibliothèque établie, adaptez le comportement en utilisant ses primitives appropriées au lieu de dupliquer ses boutons, titres ou contrôles de formulaire. Préservez la sémantique et le comportement requis tout en adaptant les conteneurs et les classes de l'exemple.
Pour un projet construit sur un framework de composants (Lumos, par exemple), utilisez la composition et le style de ce framework ; ses primitives peuvent être importées. La règle d'importation zéro du site autonome et les jetons de repli avec espace de noms ne remplacent pas le contrat propre du framework sélectionné.
Le Modèle de composant portable
Pour les composants portables autonomes, utilisez ces cinq règles. Sur un framework sélectionné, préservez les exigences comportementales et suivez son contrat de composition/style comme décrit ci-dessus :
- Zéro Importation Externe/Site : Le fichier du composant ne doit PAS importer de mises en page, boutons ou bibliothèques d'interface client tierces du site. La seule exception cataloguée est SelfHostedMap, qui nécessite un moteur de rendu cartographique et un lecteur de tuiles ; sa spécification liste les paquets, et ils ne sont installés qu'avec l'approbation du propriétaire.
- Variables CSS avec espace de noms et valeurs de repli : Ne faites jamais directement référence aux jetons hôtes (ex.
var(--color-brand)) dans la feuille de style du composant. Écrivez toujoursvar(--comp-propriete, <repli>). - BEM avec espace de noms et propriétés logiques CSS : Utilisez la dénomination de classe BEM (
.c-bascule-theme,.c-accordion__summary) et les propriétés logiques (inline-size,block-size,padding-inline,margin-block). - Amélioration progressive vanilla idempotente : Les scripts doivent s'exécuter au chargement et se rattacher proprement si les transitions de vue Astro sont actives (
document.addEventListener('astro:after-swap', init)). - Cibles tactiles et ARIA : Les boutons et contrôles interactifs doivent avoir des cibles tactiles minimales de
44px(2.75rem) ou48px(3rem), des états ARIA appropriés (aria-expanded,aria-selected,aria-pressed,aria-controls), et des anneaux de focus clavier.
Index des composants
| Composant | Fichier de spécification | Objectif | Contrat clé |
|---|---|---|---|
| 1. ThemeToggle | components/theme-toggle.md | Sélecteur de thème Clair/Sombre sans FOUC et avec morphing SVG | Script <head> en ligne + mappage de jetons OKLCH |
| 2. MobileNavDrawer | components/mobile-nav-drawer.md | Tiroir de navigation accessible coulissant avec hamburger animé | Cibles tactiles 48px, fermeture avec Échap, pas de flou GPU |
| 3. SearchBar | components/search-bar.md | Champ de recherche côté client avec bouton d'effacement et annonceur en direct | rAF debouncing (INP optimal), aria-live, coordinateur d'événements personnalisé |
| 4. FilterChips | components/filter-chips.md | Barre de filtres à puces multi-catégories avec états pressés accessibles | role="group", aria-pressed, coordinateur d'événements personnalisé |
| 5. SearchFilterBar | components/search-filter-bar.md | Modèle composé combinant SearchBar et FilterChips | Barre d'outils empilée pré-composée, dispositions flex multi-colonnes, portée partagée |
| 6. AccessibleModal | components/accessible-modal.md | Superposition de dialogue accessible utilisant le <dialog> HTML5 natif | Calque supérieur natif, clic en arrière-plan, touche Échap, restauration du focus |
| 7. AccessibleAccordion | components/accessible-accordion.md | FAQ/Accordéon natif avec expansion de grille CSS fluide | <details name="..."> natif, 0 Ko JavaScript |
| 8. AccessibleTabs | components/accessible-tabs.md | Sélecteur d'onglets WAI-ARIA pour niveaux de prix ou vues multi-panneaux | Navigation clavier par flèches (Gauche/Droite/Début/Fin) |
| 9. SocialShare | components/social-share.md | Barre de partage social respectueuse de la vie privée avec API Web Share | 100 % conforme RGPD, 0 traqueurs, URL d'intention statiques |
| 10. TableOfContents | components/table-of-contents.md | Table des matières pour articles longs avec scrollspy | Suivi des titres par IntersectionObserver, s'associe à une mise en page d'article |
| 11. AccessibleCarousel | components/accessible-carousel.md | Curseur à défilement CSS natif pour avis, cartes ou logos | Glissement tactile natif (0 Ko JS), boutons Précédent/Suivant accessibles |
| 12. InfiniteTicker | components/infinite-ticker.md | Bandeau infini CSS pur pour logo/texte avec pause au survol/focus | Conforme WCAG 2.2.2, piste dupliquée masquée avec aria-hidden |
| 13. StatsCounter | components/stats-counter.md | Barre de compteur de métriques priorisant HTML avec animation de défilement ease-out | 0 CLS, repli HTML statique, IntersectionObserver |
| 14. AddToCalendar | components/add-to-calendar.md | Lien "Ajouter au calendrier" vers un fichier iCalendar généré à la construction | .ics statique de même origine + <a download>, RFC 5545 valide, 0 Ko JS |
| 15. SelfHostedMap | components/self-hosted-map.md | Carte des lieux d'une liste à partir d'un extrait PMTiles auto-hébergé ; marqueurs numérotés correspondent à la liste | MapLibre paresseux, route de tuiles HTTP 206, carte aria-hidden avec équivalents textuels, suit le thème. Nécessite des paquets npm (approbation du propriétaire) |
| 16. ClickableParent | components/clickable-parent.md | Carte/ligne entière cliquable via un seul lien ou bouton réel | Zone de hit étirée ::after, contrôles secondaires relevés, anneau de focus sur le conteneur, 0 Ko JS |
| 17. Card | components/card.md | Carte de contenu avec média, métadonnées, corps et actions secondaires | DOM avec titre en premier, prop headingLevel, mise en page par requête de conteneur, contrat ClickableParent lorsqu'elle est liée |
Porte de décision pour les composants non catalogués (point de décision humain)
Lorsqu'une exigence de projet ou un design nécessite un composant d'interface interactif qui n'est pas l'un des 17 composants catalogués ci-dessus (par exemple : un curseur de comparaison d'images Avant/Après, un sélecteur de date, un sélecteur de plage, un assistant d'étapes, ou un lecteur multimédia personnalisé) :
[!IMPORTANT] ARRÊTEZ ET DEMANDEZ : L'agent NE doit JAMAIS installer silencieusement des bibliothèques de framework client (React, Vue, Svelte), importer des paquets npm tiers non vérifiés, ou laisser des blocs d'espace réservé de texte temporaire (ex.
<div class="c-placeholder">).L'agent DOIT faire une pause et présenter au propriétaire du projet trois choix distincts :
- Option A : Composant vanilla personnalisé (Recommandé) : Créer un composant
.astrosur mesure sans dépendance, conforme au Contrat de repli pour composant sur mesure ci-dessous.- Option B : Ligne de base HTML statique : Implémenter une mise en page sémantique purement statique (par exemple, images côte à côte ou cartes empilées standard) avec 0 Ko JavaScript, en omettant entièrement l'amélioration interactive.
- Option C : Adaptation d'un modèle du catalogue : Évaluer si un modèle existant du catalogue peut satisfaire l'exigence (par exemple, adapter
AccessibleModalen visionneuse d'images, ouAccessibleTabsen vue à panneaux étagés).
Le Contrat de repli pour composant sur mesure
Lorsque le propriétaire du projet approuve la construction d'un composant non catalogué (Option A), l'implémentation doit satisfaire ces six règles ; pour les adaptations de framework, utilisez les règles de composition, de dénomination de classes et de jetons du framework pour les points 3–4 :
- HTML sémantique d'abord : Ancrez l'interface sur des éléments HTML standards avant d'écrire du JavaScript (ex.
<input type="range">pour les curseurs,<details>pour la divulgation,<dialog>pour les superpositions). - Zéro dépendance d'exécution externe : Zéro runtime de framework client (pas de React/Vue) et zéro paquet de widgets d'interface tiers. Écrivez du vanilla TypeScript/JavaScript uniquement lorsqu'une interaction navigateur est réellement nécessaire.
- BEM avec espace de noms et propriétés logiques CSS : Utilisez la dénomination BEM standard (
.c-bloc,.c-bloc__element) et les propriétés de mise en page relatives au flux (inline-size,block-size,padding-block,margin-inline,inset). - Jetons avec espace de noms et valeurs de repli : Ne codez jamais en dur des valeurs hexadécimales. Utilisez des jetons sémantiques hôtes ou des propriétés personnalisées avec espace de noms avec des valeurs de repli sensées (
var(--comp-couleur, var(--color-primary))). - Amélioration progressive sans JavaScript : Le composant doit rester lisible, accessible et utilisable lorsque le JavaScript client est désactivé. Utilisez
@media (scripting: none)ou des mises en page de repli CSS natives (par exemple, vues côte à côte ou empilées) afin qu'aucun contenu ne soit masqué. - Conformité WCAG 2.2 AA : Maintenez des cibles tactiles minimales de
44px(2.75rem), des anneaux:focus-visiblevisibles à contraste élevé, des noms accessibles clairs (aria-label,<label>), et assurez 0 violation axe-core.
Conseils de chargement sélectif pour les agents
Lorsque l'utilisateur demande d'implémenter ou de modifier l'un des composants ci-dessus, ne lisez pas l'intégralité du catalogue. Lisez plutôt uniquement le fichier du composant spécifique nécessaire (par exemple components/accessible-carousel.md).
Vérification de l'intégration
Vérifiez la spécification sélectionnée sur la sortie construite/déployée : sémantique et noms, comportement clavier/focus, transitions d'état, traitement sans JavaScript, initialisation répétée et mappage des jetons hôtes. Les règles d'empaquetage autonome s'appliquent uniquement aux composants autonomes ; les frameworks réutilisent leurs primitives. Exécutez la vérification/construction/tests configurés du projet et divulguez les vérifications non disponibles ou les lacunes de couverture. 44px est la convention de taille de cible de cette bibliothèque, pas le seuil WCAG AA lui-même.
Les popups de sélection natifs restent l'interface du navigateur/OS à moins que le propriétaire n'approuve les compromis d'une boîte combinée personnalisée.