Patterns & guidelines

Les règles d'usage qui garantissent une expérience cohérente entre les modules. Toute nouvelle vue doit respecter ces principes.

Quand utiliser quoi

Button
Link
Action → Button. Navigation → Link.
Dialog
Sheet
Confirmation courte → Dialog. Formulaire long ou détails → Sheet (slide latéral, mobile-friendly).
Toast
Alert
Feedback transitoire → Toast (Sonner). Information persistante ou bloquante → Alert.
Select
Combobox
< 10 options fixes → Select. Recherche / liste longue → Combobox (cmdk).
Tabs
Accordion
Vues équivalentes → Tabs. Sections optionnelles à révéler → Accordion.
DataTable
CardList
Desktop dense → Table. Mobile / tablette terrain → CardList (cf. Responsive).

Responsive — Mobile-first

Toutes les vues se conçoivent d'abord pour 375px (iPhone SE), puis montent en breakpoint. Audits HSE = tablette terrain prioritaire.

sm:
640px
Mobile large / phablet
md:
768px
Tablette portrait
lg:
1024px
Tablette paysage / laptop
xl:
1280px
Desktop standard
Pattern DataTable → CardList : en < md, remplacer une table dense par une liste de cards verticale avec les 3-4 infos clés et un bouton d'expansion vers le détail.

Accessibilité (A11y)

  • ✓ Contraste AA minimum sur tous les couples token + token-foreground.
  • ✓ Focus visible sur tous les éléments interactifs (ring du token --ring).
  • ✓ Cibles tactiles ≥ 44 × 44 px sur mobile/tablette (audits terrain).
  • ✓ ARIA correct : tous les composants Radix exposent les bons rôles. Ne pas réinventer.
  • ✓ Labels explicites sur les boutons icône (aria-label).
  • ✓ Skip links et navigation clavier sur les pages publiques.

Règle d'or des tokens

Jamais de couleur brute (text-white, bg-black, #1a1a1a) dans un composant. Toujours un token sémantique. Si un token manque, l'ajouter dans src/styles.css d'abord.

Modules embarqués (iframe + platformBridge)

Les modules MultiSaaS peuvent être chargés en iframe via le PlatformBridge.

  • ✓ Origin allowlist stricte côté SaaS embarqué (jamais postMessage('*') après init).
  • ✓ Token + tenant injectés via PLATFORM_INIT puis ajoutés à chaque fetch (interception).
  • ✓ Notifications remontent via SAAS_NOTIFICATION / SAAS_TASK_COMPLETE.
  • ✓ Recherche globale Cmd+K : enregistrer un handler via platformBridge.onGlobalSearch().
  • Référence complète : docs/saas-integration/README.md

Motion

  • ✓ Transitions ≤ 300ms pour les interactions (hover, focus, toggle).
  • ✓ Animations entrée/sortie via tw-animate-css (déjà intégré aux composants Radix).
  • ✓ Animations narratives via framer-motion pour le marketing uniquement, pas dans les modules métier.
  • ✓ Respect de prefers-reduced-motion sur les animations longues.