Files
Esiah 858d862fed
deploy / deploy (push) Canceled after 0s
feat: init repo
2026-11-10 19:56:03 +01:00

187 lines
8.7 KiB
Markdown

# @cohaise/ui
Design system partagé de l'écosystème CoHaiSe. Point d'entrée unique des jetons de style
utilisés par `frontend/web`, `frontend/crm` et `frontend/cloud`, garantissant une identité visuelle
homogène et la thématisation dynamique clair/sombre.
## Couche de jetons
Ce paquet expose une chaîne CSS en trois fichiers, du plus primitif au plus dérivé.
| Fichier | Rôle |
|---|---|
| `src/styles/tokens.css` | Variables CSS brutes (`--cohaise-*`). Échelle de gris en `oklch`, jetons sémantiques, ombres, typographie, rayons, courbes et durées de mouvement. |
| `src/styles/theme.css` | Directive `@theme inline` mappant les variables brutes vers les utilitaires Tailwind (`bg-surface`, `text-muted-foreground`, `border-border`...). |
| `src/styles/index.css` | Point d'entrée, importe les deux fichiers ci-dessus. |
### Mouvement
Tailwind v4 ne réserve pas de namespace de thème aux durées : `duration-*` est un
utilitaire à valeur nue. Les trois durées sont donc exposées via `@utility` dans
`theme.css`, adossées aux jetons `--cohaise-duration-*`.
`--default-transition-duration` et `--default-transition-timing-function` sont
également déclarés, si bien que toute classe `transition-*` hérite du mouvement du
design system sans avoir à le répéter :
```css
.transition-colors {
transition-timing-function: var(--tw-ease, var(--cohaise-ease-out-soft));
transition-duration: var(--tw-duration, var(--cohaise-duration-base));
}
```
Les utilitaires `duration-fast`, `duration-base`, `duration-slow` et `ease-out-soft`
surchargent ces valeurs au cas par cas.
### Chaîne de résolution
```mermaid
flowchart TD
A["tokens.css<br/>--cohaise-gray-*, --cohaise-crimson-*"] --> B["tokens.css<br/>--cohaise-background, --cohaise-border, ..."]
B --> C["theme.css<br/>@theme inline"]
C --> D["Tailwind CSS<br/>compile les utilitaires"]
D --> E["frontend/web · frontend/crm · frontend/cloud"]
F["Classe .dark sur &lt;html&gt;"] -.->|surcharge les jetons sémantiques| B
```
L'échelle de gris et l'échelle carmin sont les seules sources de vérité des couleurs
brutes. Les jetons sémantiques n'y font référence que par `var()`, jamais par une valeur
littérale, sauf pour les statuts (`success`, `warning`, `info`) et l'ombre carmin, qui
n'existent que dans le mode sombre.
La source de vérité du rouge est `--clr-accent` du site, soit `#b71c1c`, et non le
carmin `#c3073f` qui apparaît davantage dans la feuille de style compilée. Les deux
valeurs ont été retenues à un moment de la construction du thème : le carmin est plus
vif, la valeur déclarée plus profonde et moins magenta. Sur un outil de gestion de
fichiers, c'est la seconde qui tient le mieux sur de grandes surfaces.
## Couleurs
Les valeurs viennent de `esiah.dev`. Le fond sombre est un noir à dominante rouge
(`#050000`), pas un gris neutre, et l'accent est le carmin `#b71c1c`.
| Rôle | Clair | Sombre |
|---|---|---|
| Fond | `#f7f5f4` | `#050000` |
| Surface | `#ffffff` | `#1a0505` |
| Surface surélevée | `#ffffff` | `#1e1e22` |
| Texte | `#1a1a1a` | `#f4f4f2` |
| Texte atténué | `#5c5656` | `#a8a0a0` |
| Primaire | `#b71c1c` | `#b71c1c` |
| Accent graphique | `#b71c1c` | `#c92a2a` |
| Filet de séparation | `#e8dcdc` | `#2e1c1c` |
Un seul rouge de marque dans les deux modes, ce qui rend les captures et les
comparaisons d'écran reproductibles. Il n'est appliqué qu'en aplat plein, avec du texte
blanc dessus, où il atteint 6,57:1.
`accent-graphic` est un ton séparé, réservé aux **petits éléments posés sur** une
surface : filet de carte, carré de liste, anneau de focus. Ces éléments sont lus comme
interface et relèvent du seuil de 3:1, or le rouge de marque ne donne que 2,65:1 sur la
surface sombre. Le même raisonnement impose une bordure de champ distincte, à 3,57:1 en
sombre et 3,73:1 en clair.
**Le destructif est ambre, pas rouge.** C'est une décision de lisibilité, pas un goût :
l'accent du site est un rouge, donc un bouton « supprimer » rouge serait confondu avec un
bouton d'accent. `destructive` occupe donc le ton `oklch(0.768 0.188 70)`, déjà présent
dans la palette, et `warning` garde le jaune plus clair. Le prix à payer est que
« supprimer » et « attention » sont proches en teinte ; ils ne se croisent jamais dans le
même écran, et c'est un choix à revoir si l'interface grossit.
**Les bordures de champs de formulaire ont leur propre jeton.** Les bordures
décoratives restent très discrètes, `1.2:1` sur le fond en mode sombre, pour respecter le
grain du site. Un champ de formulaire doit en revanche pouvoir être identifié sans le
remplir ni le survoler, ce que la WCAG 1.4.11 chiffre à `3:1`. `border-control` est
donc nettement plus clair, `3.5:1` en sombre et `3.7:1` en clair, et c'est lui que
`Input` utilise. Les deux valeurs ont été retenues en mesurant le contraste réel plutôt
qu'à l'œil.
## Polices
| Usage | Police | Variable |
|---|---|---|
| Titres, libellés, boutons | Orbitron | `--cohaise-font-display` |
| Texte courant et paragraphes | Poppins | `--cohaise-font-sans` |
| Marque | Orbitron | `--cohaise-font-logo` |
| Accroche courte, registre éditorial | Cinzel | `--cohaise-font-serif` |
| Code | JetBrains Mono et replis | `--cohaise-font-mono` |
Le partage vient du site, où `body` est en Orbitron. Orbitron a une chasse très large : à
32 px, un titre paraît écrit à la main, et un mot-symbole doit être resserré pour ne pas
s'éparpiller. D'où quatre jetons d'interlettrage dédiés, dont un négatif pour les titres.
Orbitron est donc cantonnée aux **chaînes courtes** — titres jusqu'à `h3`, libellés en
capitales, boutons — avec `tracking-label` en positif. Au-delà de `h3`, la chasse est trop
large pour la taille du texte. Le flux est en Poppins. C'est pourquoi `font-display` est
appliqué dans la couche `base` plutôt que laissé au soin de chaque composant : c'est la
seule façon d'éviter qu'un titre revienne en Poppins parce qu'un écran l'a oublié.
Cinzel est conservée en réserve. C'est un bon caractère, mais une serif d'inscription
romaine sur des libellés d'interface ou un paragraphe devient vite illisible, et c'est
précisément ce qui donnait au premier jet de ce thème son aspect de thème généré.
Les trois faces sont **auto-hébergées** dans `frontend/shared/fonts`, 53,6 Ko au total,
soit 30 Ko de moins que Roboto seul. Un appel à Google Fonts aurait fait fuiter l'adresse
IP de chaque visiteur de ton NAS vers un tiers, ce qui n'a pas sa place dans un écosystème
privé.
## Modes clair et sombre
Le mode est piloté par la classe `.dark` appliquée sur `<html>`. `:root` porte le mode
clair, `.dark` surcharge l'ensemble des jetons sémantiques. `color-scheme` est défini
sur les deux blocs pour aligner les contrôles natifs et les barres de défilement.
```mermaid
flowchart LR
subgraph Light["`:root` — mode clair"]
LA["--cohaise-background<br/>#f7f5f4"]
LB["--cohaise-foreground<br/>#1a1a1a"]
LC["--cohaise-primary<br/>#b71c1c"]
end
subgraph Dark["`.dark` — mode sombre"]
DA["--cohaise-background<br/>#050000"]
DB["--cohaise-foreground<br/>#f4f4f2"]
DC["--cohaise-primary<br/>#b71c1c"]
end
Light -->|bascule de classe| Dark
```
Aucune règle `@media (prefers-color-scheme)` n'est déclarée : la bascule est
explicite, ce qui garantit un comportement unique quelle que soit la préférence
système.
## Forme
Les rayons sont quasi nuls, de 2 à 6 px, contre 4 à 12 px pour les valeurs par défaut de
Tailwind. Les tuiles à coins arrondis sont la signature la plus immédiate d'une interface
sans intention, et un registre d'instrument se lit dans l'angle autant que dans la
couleur.
Trois marques complètent le registre : un filet carmin d'un pixel en tête de `Card`, un
carré plein de 6 px devant chaque élément de liste au lieu d'une puce ronde, et des
libellés en capitales espacées. Aucune n'est décorative au sens strict : elles servent à
séparer des blocs sans ajouter de bordure lourde, et à rendre les métriques denses
scannables.
## Consommation
```css
@import "tailwindcss";
@import "@cohaise/ui/styles";
```
L'application conserve la main sur la directive `tailwindcss` et sur sa configuration ;
ce paquet ne fournit que les jetons. Le build Vite résout l'entrée via le champ
`exports` du `package.json`.
## Contraintes
- Aucune valeur de couleur littérale n'est autorisée dans les composants : uniquement
des utilitaires derivés des jetons sémantiques, sinon la thématisation casse.
- `@theme inline` est obligatoire plutôt que `@theme`, car les utilitaires doivent
référencer la variable pour résoudre la valeur au changement de mode.
- Aucune durée ne doit être écrite en dur dans un composant (`duration-150` est
interdit) : passer par `duration-fast`, `duration-base` ou `duration-slow`.