Utilisation
Atomes, molécules, organismes — à quelle couche appartient votre nouvelle UI, et les règles de passage entre elles.
Les trois couches
Chaque élément d’UI ePassLive appartient à exactement une couche. La décision porte sur qui compose qui :
Atomes — primitives que les consommateurs composent
Les plus petites unités autonomes : boutons, champs, badges, avatars, tags. Un atome possède un élément DOM, ses jetons et son contrat d’accessibilité. Il ne récupère jamais de données et ne connaît jamais les autres atomes.
Exemples : Button, Input, Badge, Avatar, Tag, Switch
Molécules — composites d’UI réutilisables
Des compositions d’atomes avec un peu de comportement : étiquette + champ + erreur (FormField), champ de recherche + liste de résultats (SearchSelect), déclencheur + listbox (Dropdown). Les molécules restent agnostiques du domaine — elles affichent des props, pas des entités métier.
Exemples : FormField, SearchSelect, Dropdown, DateRangePicker
Organismes — sections de fonctionnalité
Des sections au niveau fonctionnalité composées de molécules et d’atomes : en-têtes de page, cartes d’événement, tableaux de données, résumés de paiement. Les organismes peuvent se lier aux modèles de domaine et aux types du SDK Medusa — c’est la première couche autorisée à savoir ce qu’est un « événement ».
Exemples : Header, EventCard, CartSummary, StatsTable
Le problème des jumeaux splités entre couches
Certains motifs existent deux fois : une molécule placeholder documentée dans patterns.ts et un véritable organisme qui a grandi dans le storefront. Quand vous trouvez un jumeau :
• Le code implémenté gagne — l’entrée du catalogue doit être corrigée pour décrire ce qui est réellement livré (ou marquée planned/deprecated).
• S’ils existent légitimement tous les deux, la molécule reste agnostique du domaine et l’organisme la compose — l’organisme ne réimplémente jamais les internes de la molécule.
• Documentez la résolution dans l’ADR ; la porte de cohérence documentaire (pnpm ds:consistency) continuera de signaler la paire tant que le catalogue ne correspond pas à la réalité.
Le motif de promotion
La croissance suit une seule direction : atomes → molécules → organismes. Un composite qui apparaît dans trois organismes ou plus est promu en molécule ; une molécule devenue consciente du domaine est en réalité un organisme et devrait déménager. La rétrogradation (découpage d’une couche) exige un ADR.
La promotion est additive : l’ancienne couche garde une note de dépréciation pointant vers le nouvel accueil pendant au moins une version mineure.
La règle du double import
Importez depuis le barrel uniquement. Les imports profonds dans packages/design-system/src/... sont interdits par le lint (ils cassent le contrat d’API publique et le build Docker standalone) :
✓ Import barrel
import { Button, Card, Avatar } from '@epasslive/design-system'✗ Import profond (interdit)
import { Button } from '@epasslive/design-system/dist/components/atoms/Button/Button'Exemple guidé — une carte de fonctionnalité
Vous devez afficher un producteur avec son avatar, son nom et ses statistiques. Trois implémentations candidates :
| Composition | Couche | Pourquoi |
|---|---|---|
Avatar + Card | atomes | Si le consommateur assemble lui-même la disposition à chaque fois, les atomes restent intacts — aucun nouveau code DS requis. |
UserCard = Card + Avatar + Name | molécule | Dès que le même assemblage se répète, promouvez-le en molécule agnostique du domaine. Elle prend des props (avatarSrc, name, meta) et affiche des atomes. |
ProfileHeader = UserCard + stats | organisme | Quand les données de domaine (statistiques de revenus, état de règlement) entrent en jeu, cela devient un organisme qui récupère/mappe et compose UserCard. |
Règle empirique : les atomes affichent des props nommables en un mot ; les molécules, en une phrase ; les organismes affichent des modèles de domaine.