101 lines
3.6 KiB
Markdown
101 lines
3.6 KiB
Markdown
# @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.
|