@zevra/ui 0.1.0

package/DECISIONS.md

@@ -0,0 +1,150 @@
+# Arbitrages de relevé
+
+Les cinq maquettes de la passation ne s'accordent pas toujours. Ce fichier
+liste chaque désaccord, la valeur retenue et pourquoi — pour qu'aucun écart ne
+soit tranché en silence, et que la DA puisse rejuger sur pièces.
+
+Sources : les dix planches de `reference/maquettes/` et
+`reference/prototype/experience.html`, à jour de la passation du 23/08/2026
+au soir (« handoff 3 »), qui ajoute `Blocks.html`, `Motion.html` et les trois
+landings.
+
+---
+
+## Tranchés par la passation suivante
+
+Les deux questions laissées ouvertes à la première livraison sont **closes**,
+et dans le sens qui avait été retenu. Les cinq planches ajoutées le
+confirment à l'unanimité.
+
+### 1. Le sens du dégradé de signature — clos
+
+| Source | Valeur |
+|---|---|
+| Main, DesignSystem, Mobile (1re passation) | `iris → violet 50% → cyan` |
+| Logos, prototype, token `--spectre` | `violet → bleu 55% → cyan` |
+| **Blocks, Motion, les 3 landings** | **`violet → bleu 55% → cyan`** |
+
+Les cinq nouvelles planches posent toutes `linear-gradient(90deg, #8a3af8,
+#2f6ef8 55%, #14c2f8)`, c'est-à-dire exactement `--spectre`. La valeur du
+token est donc la bonne ; les trois planches historiques sont en retard, pas
+en désaccord.
+
+### 2. Le rayon des cartes — clos
+
+Les cinq nouvelles planches codent `border-radius: 16px` sur `.panel`, soit
+`--r-card`. Le `14px` de DesignSystem et Logos et le `12px` du prototype
+appartiennent à l'état antérieur.
+
+---
+
+## Tranché sans ambiguïté
+
+**Hauteur des boutons — 48px.** Main, Mobile et le prototype s'accordent ;
+DesignSystem est seule à 46px.
+
+**Icône du lien fléché — 15×15.** Quatre occurrences dans Main contre une à
+16px dans DesignSystem.
+
+**Pastille — 28px de haut, 10px de texte, 0.18em.** Main et le prototype
+s'accordent ; DesignSystem est plus grande (30/11), Mobile plus petite
+(26/0.16em — repris dans la déclinaison mobile).
+
+**Puce de source — `--accent-deep`.** Main et le prototype ; DesignSystem pose
+`--accent`.
+
+**Entité pseudonymisée — 10px, `1px 6px`.** Main et DesignSystem ; le
+prototype est plus grand (11px, `2px 7px`).
+
+**Les deux encarts ne sont pas le même composant.** `.zv-inset` (blanc,
+`--line`, 13px/1.6, `--muted`) vient de DesignSystem ; `.zv-inset--quiet`
+(`--panel`, `--hairline`, 12px/1.9, `--ink`) vient de Main. Les fusionner
+donnait une chimère qui n'existe dans aucune maquette.
+
+---
+
+## Apports de la passation « handoff 3 »
+
+**Le mouvement est spécifié.** `Motion.html` nomme neuf animations, leurs
+plages de défilement et leurs règles : une seule courbe
+(`cubic-bezier(.2,.7,.2,1)`), un seul type de mouvement par scène, des
+entrées toujours vers le haut, aucun mouvement sur la typographie posée.
+Elles vivent dans `motion.css` sous le préfixe `zv-anim-`.
+
+Deux choix d'implémentation méritent d'être dits :
+
+- les entrées ne sont déclarées QUE dans `@supports (animation-timeline:
+  view())`. Un navigateur sans support affiche la page complète, jamais un
+  écran vide en attente d'une animation qui ne viendra pas ;
+- les deux boucles animent les propriétés `translate` et `scale`
+  indépendantes, jamais `transform` — le halo est centré par
+  `translateX(-50%)`, qu'une animation sur `transform` écraserait. La
+  maquette contournait le problème en recopiant le `translateX(-50%)` dans
+  chaque image-clé ; la propriété indépendante compose proprement.
+
+**Six blocs de plus.** Citation, carte de tarif, FAQ, aperçu d'interface,
+bande de preuve sociale, pied de page réduit — relevés dans `Blocks.html`,
+qui liste les composants du site. Deux d'entre eux portent une règle
+éditoriale que le CSS ne peut pas faire respecter et qui est donc écrite en
+commentaire : **jamais de fausse citation**, et **jamais de lorem dans un
+aperçu d'interface** — c'est ce bloc qui porte la crédibilité de la page.
+
+**Un palier typographique et une accroche.** `.zv-note` (12,5px) et
+`.zv-tagline`, la phrase d'accroche posée sous le nom d'un glyphe, moins
+interlettrée que le label qu'elle suit.
+
+**Un titre de section plus court.** `.zv-h2--sm` (48px) pour les landings
+produit, à côté du 56px de la home et du 64px des CTA.
+
+`Blocks.html` s'intitule « Quinze blocs » mais n'en étiquette que quatorze :
+le bloc de hero, présent dans les trois landings, n'a pas d'étiquette. Rien
+n'a été inventé pour combler l'écart.
+
+---
+
+## Ajouts assumés, hors relevé
+
+**Le point de rupture à 768px.** Les cinq maquettes sont à largeur fixe, sans
+une seule media query — Mobile.html est un rendu figé à 390px. Le seuil vient
+de la convention `md` du projet ; les valeurs mobiles, elles, sont toutes
+relevées dans Mobile.html. Un test vérifie qu'il reste unique.
+
+**Les conteneurs sont fluides.** `.zv-page` est plafonnée à 1440px, pas figée :
+la reproduire à l'identique garantissait un débordement horizontal sur
+téléphone.
+
+**Le focus clavier.** Aucune maquette ne déclare d'état de focus. Un système
+livré sans focus visible est inutilisable au clavier : `:focus-visible` est
+posé avec `--accent`, sans introduire de valeur nouvelle.
+
+**`prefers-reduced-motion`.** Neutralise les deux animations.
+
+**L'état désactivé des boutons.** Absent du relevé. Traitement neutre
+(opacité), plutôt qu'une couleur inventée.
+
+**Le liseré interne du bouton plein.** `0 1px 0 rgba(255,255,255,0.18) inset`
+est bien dans Main.html, mais absent de `--shadow-btn`. Il est recomposé dans
+le composant plutôt qu'ajouté au token.
+
+---
+
+## Écarté du paquet
+
+Ce que le relevé recense mais que le paquet ne livre pas, faute d'usage hors
+des planches de documentation : nuanciers, damier de transparence, cotations
+de zone de protection, échelle de tailles minimales, grille de lockups,
+nomenclature de fichiers, scènes de constellation et motifs d'animation liés
+au défilement (`animation-timeline`, encore mal supporté).
+
+Ces éléments restent consultables dans `reference/`.
+
+---
+
+## Asymétries connues, laissées telles quelles
+
+`--ok-line` existe, `--err-line` non : la carte en erreur code `#efc9cd` en
+dur. Même chose pour `#8fd3a8` / `#f0a5ad`, les états sur fond sombre.
+
+Trois rayons de surface pour un seul token : `--r-card` (16), la puce de
+source (4px) et le rayon 18px de la carte verre de DesignSystem — ce dernier
+ramené à `--r-card`, comme le fait Mobile.html.

package/README.md

@@ -0,0 +1,177 @@
+# Zevra UI — design system « Encre & Papier »
+
+Tokens, CSS des composants et logos officiels de la plateforme Zevra.
+Source de vérité pour tout ce qui touche à l'identité visuelle : une app qui
+recopie un hexadécimal au lieu de lire une variable d'ici finira par diverger.
+
+Issu de la passation DA du 23/08/2026. L'atelier où la direction évolue reste
+le canvas Claude Design « Zevra DA Encre et Papier » ; **ce dépôt est ce qui en
+sort**, versionné et consommable.
+
+---
+
+## Installer
+
+```bash
+pnpm add @zevra/ui
+```
+
+## Utiliser
+
+### Le CSS
+
+```css
+/* tout d'un coup */
+@import "@zevra/ui/css";
+
+/* ou à la carte */
+@import "@zevra/ui/tokens.css";      /* les variables, indispensable */
+@import "@zevra/ui/base.css";        /* reset, typographie, kicker, liens */
+@import "@zevra/ui/components.css";  /* boutons, badges, cartes, encarts */
+@import "@zevra/ui/layout.css";      /* conteneurs, grilles, sections, chrome */
+@import "@zevra/ui/surfaces.css";    /* halos, sols, voiles, manifeste */
+@import "@zevra/ui/motion.css";      /* les neuf animations autorisées */
+```
+
+L'ordre compte : les tokens d'abord, le socle ensuite. Toutes les classes sont
+préfixées `zv-`. Aucune dépendance, aucun préprocesseur : le paquet fonctionne
+à l'identique en React, en Astro, en HTML brut et dans un canvas de design.
+
+Le CSS est **fluide et responsive** là où les maquettes étaient figées à
+1440px : `.zv-page` est plafonnée, pas verrouillée, et un point de rupture
+unique à 768px reprend les valeurs mobiles du relevé.
+
+Chaque valeur vient des maquettes de la passation. Là où deux planches se
+contredisaient, l'arbitrage est écrit dans [DECISIONS.md](DECISIONS.md).
+
+## Le mouvement
+
+Neuf animations, pas une de plus, sous le préfixe `zv-anim-`. Sept sont
+pilotées par le défilement, deux tournent en continu :
+
+```html
+<span class="zv-halo zv-halo--hero zv-anim-breathe"></span>
+<h2 class="zv-h2 zv-anim-rise">…</h2>
+<img class="zv-glyph zv-anim-drift" style="--zv-delay: .8s">
+```
+
+Les règles de la passation : une seule courbe, un seul type de mouvement par
+scène, des entrées toujours vers le haut, et **aucun mouvement sur la
+typographie une fois posée**.
+
+Les entrées ne sont déclarées que dans un bloc `@supports` : sans
+`animation-timeline`, la page s'affiche complète plutôt que vide. Un seul
+media query neutralise les neuf pour `prefers-reduced-motion`.
+
+### Les tokens en JavaScript
+
+Pour ce qui ne peut pas lire une variable CSS — graphes, images générées,
+gabarits d'e-mail :
+
+```js
+import { couleurs, serieGraphique, polices } from '@zevra/ui'
+
+couleurs.accent      // '#2a2aa8'
+serieGraphique       // palette ordonnée, dérivée du spectre
+```
+
+C'est un **miroir** de `tokens.css`, pas une seconde source. Un test échoue si
+les deux divergent.
+
+### Les logos
+
+`logos/index.json` décrit les 40 fichiers : produit, forme, nuance, et surtout
+**sur quel fond chacun se pose**.
+
+```js
+import index from '@zevra/ui/logos/index.json'
+```
+
+Nommage : `<produit>-<forme>-<nuance>.svg` — par exemple
+`campus-lockup-navy.svg`. Produits : `zevra`, `campus`, `lexform`, `mcp`,
+`memoire`. Formes : `glyph`, `lockup`, `mark` (Zevra). Nuances : `ink`, `navy`,
+`white`, `orig`.
+
+Les SVG sont **autonomes** (aucune ressource externe, ~4 Ko) : ils s'inlinent
+partout, y compris là où les images distantes sont interdites.
+
+## Polices
+
+Trois familles Google : **Outfit** (titres), **Public Sans** (texte),
+**Space Grotesk** (labels capitales).
+
+En production, chargez-les par balise — une `@import` CSS bloque le rendu :
+
+```html
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Outfit:wght@200;300;400;500;600&family=Public+Sans:wght@400;600&family=Space+Grotesk:wght@500;600;700&display=swap">
+```
+
+`@import "@zevra/ui/fonts.css"` existe pour les prototypes et les
+maquettes, où la simplicité prime.
+
+---
+
+## Les règles qui ne se négocient pas
+
+Elles viennent de la passation. Les ignorer produit du « presque Zevra », qui
+coûte plus cher à corriger qu'à respecter.
+
+**Un seul bouton plein par écran.** L'indigo porte l'action. Pas de bouton en
+dégradé, pas de rayon 999.
+
+**Jamais de fausse citation, jamais de lorem.** Le bloc `.zv-quote` reste en
+réserve tant qu'un verbatim client n'a pas été recueilli ; `.zv-ui-preview`
+montre de vraies données réalistes — c'est lui qui porte la crédibilité de la
+page.
+
+**Trois cartes de tarif par page au maximum, cinq questions de FAQ, une seule
+ligne de preuve sociale.** Au-delà, la preuve se dilue au lieu de s'accumuler.
+
+**Le spectre ne sert qu'à trois choses** : le filet de section (56×2 px devant
+un kicker), la barre de progression, les points de la méthode. Jamais en fond,
+jamais en texte.
+
+**Les logos ne se retouchent pas** : ni recoloration, ni resaturation, ni
+inclinaison. Sur navy, utiliser les versions blanches. Sous 24 px, passer en
+mono. Zone de protection X/2 ; hauteur de capitale du wordmark = 0,30 × glyphe.
+
+**Le système est clair par nature.** Une surface sombre se fait avec
+`--manifeste` et `--accent-on-dark`, pas en inversant les neutres : les
+contrastes ont été réglés dans ce sens-là.
+
+---
+
+## Dans un canvas Claude Design
+
+Un canvas interdit les ressources distantes : ni feuille de style externe, ni
+image par URL. Pour y travailler dans la charte :
+
+1. coller le bloc `:root { … }` de `src/tokens.css` en tête de l'artboard ;
+2. coller les SVG de logo **en ligne** plutôt que de les référencer.
+
+L'admin Zevra propose les deux au presse-papier (page *Plateforme → Design
+system*), c'est le chemin le plus court.
+
+Les polices Google, elles, sont autorisées dans un canvas : la balise `<link>`
+ci-dessus fonctionne telle quelle.
+
+---
+
+## Faire évoluer
+
+1. La décision visuelle se prend dans le canvas Claude Design, avec Pierre.
+2. Elle atterrit ici : `src/tokens.css` d'abord, puis son miroir
+   `tokens/index.js`, puis les modules CSS concernés.
+3. `pnpm test` doit rester vert. Les tests ne jugent pas l'esthétique : ils
+   attrapent le token appelé mais inexistant, la classe définie dans deux
+   modules (où c'est l'ordre de chargement qui tranche à la place de la DA),
+   le second point de rupture glissé au fil de l'eau, et le spectre écrit à
+   la main hors de ses trois emplois autorisés.
+4. Après ajout de logos : `node scripts/build-logo-index.mjs`, et committer
+   l'index régénéré.
+5. Publier une version : `npm version <patch|minor|major>` puis `npm publish`.
+
+`reference/` conserve les maquettes HTML, le prototype animé et les fichiers
+d'origine de la passation. Ce dossier n'est **pas publié** dans le paquet : il
+sert d'archive et de référence visuelle, pas de dépendance.