- 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
7.8 KiB
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.cssdoit 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. SkeletonetSpinnersont prévus pour les états de chargement ; ne pas réinventer un spinner.
Thème
- Bascule clair/sombre par la classe
.darksur<html>. - Script inline dans
frontend/web/app/layout.tsx(avant le bundle) : litlocalStorage["cohaise-theme"], sinonprefers-color-scheme. C'est lui qui évite le flash de thème. color-scheme: light darkdéclaré pour les contrôles natifs.- Toute règle sombre va dans le bloc
.darkdetokens.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 dansapp/lib/site.tspour 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>posedata-regionetmin-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-delayetuseScrollReveal(délai par région viadata-region-delay) ; ne pas animer un élément sans prévoir son état sans JS. next buildproduitout/(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 parsetPendingSection/sessionStoragepuis est rejointe après le retour à/.scrollToSectionsuspend 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 parscrollToSection, 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èglesection[data-region]:only-childdansglobals.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) portentmin-h-0+overflow-auto. Ne pas retirermin-h-0d'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 sousmd. 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 utilisentRowActionButton. - Les pictogrammes viennent des WebP du dépôt, rendus par
MaskIcondanscomponents/icons.tsx:FolderMaskIcon/UsersMaskIcon/ActivityMaskIconpour le rail,PenMaskIcon,TrashMaskIcon,SearchMaskIcon,CloseMaskIcon,LogoutMaskIconpour les actions. Le masque CSS +background-color: currentColorpermet 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.tsxne garde que les flèches (ChevronDownGlyph,ArrowUpGlyph). - L'en-tête du CRM porte
.glass(défini danstheme.css, commun à la vitrine et au CRM) ; la surface de travail reste sans flou etDataTableporte son propre fond translucide (bg-surface/80 backdrop-blur-xl), avec un en-tête sticky à/90pour garder le texte lisible quand les lignes passent dessous. - Les champs (
Inputpartagé, selects, recherche) réagissent au survol par un bord accent ; le bouton de déconnexion est une icône seule (LogoutMaskIcon) avecaria-labelettitle, 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
dbet des données déjà typées ; il lèveAppErrorpour 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
mainunique, remoteoriginsurgit.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 lignedocs/de.gitignorea é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 |