@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
• Démo kitchen sink : npm run dev → /demo (neutre), /demo/renovation, /demo/aep

Installation dans un site

Voie principale — dépendance npm depuis Gitea

// 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) :

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 :

---
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 :

/* 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

npm install
npm run dev      # démo sur localhost:4321/demo
npm run build    # vérification

Ajouter un thème : voir PROTOCOLE.md §5.