# @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.