@cyrilld/zestds 0.1.0

package/README.md

@@ -0,0 +1,578 @@
+# Zest Design System
+
+A React 18 component library, published as a single npm package: `@cyrilld/zestds`. All
+components are exported from the package root:
+
+```tsx
+import { Home01 } from "@cyrilld/zestds";
+import "@cyrilld/zestds/dist/index.css";
+
+<Home01 width={20} height={20} />
+```
+
+Today the package publishes **the tokens and the 121 icons**. Interface components are phase 2 —
+see "Ce qui reste à faire".
+
+**Both imports matter.** The code and the styles travel separately — `dist/index.js` on one
+side, `dist/index.css` on the other. Importing the first without the second gives components
+that render, structurally, with no background, no spacing and no radius. Nothing fails and
+nothing warns.
+
+Its Storybook is the design system's documentation, written in French. Seven Foundations pages
+are written — colors, typography, spacing, radius, shadows, the focus ring, icons — and the rest
+of the plan sits alongside them as **announced but empty pages**: the remaining foundations, then
+Base components and Application components.
+
+That isn't decoration. A sidebar that only shows what exists gives the illusion of a complete
+system: someone looking for "Badges" and not finding it can't tell whether it doesn't exist, is
+named something else, or lives elsewhere. Showing the rest says where we are, on every visit.
+
+```sh
+yarn storybook
+```
+
+## Structure
+
+```
+src/
+  styles/            theme.css (the tokens), fonts.css, typography.css, base.css
+  fonts/             the six Averta .woff2 files — commercial license, see fonts/README.md
+  components/
+    base/            interface components — empty, phase 2
+    foundations/     the icons: catalogue.ts generated from Figma, index.tsx built on it
+  docs/              the Storybook documentation — MDX pages and their boards. NOT shipped.
+  Introduction.mdx   the Storybook landing page
+  index.ts           the barrel: imports the four sheets, re-exports everything else
+  css.d.ts           ambient module declaration for CSS imports
+.storybook/          Storybook config, discovers stories and MDX under src/
+tsup.config.ts       build config (ESM + CJS + .d.ts + CSS)
+```
+
+The layout mirrors the `zest-design-system` monorepo, so the two can be read side by side.
+
+`src/docs/` never ships: `src/index.ts` doesn't import it, so `tsup` never sees it. Its classes
+are all prefixed `zds-doc-`, which keeps them out of what the library exposes — after a change
+to the barrel, `grep -c 'zds-doc-' dist/index.css` must print `0`.
+
+Adding a new component means adding a `src/components/base/<Name>/` folder (component, styles,
+tests, stories, local `index.ts`), then re-exporting it from the root `src/index.ts`.
+
+## What the package publishes
+
+**Variables, not utility classes.** There is no CSS engine here. A component writes
+`color: var(--zds-color-text-primary)`.
+
+Colors are layered, and a component only ever cites the last two:
+
+| Layer | Example | Cited by a component? |
+| --- | --- | --- |
+| Ramps | `--zds-color-brand-600` | Never |
+| Utility palettes | `--zds-color-utility-lime-500` | To categorize |
+| Roles | `--zds-color-text-primary` | Yes |
+| Component | `--zds-color-toggle-border` | Last resort |
+
+Beyond colors: the type scale (thirteen sizes, each with its line height), the named spacing
+scale, thirteen widths, eleven radii, seven shadows plus the relief, the focus ring, and the
+eight brand gradients in three angles each.
+
+### Three entry points, not one
+
+| Import | What | Weight |
+| --- | --- | --- |
+| `@cyrilld/zestds` | tokens, 121 icons, 27 file icons | 197 KB |
+| `@cyrilld/zestds/flags` | 234 country flags | 328 KB |
+| `@cyrilld/zestds/cursors` | 50 cursors | 94 KB |
+
+⚠️ **The two catalogues are deliberately NOT re-exported from the root.** A catalogue is a data
+object queried by key at runtime — that is the whole point of `<FlagIcon code={country} />` — so
+no bundler can prove an entry is unused and nothing gets tree-shaken away. A single `export *`
+added to `src/index.ts` for convenience would take the root from 197 KB to nearly 600 KB without
+breaking anything visible: typecheck passes, build passes, the package silently triples.
+
+Flags need no CSS at all — their colours are national facts, not tokens. Cursors need
+`dist/index.css` for exactly one of the fifty.
+
+## Getting started
+
+```sh
+yarn install
+```
+
+## Using it locally with `yarn link`
+
+To try local changes in another project before publishing a new version:
+
+1. In this repo, build once (the `prepare` script also does this on `yarn install`), then
+   keep rebuilding on every change:
+
+   ```sh
+   yarn build     # one-off build
+   yarn dev       # or: rebuild dist/ on every save
+   ```
+
+2. Register this package globally and link it from the consumer project:
+
+   ```sh
+   # in this repo
+   yarn link
+
+   # in the consumer project
+   yarn link "@cyrilld/zestds"
+   ```
+
+3. `react` and `react-dom` are peer dependencies, not bundled — if the linked package
+   resolves its own copy of React instead of the consumer's, you'll hit "Invalid hook
+   call" errors from two React instances existing side by side. Point this repo's React
+   back at the consumer's copy to dedupe them:
+
+   ```sh
+   # in the consumer project
+   cd node_modules/react && yarn link && cd -
+   cd node_modules/react-dom && yarn link && cd -
+
+   # in this repo
+   yarn link react react-dom
+   ```
+
+4. Leave `yarn dev` running in this repo while you work — it watches `src/` and rebuilds
+   `dist/`, which the linked consumer picks up on its own rebuild/HMR.
+
+5. When you're done testing:
+
+   ```sh
+   # consumer project
+   yarn unlink "@cyrilld/zestds"
+   yarn install --force   # restore the regular installed copy
+
+   # this repo
+   yarn unlink
+   ```
+
+## Scripts
+
+| Command                  | Description                                              |
+| ------------------------ | ---------------------------------------------------------|
+| `yarn storybook`          | Launch the documentation locally at http://localhost:6006 |
+| `yarn build-storybook`    | Build a static Storybook site to `storybook-static/`     |
+| `yarn test`               | Run all tests once (Vitest + Testing Library) — see Testing |
+| `yarn test:watch`         | Run tests in watch mode                                  |
+| `yarn typecheck`          | Type-check the package                                   |
+| `yarn lint`               | Lint the package                                         |
+| `yarn build`              | Build to `dist/` (ESM, CJS, types, CSS)                  |
+| `yarn verify:render`      | Drive Edge over the pages: fonts, boards, red flags, console errors |
+| `yarn verify:labels`      | Contraste des étiquettes d'icône de fichier, sans navigateur |
+
+`verify:render` needs a dev server running and `storybook-static/index.json` present (it reads
+the story ids from there rather than guessing them). Point it elsewhere with
+`--port`, and add `--capture page.png` for a screenshot.
+
+⚠️ **It refuses to conclude rather than report a false green.** It carries a decoy token and
+stops if the decoy doesn't trip; it stops if Storybook answers "Couldn't find story"; and it
+skips anything with `offsetParent === null`. Both failure paths are tested — breaking
+`--zds-color-brand-600` on purpose makes it abort, and so does a bad story id.
+
+## Versioning & releases
+
+The package has a single semver version (`package.json`). To cut a release:
+
+```sh
+npm version patch   # or minor / major
+git push --follow-tags
+npm publish
+```
+
+`npm version` bumps `package.json`, commits the change, and creates a matching `v<version>`
+git tag automatically (e.g. `v0.2.0`) — `--follow-tags` pushes both the commit and that tag.
+`prepublishOnly` runs `yarn build` automatically before `npm publish`.
+
+## Testing
+
+⚠️ **There is no test suite right now**, because there is no component to test: removing `Button`
+emptied it. `yarn test` runs with `--passWithNoTests` so it stays green — a red `yarn test` that
+only means "nothing to run" trains people to ignore red. **Drop the flag with the first phase-2
+component.**
+
+When components arrive, they are tested with [Vitest](https://vitest.dev) and
+[React Testing Library](https://testing-library.com/react), driving them the way a user would
+(queries by role/text, `@testing-library/user-event` for interactions) rather than testing
+implementation details.
+
+One suite is worth writing before that, and it has nothing to do with components: the icon
+catalogue is **generated**, and its invariants are exactly what a bad regeneration breaks — every
+name unique, every component in `index.tsx` resolving to an entry, every `ZEST_ICONS_EN_CONFLIT`
+name also present in `ZEST_ICONS`. Three separate hand-counts of that catalogue came out wrong
+during the port.
+
+A green build says nothing about the rendering. Two defects on this project were invisible to
+both `tsc` and `storybook build`, and only a real browser found them:
+
+- an **infinite render loop** — an effect depending on an array rebuilt at every render. React
+  cut it off with `Maximum update depth exceeded`, and the page displayed anyway, so nothing
+  looked wrong;
+- a **probe that concluded on a page it had never loaded**, because the story id was wrong. It
+  reported "0 boards" for a page Storybook was refusing to open. An id with an accent is
+  URL-encoded: `Foundations/Icônes` is `foundations-ic%C3%B4nes--docs`. Read the ids from
+  `storybook-static/index.json` rather than guessing them.
+
+## Ce qui reste à faire
+
+- [x] **Phase 1a** — les couleurs : les couches de jetons, et une page de documentation qui lit
+      ses valeurs dans le navigateur au lieu de les recopier
+- [x] **Phase 1a bis** — la vraie palette Zest depuis le Figma *❖ Design System V2.0* : six
+      rampes, le vert de marque, les huit dégradés, la table de correspondance des paliers
+- [x] **Phase 1b** — typographie, espacements, rayons, ombres, anneau de focus
+      - ⚠️ reste ouvert : la collection Figma `Couleurs/Effets/Ombres` n'a pas été lue. Les sept
+        ombres portent la géométrie de la référence et des teintes `rgba(0, 0, 0, …)` ; celles de
+        Zest sont teintées `#101828` sur deux couches. La **géométrie** est la même de part et
+        d'autre, la **teinte** changera.
+- [ ] **Phase 1c** — icônes, file icons, drapeaux, avatars, logo
+      Les quatre pages restantes existent déjà dans la barre latérale, annoncées et vides — voir
+      `src/docs/a-venir/`.
+      - [x] **Icônes** — 121 publiées, les neuf catégories de la page « Icônes » du Figma.
+        Navigateur et règles d'usage. Les conflits de nom et les styles à revoir sont sortis de
+        la page le 2026-09-08 : voir « Les décisions ouvertes sur les icônes » plus bas.
+      - [x] **File icons** — 27 types × 3 habillages, page en ligne. Les dessins viennent
+        **du Figma** (`3847:2911`), re-teintés sur les jetons : dix substitutions,
+        l'écart mesuré en Lab. ⚠️ Le cadre Figma `3847:2911` est la bibliothèque d'Untitled UI
+        collée telle quelle — variables d'origine, collection en anglais, et en retard sur le
+        paquet. Il ne décide que la LISTE des 27 types. ⚠️ Les trois règles d'usage des habillages
+        (Default / Gray / Solid) sont une **proposition** : ni la page de ressources d'origine ni
+        le Figma n'en donnent, elles attendent un arbitrage.
+      - [x] **Flag icons** — 234 drapeaux, page en ligne, renommée « Flag icons » à la demande de
+        Micka. Générés depuis le Figma (`3853:17761`), pastille ronde, une seule forme. Les
+        couleurs ne sont **pas** portées sur les jetons : celles d'un drapeau sont des faits
+        nationaux. Les noms français viennent d'`Intl.DisplayNames`, pas d'une liste recopiée.
+        ⚠️ Cinq codes du Figma sont faux et corrigés dans le catalogue — voir « En attente ».
+      - [x] **Curseurs** — 50 dessins (29 classiques, 21 macOS 26), page en ligne. Entrée nouvelle,
+        pas prévue au plan d'origine, demandée le 2026-09-08. Chaque entrée porte le mot-clé CSS
+        qu'elle représente, parce que le cas courant n'est PAS de dessiner un curseur.
+      - [x] **Avatars** — page en ligne, 282 fichiers rangés en quatre : Défaut, Couleur, Neutre,
+        Transparent. Le Figma ne contient que DEUX choses par personne — sa photo avec son fond
+        (154) et le même sujet détouré (128) ; Couleur et Neutre sont ce détourage composé sur un
+        fond à l'affichage, pas des fichiers. Recherche par nom ou par photographe, et deux actions
+        au survol : Copier et Télécharger, qui aplatissent le fond dans un PNG.
+        ⚠️ **Aucun composant `Avatar` n'est livré**, et c'est délibéré : le cadre Figma
+        `3857:23794` est une BANQUE D'IMAGES, il ne définit ni tailles, ni anneau, ni pastille de
+        présence, ni repli. Il est annoncé dans **Base components → Avatars**, avec les trois
+        questions à trancher. Les fichiers sont dans `.storybook/public/avatars/`, jamais dans
+        `dist/`.
+      - [x] **Logo** — page en ligne. `ZestLogo`, `ZestLogomark`, `ZestWordmark`, `ZestAiLogo`,
+        livrés depuis la racine (24 Ko). Le blocage est levé : les SVG viennent du Figma
+        (`248:1409` pour le logotype, `3218:143` pour Zest AI). Le favicon
+        provisoire — un `Z` sur `brand-600` — a été remplacé par le vrai isotype. ⚠️ C'est une
+        COPIE du catalogue : Storybook réclame un fichier, pas un composant. Si le logo change,
+        régénérer le catalogue **et** recopier le favicon.
+- [ ] **Phase 2** — base components : boutons, badges, champs, sélecteurs, info-bulles
+      - ⚠️ **Un `Button` a été retiré le 2026-09-08**, plutôt que corrigé à moitié. Hérité d'avant
+        les fondations, il peignait son primaire en `#4f46e5` — un indigo qui n'est pas le bleu de
+        Zest — dimensionnait son `sm` à 13 px, taille absente de l'échelle, et ne citait aucun
+        jeton : six de ses sept couleurs n'existaient nulle part dans le thème. Un composant faux
+        dans un paquet enseigne le faux, et celui-là contredisait les pages qui documentent les
+        jetons. Récupérable par `git checkout 69a30fa -- src/Button` si on veut le relire.
+      - ⚠️ **Bloquant pour les badges et les boutons pleins** : les deux aplats de statut sous
+        l'AA, voir « En attente ».
+      - Chaque composant livré retire un morceau du provisoire de `docs.css` — le tableau est
+        dans le `CLAUDE.md`.
+- [ ] **Phase 3** — application components : navigation, tableaux, modales
+- [ ] **Phase 4** — application UI examples
+
+## En attente
+
+Des décisions qui appartiennent à Micka ou à l'équipe produit, pas au code.
+
+- ⚠️ **Les deux aplats de statut ne tiennent pas l'AA — et ils ont maintenant des victimes.**
+  `yarn verify:labels` sort en échec sur **dix étiquettes d'icône de fichier** : CSV, XLS et XLSX
+  portent du blanc sur `success-600` (3,59:1), PPT et PPTX sur `warning-600` (3,49:1), en Default
+  comme en Solid. Ce n'est pas un défaut de code : c'est cette décision-ci, devenue concrète. Le
+  contrôle échoue exprès pour qu'elle ne s'oublie pas. `bg-warning-solid` (`#DC6803`) tient
+  **3,49:1** et `bg-success-solid` (`#119B57`) **3,59:1** sous du texte blanc, pour un seuil AA
+  de 4,5:1. `bg-error-solid` (4,83) et `bg-brand-solid` (4,54) passent, de justesse pour le
+  second. Les fonds **doux** vont bien (4,69 à 6,05) : le défaut ne touche que les aplats. Trois
+  issues, à choisir un badge et un bouton sous les yeux — descendre les deux aplats sur le palier
+  **700** (5,43 et 5,08) ; ne jamais poser de texte blanc dessus, en privilégiant les badges en
+  fond doux ; ou assumer, si ces aplats ne portent jamais de libellé.
+- **La ligne de `.prose` fait 103 caractères**, mesurés ici (Averta 16 px sur 720 px, médiane sur
+  les lignes pleines de l'article d'exemple). Le confort de lecture se situe entre 45 et 75, et
+  85 est la limite haute usuelle. Les 720 px viennent pourtant du Figma (`paragraph-max-width`)
+  et sont en vigueur : la valeur est **sourcée**, elle n'a donc pas été changée unilatéralement.
+  Les replis, mesurés eux aussi :
+
+  | Colonne | Caractères (médiane) | |
+  |---|---|---|
+  | 720 px — actuel, du Figma | **103** | au-dessus de la limite usuelle |
+  | 680 px | 90 | |
+  | 640 px | 87 | |
+  | 600 px | **79** | dans la fourchette haute du confort |
+  | 560 px | 76 | |
+
+  ⚠️ La livraison de référence annonce 89 pour la même colonne et la même police. L'écart vient
+  du **texte** mesuré, pas du réglage : les deux articles d'exemple n'ont ni les mêmes mots ni la
+  même densité d'élisions. C'est une raison de plus de ne pas recopier un chiffre d'un dépôt à
+  l'autre. À arbitrer, parce que ça touche un jeton du Figma.
+- ⚠️ **Il n'y a pas de composant `Avatar`, et il en faut un.** Le Figma V2.0 n'en contient aucun :
+  `3857:23794` est une banque de photos. Trois spécimens existent dans l'ancienne bibliothèque
+  *Design System - ZestMeUp* — `Zestie avatar`, `Anonymous avatar`, `Avatars` — dernière mise à
+  jour 2024, et ce n'est pas la source déclarée du V2.0. **Faut-il les porter, ou en dessiner un
+  dans le V2.0 ?** Rien n'a été codé en attendant : la page montre des règles, pas un composant.
+- **Les avatars à initiales.** La règle Zest les interdit ; la livraison de référence a tranché
+  que la règle vaut pour les *produits*, pas pour une bibliothèque — un composant *offre* un
+  état, l'écran choisit de le rendre. ⚠️ `quote-avatar.example.tsx` énonce aujourd'hui la règle
+  produit comme si c'était la règle de la bibliothèque. La page « Avatars » montre la variante à
+  initiales **uniquement pour dire qu'on ne l'emploie pas** ; elle n'existe nulle part ailleurs.
+- **L'échelle de tailles d'avatar** — 24, 32, 40, 48, 64, 96 — est une **proposition**. Le Figma
+  n'en donne aucune ; ces paliers viennent de l'échelle d'espacement du thème parce qu'ils
+  existent déjà. À arbitrer en même temps que le composant.
+- **L'aire de protection et la taille plancher du logo** sont une **proposition** elles aussi :
+  une demi-hauteur d'isotype, et 24 px sous lesquels on passe à l'isotype seul. Le Figma ne dit
+  rien des deux. Dessinées dans la page pour être discutées.
+- **Il n'y a pas de logo monochrome.** La variante `sombre` est du blanc plein ; rien ne couvre le
+  noir plein, dont une impression une couleur ou une gravure aura besoin.
+- **Le turquoise du dégradé de Zest AI n'a pas de jeton exact.** `#39D7E4` tombe à ΔE 1,8 de
+  `--zds-color-utility-turquoise-500` (`#30D2E0`) — invisible à l'œil, mesurable. Écart voulu ou
+  dérive ? À vérifier au Figma. Les deux autres couleurs du logo tombent à ΔE 0,0 de leur jeton.
+- **Une étiquette d'icône diverge** : le symbole Figma `refresh-cw-02` est étiqueté
+  `refresh-cw-01`. C'est le libellé qui fait foi, donc le catalogue suit — mais c'est peut-être
+  une coquille du Figma.
+- **Les cinq conflits de nom et les sept styles « à revoir »** — détaillés plus bas, avec les
+  deux tableaux. La correction se fait dans le Figma, puis on régénère.
+- **Les onze autres ombres de Zest**, dans `Couleurs/Effets/Ombres`. Les valeurs existent et
+  feront foi.
+- ⚠️ **Cinq codes de drapeau sont faux dans le Figma**, relevés en regardant les dessins et
+  corrigés dans le catalogue. `DS` porte le drapeau du **Soudan** (`SD`, absent du jeu, une
+  transposition) ; l'un des deux `CD` porte le **Congo-Brazzaville** (`CG`, absent du jeu) ;
+  `GB-2` porte l'**Angleterre** (`GB-ENG` en ISO 3166-2). Sans correction, un sélecteur de pays
+  n'aurait jamais rendu le Soudan. Chaque entrée garde `codeFigma`, le code d'origine, pour que
+  l'écart reste trouvable. **Le Figma reste à corriger** — après quoi il faudra retirer les
+  corrections du générateur.
+  ⚠️ `BQ` ×3 n'est **pas** une erreur : `BQ` couvre trois îles avec trois drapeaux, distinguées
+  en `BQ-BO`, `BQ-SE`, `BQ-SA`. `FLAG_ALIAS` renvoie `BQ` sur Bonaire.
+- ⚠️ **19 codes ISO n'ont pas de drapeau, et cinq sont français** — Guadeloupe, La Réunion,
+  Mayotte, Guyane, Saint-Pierre-et-Miquelon. Sur un produit français, c'est le trou qui se
+  remarquera en premier. Les 14 autres sont des territoires peu peuplés (Antarctique, Vatican,
+  Svalbard, îles diverses). Liste complète dans l'en-tête du catalogue. À relever au Figma.
+- **Deux familles de curseurs de redimensionnement couvrent les mêmes mots-clés CSS**, et
+  laquelle employer quand n'est pas tranché. Les huit `Resize single …` (une flèche nue) et les
+  quatre `Resize …` (une flèche contre une barre) donnent tous `n-resize`, `e-resize`,
+  `s-resize`, `w-resize`. Constat du cadre Figma, pas une règle. La page le dit et ne choisit pas.
+
+## Décidé
+
+Le journal des arbitrages. Plusieurs de ces choix paraissent arbitraires et sont le résultat
+d'une mesure ou d'une décision produit — ne pas les « harmoniser » sans lire l'entrée.
+
+- **Le logo porte ses couleurs EN DUR, et il est à la racine** (2026-09-08). Elles correspondent
+  pourtant exactement à deux jetons — mesuré, `#00D85D` = `--zds-color-mark` et `#21304E` =
+  `--zds-color-navy-100`, ΔE 0,0 tous les deux. Les écrire en `var(--zds-…)` serait une faute :
+  un jeton peut être redéfini, c'est sa raison d'être, et un logo qui suit le thème n'en est plus
+  un. À la racine et non en sous-chemin parce que les cinq dessins font 24 Ko, et qu'un produit
+  qui charge le design system affiche presque toujours le logo.
+- **Les 282 fichiers de portraits ne sont pas livrés** (2026-09-08). Ils vivent sous
+  `.storybook/public/avatars/`, que `files: ["dist"]` exclut de npm. Ce sont des images de
+  MAQUETTE : dans un produit, l'avatar vient du compte de la personne. Le Figma en sert 23,4 Mo
+  (du 640×640) ; ramenés à la taille d'affichage ils en pèsent 4,2.
+- ⚠️ **128 détourages ont été détruits, puis réparés** (2026-09-08). Le premier ré-encodage sortait
+  TOUT en JPEG, un format sans couche alpha : les 128 photos détourées ont été aplaties sur le noir
+  du canevas. Rien n'a échoué — les fichiers étaient valides, la page les affichait, et sur la
+  planche de contrôle je les ai lues comme des « fonds studio sombres ». **Un défaut qui produit
+  un résultat plausible ne se voit pas.** Il n'a été trouvé qu'en comptant les pixels non opaques
+  des sources, en cherchant tout autre chose. Mesuré : 37 à 54 % de transparence par détourage.
+  Ils sont maintenant en **WebP** — 2 Mo contre 17,3 en PNG — et le générateur relit chaque fichier
+  écrit pour vérifier que l'alpha a survécu. La sortie (copie, téléchargement) reste du PNG : le
+  presse-papier n'accepte que lui, et un fichier téléchargé part souvent vers un outil sans WebP.
+- **Les fonds du rangement « Couleur » viennent de la couche utilitaire** (2026-09-08), pas de la
+  marque. C'est la couche dont le rôle est de catégoriser ; un fond d'avatar ne dit ni succès, ni
+  erreur, ni appartenance. La teinte est tirée du nom, donc stable d'un rendu à l'autre.
+- **Les drapeaux et les curseurs sont derrière leur propre point d'entrée** (2026-09-08). 328 Ko
+  et 94 Ko, contre 197 pour tout le reste : dans le tronc commun, ils auraient triplé le paquet
+  pour tout le monde, y compris les écrans qui n'en affichent aucun. C'est une modification de la
+  **forme publique** du paquet, pas un arbitrage de conception — signalée à Micka avant d'être
+  faite. Voir « Three entry points » plus haut, et la garde écrite dans `src/index.ts`.
+- **Les couleurs des drapeaux ne sont PAS portées sur les jetons** (2026-09-08), à l'inverse
+  exact de la règle des icônes de type de fichier. Là-bas la couleur catégorise, donc elle doit
+  suivre le thème ; ici le bleu du drapeau français est un fait national. Les deux familles se
+  ressemblent — un petit dessin polychrome dans une liste — et obéissent à des règles opposées.
+  Même raisonnement pour les curseurs : noirs et blancs parce qu'ils doivent rester lisibles sur
+  n'importe quel fond, pas par défaut de marque. Deux exceptions mesurées, dans leurs catalogues.
+- **`brand` est le BLEU de Zest, pas son vert** (2026-09-07). Le Figma nomme sa rampe bleue
+  « Bleu (Primaire) » et dit qu'elle porte « tous les éléments interactifs » ; sa rampe verte
+  s'appelle « Vert (Succès) ». Peindre la marque en vert rendrait un bouton principal et un badge
+  « Terminé » indiscernables. Le vert de marque `#00D85D` vit à part, sous `--zds-color-mark`,
+  pour le logo et les dégradés — il n'affiche que 1,83:1 sur blanc. ⚠️ **Les quatre prototypes
+  Zest ont `brand` en vert** : le design system les contredit volontairement.
+- **`brand-600` vaut le `Bleu/200` du Figma, pas son pivot `Bleu/100`.** Le pivot n'affiche que
+  3,60:1 sous du texte blanc, le 200 tient 4,54:1 — et un bouton plein doit tenir 4,5:1. Le pivot
+  atterrit sur le 500, où la couche 3 s'en sert pour `border-brand` et `focus-ring`.
+- **On garde la numérotation 50 → 950**, pas celle de Zest (10 → 600). Un composant transposé
+  fonctionne sans être renuméroté. La page « Couleurs » affiche les deux numéros sur chaque
+  palier, et c'est le seul endroit où la correspondance est visible.
+- **Le texte de statut est sur le 700, pas le 600** (2026-09-07). Le Figma nomme ces variables
+  `text-error-primary (300)`, et Zest/300 est notre 700. Le contraste va dans le même sens : deux
+  des trois ne tenaient pas l'AA (3,59 et 3,49), les trois le tiennent maintenant
+  (6,57 / 5,08 / 5,43). Les `fg-*` (icônes) et les `bg-*-solid` (aplats) restent sur le 600 :
+  l'annotation du Figma ne porte que sur `Couleurs/Texte`, et une icône relève du seuil 3:1.
+- **Les DEUX rampes neutres servent, et c'est la règle** (2026-09-07 : « dans la réalité, on
+  utilise les deux »). Ce n'est pas une incohérence à réparer : `navy` porte ce qu'on **lit**,
+  `gray` ce **sur quoi** on lit.
+
+  | | `navy` (Bleu marine) | `gray` (Gris) |
+  |---|---|---|
+  | Texte | les huit rangs | — |
+  | Bordures | les trois neutres | — |
+  | Fonds | — | tous |
+  | Icônes (`fg-*`) | — | toutes |
+
+- **Les trois bordures neutres sont sur `navy`** (2026-09-07). `border-primary = navy-40` est
+  donné ; les deux autres sont déduits — `secondary = navy-30`, `tertiary = navy-20`. La
+  déduction est **mesurée** : chaque palier du Bleu marine est le jumeau bleuté d'un palier du
+  Gris à 4-5 unités par canal, et décaler d'un cran ferait bondir l'écart à 20-22.
+- **Les palettes utilitaires vont jusqu'à 950** (2026-09-07). Elles s'arrêtaient à 700, ce qui
+  amputait chaque palette secondaire de ses trois paliers les plus sombres — 21 valeurs
+  dessinées, absentes du code. Le Figma annote leur contraste AAA : elles sont prévues pour
+  porter du texte. Une seule échelle dans tout le fichier.
+- **Le huitième dégradé s'appelle « Piloter »** (2026-09-07). Le seul des huit dont le nom ne
+  vient pas du Figma : ses trois pastilles n'y sont reliées à aucune variable. Il complète la
+  famille de verbes du produit — Écouter, Réussir, Partager, Piloter.
+- **Six jetons `_alt` identiques à leur jumeau ont été retirés** (2026-09-07). Ils n'existaient
+  que pour qu'un mode sombre puisse les faire diverger ; sans mode sombre, deux noms pour une
+  seule couleur. **Trois restent, et ce ne sont pas des doublons** : `border-brand-alt`
+  (brand-600 quand `border-brand` est sur le 500), `border-error-subtle`, et surtout
+  `border-secondary-alt`, le noir à 10 % — une bordure translucide prend la teinte de ce qu'elle
+  recouvre au lieu de la trancher. C'est le seul jeton de couleur sans source dans le tableau de
+  la page « Couleurs », qui l'affiche « valeur propre ».
+- **L'échelle typographique porte les noms de Zest** (2026-09-07) : `caption`, `body`, `heading`,
+  `display`, parce que le nom dit à quoi une taille **sert** plutôt que sa place dans un
+  classement. Treize tailles — les dix du Figma, plus `display-xs`, `display-xl` et
+  `display-2xl`, conservées parce qu'un design system a besoin de grands titres même si les
+  maquettes actuelles n'en ont pas.
+- **`font-weight-medium` n'existe pas, et n'existera pas** (2026-09-07). Averta n'a pas de
+  Medium. Le jeton a existé une demi-journée, aliasé sur 600 ; retiré parce qu'un rang de graisse
+  sans dessin propre est un piège. ⚠️ Dans la livraison de référence, le retirer a demandé
+  `--font-weight-medium: initial` et pas seulement de cesser de le déclarer, parce que son moteur
+  CSS livre le sien à 500. **Ce paquet-ci n'a pas ce problème** : sans moteur, un jeton non
+  déclaré n'existe pas — c'est pourquoi l'`initial` n'est pas porté.
+- **Les six faces de la police sont servies**, vérifié par la mesure : les trois italiques ont
+  leur propre avance — environ 48 px de moins que le droit sur une même chaîne à 48 px — donc ce
+  sont de vrais dessins et non un faux penché par le navigateur.
+- **Pas de `--breakpoint-*` ni de `--animate-*`** (2026-09-08). La bibliothèque de référence en
+  déclare, notre thème n'en a aucun, et c'est voulu : aucun composant n'en réclame encore. Ce
+  n'est pas un oubli à combler au prochain passage.
+- **Le paquet accepte React 18** ; la livraison de référence déclare `^18.3.1 || ^19.0.0` à la
+  demande de l'équipe produit, dont le projet est en `^18.3.1`. Ici les `peerDependencies` sont
+  en `^18.0.0`. ⚠️ **Notre `typecheck` ne vérifie donc qu'une version** ; le jour où un composant
+  emploiera une API de React 19, rien ne le signalera. À revoir quand la couche de composants
+  existera — et la sonde de compilation croisée demande un **témoin** (un fichier important
+  `useActionState`, qui n'existe que dans les types de React 19) : sans lui, le premier essai de
+  la référence était vert pour la mauvaise raison, le fichier de test étant hors du `include`.
+- **La feuille de style ne garde que ce qu'un dev ne peut pas déduire du code** (2026-09-08).
+  Dans la livraison de référence, `theme.css` est passé de 1355 à 630 lignes **sans qu'aucune
+  déclaration ne change** — le CSS émis était identique octet pour octet. Ce qui a disparu, c'est
+  le récit : les dates, les mesures, les tableaux de contraste, les étiquettes
+  `/* Zest Bleu/20 */` répétées ligne à ligne. Tout ça vit dans ce README. **Ne pas re-gonfler
+  les commentaires au prochain passage.**
+
+## Findings kept from the port
+
+Les constats de fabrication : le pourquoi du code, quand il n'appartient ni à une règle du
+design system ni à un arbitrage.
+
+**The Figma numbers ramps 10 → 600, we number 50 → 950.** Zest's pivot is each ramp's 100; ours
+is the 600, because a solid fill has to hold 4.5:1 under white text and the blue pivot only
+reaches 3.60:1. Twelve Zest values for eleven slots: `Zest/10` stays out, being the near-white
+whose absence costs least. The correspondence table lives in `theme.css` **and** on the Colors
+page — the two must stay in agreement.
+
+**`fuschia`, not `fuchsia`.** It's the Figma's spelling, confirmed by the product team on
+2026-09-07. Never "correct" it.
+
+**Never infer a value from a name**, even one carrying a number in parentheses. Twice disproved
+on the source files: `text-secondary (700)` is Navy/**70**, and `text-error-primary (300)` is our
+**600**, not our 700. The Figma even carries stale labels in its own swatches. The variable
+paints, the label narrates.
+
+**Averta has no Medium, and there will be no `--zds-font-weight-medium`.** The family runs
+Extrathin, Thin, Light, Regular, Semibold, Bold, Extrabold, Black — nothing between Regular and
+Semibold. A weight step with no drawing of its own is a trap: the browser fakes one.
+
+**The fallback stack does not contain Inter, on purpose.** A close-looking substitute would mask
+a failed Averta load — the page would look right while being wrong. If Averta doesn't load,
+everything drops to Segoe UI, which is ugly and exactly what we want to see.
+
+**Five names in the icon catalogue carry two drawings.** Not duplicates: other drawings, all
+usable, where a filled silhouette meets an outlined stroke. Only one of each is published as a
+component, because a catalogue with duplicate keys has no single source. Seven more icons mix
+solid and hollow and are filed under "trait" by choice, not by measurement. Both lists are shown
+on the Icons page so the decision can be made by looking — the catalogue's own comment promised
+that, and nothing was keeping the promise. **The fix belongs in the Figma, then regenerate.**
+
+**`overflow-x: auto` also sets `overflow-y`.** Per spec, when one axis is not `visible` the other
+computes to `auto`. It costs nothing here, but a height constraint added later would clip a
+board's bottom rows with no warning.
+
+**Storybook restyles everything inside its docs area, font AND size, and `.sb-unstyled` is the
+way out.** Measured: `.prose` paragraphs rendered at **14px in Nunito Sans** while the sheet asks
+for 16px in Averta — so the Typography page was showing its specimen, its scale and its nine
+examples in neither the font nor the size it documents. Nothing flagged it: `<body>` was in
+Averta and `document.fonts.check("16px Averta")` answered "loaded". **Loaded is not applied.**
+
+Two fixes, and they are not interchangeable. `parameters.docs.theme` with `fontBase` sets the
+font of the *chrome* — the guidelines text, which is Storybook's to style and was in an unchosen
+default. `.sb-unstyled`, Storybook's own opt-out class, is what a *board* needs: a board
+demonstrates the design system, so it must render what the design system renders. `Frame` carries
+it; anything dropped straight into an `.mdx` outside a frame has to carry it itself.
+
+**A hidden element measures like a broken one.** Three probes on this project concluded on
+something invisible: Storybook's loading skeleton (an argstable stub counted as real rows), its
+"No Preview" screen (two `h1` in the wrong font), and a page that was never loaded at all. Any
+probe should skip `offsetParent === null` and refuse to conclude when Storybook says "Couldn't
+find story".
+
+**A number measured in the reference delivery is not a number about this repo.** Its README
+states 89 characters per prose line; the same column and the same font measure **103** here,
+because the example article isn't the same text. Re-measure, don't inherit.
+
+### Les décisions ouvertes sur les icônes
+
+Retirées des pages le 2026-09-08 : elles posent une question à trancher, mais le site dit ce qu'il
+faut faire, pas ce qui reste à décider. **Les deux se corrigent dans le Figma, puis on régénère** —
+le catalogue est généré, une retouche locale serait écrasée sans laisser de trace.
+
+**Cinq noms portent deux dessins.** Ce ne sont pas des doublons : ce sont d'autres dessins, tous
+utilisables, où une silhouette remplie affronte un tracé au contour. Un seul est publié, l'autre
+vit dans `ZEST_ICONS_EN_CONFLIT`. Le départage actuel n'est pas un choix de dessin — c'est
+l'ordre des catégories du Figma.
+
+| Nom | Publié | Écarté | Pourquoi celui-là |
+| --- | --- | --- | --- |
+| `share-01` | contour (Général) | contour (Général) | Général arrive avant |
+| `help-circle-01` | remplissage (Général) | contour (Général) | Général arrive avant |
+| `help-circle-02` | remplissage (Général) | remplissage (Général) | Général arrive avant |
+| `settings-01` | remplissage (Général) | contour (Général) | Général arrive avant |
+| `mail-01` | remplissage (Modules) | contour (Général) | préférence explicite pour Modules |
+
+⚠️ Le commentaire de `ZEST_ICONS_EN_CONFLIT` promet que « la page Icônes les montre à côté de ceux
+qui gagnent ». Ce n'est plus vrai, et ça ne l'a jamais été côté site de référence. **Corriger le
+commentaire à la prochaine génération** — une promesse écrite dans le code que rien ne tient est
+pire que pas de promesse.
+
+**Sept icônes ont un style discutable**, rangées en « trait » par choix et non par mesure. Les
+basculer en « plein » les sortirait de l'onglet où on les cherche.
+
+| Nom | Ce qui hésite |
+| --- | --- |
+| `feature-action-plan` | le curseur est plein, l'arc est un trait épais |
+| `feature-objective` | des anneaux pleins qui se lisent comme un dessin creux |
+| `feature-idea` | l'ampoule est creuse, son culot est plein |
+| `download-01` | remplie, mais dessinée comme un trait |
+| `upload-01` | remplie, mais dessinée comme un trait |
+| `plus` | une croix n'a ni creux ni plein |
+| `tick` | une coche n'a ni creux ni plein |
+
+### Les ombres livrées ne sont pas celles de la marque
+
+Retiré de la page « Ombres » le 2026-09-08, pour la même raison.
+
+La seule ombre relevée dans le Figma — `Shadows/shadow-lg` — est teintée `#101828`, un bleu très
+sombre, et elle empile **deux** couches là où la nôtre en met trois. Les sept paliers du thème
+viennent de la feuille de référence, en `rgba(0, 0, 0, …)`. **La géométrie est la même de part et
+d'autre ; la teinte changera** le jour où `Couleurs/Effets/Ombres` sera lu. Un composant écrit
+aujourd'hui n'aura rien à changer — seule la valeur des jetons bougera.