P1 fondation : tokens layerés, reset, thèmes (base/renovation/aep/tmip), 9 primitives Astro, pont Tailwind 4, démo kitchen sink

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

README.md

@@ -0,0 +1,100 @@
+# @transformer/ui
+
+Design system partagé de la constellation `trans-former.fr` (~6 sites Astro 5 statiques). Une fondation, pas un site : **tokens** (schéma universel), **thèmes** (palette + polices par site), **primitives Astro** (comportements définis une seule fois).
+
+- Règles et checklist : [`PROTOCOLE.md`](./PROTOCOLE.md)
+- Démo kitchen sink : `npm run dev` → `/demo` (neutre), `/demo/renovation`, `/demo/aep`
+
+## Installation dans un site
+
+### Voie principale — dépendance npm depuis Gitea
+
+```jsonc
+// package.json du site
+"dependencies": {
+  "@transformer/ui": "git+https://git.trans-former.fr/jules/design-system.git"
+}
+```
+
+Épingler une version : `git+https://git.trans-former.fr/jules/design-system.git#v0.1.0` (tag) ou `#<commit>`. Mettre à jour : `npm update @transformer/ui` (ou réinstaller si épinglé).
+
+### Fallback — git submodule
+
+Si npm-from-git pose souci (réseau, auth CI) :
+
+```bash
+git submodule add https://git.trans-former.fr/jules/design-system.git vendor/ui
+git submodule update --init
+```
+
+Puis dans le `package.json` du site : `"@transformer/ui": "file:./vendor/ui"`.
+Mise à jour : `git -C vendor/ui pull && git add vendor/ui && git commit`.
+
+## Consommation
+
+### Site vanilla (TMIP, renovation…)
+
+Dans le layout du site :
+
+```astro
+---
+import BaseLayout from "@transformer/ui/BaseLayout.astro";
+import Nav from "@transformer/ui/Nav.astro";
+import Footer from "@transformer/ui/Footer.astro";
+// tokens.css et reset.css vivent dans des @layer : le thème (non-layeré)
+// gagne toujours, quel que soit l'ordre de bundling.
+import "@transformer/ui/theme/renovation.css";
+---
+
+<BaseLayout title="..." description="...">
+  <Nav slot="header" links={[{ href: "/", label: "Accueil" }]}>
+    <a slot="brand" href="/">Mon site</a>
+  </Nav>
+  <slot />
+  <Footer slot="footer">…</Footer>
+</BaseLayout>
+```
+
+`BaseLayout` importe déjà `tokens.css` + `reset.css`. **Changer de thème = changer ce seul import.**
+
+Primitives : `Button.astro`, `Card.astro`, `Prose.astro`, `Section.astro`, `Container.astro`, `Reveal.astro` (+ `reveal.js` en utilitaire nu). Props documentées en tête de chaque fichier.
+
+Polices : le thème ne définit que les stacks — le site charge ses `@font-face` (self-host recommandé).
+
+### Site Tailwind 4 (racine `astro-site-cerveau`)
+
+La racine garde ses composants Vue mais s'aligne sur les tokens :
+
+```css
+/* entrée CSS du site */
+@import "tailwindcss";
+@import "@transformer/ui/tokens.css";
+@import "@transformer/ui/theme/base.css";     /* ou le thème racine */
+@import "@transformer/ui/tailwind.css";       /* pont @theme → utilitaires */
+```
+
+Utilitaires générés : `bg-primary`, `text-text-muted`, `border-border`, `text-2xl` (échelle fluide), `p-md`, `gap-xl`… Cas en collision de nom (non mappés) : `rounded-(--radius-md)`, `shadow-(--shadow-md)`, `ease-(--ease-out)`, `font-(family-name:--font-heading)`.
+
+## Structure du repo
+
+```
+tokens.css        schéma canonique (rôles, échelles, motion) — clair + sombre
+reset.css         reset moderne + kill-switch reduced-motion
+tailwind.css      pont @theme pour Tailwind 4
+theme/            base (à cloner) · renovation · aep · tmip (placeholder P2)
+components/       BaseLayout · Nav · Footer · Button · Card · Prose
+                  Section · Container · Reveal
+js/reveal.js      apparition au scroll (IntersectionObserver)
+src/              démo kitchen sink uniquement (pas publiée dans le paquet)
+PROTOCOLE.md      règles mobile-first, motion charter, lois design, DoD
+```
+
+## Développement
+
+```bash
+npm install
+npm run dev      # démo sur localhost:4321/demo
+npm run build    # vérification
+```
+
+Ajouter un thème : voir `PROTOCOLE.md` §5.