core/docs/DESIGN.md

ZEN — Design Language

Document de référence visuelle. Décrit l'apparence, le ressenti et les règles visuelles du produit. Valable pour toute reproduction, quelle que soit la technologie.

---

Philosophie

ZEN est un outil de travail. Pas un produit marketing. L'interface disparaît pour laisser place au contenu.

Un seul principe directeur : ne jamais ajouter un élément sans raison.

Chaque couleur, bordure, espace ou texte supplémentaire doit justifier sa présence. Le doute se résout toujours en faveur de la suppression.

---

Palette

Base

Le produit est noir et blanc. Pas de couleurs de marque, pas de teintes bleues ou violettes dans les fonds. Le fond est blanc pur. Le texte est presque noir.

Accents sémantiques

Quatre couleurs uniquement. Utilisées avec grande parcimonie — pour les statuts, les alertes, les deltas. Jamais comme couleur décorative. Jamais sur un fond.

Couleur	Usage
Bleu	Information, liens, action principale
Vert	Succès, actif, delta positif
Ambre	Avertissement, en attente, brouillon
Rouge	Erreur, danger, suppression, delta négatif

Chaque couleur existe en trois déclinaisons : la couleur elle-même (pour le texte), un fond très pâle, et une bordure légère. Ces trois valeurs forment toujours un ensemble — on ne mélange pas les déclinaisons de couleurs différentes.

Ce qu'on n'utilise pas

• Dégradés
• Couleurs de fond dans la sidebar ou les sections (sauf hover/actif)
• Couleurs de marque personnalisées
• Transparence et flou (sauf l'overlay des modales)

---

Typographie

Police unique : IBM Plex Sans. Pour les codes, IDs, montants et dates : IBM Plex Mono.

Hiérarchie

Rôle	Taille	Graisse	Notes
Titre de page	20px	600
Titre de section	14–20px	600
Corps de texte	13px	400
Texte secondaire	12px	400	Dans les tableaux, les listes
Labels / captions	12px	400–500
Labels colonnes	11px	500	Uppercase, lettre-espacement +0.04em
Codes / IDs / montants	11–13px	400	IBM Plex Mono

Taille minimale : 11px. En dessous, on ne descend pas.

Règles d'écriture

• Sentence case partout. "Tableau de bord", pas "TABLEAU DE BORD".
• Seule exception : les en-têtes de colonnes de tableau, en majuscules petits.
• Texte court et direct. Pas de phrase là où un mot suffit.
• Les montants financiers, les dates ISO et les identifiants sont toujours en monospace.

---

Espace

Base : 4px. Tout espacement est un multiple de 4.

Valeur	Usage typique
4px	Espacement interne minimal (gap entre icône et texte)
8px	Padding compact, gap entre éléments proches
12px	Padding interne des petits composants
16px	Padding standard des cartes et panneaux
24px	Espacement entre sections
32px	Padding latéral du contenu principal
48–64px	Espacement entre blocs majeurs

La densité est moyenne. Pas étouffant, pas aéré. Un admin est un outil qu'on utilise plusieurs heures par jour — la densité confortable prime sur l'esthétique aérée.

---

Formes et bordures

Rayon de bordure

Contexte	Rayon
Badges, étiquettes, petits éléments	Complet
Boutons, champs de saisie	8px
Modales, panneaux flottants importants, tableau, cartes	12px
Avatars, indicateurs ronds	Cercle complet

12px est le rayon standard. On ne mélange pas les rayons dans un même composant.

Bordures

Toutes les séparations sont des bordures 1px solid. Pas d'ombres sur les cartes et surfaces statiques. Pas de lignes de 2px ou plus.

Les ombres existent uniquement pour les éléments qui flottent au-dessus de l'interface : menus déroulants, modales, toasts. Elles sont discrètes — juste assez pour indiquer la profondeur.

---

Structure de l'admin

┌─────────────────────────────────────────────┐
│ Sidebar 230px    │ Barre supérieure 48px      │
│                  ├─────────────────────────── │
│  Logo            │                            │
│                  │   Zone de contenu          │
│  Nav principale  │   padding 28px / 32px      │
│                  │                            │
│  ──────────────  │                            │
│  Paramètres      │                            │
└─────────────────────────────────────────────┘

• Sidebar : fixe, 230px. Fond blanc (#ffffff). Séparée par une bordure droite.
• Barre supérieure : fixe, 48px. Fond blanc. Fil d'Ariane à gauche, utilisateur à droite.
• Contenu : gris très pâle (#fafafa / neutral-50). Les cartes et tableaux ont un fond blanc, ce qui crée naturellement la séparation visuelle sans avoir besoin de bordures de section. Sur thème sombre le fond deviens noir est le boite sont grise.

---

Navigation sidebar admin

Structure

La sidebar fait 230px de large, fixe. Fond blanc / noir complet en sombre. Séparée du contenu par une bordure droite 1px.

Elle se compose de trois zones verticales :

1. Logo — hauteur 48px, aligné sur la barre supérieure. Séparé par une bordure basse.
2. Navigation principale — défile si nécessaire. Padding 8px autour des items.
3. Items épinglés en bas — optionnels. Séparés par une bordure haute. Jamais dans la zone défilable.

Items de navigation

Deux types d'items coexistent :

• Lien direct : section avec un seul item dont le nom est identique au titre de la section. S'affiche comme un lien simple, sans chevron.
• Section accordéon : section avec plusieurs items. Un bouton parent déploie ou replie les sous-items.

États visuels

État	Apparence
Inactif	Texte neutral-500 (sombre : neutral-400), fond transparent
Hover	Fond neutral-100 (sombre : neutral-900), texte neutral-900 (sombre : blanc)
Actif replié	Fond neutral-100 (sombre : neutral-900), texte noir (sombre : blanc), graisse 500
Actif ouvert (parent)	Pas de fond, texte noir (sombre : blanc), graisse 500 — le fond actif est sur le sous-item
Sous-item actif	Fond neutral-100 (sombre : neutral-900), texte noir (sombre : blanc), graisse 500

Gabarit d'un item

• Padding : 7px vertical, 10px horizontal.
• Rayon : 8px.
• Icône à gauche, 15×15px, flex-shrink-0. Gap icône–texte : 8px.
• Texte : 13px.
• Transition : 120ms ease-out.
• Badge numérique (optionnel) : à droite, fond rouge, texte blanc, 10px, rayon 8px.

Sous-items

Pas d'icône. Indentation via padding-left: 25px. Même gabarit que les items parents.

Accordéon

Le chevron (12×12px) est à l'extrême droite du bouton parent. Il pivote de -90deg quand la section est repliée, revient à 0deg quand elle est ouverte. L'animation du conteneur : max-height + opacity, 120ms ease-out.

Une section s'ouvre automatiquement au chargement si elle contient l'item actif courant. Toutes les autres sont repliées par défaut.

Mobile

En dessous de 1024px, la sidebar sort du flux et se positionne en fixe sur toute la hauteur. Elle est masquée par défaut (translate-x: -100%) et s'ouvre via un bouton externe. Un overlay semi-transparent (black/50) couvre le contenu derrière. Cliquer l'overlay ou naviguer vers un lien ferme la sidebar. Au redimensionnement au-delà de 1024px, la sidebar mobile se ferme automatiquement.

---

Boutons

Sept variantes :

Variante	Apparence	Usage
Primaire	Fond neutral-900, texte blanc	Action principale de la page
Secondaire	Fond transparent, bordure neutral-300, texte neutral-700	Actions secondaires, annulation
Fantôme	Fond transparent, pas de bordure, texte neutral-600	Actions tertiaires
Fantôme plein	Identique au fantôme, sans focus ring	Boutons très discrets dans des zones déjà interactives
Danger	Fond rouge très pâle, bordure rouge pâle, texte rouge	Suppression, actions destructives
Succès	Fond vert très pâle, bordure verte pâle, texte vert	Confirmation, validation
Avertissement	Fond ambre très pâle, bordure ambre pâle, texte ambre	Alertes, actions risquées

Il ne doit jamais y avoir plus d'un bouton primaire par section ou en-tête de page.

Tailles

Taille	Padding horizontal	Padding vertical	Texte
sm	10px	5px	12px
md	12px	7px	13px
lg	14px	9px	14px

La taille par défaut est md.

Icônes et chargement

• Une icône peut se placer à gauche ou à droite du texte.
• Un bouton icône seule (sans texte) a un padding uniforme.
• L'état de chargement remplace le contenu par un spinner et désactive l'interaction.
• L'état désactivé : opacité 50 %, curseur interdit.

Règles communes

• Rayon : 8px (rounded-lg).
• Transition : 120ms, ease-out.
• Focus : anneau fin de la couleur de la variante.

---

Cartes et panneaux

• Fond blanc.
• Bordure 1px.
• Rayon 12px (rounded-xl).
• Padding interne 16–20px.
• Pas d'ombre.
• En-tête interne séparé du contenu par une bordure horizontale.
• Pied de panneau (actions de formulaire) séparé par une bordure horizontale.

---

Tableaux

• En-têtes de colonnes : texte 11px uppercase, couleur secondaire.
• Lignes : fond blanc. Hover : fond légèrement grisé.
• Bordure horizontale entre chaque ligne. Pas de bordure sur la dernière ligne.
• Données numériques, IDs, dates : IBM Plex Mono.
• Actions (modifier, supprimer) : à l'extrême droite, boutons icône discrets.
• Pas de fond alterné sur les lignes.

---

Badges de statut

Petits éléments inline qui indiquent un état. Toujours composés de trois éléments : fond pâle de la couleur sémantique, bordure légère, texte de la couleur sémantique.

Rayon : full. Taille du texte : 11px.

---

États interactifs

État	Apparence
Hover	Fond légèrement plus sombre (4–5% de gris)
Actif / focus	Bordure de 1px devient la couleur du texte principal
Désactivé	Opacité 50%, curseur interdit
Chargement	Pas défini — à traiter au cas par cas

Toutes les transitions durent 120ms, courbe ease-out. Aucune animation décorative.

---

Ce qu'on n'utilise jamais

• Dégradés de couleur sur les fonds ou les boutons
• Cartes avec une bordure colorée uniquement sur le côté gauche
• Ombres internes
• Texte en gras uniquement pour l'emphase décorative
• Icônes sans fonction claire
• Statistiques ou chiffres inventés pour remplir l'espace
• Couleurs de fond dans les sections de contenu

---

Thème sombre

Le thème sombre est une inversion calibrée : les fonds passent au noir complet puis les zone par dessus sont noir-gris, les textes s'éclaircissent, les accents gagnent légèrement en luminosité pour rester lisibles. La structure, les espaces et les proportions restent identiques.