design-system/PROTOCOLE.md

# PROTOCOLE — design system trans-former.fr

La « matrice » : les règles que tout site de la constellation applique. Un build n'est pas fini tant que la Definition-of-Done en bas n'est pas cochée.

## 1. Mobile-first — règle de base

- Les styles de base ciblent **360px**. On monte ensuite avec des media queries **`min-width` uniquement** (jamais `max-width` pour la structure ; une exception encadrée : l'état hamburger de la Nav).
- Typographie **fluide** en `clamp()` — l'échelle `--fs-*` est calibrée entre 360px et 1280px, ne pas la redéfinir par breakpoint.
- Cibles tactiles **≥ 44px** (boutons, liens de nav, toggles). Sur `pointer: coarse`, aucune taille ne descend en dessous.

### Breakpoints — constantes

Les variables CSS ne fonctionnent pas dans `@media` : ces valeurs sont des **constantes de la constellation**, à utiliser telles quelles partout.

| Nom | px | rem | Usage type |
|-----|----|-----|------------|
| base | 360 | — | styles par défaut (pas de media query) |
| sm | 480 | 30rem | ajustements petits écrans larges |
| md | 768 | 48rem | passage nav inline, grilles 2-3 col |
| lg | 1024 | 64rem | layouts larges |
| xl | 1280 | 80rem | plafond de l'échelle fluide |

Écrire les media queries en **rem** (`@media (min-width: 48rem)`).

## 2. Motion charter

- **Motion piloté-utilisateur** : toute animation répond à une action (scroll, hover, focus, clic). **Jamais d'auto-play** — pas de carrousel automatique, pas d'animation en boucle — sans pause au survol/focus **et** contrôles visibles.
- `@media (prefers-reduced-motion: reduce)` **coupe tout mouvement non essentiel**. Le kill-switch global est dans `reset.css` ; tout JS d'animation doit aussi tester `matchMedia("(prefers-reduced-motion: reduce)")` (cf. `js/reveal.js`).
- **Budget reveal** : fade + translate court (≤ 12px), durées `--dur-base`/`--dur-slow` max, easing `--ease-out`. Pas de zoom, pas de rotation, pas de parallaxe décorative.
- Le JS est **progressif** : sans JS, rien n'est masqué, rien n'est cassé (garde `html[data-js]`).

## 3. Lois design (anti-patterns) — appliquées sans exception

- ❌ `border-left`/`border-right` > 1px colorée comme accent (card, callout)
- ❌ gradient text (`background-clip: text`)
- ❌ glassmorphisme décoratif par défaut
- ❌ template hero-metric (grand chiffre + petit label + gradient accent)
- ❌ grilles de cards identiques icon+heading+text
- ❌ modal comme premier réflexe UX
- ❌ em-dashes (`—` / `--`) dans les textes UI
- ❌ Inter par défaut sans raison
- ❌ gradients violets sans justification
- ❌ dark glow décoratif

## 4. Tokens — conventions de nommage

- Nommage par **rôle**, jamais par couleur brute : `--primary`, pas `--green`. Un thème peut changer toute la palette sans toucher un composant.
- Préfixes d'échelle : `--fs-*` (font-size), `--lh-*` (line-height), `--fw-*` (weight), `--space-*`, `--radius-*`, `--shadow-*`, `--dur-*`, `--ease-*`, `--z-*`.
- Paires de contraste : `--primary`/`--on-primary`, `--accent`/`--on-accent`. Toujours utiliser le `on-*` correspondant comme couleur de texte sur ces fonds.
- **Layers** : `tokens.css` vit dans `@layer tf-tokens`, `reset.css` dans `@layer tf-reset`. Les thèmes et le CSS des sites restent **non-layerés** → ils gagnent toujours sur la fondation, quel que soit l'ordre de chargement. Ne jamais mettre un thème dans un layer. (Exception voulue : le kill-switch reduced-motion du reset est en `!important` layeré, il bat donc tout le monde.)
- Le schéma (noms + échelles) est **universel** et gelé : en ajouter demande une mise à jour ici + dans `tokens.css` + dans les thèmes. En retirer/renommer = breaking change pour tous les sites.
- **Tailwind 4** (site racine) : les tokens sont mappés via `tailwind.css` (`@theme inline`). Les namespaces en collision de nom (`--font-*`, `--radius-*`, `--shadow-*`, `--ease-*`) s'utilisent en syntaxe var arbitraire : `rounded-(--radius-md)`, `shadow-(--shadow-md)`, `ease-(--ease-out)`, `font-(family-name:--font-heading)`.

## 5. Ajouter un thème (nouveau site)

1. `cp theme/base.css theme/mon-site.css`
2. Remplacer palette claire, palette sombre (bloc `[data-theme="dark"]` **et** duplication `@media (prefers-color-scheme: dark)` avec le garde `:not([data-theme="light"])`), et les deux stacks de polices.
3. Ne toucher à **rien d'autre** : pas d'échelles, pas de spacing, pas de motion dans un thème.
4. Vérifier les contrastes **AA** (4.5:1 texte courant, 3:1 grands titres/UI) dans les deux modes — y compris `--on-primary` sur `--primary` et `--on-accent` sur `--accent`.
5. Charger les `@font-face` côté site (self-host / fontsource) ; le thème ne définit que les stacks.
6. L'ajouter à la page démo (`src/pages/demo/mon-site.astro`, 4 lignes) et valider le kitchen sink.

Clair/sombre : mode clair par défaut + sombre via préférence système, le toggle explicite (`data-theme`) **gagne toujours dans les deux sens**. Un site peut être sombre par défaut (cf. `theme/aep.css` : `:root` sombre, variante claire sur `[data-theme="light"]` seulement).

## 6. Accessibilité — socle

- Contraste **AA** partout, dans les deux modes.
- **Focus visible** partout : `:focus-visible` global dans `reset.css`, ne jamais le supprimer sans remplacement équivalent.
- Navigation **clavier** complète : hamburger avec `aria-expanded`/`aria-controls`, fermeture Échap, focus trap panneau ouvert, skip-link (`BaseLayout`).
- `lang` défini sur `<html>` (prop de `BaseLayout`), `aria-current="page"` sur le lien actif, `alt` sur toute image porteuse de sens.

## 7. Definition-of-Done — checklist de fin de build

Avant de déclarer un site « fini » :

- [ ] Testé à **360, 768, 1280** px — aucun débordement horizontal, hiérarchie lisible aux trois tailles.
- [ ] Testé en **clair ET sombre** (préférence système + toggle) — contrastes AA dans les deux.
- [ ] Testé avec **prefers-reduced-motion: reduce** — plus aucun mouvement non essentiel.
- [ ] Testé **sans JS** — contenu et navigation accessibles (liens visibles, rien de masqué).
- [ ] Navigation **clavier seul** : tout est atteignable, focus visible, hamburger Échap + trap OK.
- [ ] Cibles tactiles ≥ 44px sur mobile.
- [ ] Zéro valeur en dur qui duplique un token (couleur hex, taille de police, spacing) dans le CSS du site.
- [ ] Aucune violation des lois design (§3).
- [ ] Le site n'importe qu'**un seul** `theme/*.css` ; en changer suffit à changer le look.
- [ ] Lighthouse a11y ≥ 95, aucune erreur console.