design-system/HANDOFF.md

HANDOFF — P1 fondation → P2 (TMIP) / P3 (racine)

État au 2026-07-19. Repo : git.trans-former.fr/jules/design-system, branche main. Local : ~/dev/design-system (Linux).

1. Le contrat — ce que P2/P3 consomment

Tokens (schéma complet, tokens.css, layer tf-tokens)

• Couleur (rôles) : --bg --bg-alt --surface --surface-2 --text --text-muted --text-subtle --border --border-strong --primary --primary-hover --on-primary --accent --on-accent --link --link-hover --focus-ring --success --warning --danger
• Typo : --font-heading --font-body --font-mono · tailles fluides --fs-xs|sm|base|lg|xl|2xl|3xl|4xl (clamp 360→1280) · --lh-tight|base|loose · --fw-regular|medium|semibold|bold
• Spacing : --space-2xs|xs|sm|md|lg|xl|2xl|3xl (4/8px, fluide sur 2xl/3xl)
• Rayons : --radius-sm|md|lg|full · Ombres : --shadow-sm|md|lg
• Layout : --container-max (75rem) --container-pad (fluide 16→32)
• Z-index : --z-nav|overlay|modal|toast (100/200/300/400)
• Motion : --dur-fast|base|slow (150/250/400ms) · --ease-out|in-out|spring
• Breakpoints (constantes, PAS des variables) : 360 base · 480 sm · 768 md · 1024 lg · 1280 xl — media queries en rem, min-width only.

Mode sombre : préférence système + data-theme explicite qui gagne dans les deux sens. Helper window.tfSetTheme('light'|'dark'|'auto') fourni par BaseLayout.

API des primitives (props → détail en tête de chaque fichier)

Primitive	Props	Slots
BaseLayout.astro	title* · description · lang('fr') · ogImage · canonical	default, header, footer, head
Nav.astro	links: {href,label}[]* · label	brand, actions
Footer.astro	—	default, legal
Button.astro	variant: primary|secondary|ghost|link · size: sm|md|lg · href · type · disabled · class + attrs passthrough	default
Card.astro	href (carte cliquable + hover élévation) · class	media, default
Prose.astro	class	default (HTML long)
Section.astro	alt (fond alterné) · size: base|lg · id · class	default
Container.astro	size: base|narrow · class	default
Reveal.astro	delay (ms) · class	default

Utilitaire nu : js/reveal.js → initReveal(selector?).

Consommation (rappel pour P2)

// package.json du site
"dependencies": { "@transformer/ui": "git+https://git.trans-former.fr/jules/design-system.git" }

---
import BaseLayout from "@transformer/ui/BaseLayout.astro";
import "@transformer/ui/theme/tmip.css";   // ← le seul import qui change par site
---

Fallback submodule + variante Tailwind 4 (racine) : voir README.md. Pont Tailwind : tailwind.css (@theme inline) — namespaces en collision non mappés, syntaxe rounded-(--radius-md) etc. (PROTOCOLE §4).

2. Déviations vs brief + blockers

• Chemin local : brief dit C:\dev\ (Windows) ; la machine est Linux → repo dans ~/dev/design-system (même logique hors-Dropbox, remote Gitea identique).
• Ajout @layer (pas dans le brief) : Astro inline le CSS des thèmes AVANT le <link> du bundle tokens → l'ordre d'import ne suffisait pas. tokens.css→@layer tf-tokens, reset.css→@layer tf-reset, thèmes non-layerés → la cascade est correcte quel que soit l'ordre de bundling. Règle : ne jamais layerer un thème.
• Ajout tailwind.css (maj ligne 18 du brief) : pont @theme inline pour la racine.
• Blockquote sans border-left (loi Impeccable « border-left accent » prise au sens strict) : fond --surface-2 + radius à la place.
• Polices non embarquées : les thèmes ne définissent que les stacks ; chaque site charge ses @font-face (la démo affiche donc les fallbacks système, pas Poppins/Open Sans).
• BLOCKER P2 : palette TMIP inconnue → levé le 2026-07-20 : theme/tmip.css rempli depuis la palette réelle (P2), page démo /demo/tmip ajoutée. Et reveal.js corrigé (threshold 0 — les sections plus hautes que le viewport ne se révélaient jamais).

3. Reste à faire pour P2 (migration TMIP)

1. Confirmer la palette TMIP (clair + sombre) + couple de polices → remplir theme/tmip.css, ajouter src/pages/demo/tmip.astro (4 lignes), valider le kitchen sink.
2. Dans le repo TMIP : ajouter la dépendance @transformer/ui, remplacer le layout maison par BaseLayout + Nav + Footer, importer theme/tmip.css.
3. Dégraisser le global.css de TMIP : supprimer tout ce que tokens/reset/primitives couvrent ; le CSS restant = spécifique métier uniquement, zéro valeur en dur qui duplique un token.
4. Passer la Definition-of-Done (PROTOCOLE §7) : 360/768/1280, clair/sombre, reduced-motion, sans JS, clavier.
5. Tagger v0.1.0 ici et épingler le tag côté TMIP si on veut du reproductible.

4. Auto-audit — lois Impeccable + mobile-first

Vérifié (build + Puppeteer sur le build de prod) :

• 3 pages démo × 3 viewports (360/768/1280) × clair/sombre = 18 combinaisons, zéro overflow-x.
• Hamburger : aria-expanded OK, Échap referme, focus revient au bouton, focus trap actif panneau ouvert.
• prefers-reduced-motion: reduce → reveals visibles d'office, kill-switch global dans le reset (!important layeré, imbattable).
• Sans JS → liens de nav visibles, rien de masqué (garde html[data-js]).
• Lois design : aucun border-left accent, aucun gradient text, pas de glassmorphisme, pas de hero-metric, pas de modal, pas d'auto-play. Ombres discrètes uniquement.
• Cibles tactiles : boutons/liens nav ≥ 44px ; sm remonte à 44px sur pointer: coarse.

Fragile / à surveiller :

• Contrastes AA vérifiés à l'œil et par calcul ponctuel, pas outillés : passer un audit Lighthouse/axe sur la démo au prochain cycle (surtout --text-subtle sur --bg-alt et le jaune --accent renovation, utilisable seulement avec --on-accent dessus).
• Le pont Tailwind n'a pas été testé contre un vrai build Tailwind 4 (aucun site Tailwind dans ce repo) → à valider en P3 sur astro-site-cerveau.
• npm install git+https://… non testé depuis un site consommateur réel (testé uniquement en local) → premier point à vérifier en P2 ; le fallback submodule est documenté si souci.
• La condensation de nav est discrète (padding) ; si un site veut un vrai shrink (logo qui réduit), l'étendre ICI, pas dans le site.