Files
CoHaiSe/docs/standards.md
T
Esiah 09cf07d79b feat: migrate showcase to Next.js and overhaul CRM UI
- rebuild the public site on the Next.js App Router with static export,
  per-section SEO pages, metadata, sitemap, robots and a generated OG image
- add full-screen scroll-snap regions, staged scroll reveals, a hash-free
  tab navigation with a sliding indicator and region-by-region menu scrolling
- replace the theme text toggle with animated sun/moon icons
- restructure the CRM API into config, middleware, models, routes, services
  and utils layers
- redesign the CRM shell with a single surface, tab rail, full-width blurred
  DataTable, record dialogs and mask-based icons
- update Docker/Nginx publishing, Makefile targets, shared UI polish and docs
2026-11-16 00:52:29 +01:00

7.8 KiB

Standards — CoHaiSe Web

Conventions à respecter pour que ce dépôt reste cohérent avec les deux autres (CoHaiSe-CLOUD, CoHaiSe-CRM), qui partagent le même design system.

Formatage

.editorconfig fait foi :

Réglage Valeur
Charset UTF-8, fin de ligne LF
Indentation 2 espaces (pas de tabs)
trim_trailing_whitespace false pour *.md, vrai ailleurs

Aucun Prettier n'est installé : l'éditeur et l'.editorconfig sont la seule norme mécanique. ESLint a été retiré de frontend/web : typescript-eslint ne supporte pas encore TypeScript 7.0. Ne pas le réintroduire tant que ce support n'existe pas.

Palette

Source unique : frontend/shared/src/styles/tokens.css.

Jeton Rôle Valeur
--cohaise-accent accent de marque (liens, focus, éléments primaires) carmin #b71c1c (crimson-700)
--cohaise-destructive suppression, erreurs, champs invalides #d32f2f clair / #ef4444 sombre
--cohaise-destructive-foreground texte posé dessus #ffffff clair / #1a0505 sombre
--cohaise-warning avertissement, badges d'état jaune yellow-500
--cohaise-surface, --cohaise-background fonds gris chaud #f7f5f4 / #050000

Règles :

  • L'orange n'existe plus : --cohaise-amber-* a été retiré. Ne pas le réintroduire — le rouge a remplacé l'ambre sur le bouton destructif pour des raisons de contraste (≥4.5:1 en clair comme en sombre).
  • Ne pas dériver la palette dans un seul dépôt : tokens.css doit rester identique partout.
  • Toute nouvelle couleur doit être lisible comme texte sur le fond d'application ET comme fond avec un texte posé dessus. Vérifier les deux cas.

Typographies

Chargées en local (frontend/shared/fonts/*.woff2), jamais par CDN :

Usage Police
Texte courant Poppins 400/600
Titres display Orbitron, Cinzel
Code / monospace JetBrains Mono

Composants

@cohaise/ui expose Button, Card (+ sous-composants), Input, Skeleton, Spinner et l'utilitaire cn.

  • Un composant partagé ne doit pas connaître le métier d'une app.
  • Une variante visuelle propre à une app se développe dans cette app, pas dans frontend/shared.
  • Skeleton et Spinner sont prévus pour les états de chargement ; ne pas réinventer un spinner.

Thème

  • Bascule clair/sombre par la classe .dark sur <html>.
  • Script inline dans frontend/web/app/layout.tsx (avant le bundle) : lit localStorage["cohaise-theme"], sinon prefers-color-scheme. C'est lui qui évite le flash de thème.
  • color-scheme: light dark déclaré pour les contrôles natifs.
  • Toute règle sombre va dans le bloc .dark de tokens.css, pas en @media (prefers-color-scheme: dark) : la préférence utilisateur prime.

Next.js (vitrine)

  • Tout fichier qui utilise un hook, un événement ou une API navigateur porte "use client" ; les pages et le layout restent des Server Components.
  • Les métadonnées SEO vont dans export const metadata (page ou layout), pas dans un composant client. Une page = une entrée dans app/lib/site.ts pour rester alignée avec le sitemap.
  • Les données statiques vivent dans app/data/. Un objet contenant des fonctions ou des icônes React ne doit jamais traverser la frontière serveur → client : le composant importe la donnée lui-même.
  • Une section = une région plein écran : <Section> pose data-region et min-h-dvh. Ne pas créer de section hors de ce composant, sinon elle échappe au scroll-snap.
  • Les reveals passent par data-reveal / data-reveal-delay et useScrollReveal (délai par région via data-region-delay) ; ne pas animer un élément sans prévoir son état sans JS.
  • next build produit out/ (output: "export"). Ne pas ajouter de route dynamique sans vérifier la compatibilité avec l'export statique.
  • Le menu de l'en-tête est une barre d'onglets, pas une liste d'ancres : aucun # n'est écrit dans l'URL. Sur l'accueil, clic → séquence GSAP région par région et pastille qui glisse vers l'onglet ; ailleurs, la cible passe par setPendingSection/sessionStorage puis est rejointe après le retour à /. scrollToSection suspend le snap (data-scroll-anim) le temps de la séquence, sinon le navigateur saute directement à la destination ; la durée renvoyée prolonge le verrou d'onglet. L'onglet actif suit la région visible (bande centrale) sauf pendant le défilement déclenché par un clic, où il reste sur l'entrée choisie. Une cible imbriquée (About dans la région Stack) est ramenée à sa région par scrollToSection, car le snap opère par région.
  • Les pages SEO autonomes (/services, /about, …) réutilisent une seule région sans pied de page et tiennent dans le viewport (règle section[data-region]:only-child dans globals.css). Ne pas les laisser défiler : le menu est justement là pour ramener aux régions de l'accueil.

Front CRM

  • La page ne défile jamais : le shell est en h-dvh overflow-hidden, et les zones de contenu (DataTable, dialogue) portent min-h-0 + overflow-auto. Ne pas retirer min-h-0 d'un parent flex, sinon le tableau repousse la page.
  • Toute liste passe par components/DataTable.tsx : colonnes triables, recherche, actions de ligne, squelette et cartes sous md. Ne pas recréer un <table> dans une page.
  • Les formulaires de création/édition passent par RecordDialog ; seul son corps défile. Les boutons d'action de ligne utilisent RowActionButton.
  • Les pictogrammes viennent des WebP du dépôt, rendus par MaskIcon dans components/icons.tsx : FolderMaskIcon/UsersMaskIcon/ActivityMaskIcon pour le rail, PenMaskIcon, TrashMaskIcon, SearchMaskIcon, CloseMaskIcon, LogoutMaskIcon pour les actions. Le masque CSS + background-color: currentColor permet au survol de les teinter en accent ou en destructif sans filtre. Ne pas revenir à un <img> : les fichiers sont blancs et disparaîtraient sur fond clair. components/glyphs.tsx ne garde que les flèches (ChevronDownGlyph, ArrowUpGlyph).
  • L'en-tête du CRM porte .glass (défini dans theme.css, commun à la vitrine et au CRM) ; la surface de travail reste sans flou et DataTable porte son propre fond translucide (bg-surface/80 backdrop-blur-xl), avec un en-tête sticky à /90 pour garder le texte lisible quand les lignes passent dessous.
  • Les champs (Input partagé, selects, recherche) réagissent au survol par un bord accent ; le bouton de déconnexion est une icône seule (LogoutMaskIcon) avec aria-label et title, jamais un libellé visible.

Backend CRM

  • Une route valide l'entrée (Zod), appelle un service, renvoie le statut HTTP. Aucune requête SQL directement dans routes/.
  • Un service reçoit db et des données déjà typées ; il lève AppError pour les cas métier (404, 409, 422) et laisse remonter le reste.
  • Les noms de colonnes SQL restent dans les services et models/types.ts ; l'API expose ses propres champs.
  • Les erreurs de contrainte MariaDB passent par utils/dbErrors.ts (1062, 1451, 1452), jamais par une comparaison de message.

Git

  • Branche main unique, remote origin sur git.cohaise.dev.
  • Pas de convention de message imposée par l'historique (dépôt neuf).
  • N'exclure de git que : .env* (sauf .env.example), node_modules/, dist/, .next/, out/, *.log, backups/.
  • docs/ est versionné (la ligne docs/ de .gitignore a été retirée).

Interdépôts

Élément Attendu
frontend/shared/src/styles/tokens.css identique (même md5sum)
Composants @cohaise/ui dupliqués, peuvent diverger
Ports web 8080, CRM 8082, Cloud 8083
Remotes un dépôt Git autonome par app, aucun lien de code entre eux