@cyrilld/zestds 0.1.0 → 1.0.0

package/README.md

@@ -10,18 +10,20 @@ 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".
+Today the package publishes **the tokens, the icon families, the logo and the button family**.
+Phase 2 started on 2026-09-09 with `Button`, `CloseButton`, `UtilityButton` and `Spinner` — see
+"Ce qui reste à faire" for what follows.
 
 **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.
+Its Storybook is the design system's documentation, written in French. Twelve Foundations pages
+are written — colors, typography, spacing, radius, shadows, the focus ring, icons, file icons,
+flag icons, cursors, avatars, logo — plus the first Base components page, Boutons. The rest of the
+plan sits alongside them as **announced but empty pages**: two remaining foundations, then the
+other Base components and the 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
@@ -38,7 +40,8 @@ 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
+    base/            Button/ CloseButton/ UtilityButton/ Spinner/ Badge/ Avatar/ Tooltip/
+                     Checkbox/ Toggle/ — phase 2, since 2026-09-09
     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
@@ -69,7 +72,7 @@ Colors are layered, and a component only ever cites the last two:
 | 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 |
+| Component | `--zds-color-toggle-bg-pressed` | 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
@@ -79,14 +82,14 @@ eight brand gradients in three angles each.
 
 | Import | What | Weight |
 | --- | --- | --- |
-| `@cyrilld/zestds` | tokens, 121 icons, 27 file icons | 197 KB |
-| `@cyrilld/zestds/flags` | 234 country flags | 328 KB |
+| `@cyrilld/zestds` | tokens, 135 icons, 27 file icons, the logo, the nine base components | 249 KB (+ 70 KB CSS) |
+| `@cyrilld/zestds/flags` | 234 country flags | 329 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
+added to `src/index.ts` for convenience would take the root from 249 KB to over 670 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
@@ -159,8 +162,16 @@ To try local changes in another project before publishing a new version:
 | `yarn typecheck`          | Type-check the package                                   |
 | `yarn lint`               | Lint the package                                         |
 | `yarn build`              | Build to `dist/` (ESM, CJS, types, CSS)                  |
+| `yarn verify:interrupteur` | Les QUATRE géométries, le déplacement PEINT du bouton, la bordure déclarée ET peinte, le survol dans les deux sens, et cinq contrastes épinglés |
 | `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 |
+| `yarn verify:tokens`      | Les composants ne citent que les couleurs de Zest, et aucun jeton de composant ne redouble un rôle |
+| `yarn verify:foundations` | Le thème se lit en entier, aucune valeur brute qu'un jeton nomme déjà, aucune mention du fournisseur tiers |
+| `yarn verify:buttons`     | Géométrie, spinner, contrastes et anneau de focus des boutons — mesurés sur la peinture |
+| `yarn verify:badges`      | Les 207 badges contre le modèle relevé sur les 477 symboles du Figma, plus 26 contrastes |
+| `yarn verify:avatars`     | Les six boîtes, les deux géométries du point de statut, les chevauchements, trois contrastes |
+| `yarn verify:info-bulles` | Les deux anatomies, le débord PEINT de la flèche sur les quatre côtés, les six placements, et que la flèche pointe sur le centre du déclencheur |
+| `yarn verify:checkboxes`  | Les DEUX pages en une passe : les tailles et les sept valeurs qui changent avec elles, l'épaisseur PEINTE de la marque, et cinq contrastes épinglés |
 
 `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
@@ -187,10 +198,18 @@ git tag automatically (e.g. `v0.2.0`) — `--follow-tags` pushes both the commit
 
 ## 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.**
+**127 tests across nine component suites** (counted 2026-09-11): 27 on the avatars, 23 on the
+tooltip, 18 on the checkbox and its radio, 17 on the badge, 15 on the toggle, and 27 over the
+button family — `Button` 15, `CloseButton` 5, `UtilityButton` 4, `Spinner` 3. `--passWithNoTests` was dropped on
+2026-09-09, as planned: the suite is no longer empty, so a red `yarn test` means something again.
+
+The tests check **behaviour, not paint**. They do not assert a padding or a colour: those live in
+the component's CSS sheet, and jsdom does not apply imported sheets — a test claiming
+`padding: 10px` here would lie the day the CSS moved, without ever failing. The browser boards on
+the Boutons page measure those, for real. What the tests do pin down is the three places the
+button departs from reflex: loading blocks activation WITHOUT leaving the tab order, "icon only"
+is derived from the absence of a label rather than declared, and an unnamed icon-only button
+warns.
 
 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
@@ -231,15 +250,17 @@ both `tsc` and `storybook build`, and only a real browser found them:
       - [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
+      - [x] **Icônes de fichier** — 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
+        l'écart mesuré en Lab. ⚠️ Le cadre Figma `3847:2911` est une bibliothèque **tierce** 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 source d'origine ni le Figma
+        n'en donnent, elles attendent un arbitrage.
+      - [x] **Drapeaux** — 234 drapeaux, page en ligne. ⚠️ **Cette page a changé de nom deux
+        fois** : « Flag icons » à la demande de Micka, puis « Drapeaux » de nouveau le
+        2026-09-11, quand les titres de pages sont repassés en français — voir « Décidé ».
+        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 ».
@@ -263,14 +284,110 @@ both `tsc` and `storybook build`, and only a real browser found them:
         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 ».
+      - [x] **Boutons** — page en ligne, quatre composants livrés le 2026-09-09. `Button`
+        (11 hiérarchies × 5 tailles × 5 états × icône seule), `CloseButton` (3 tailles + fond
+        sombre), `UtilityButton` (28 et 32 px) et `Spinner`. Relevés sur cinq cadres du Figma.
+        Le `Button` retiré le 2026-09-08 est celui-ci, recodé : l'ancien 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. Récupérable par
+        `git checkout 69a30fa -- src/Button` si on veut le relire.
+        ⚠️ **Un écart au Figma, arbitré** — voir « Décidé ».
+        ⚠️ **Trois questions restent ouvertes** — voir « En attente » : les bordures sous les 3:1,
+        le tracé du spinner, et le soulignement des liens.
+        ✅ Retire `.zds-doc-bouton` du provisoire de `docs.css`.
+      - [x] **Badges** — page en ligne, un composant livré le 2026-09-10. `Badge` : 3 habillages
+        (`pill`, `badge`, `modern`) × 3 tailles × **13 couleurs**, plus quatre emplacements — le
+        point, la croix de retrait, une icône de tête, une icône de fin. Relevé sur trois cadres :
+        `Badge` (3869:2612, **477 symboles**), `_Dot` (3874:1192) et `_Badge close X` (3869:4461).
+        ⚠️ **ILS N'ÉTAIENT PAS BLOQUÉS**, et cette ligne a longtemps dit le contraire. Les trois
+        habillages sont deux fonds DOUX et un fond blanc : le Figma ne dessine aucun badge en
+        aplat, donc `success-solid` et `warning-solid` n'y sont employés par personne. L'arbitrage
+        de ces deux jetons reste ouvert — il concerne le premier bouton plein, pas le badge.
+        ✅ **Les treize couleurs tiennent leurs deux seuils de contraste** depuis l'arbitrage du
+        2026-09-10 : turquoise, tilleul et jaune, les trois teintes claires, descendent de deux
+        crans là où les dix autres gardent les leurs. Voir « Décidé ».
+        ⚠️ **Une anomalie du Figma est reproduite** en taille `sm`, et **deux neutres presque
+        identiques** sont livrés faute d'arbitrage. Voir « En attente ».
+        ✅ Ajoute `verify:badges` : géométrie rendue contre le modèle des 477 symboles, 26
+        contrastes, anneau de focus de la croix.
+      - [x] **Avatars** — page en ligne, trois composants livrés le 2026-09-10. `Avatar`
+        (6 tailles × 4 contenus, bordure et statut optionnels), `AvatarGroup` et
+        `AvatarLabelGroup`. Relevé sur CINQ cadres : `Avatar` (3881:5036, 48 symboles),
+        `Status icon` (3881:5020), `Avatar group` (3881:4989), `_Avatar add button` (3881:4946) et
+        `Avatar label group` (3881:4930).
+        ⚠️ **CE DÉPÔT AFFIRMAIT QU'IL N'Y AVAIT PAS DE COMPOSANT AVATAR.** C'était faux : le relevé
+        s'était arrêté sur le cadre de la banque de photos. Voir « Décidé ».
+        ✅ Les **initiales** entrent dans le système, à leur place dans un ordre de priorité —
+        photo > initiales > picto. La règle « jamais d'initiales » de la page Foundations est
+        abrogée, et l'échelle de tailles qu'elle proposait était fausse.
+        ✅ Ajoute deux icônes au catalogue (133 → **135**) et `verify:avatars`.
+        ⚠️ Le statut est **absent par défaut** : la production ne le gère pas encore.
+      - [x] **Info-bulles** — page en ligne, trois composants livrés le 2026-09-10. `Tooltip`
+        (6 positions × flèche optionnelle × ligne de support optionnelle), `HelpTooltip` — l'icône
+        d'aide de 16 px qui porte sa propre bulle — et `TooltipArrow`, le dessin de la flèche.
+        Relevés sur deux cadres : `Tooltip` (3266:935, 14 symboles) et `Help icon` (3266:1096,
+        28 symboles).
+        ⚠️ **Le développeur choisit la position, et rien ne se retourne tout seul.** Arbitrage du
+        lead front : le paquet reste à zéro dépendance d'exécution, donc les six placements sont
+        du CSS. La conséquence est à connaître avant de s'en servir — une bulle posée près du bord
+        de l'écran en sort, et rien ne la retournera. Voir « Décidé ».
+        ⚠️ **Une décision prise le matin même a été renversée** : un premier jet passait par
+        `react-aria-components`, approuvé en dépendance paire puis retiré. Ce qui survit du détour,
+        ce sont ses MESURES, relevées dans un vrai navigateur et reprises à l'identique. Voir
+        « Décidé ».
+        ⚠️ `--zds-color-tooltip-supporting-text` existait déjà, porté du thème de référence, et
+        portait une valeur fausse. Ses trois voisins de bloc sont dans le même cas — des ports que
+        rien n'a confrontés au Figma, et qu'aucun contrôle ne regarde tant que rien ne les cite.
+        ✅ Retire `.zds-doc-bulle` du provisoire de `docs.css` — et ce retrait a découvert que la
+        bulle de la page Icônes n'avait **jamais** peint la bonne couleur. Retire aussi le `title`
+        natif du bouton d'ajout des groupes d'avatars, qui porte désormais une vraie info-bulle.
+        ✅ Ajoute `verify:info-bulles`.
+      - [x] **Cases à cocher et boutons radio** — deux pages en ligne, deux composants livrés le
+        2026-09-10. `Checkbox` (2 tailles × cochée/indéterminée × 4 états, libellé et indication
+        optionnels) et `Radio`, le même atome en rond, dont le `name` est OBLIGATOIRE. Relevés sur
+        deux cadres : `_Checkbox base` (3891:11902, 40 symboles) et `Checkbox` (3891:11629,
+        74 symboles).
+        ⚠️ **Deux pages, une seule feuille de style.** « Cases à cocher » et « Boutons radio » sont
+        rangés séparément — demande produit, alignée sur la bibliothèque de référence — mais les
+        deux composants restent UN atome : `Checkbox.css` habille les deux et `verify:checkboxes`
+        visite les DEUX pages en une passe. Voir « Décidé ».
+        ⚠️ **Sept valeurs changent avec la taille, et trois avaient été uniformisées** — dont
+        l'épaisseur PEINTE de la marque, qui sortait à 1 px au lieu de 1,6666 et se lisait pâle.
+        C'est l'œil de Micka qui l'a signalé, pas les contrôles. Voir « Décidé ».
+        ⚠️ **Deux écarts au Figma, arbitrés, à remonter dans le Figma** : la bordure de la case
+        décochée est foncée à navy-70, le cadre la peignant à 1,44 de contraste — le plus bas
+        mesuré sur ce design system, et ici la boîte EST le contrôle ; et l'état de survol, que le
+        Figma dessine identique au repos sur ses quarante symboles, est dessiné. Voir « Décidé ».
+        ⚠️ **L'indication sous le libellé reste sous le seuil AA**, et ce n'est pas la faute du
+        composant : le Figma la peint `text-secondary`, un rôle qui est sous le seuil partout où il
+        porte du texte. Épinglée à l'envers dans le vérificateur — voir « En attente ».
+        ✅ L'anneau de focus se montre enfin sur une planche, par le crochet `data-zds-demo="focus"`
+        que la page Boutons avait déjà et qui n'avait pas été repris.
+        ✅ Ajoute `verify:checkboxes`.
+      - [x] **Interrupteur** — page en ligne, un composant livré le 2026-09-11. `Toggle` :
+        2 tailles × 2 types (`default`, `slim`) × 4 états, libellé et aide optionnels. Relevé sur
+        deux cadres : `_Toggle base` (3896:1480, 32 symboles) et `Toggle` (3896:1553, 64 symboles).
+        L'ORGANISATION de la page est celle de la page « Toggles » de la bibliothèque de référence,
+        à la demande de Micka : intro, un exemple de tête, Installation, puis les variantes dans son
+        ordre — nu, libellé, libellé + aide, désactivé, tailles, slim, slim + libellé et aide.
+        ⚠️ **Ce n'est pas une case à cocher, et ça ne se remplace pas** : l'interrupteur applique son
+        effet tout de suite. D'où `role="switch"` sur l'input, pour qu'un lecteur d'écran annonce
+        « activé » au lieu de « coché ».
+        ⚠️ **`slim` n'est pas `default` en plus petit** : en `md`, 40 × 20 contre 44 × 24, pour le
+        même bouton de 20. Ce qui change est le retrait, donc la piste du `slim` fait exactement la
+        hauteur de son bouton, et c'est sa bordure qui le détache au lieu de son ombre.
+        ✅ **Les trois jetons `toggle-*` du thème étaient faux, tous les trois**, et le relevé l'a dit
+        d'un coup — dont un dans la rampe grise que le design system n'emploie pas. Voir « Décidé ».
+        ✅ **La collection d'ombres de Zest est lue pour la première fois** : elle est teintée
+        #0a0d12, et pas #101828 comme la phase 1b le supposait. Voir « Décidé ».
+        ✅ **Deux écarts au Figma, arbitrés le jour même** : la bordure de la piste éteinte est
+        foncée à navy-70 comme celle de la case à cocher, et l'état éteint gagne un survol que le
+        Figma ne dessine pas. **Les deux sont à remonter dans le Figma.** Voir « Décidé ».
+        ⚠️ **Une question reste ouverte, et elle vaut aussi pour la case à cocher** : le bouton
+        blanc tient 1,11 contre sa piste. Voir « En attente ».
+        ✅ Ajoute `verify:interrupteur`.
+      - [ ] Champs et liste déroulante — ce qui reste de la phase 2. Les deux pages sont annoncées
+        et vides sous `src/docs/a-venir/` : `Champs.mdx` et `Selecteurs.mdx`.
       - 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
@@ -278,8 +395,149 @@ both `tsc` and `storybook build`, and only a real browser found them:
 
 ## En attente
 
+- ⚠️ **LES TABLEAUX MARKDOWN NE SE RENDENT PAS DANS LA DOCUMENTATION, ET 15 S'AFFICHENT EN MUR DE
+  BARRES VERTICALES** (constaté le 2026-09-11 en relisant une capture de la page « Interrupteur »).
+  Un `| … | … |` écrit dans un `.mdx` ressort tel quel, en une seule ligne de texte : l'extension
+  GFM de remark n'est branchée nulle part dans la configuration de Storybook, et `remark-gfm` n'est
+  même pas installé.
+
+  Le compte, relevé page par page dans le navigateur : « Info-bulles » 5, « Cases à cocher » 3,
+  « Boutons radio » 3, « Introduction » 2, « Logo » 2. Ce sont pour l'essentiel les tableaux de
+  CHOIX (« quel contrôle pour quelle question ») et les tableaux d'API — c'est-à-dire les deux
+  endroits où un développeur va chercher sa réponse.
+
+  ⚠️ **Les tableaux qui se rendent bien sont ceux qui sont des COMPOSANTS.** `<Tableau>` construit
+  un vrai `<table>` en React, donc il ne dépend pas du Markdown : c'est pour ça que les tableaux de
+  tailles et d'états ont toujours eu l'air corrects, et que le défaut est resté invisible. La page
+  « Interrupteur » est passée sur `<Tableau>` pour ses deux tableaux, donc elle n'en porte plus.
+
+  **Deux réparations possibles, et c'est un arbitrage :** brancher `remark-gfm` dans
+  `.storybook/main.ts`, ce qui répare les 15 d'un coup mais ajoute une dépendance de développement
+  et change le rendu de cinq pages ; ou convertir les 15 en `<Tableau>`, sans dépendance, mais à la
+  main.
+
+  *Repère : le défaut ne se voit pas en écrivant la page — il se voit en la REGARDANT rendue. Aucun
+  contrôle du dépôt ne lit le texte d'une page pour y chercher du Markdown non interprété.*
+
+- ⚠️ **LE BOUTON BLANC DE L'INTERRUPTEUR ÉTEINT TIENT 1,11 CONTRE SA PISTE, ET RIEN NE LE RATTRAPE**
+  (mesuré le 2026-09-11, en tranchant les deux questions ci-dessus). Une fois la bordure de la piste
+  montée à navy-70, la limite du contrôle passe son seuil — mais la POSITION du bouton, qui est ce
+  qui porte l'état, reste portée par un disque blanc sur un fond navy-20. En type `default` il n'a
+  même pas de bordure : c'est son ombre seule qui le détache, et une ombre ne compte pas dans un
+  calcul de contraste.
+
+  La WCAG 1.4.11 demande 3:1 pour « les parties d'un objet graphique nécessaires à la
+  compréhension ». La position du bouton en est une.
+
+  **Ce n'est pas arbitré, et je ne l'ai pas arbitré tout seul**, pour deux raisons : réparer
+  demanderait de changer le dessin du bouton — une bordure sur le type `default`, ou un fond qui
+  n'est plus blanc — c'est-à-dire de s'écarter du Figma sur la pièce la plus visible du composant ;
+  et c'est un dessin que toutes les bibliothèques du marché livrent tel quel. **La même question se
+  pose à l'identique sur la case à cocher décochée**, dont la boîte blanche tient 1,11 contre la
+  page. À trancher pour les deux, ou pour aucun.
+
+- ⚠️ **`text-secondary` EST SOUS LE SEUIL AA, PARTOUT OÙ IL PORTE DU TEXTE** (relevé le
+  2026-09-10). Le rôle vaut navy-70 (#7e8694), qui tient **3,67** sur du blanc pour un seuil de 4,50
+  sur du petit texte. Ce n'est pas le problème d'un composant : c'est le rôle.
+
+  Découvert en codant la case à cocher, dont le Figma peint le texte d'aide avec ce rôle. Le foncer
+  dans ce composant seulement rendrait cette aide différente de toutes les autres du design system,
+  donc il est resté tel quel et **épinglé** dans `verify:checkboxes` — le jour où le rôle sera
+  foncé, ce contrôle rougira, et ce sera le rappel qu'il faut retirer l'exception.
+
+  Les paliers : navy-80 (#4d5971) tient 7,04, navy-70 tient 3,67. Il n'y a **rien entre les deux**
+  dans la rampe — c'est la même pénurie de paliers sombres que l'échelle de texte documente déjà
+  (quatre paliers foncés pour huit rangs). Foncer `text-secondary` sur navy-80 le rendrait égal à
+  `text-tertiary`, donc la question n'est pas seulement « quel palier » mais « combien de rangs de
+  texte gris nous faut-il vraiment ». **À arbitrer par l'équipe produit, pas par un composant.**
+
+
 Des décisions qui appartiennent à Micka ou à l'équipe produit, pas au code.
 
+- ⚠️ **LA COLLECTION SÉMANTIQUE DU FIGMA NE COUVRE PAS LES FONDS.** C'est la question de fond
+  soulevée le 2026-09-09, et elle est plus large qu'un jeton mal choisi.
+
+  Relevé sur la page « Couleurs » (`4:8067`) : la collection « 1. Usage des couleurs » nomme
+  `Couleurs/Texte/`, `Couleurs/Bordure/` et `Couleurs/Effets/Ombres/`. **Il n'y a pas de
+  `Couleurs/Fond/`.** Conséquence directe et vérifiable : le Figma peint lui-même l'aplat du
+  `Secondary gray` avec `Couleurs/Bleu marine/20`, une RAMPE BRUTE, parce qu'aucun jeton sémantique
+  ne nomme cette surface.
+
+  Côté thème, la couture est la même vue d'un autre angle : `text-*` et `border-*` sont passés sur
+  le navy de Zest le 2026-09-07, `bg-*` et `fg-*` sont restés sur la rampe gris NEUTRE, celle que
+  Zest n'emploie pas pour son interface. `--zds-color-bg-secondary` vaut `gray-50` (`#FAFAFA`) quand le Figma peint
+  `navy-20` (`#F1F3F5`) — deux familles différentes, donc aucun rôle existant ne peut nommer ces
+  aplats sans mentir.
+
+  Les quatre aplats du bouton sont donc écrits en jetons de COMPOSANT
+  (`--zds-color-button-secondary-bg` & co) plutôt qu'en repointant `bg-secondary`, ce qui aurait
+  déplacé toutes les surfaces du paquet. **Deux décisions à prendre, dans cet ordre :**
+
+  1. **ajouter un groupe `Couleurs/Fond/` à la collection sémantique du Figma** — c'est lui qui
+     manque, et tant qu'il manque chaque composant réinventera ses noms d'aplat ;
+  2. **repointer `bg-*` et `fg-*` sur le navy** une fois ce groupe écrit.
+
+  Le bouton est le premier composant à s'asseoir sur cette couture ; le deuxième la retrouvera.
+  `yarn verify:tokens` garde la trace : il échoue si un jeton de composant redouble un rôle
+  existant de la MÊME catégorie, et laisse passer les fonds — l'exception est explicite dans le
+  script, pas oubliée.
+- ⚠️ **LE CORPS DE TEXTE DE LA DOCUMENTATION N'EST PAS SUR L'ÉCHELLE DU DESIGN SYSTEM.** Mesuré
+  dans le navigateur le 2026-09-09 : les paragraphes des pages Storybook rendent à **14 px** en
+  `#2E3438` — ni le `body-md` de 16 px de l'échelle, ni aucune couleur de Zest (`text-tertiary`
+  vaut `#4D5971`). La POLICE avait été corrigée en septembre via `fontBase` dans `preview.ts` ; la
+  taille et la couleur ne l'ont pas été.
+
+  ⚠️ **Et `.prose` ne peut pas servir à ça**, ce qui a été vérifié empiriquement plutôt que
+  supposé : posée sur `.sbdocs-content`, elle ne change QUE la couleur héritée du conteneur. Les
+  paragraphes restent à 14 px, les titres à 24, la largeur à 1000. C'est par construction — son
+  en-tête dit que « chaque sélecteur est enveloppé dans `:where()`, donc à spécificité nulle :
+  cette feuille propose une mise en page, elle ne l'impose pas ». Les règles de Storybook la
+  battent partout. Deux autres raisons l'excluent de toute façon : elle plafonne à **720 px**, ce
+  qui écraserait les aperçus et les planches pleine largeur, et la page « Typographie » la
+  DÉMONTRE — un spécimen posé dans un conteneur identique à lui ne démontre plus rien.
+
+  **La voie praticable** est celle que `preview.ts` a déjà prise pour la police : des règles dans
+  `docs.css`, avec la spécificité nécessaire pour battre Storybook. Ça touche l'aspect des douze
+  pages, d'où l'arbitrage. **Faut-il aligner le corps de texte de la doc sur l'échelle ?**
+- **Les deux bornes du biseau skéuomorphique** (2026-09-09). Le MCP Figma rapporte le contour des
+  aplats comme plat, sur deux lectures ; le dégradé est donc implémenté d'après la recette standard
+  (`rgba(255,255,255,0.12)` en haut, extinction complète en bas) et non d'après un relevé. **À
+  confirmer dans le Figma**, ou à corriger sur les deux jetons `--zds-color-button-bevel-*`.
+- **Le tracé du spinner est une construction, pas un relevé** (2026-09-09). Le cadre
+  `Buttons/Button loading icon` (3861:2509) existe et donne deux tailles, 20 et 24 px, mais son
+  export SVG passe par une URL que la machine de relevé n'a pas le droit d'appeler. Ce qui est
+  livré est un anneau conventionnel — piste à 30 % du `currentColor`, tête d'un quart de tour —
+  qui a l'avantage de suivre la couleur du texte, donc de servir en blanc sur un Primary comme en
+  rouge sur un destructif. **À remplacer par le vrai tracé**, ou à valider tel quel. Et de toute
+  façon un cadre statique ne décrit ni durée, ni sens, ni courbe d'accélération.
+- **Le soulignement des liens au survol** (2026-09-09). Le Figma le peint plus CLAIR que le
+  libellé — texte au palier 700, trait au 500 — et il fait pareil sur le lien destructif. Mais
+  `link-gray` ne suit pas : son trait suit son texte. Reproduit tel quel, pas harmonisé. **Motif
+  ou oubli ?**
+
+
+- ⚠️ **LE BADGE OFFRE DEUX NEUTRES, ET ILS SE RESSEMBLENT** (2026-09-10). `navy`, le neutre de
+  Zest, et `gray`, celui de la livraison de référence. Trois indices font penser à une migration
+  inachevée plutôt qu'à un choix : le fond du badge `navy` est encore peint dans le Figma par
+  `Component colors/Utility/Slate/utility-slate-50` (#f8fafc), une variable d'une **collection
+  tierce** étrangère à celle de Zest ; le `gray` porte son libellé sur la rampe grise, que Zest
+  n'emploie pas pour ses textes ; et rien ne dit lequel employer quand.
+
+  Les deux sont livrés, parce que les deux sont dessinés. `verify:tokens` porte une exception
+  **énumérée** — cinq citations nommées dans `GRIS_ADMIS` — et il échoue aussi si l'une d'elles
+  cesse d'être citée : le jour où `gray` disparaît, la dispense part avec lui. **À trancher.**
+
+- **Quatre fonds de badge s'écartent du Figma, et c'est mesuré** (2026-09-10). Le Figma peint le
+  fond de `brand`, `success`, `horizon` et `fuschia` avec le palier `Zest/10`, celui que notre
+  échelle 50 → 950 laisse dehors. Les quatre prennent le `-50` : ΔE 5,46 · 5,79 · 4,45 · 8,79.
+  Les quatre restent au-dessus de l'AA sous leur libellé — l'écart coûte une nuance, pas une
+  lisibilité. Récupérer `Zest/10` demanderait un palier `25` sur les rampes, ce qui est la
+  décision de design system déjà listée dans le `CLAUDE.md`.
+
+  Le badge `navy` est dans le même cas, l'écart en moins : `utility-slate-50` #f8fafc contre notre
+  `navy-10` #f9fafb, **ΔE 0,61** — invisible à l'œil et mesurable. Substitué sans hésitation, mais
+  le Figma reste à repointer.
+
 - ⚠️ **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
@@ -287,10 +545,36 @@ Des décisions qui appartiennent à Micka ou à l'équipe produit, pas au code.
   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é.
+  second. Les fonds **doux** vont bien : le défaut ne touche que les aplats.
+
+  ⚠️ **CETTE ENTRÉE A LONGTEMPS DIT DEUX CHOSES FAUSSES**, corrigées le 2026-09-10.
+
+  **Un.** Elle annonçait que ces deux jetons bloquaient « le premier badge ». C'est faux : le
+  cadre `Badge` ne dessine aucun aplat, ses trois habillages sont deux fonds doux et un fond
+  blanc. Aucun des deux jetons n'y est cité. Seul le premier bouton PLEIN de statut les attend.
+
+  **Deux.** Elle présentait les dix étiquettes d'icône de fichier comme des « victimes » de cette
+  décision. Elles n'en sont pas, et ça a été vérifié plutôt que déduit : en basculant les deux
+  jetons sur le 700, `verify:labels` sort **les dix mêmes échecs, aux mêmes 3,59 et 3,49**. Les
+  SVG citent `--zds-color-success-600` et `--zds-color-warning-600` DIRECTEMENT, pas le jeton
+  d'aplat. C'est un problème indépendant, dont l'en-tête du catalogue nomme déjà la cause : « le
+  design system n'a ni orange, ni vert, ni rouge utilitaires », donc CSV et PPT empruntent les
+  rampes sémantiques faute de teinte de catégorisation. À trancher à part, et `verify:labels`
+  devrait cesser d'accuser `bg-*-solid`.
+
+  **Ce qui reste, et ce que la mesure ajoute.** Descendre les deux aplats sur le **700** (5,08 et
+  5,43) répare le statut et rien de plus : mesuré sur les 13 couleurs de la palette, un aplat
+  saturé sous du texte blanc échoue pour **7 couleurs sur 13** au palier 600 et encore **3 sur 13**
+  au palier 700 — lime, jaune et turquoise, qu'il faudrait descendre au 800 ou au 900, où le lime
+  n'est plus du lime. Autrement dit : **il n'existe aucun palier qui fasse marcher un BOUTON PLEIN
+  sur toute la palette.**
+
+  ⚠️ **Ne pas lire cette dernière phrase comme un verdict sur le badge.** Le badge, lui, a été
+  réglé le 2026-09-10 en descendant ces trois teintes de deux crans — voir « Décidé » — et ça
+  marche parce que son FOND reste au palier 50 : c'est le fond pâle qui porte l'identité de la
+  teinte, et seuls le texte et la pièce foncent. Sur un aplat saturé c'est l'inverse : le fond EST
+  la teinte, et le foncer la détruit. La même couleur, deux conclusions opposées, parce que ce
+  n'est pas la même surface qui porte l'information.
 - **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`)
@@ -309,19 +593,53 @@ Des décisions qui appartiennent à Micka ou à l'équipe produit, pas au code.
   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.
+- ⚠️ **DEUX ICÔNES ET UN STATUT À FINIR DE CADRER, côté Figma** (2026-09-10). Le composant Avatar
+  est livré, mais trois choses lui restent dues :
+
+  `message-alert-square-01` et `-02` ont été **ajoutées au catalogue à la main** depuis le cadre
+  `31:9082`. Le catalogue se dit « généré » : il n'existe en réalité aucun générateur dans le
+  dépôt, et les 135 entrées ont toutes été relevées de la même façon. Ce n'est pas un défaut, mais
+  l'en-tête du catalogue promet une régénération qui n'est pas outillée. **À écrire, ou à
+  reformuler.**
+
+  Le statut « Com. sensible » porte une **étiquette abrégée** dans le Figma, et rien dans les
+  projets Zest ne la définissait — il a fallu demander. L'API l'appelle `sensitive-comment` et la
+  page écrit « commentaire sensible ». **À renommer dans le Figma** pour que le prochain relevé
+  n'ait pas à demander.
+
+  Enfin ses trois cadres portent des variables d'une **collection tierce** :
+  `utility-neutral-300` peint le statut hors ligne, `Colors/Background/bg-primary` l'anneau du
+  groupe, et `Bleu marine/100` existe en double — une fois dans `Couleurs/`, une fois hors
+  collection. Substitués par mesure, **le Figma reste à repointer**.
+
+- ⚠️ **LE RAYON DE L'INFO-BULLE EST ÉCRIT AVEC UN JETON D'ESPACEMENT DANS LE FIGMA** (relevé le
+  2026-09-10 sur le spécimen `Size=md, State=Hover` du cadre `_Avatar add button`, 3881:4984) —
+  `rounded-[var(--spacing-md)]`, et non un jeton de rayon. Les 8 px tombent juste par
+  coïncidence : c'est aussi la valeur du `radius-sm` du Figma. **À repointer** avant que quelqu'un
+  ne change l'échelle d'espacement.
+
+  ✅ **Le reste de cette entrée est clos depuis le 2026-09-10.** Elle disait que l'info-bulle du
+  bouton d'ajout d'un groupe d'avatars attendait le composant `Tooltip`, et que le bouton portait
+  un `title` de navigateur en attendant. `Tooltip` est livré, le bouton le porte, et le `title` a
+  été retiré — voir « Décidé ». Le relevé du spécimen reste ici, puisque c'est lui qui porte la
+  question du rayon ouverte ci-dessus, et qu'il dit à quoi la bulle du bouton d'ajout doit
+  ressembler :
+
+  | Ce que c'est | Ce que le Figma peint |
+  |---|---|
+  | Fond | `Couleurs/Bleu marine/100` (#21304e) |
+  | Libellé | `caption-md` 12/18 semibold, blanc, centré, sans retour |
+  | Padding | `spacing-lg` 12 px à l'horizontale, `spacing-md` 8 px à la verticale |
+  | Rayon | 8 px |
+  | Flèche | 16 × 6, sous la bulle, centrée |
+  | Ombre | `0 12px 8px rgb(16 24 40 / 0.08)`, `0 4px 3px rgb(16 24 40 / 0.03)` |
+  | Position | au-dessus du bouton, centrée, base à 43 px de son centre |
+
+- ⚠️ **LA PLANCHE DU REPLI DE LA PAGE FOUNDATIONS DESSINE SES RONDS À LA MAIN** (2026-09-10). Elle
+  a été faite quand aucun composant n'existait. La basculer sur `<Avatar>` changerait le dessin de
+  cette page — un arbitrage de design et non un rangement — donc c'est signalé et non appliqué,
+  comme `.zds-doc-copie` l'est pour les boutons. Même remarque pour la planche des tailles, dont
+  l'échelle est désormais fausse : la page le dit en rouge au lieu de la refaire.
 - **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.
@@ -360,6 +678,796 @@ Des décisions qui appartiennent à Micka ou à l'équipe produit, pas au code.
 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.
 
+- ⚠️ **LES TITRES DE PAGES SONT PASSÉS EN FRANÇAIS LE 2026-09-11** (demande de Micka). Quatre
+  restaient en anglais : « Checkboxes » devient **Cases à cocher**, « Radio buttons » **Boutons
+  radio**, « File icons » **Icônes de fichier** et « Flag icons » **Drapeaux**.
+
+  Les trois SECTIONS restent en anglais — « Foundations », « Base components », « Application
+  components ». Ce n'est pas un oubli : le préfixe du titre est ce sur quoi `verify:foundations`
+  partage les pages de composant des pages de fondations, et le renommer changerait l'identifiant
+  de toutes les pages du dépôt d'un coup.
+
+  ⚠️ **« Drapeaux » ANNULE UNE DÉCISION DE MICKA LUI-MÊME.** Cette page avait été renommée
+  « Flag icons » — en anglais — à sa demande ; la règle du jour la ramène au français. Les deux
+  fois, c'est bien lui qui a tranché. C'est écrit ici pour que personne ne « répare » le nom en
+  tombant sur l'ancienne entrée.
+
+  **Un titre n'est pas une étiquette, c'est l'identifiant de la page.** Storybook le dérive du
+  `<Meta title>` : « Cases à cocher » donne `base-components-cases-à-cocher--docs`, accents
+  compris, à encoder en URL comme `Foundations/Icônes` l'était déjà. Ont dû suivre le renommage :
+  l'ordre de la barre latérale dans `.storybook/preview.ts`, les deux pages et leurs identifiants
+  de repli dans `verify:checkboxes`, les renvois d'une page à l'autre, et les commentaires des
+  planches. Et `verify:render` lit les identifiants dans `storybook-static/index.json` : sans un
+  `yarn build-storybook` rejoué, il visite les anciens.
+
+- ⚠️ **LA BORDURE DE L'INTERRUPTEUR ÉTEINT EST FONCÉE À navy-70, COMME CELLE DE LA CASE À COCHER**
+  (2026-09-11, arbitrage délégué après mesure). Le Figma peint la limite du contrôle
+  `border-primary` (navy-40), qui tient **1,44** sur du blanc pour un seuil de 3:1, sur un fond
+  navy-20 qui tient 1,11.
+
+  **Ce dépôt tranche ce cas sur une seule question, et elle est mesurable :** y a-t-il autre chose,
+  DANS le contrôle, qui le rende identifiable à 3:1 ? Le bouton garde son libellé à 11,82, donc sa
+  bordure est restée au Figma à 2,17. La case à cocher n'a rien, donc elle est montée à navy-70.
+  L'interrupteur éteint, mesuré : son bouton blanc tient **1,11** contre sa piste, et en `slim` la
+  bordure de ce bouton tient **1,30**. Rien n'atteint 3 — il est dans le cas de la case, pas dans
+  celui du bouton. navy-70 tient 3,67.
+
+  ⚠️ **ET LA BORDURE DU BOUTON DU TYPE `slim` SUIT, pas seulement la piste.** En `slim` le bouton
+  remplit la piste : sa bordure est la SEULE chose qui l'en sépare, et la position du bouton EST
+  l'état. La foncer d'un côté seulement donnerait un anneau extérieur net autour d'un bouton
+  invisible — 3,30 contre la piste au lieu de 1,30.
+
+  ⚠️ **TROISIÈME FOIS QUE CET ARBITRAGE EST RENDU À PARTIR DE navy-40** — la case à cocher, le point
+  « hors ligne » de l'avatar, l'interrupteur. **Ce n'est plus une exception, c'est la règle du
+  dépôt**, et elle s'énonce en une phrase : *une limite de contrôle qui n'est rattrapée par rien
+  d'autre monte à navy-70.* À remonter dans le Figma, pour les trois.
+
+  ⚠️ **Le jeton retrouve son NOM d'origine.** `--zds-color-toggle-border` était le jeton porté du
+  thème de référence, supprimé le matin même parce qu'il valait `gray-300` et qu'un rôle suffisait.
+  Il revient le soir, à navy-70 : **son nom était juste, sa valeur était fausse, et le rôle ne
+  suffisait plus une fois l'arbitrage rendu.**
+
+- ⚠️ **L'INTERRUPTEUR ÉTEINT GAGNE UN SURVOL, QUE LE FIGMA NE DESSINE PAS** (2026-09-11, arbitrage
+  délégué). Les seize symboles `Pressed=False, State=Hover` sont identiques, propriété par
+  propriété, à leurs `State=Default`. Même constat que sur la case à cocher le 2026-09-10, et même
+  décision : un contrôle qui applique son effet AU CLIC et qui ne répond pas au survol paraît inerte.
+
+  **Une seule règle couvre les deux états** — « au survol, la piste descend d'un cran de sa rampe » :
+  navy-20 → navy-30 éteinte, brand-500 → brand-700 allumée. Micka doit pouvoir la réexpliquer de
+  mémoire, et une exception greffée sur l'éteint l'en empêcherait.
+
+  ⚠️ **LE CRAN EST DISCRET, ET C'EST MESURÉ AVANT D'ÊTRE ASSUMÉ : 1,12** contre la piste au repos.
+  Le palier suivant, navy-40, tiendrait 1,30 — et ce ne serait plus un cran. Un survol n'est pas un
+  état qu'on lit, c'est une confirmation que le contrôle est vivant ; le rendre spectaculaire le
+  ferait concurrencer l'état allumé, qui lui porte l'information. À remonter dans le Figma.
+
+  ✅ **`verify:interrupteur` vérifie les deux sens.** Le survol doit exister sur l'éteint ET sur
+  l'allumé : un ajout au Figma que rien ne garde disparaît sans laisser de trace — la piste
+  resterait plausible, et ni un test ni une capture ne le diraient.
+
+- ⚠️ **ET LE CONTRASTE ÉPINGLÉ A ATTRAPÉ UN DÉFAUT DE LA SONDE, PAS DU COMPOSANT** (2026-09-11).
+  En ajoutant le survol de l'éteint, `verify:interrupteur` s'est mis à mesurer la piste au repos à
+  **1,24 au lieu de 1,11** : le test de survol laisse la souris posée sur un interrupteur, et la
+  mesure des contrastes, qui vient après, lisait donc une piste SURVOLÉE.
+
+  La sonde éloigne maintenant la souris et attend la transition de 0,15 s. **Sans l'épingle, elle
+  aurait rapporté une valeur plausible et fausse** — 1,24 ne ressemble pas à une erreur.
+
+  *Repère : une sonde qui simule une interaction laisse le navigateur dans l'état où elle l'a mis.
+  Ce qu'elle mesure ensuite n'est pas l'état au repos.*
+
+- ⚠️ **LES TROIS JETONS `toggle-*` PORTÉS DANS LE THÈME ÉTAIENT FAUX, TOUS LES TROIS** (2026-09-11).
+  `--zds-color-toggle-border` valait `gray-300` — la rampe que ce design system n'emploie pas —
+  quand le Figma peint la piste éteinte avec `border-primary`, un RÔLE qui existait déjà : le jeton
+  de composant n'avait même pas lieu d'être, et il a été supprimé plutôt que corrigé. Les deux
+  autres peignaient la bordure du bouton fin en brand-600 et son survol en brand-700, quand le Figma
+  dit brand-500 et brand-700.
+
+  C'est exactement ce qui était arrivé à `--zds-color-tooltip-supporting-text` la veille, et pour la
+  même raison : **rien ne les citait, donc aucun contrôle ne les lisait.** La prédiction écrite ici
+  le 2026-09-10 — « des ports, pas des relevés, à vérifier au moment où l'interrupteur sera codé » —
+  s'est vérifiée à 3 sur 3.
+
+  *Repère : un jeton porté d'un autre thème est une hypothèse, pas une valeur. Tant que rien ne le
+  cite, il est invérifiable ; le jour où on le cite, il faut le relire au Figma AVANT de s'en
+  servir.*
+
+  ⚠️ **ET LE SUPPRIMER A LAISSÉ DEUX ÉCHOS.** `--zds-color-toggle-border` servait d'EXEMPLE de
+  jeton de composant à deux endroits — la page « Couleurs » et l'exemple de prose de la page
+  « Typographie » — qui ont donc cité un jeton mort le temps d'un commit. Les deux pointent
+  désormais sur `--zds-color-toggle-bg-pressed`, qui existe et qui illustre mieux la règle : aucun
+  rôle de FOND ne porte brand-500. Aucun contrôle ne l'a vu, parce qu'un nom de jeton écrit dans
+  une page est du texte, pas une citation.
+
+- ⚠️ **LA COLLECTION D'OMBRES DE ZEST EST TEINTÉE #0a0d12, ET NON #101828** (relevé le 2026-09-11,
+  premier accès à `Couleurs/Effets/Ombres`). Le relevé donne `shadow-xs` à 5 %, `shadow-md_01` à
+  10 % et `shadow-md_02` à 6 %, tous sur #0a0d12 — c'est-à-dire le `gray-950` de la livraison de
+  référence, pas la teinte que l'entrée ouverte de la phase 1b annonçait.
+
+  La teinte est **substituée** au noir de notre rampe sur l'ombre du bouton de l'interrupteur, comme
+  elle l'avait été sur l'info-bulle : à 10 % sur du blanc, l'écart ne fait pas trois niveaux sur
+  255, et la cohérence du thème vaut plus. **La question des sept ombres reste ouverte** — ce n'est
+  pas depuis un composant qu'on la tranche — mais elle a maintenant sa vraie valeur de départ.
+
+  ⚠️ **Et la géométrie, elle, diverge.** L'`ombre-md` du Figma est `0 4px 6px 0` puis
+  `0 2px 4px -2px`, là où `--zds-shadow-md` écrit `0 4px 6px -1px` sur sa première couche. Une
+  couche sur deux : le jeton ne se réemploie pas, d'où `--zds-shadow-toggle-knob`. L'entrée de la
+  phase 1b disait « la géométrie est la même de part et d'autre, la teinte changera » : **les deux
+  moitiés de cette phrase sont fausses.**
+
+- ⚠️ **0,5 px ET 1 px SONT LE MÊME PIXEL SUR UN ÉCRAN À 1×** (2026-09-11). Le Figma donne deux
+  épaisseurs de bordure à la piste éteinte selon le type — 0,5 sur le `default`, 1 sur le `slim` —
+  et Chromium arrondit une bordure sous-pixel à un pixel d'écran. Les deux rendent donc 1 px, et la
+  distinction n'apparaît qu'à partir de 2×.
+
+  `verify:interrupteur` mesure les DEUX : l'épaisseur que la feuille déclare, où la distinction
+  vit, et celle que le navigateur peint, comparée à ce que la densité de l'écran permet. Le premier
+  jet ne mesurait que la peinte, et reprochait au composant un arrondi du navigateur.
+
+  *Repère : une mesure prise dans un navigateur est prise sur UNE densité d'écran. Ce qui s'y voit
+  n'est pas toujours ce que la feuille demande.*
+
+- ⚠️ **L'HABITUDE D'AVANT-COMMIT COMPTE QUATRE CONTRÔLES DEPUIS LE 2026-09-10**, et le quatrième est
+  celui qui manquait : **aucun récit de fabrication dans une page de composant**. Micka l'a demandé
+  deux fois ; à la seconde, il est devenu un script.
+
+  `verify:foundations` relit donc les pages dont le `<Meta>` commence par « Base components/ » et
+  refuse huit tournures — « relevé », « mesuré », « un premier jet », « arbitré », « le Figma
+  dessine… », « à remonter dans le Figma », un numéro de nœud, « symbole ». Les pages Foundations sont
+  écartées : elles MESURENT par conception, le mot y est le sujet. Le partage se fait sur le TITRE,
+  pas sur un nom de fichier — c'est le titre qui décide du rangement.
+
+  ⚠️ **UNE EXCEPTION ÉNUMÉRÉE, et elle est instructive.** La page « Badges » écrit « le choix entre
+  eux n'est pas arbitré » : le mot est le même, l'usage est l'inverse — cette phrase DIT au
+  développeur que le choix lui revient. Le contrôle échoue aussi si l'exception cesse d'être
+  employée, comme `GRIS_ADMIS`.
+
+  Le contrôle a trouvé quatre passages sur trois pages écrites plus tôt : les notes de clôture de
+  « Badges » et « Avatars » qui décrivaient notre outillage de vérification, une phrase de « Boutons »
+  sur le même sujet, et une note de l'avatar **périmée en plus d'être narrative** — elle annonçait
+  encore une info-bulle provisoire alors que `Tooltip` était arrivé et que le bouton d'ajout
+  l'employait.
+
+  *Repère : une règle qu'on s'écrit ne tient pas. Le réflexe d'écrire ce qu'on vient de comprendre là
+  où on vient de le comprendre est plus fort qu'une consigne — il faut un contrôle.*
+
+- ⚠️ **`git checkout -- <fichier>` A EFFACÉ DU TRAVAIL NON COMMITÉ, POUR LA DEUXIÈME FOIS**
+  (2026-09-10). Employé pour défaire une mutation de test, il a ramené trois pages à HEAD — et
+  emporté avec la mutation **trois corrections de documentation venant d'être écrites**.
+
+  La première fois, c'étaient quatre correctifs de `verifier-jetons.mjs`, et la leçon était déjà dans
+  ce README. Elle n'a pas tenu, parce qu'au moment du nettoyage on pense « annuler la mutation », pas
+  « ce fichier contient aussi autre chose ». La commande est la même ; git ne connaît pas l'intention.
+
+  Et l'effacement est **silencieux** : la commande réussit, le fichier existe, les tests passent —
+  ils portaient sur autre chose. Ce qui l'a révélé, c'est un `grep -c` sur les phrases censées avoir
+  disparu.
+
+  **La règle : restaurer une mutation depuis une COPIE prise juste avant (`cp`), jamais depuis git**,
+  et vérifier la restauration par son CONTENU, pas par l'absence d'erreur.
+
+- ⚠️ **UN ÉTAT QU'AUCUNE PLANCHE NE MONTRE EST UN ÉTAT QUE PERSONNE NE RELIT** (2026-09-10, question
+  de Micka : « pourquoi il n'y a pas le focus ring pour le state focus ? »). L'anneau de la case à
+  cocher était juste, le vérificateur le mesurait, et **aucune planche ne l'affichait** : le tableau
+  des états en annonçait quatre pour trois visibles.
+
+  Deux raisons se cumulaient, et les deux sont normales : `:focus-visible` ne se déclenche qu'à la
+  navigation clavier — un clic ne montre rien, mesuré à `box-shadow: none` — et un seul élément du
+  document tient le focus à la fois, donc une planche ne peut pas le montrer sur trois spécimens.
+
+  La page Boutons avait déjà résolu ça avec `data-zds-demo="focus"`, un crochet qui **partage une
+  seule déclaration** avec `:focus-visible` pour que la démonstration ne puisse pas dériver. **Il n'a
+  simplement pas été repris.** Il l'est, sur les deux pages, et `verify:checkboxes` referme la porte
+  comme `verify:buttons` : un vrai focus clavier contre un forcé, comparés octet pour octet, avec un
+  refus de conclure si l'un des deux ressort vide — deux absences se comparent égales.
+
+  *Repère : quand un composant a un état que le Figma dessine, vérifier que la PAGE peut le montrer,
+  pas seulement que le CSS le déclare. Les deux questions sont différentes, et la seconde ne répond
+  pas à la première.*
+
+  ⚠️ **Et la sonde marque son témoin par un ATTRIBUT, pas par son identifiant.** Le `useId` de React
+  fabrique des identifiants à deux-points (« :r0: ») : valides en HTML, corrects pour un `for`, et
+  invalides dans un sélecteur CSS. Une sonde bâtie dessus échoue sur son propre sélecteur, pas sur un
+  défaut du composant.
+
+- ⚠️ **UNE PAGE DE COMPOSANT EST UNE CONSIGNE, PAS UN CARNET DE BORD** (2026-09-10, demande de
+  Micka). Les pages « Cases à cocher » et « Info-bulles » avaient dérivé vers le récit de leur
+  FABRICATION : ce que le Figma dessine, ce qui a été mesuré, ce qu'un premier jet rendait, qui a
+  arbitré quoi, quel nœud est cité. Rien de tout ça n'aide un développeur à choisir une taille ou à
+  écrire un libellé.
+
+  Une page sous « Base components » répond à trois questions et pas une de plus : **quand l'employer**,
+  **quelle variante**, **ce que l'API prend**. Le reste — les relevés, les écarts à la maquette, les
+  défauts trouvés et comment — vit dans ce README et dans le CLAUDE.md, où il était déjà. Les pages
+  Foundations sont l'exception et continuent de mesurer : mesurer EST leur sujet.
+
+  Les tournures à chercher avant de livrer une page : « relevé », « mesuré », « un premier jet »,
+  « arbitré », « le Figma dessine », « à remonter dans le Figma », un numéro de nœud, « symbole ».
+
+  *Repère : j'avais déjà cette règle en note et je l'ai quand même enfreinte deux fois. Le réflexe
+  d'écrire ce qu'on vient de comprendre là où on vient de le comprendre est fort — la relecture de la
+  page doit se faire en se demandant « qu'est-ce qu'un dev fait de cette phrase ? ».*
+
+- ⚠️ **SEPT VALEURS CHANGENT AVEC LA TAILLE DE LA CASE, ET TROIS AVAIENT ÉTÉ UNIFORMISÉES**
+  (2026-09-10). La boîte, le rayon, l'écart au texte, l'écart entre les deux textes, le palier
+  typographique, **la part de la marque** et **son épaisseur de trait**.
+
+      taille   boîte   marque   part    trait peint   point radio
+      sm       16      12       75 %    1,6666        37,5 %
+      md       20      14       70 %    2             40 %
+
+  Les trois dernières colonnes avaient une seule valeur, et **ça se voyait** : la coche sortait à 1 px
+  au lieu de 1,6666, donc pâle. **C'est l'œil de Micka qui l'a signalé, pas les contrôles** — qui
+  mesuraient la part de la marque à une seule valeur et ne regardaient pas le trait du tout.
+
+  ⚠️ **Et le trait ne suit pas l'échelle du dessin.** Les coordonnées du tracé la suivent
+  exactement — celles du Figma sont celles de notre catalogue multipliées par 12/24 puis 14/24, au
+  chiffre près. Le TRAIT, lui, reste épais : une réduction proportionnelle donnerait 1 px en `sm`.
+  C'est un choix de dessin — une coche fine dans une petite boîte disparaît. `stroke-width`
+  s'exprimant dans les unités du `viewBox` (24 pour nos icônes), peindre une épaisseur E sur une
+  marque de M pixels demande `E × 24 / M`. `verify:checkboxes` mesure l'épaisseur PEINTE, jamais
+  l'attribut.
+
+  *Repère : quand une taille change, lister ce qui change AVEC elle avant de coder. Une proportion
+  qui vaut pour une taille est une hypothèse, pas un relevé.*
+
+- ⚠️ **« CASES À COCHER » ET « BOUTONS RADIO » SONT DEUX PAGES, ET UNE SEULE FEUILLE DE STYLE**
+  (2026-09-10, demande produit, alignée sur la façon dont la bibliothèque de référence les range).
+  Les deux composants restent UN atome : `Checkbox.css` habille les deux, et `verify:checkboxes`
+  visite les DEUX pages en une passe.
+
+  Ne lire que la première laisserait le radio non vérifié, et un correctif fait pour l'un peut casser
+  l'autre sans qu'aucune page ne le dise. Le radio doit apparaître dans ses DEUX tailles : son point
+  fait 37,5 % en `sm` et 40 % en `md`, donc une page qui n'en montrerait qu'une laisserait la
+  seconde sans mesure.
+
+- ⚠️ **LA BORDURE DE LA CASE DÉCOCHÉE A ÉTÉ FONCÉE, ET C'EST UN ÉCART ARBITRÉ AU FIGMA**
+  (2026-09-10, décision produit). Le cadre la peint `border-primary` (navy-40), qui tient **1,44**
+  sur du blanc pour un seuil de 3:1 — **le plus bas mesuré sur ce design system**.
+
+  Et c'est plus grave que sur le bouton, où le même compromis a été accepté à 2,17 : un bouton garde
+  son libellé à 11,82, donc il reste identifiable, tandis qu'ici **la boîte EST le contrôle**. Une
+  case décochée à 1,44 est presque invisible. `navy-70` tient 3,67 : le palier le plus CLAIR de nos
+  neutres qui passe le seuil, donc le plus proche de l'intention du dessin. Exactement l'arbitrage
+  rendu pour le point de statut « hors ligne » de l'avatar, qui partait lui aussi de navy-40.
+
+  ⚠️ **Et aucun rôle de bordure ne porte navy-70.** Les rôles de bordure vont de navy-40 à navy-20,
+  plus les teintes de marque et d'erreur. navy-70 est porté par `text-secondary`, un rôle de TEXTE :
+  s'en servir pour peindre une BORDURE serait la confusion que la seconde vérification de
+  `verify:tokens` existe pour empêcher. D'où un jeton de composant. À remonter dans le Figma.
+
+- ⚠️ **LE FOND COCHÉ RESTE SUR brand-500, LÀ OÙ LE BOUTON EST DESCENDU À brand-600** (2026-09-10).
+  Ce n'est pas une incohérence : le bouton a bougé parce que du TEXTE blanc sur brand-500 tient 3,60
+  pour un seuil AA de 4,50. Ici la marque blanche n'est pas du texte, c'est un objet graphique, et la
+  WCAG 1.4.11 en demande 3:1 — les 3,60 passent. Descendre d'un cran « par cohérence » foncerait un
+  contrôle qui n'en a pas besoin.
+
+- ⚠️ **L'ÉTAT « HOVER » DU FIGMA NE DESSINE RIEN, ET LE NÔTRE EST UN AJOUT** (2026-09-10, décision
+  produit). Les quarante symboles portent bien une variante `Hover`, et elle est **identique au
+  PIXEL** à l'état `Default` — établi en échantillonnant la capture du cadre aux coordonnées que
+  `get_metadata` donne, sur les décochés, les cochés, les indéterminés et les radios.
+
+  La variante existe, donc l'intention y était ; elle dessine juste la même chose. Un contrôle sans
+  retour au survol paraît inerte, donc on en dessine un : décoché il prend un fond navy-20, coché il
+  descend d'un cran. Ce cran ne demande aucun jeton — `bg-brand-solid` EST brand-600, c'est un rôle,
+  et de la bonne catégorie. À remonter dans le Figma.
+
+  *Repère : une variante qui existe et ne dessine rien n'est pas un choix, c'est un oubli de
+  maquette — et elle ne se voit qu'en comparant deux symboles au pixel.*
+
+- ⚠️ **LE DÉSACTIVÉ EST DEUX CHANGEMENTS À LA FOIS, ET CE SONT LES PIXELS QUI L'ONT TRANCHÉ**
+  (2026-09-10). On pouvait croire à une simple opacité posée sur l'état par défaut : un blanc à 50 %
+  sur du blanc reste blanc, et la bordure aurait donné #e9ebef, alors que la case désactivée mesure
+  **#f8f9fa** — soit exactement navy-20 à 50 %. Le symbole confirme : fond navy-20, bordure
+  conservée, `opacity: 0.5`.
+
+  L'opacité est le même mécanisme que le bouton désactivé, et c'est elle qui explique la marque :
+  elle reste blanche parce que l'opacité s'applique au GROUPE, pas à chaque couche. **Elle est posée
+  sur la LIGNE, pas sur la case** — sur la case seule, le libellé resterait à pleine intensité à côté
+  d'un contrôle éteint.
+
+- ⚠️ **L'ANNEAU DE FOCUS EST UN RELEVÉ, POUR UNE FOIS, PAS UN AJOUT** (2026-09-10). Le Figma l'écrit
+  `0 0 0 2px bg-primary, 0 0 0 4px Bleu/100` — soit exactement la recette que le bouton avait posée
+  et que la croix de fermeture, la croix du badge et l'icône d'aide de l'info-bulle réemploient.
+  Quatre pièces l'avaient ajoutée de leur côté, faute de la trouver dans les cadres ; celle-ci
+  confirme qu'elle était juste.
+
+- ⚠️ **L'ÉLÉMENT EST UN VRAI `<input>`, ET C'EST CE QUI REND `:indeterminate` POSSIBLE** (2026-09-10).
+  Il porte `appearance: none` et se laisse habiller, mais il garde ce qu'un `div` n'a pas : le
+  clavier, la participation au formulaire, le groupement des radios par `name`, et les
+  pseudo-classes natives `:checked`, `:disabled`, `:focus-visible` et `:indeterminate`.
+
+  `verify:checkboxes` vérifie explicitement `appearance: none` : sans lui, le navigateur peint SA
+  case par-dessus la nôtre. Le résultat n'est pas vide — c'est une case native, à la bonne place, qui
+  ignore tous nos jetons.
+
+  ⚠️ **`indeterminate` est une propriété du NŒUD, pas un attribut, et elle se réécrit à chaque
+  rendu.** Aucun attribut HTML ne la déclare, donc React ne la synchronise jamais : sans l'écriture
+  répétée, une case rendue indéterminée le RESTERAIT après être repassée à `false`, et l'écart entre
+  l'état demandé et le DOM n'apparaît ni dans le balisage, ni dans un diff, ni sur une capture.
+
+  ⚠️ **Et elle est indépendante de `checked`, contre le Figma.** Le cadre ne la dessine qu'avec
+  `Checked=True`, mais obliger à cocher une case pour la rendre indéterminée serait l'inverse de son
+  sens. HTML gagne.
+
+- ⚠️ **LE LIBELLÉ EST RELIÉ PAR `htmlFor`, IL N'ENVELOPPE PAS** (2026-09-10). Un `<label>` qui
+  envelopperait le contrôle ET le texte d'aide ferait de l'aide une partie du NOM accessible : un
+  lecteur d'écran annoncerait les deux d'un bloc, à chaque rencontre du contrôle. Le libellé est le
+  nom, l'aide est une DESCRIPTION via `aria-describedby`.
+
+  Conséquence assumée : cliquer le libellé bascule la case, cliquer l'aide ne fait rien. **Et la
+  mutation mord** — envelopper dans un `<label>` fait échouer le test de nom/description de la case
+  ET celui du radio. C'est précisément l'implémentation « évidente », celle qui rend toute la ligne
+  cliquable, qui casse la sémantique.
+
+- ⚠️ **LE TEXTE D'AIDE RESTE SOUS L'AA, ET CE N'EST PAS UN PROBLÈME DE CE COMPOSANT** (2026-09-10).
+  Il tient 3,67 pour un seuil de 4,50 — mais le Figma le peint `text-secondary`, et ce RÔLE est
+  navy-70 : il est sous le seuil **partout où il porte du texte**. Le foncer ici seulement rendrait
+  cette aide différente de toutes les autres du design system.
+
+  Épinglé dans `verify:checkboxes` **dans l'autre sens** : le jour où le rôle sera foncé, ce contrôle
+  rougira, et ce sera le rappel qu'il faut retirer l'exception. **C'est une décision de fondation, et
+  elle est ouverte** — voir « En attente ».
+
+- ⚠️ **LE PLACEMENT DE L'INFO-BULLE EST CHOISI PAR LE DÉVELOPPEUR, ET LE PAQUET N'A TOUJOURS AUCUNE
+  DÉPENDANCE D'EXÉCUTION** (2026-09-10, arbitrage du lead dev front). Les six placements de la
+  maquette sont en CSS, et l'appelant en choisit un.
+
+  **La conséquence est à connaître avant de s'en servir : rien ne retourne la bulle si elle ne tient
+  pas.** Une info-bulle placée près du bord de l'écran en sortira. C'est le prix de zéro dépendance,
+  et la page de documentation énonce les trois cas où il faut changer de placement.
+
+  ⚠️ **CETTE DÉCISION EN A ANNULÉ UNE PRISE LE MÊME JOUR, ET LE DÉTOUR A SERVI.** Une première
+  version passait par `react-aria-components`, déjà en production sur `liste-evaluations` et
+  `export-rapport-entretien` ; l'équipe produit l'avait validée en `peerDependency`, en connaissance
+  du coût. Le lead dev front a tranché l'autre branche — celle que la recommandation d'origine
+  proposait — et le paquet est revenu à **zéro dépendance d'exécution**.
+
+  Ce qui SURVIT du détour, ce sont ses MESURES : le recouvrement de la flèche, son retrait de 12 px
+  sur les placements décalés et l'écart de 4 px au déclencheur ont tous été relevés dans un vrai
+  navigateur pendant ce passage, et sont reproduits à l'identique. Trois problèmes sont partis avec
+  la bibliothèque :
+
+  · son `transform` en style EN LIGNE sur l'enveloppe de la flèche écrasait notre rotation sans
+    bruit ;
+  · les bulles forcées ouvertes étaient mal placées dans une page MDX longue — un relevé donnait
+    4 px d'écart, le suivant 118 px sur le MÊME code — ce qui avait obligé à rendre deux planches
+    « en statique » ;
+  · une bulle « froide » était intestable sous jsdom, donc le fichier de test devait réchauffer la
+    bibliothèque avant CHAQUE cas, ce qui masquait justement la question.
+
+  Et une chose est devenue MEILLEURE que la bibliothèque : elle ancrait la flèche au CENTRE du
+  déclencheur, donc les 12 px du Figma ne tombaient juste que sur une icône de 16 px et dérivaient à
+  70,64 px sur un bouton `sm`. En CSS, les placements décalés s'ancrent sur la FLÈCHE : le retrait
+  vaut 12 px quelle que soit la largeur du déclencheur, et `verify:info-bulles` le mesure sur trois
+  largeurs différentes.
+
+  *Repère : une décision produit peut être renversée par une décision technique le jour même, et
+  c'est normal. Ce qu'il faut sauver du travail annulé, ce sont ses MESURES — pas son architecture.*
+
+- ⚠️ **LE COMPOSANT N'AJOUTE QU'UN SEUL NŒUD : UNE ANCRE** (2026-09-10). Un `span` qui sert de repère
+  de position à la bulle et qui ne prend pas de `tabIndex`. Envelopper le déclencheur dans un bouton
+  est ce que fait l'implémentation en production, et ça y a créé **six arrêts de tabulation morts** —
+  six boutons focusables sans action. Un test vérifie qu'un seul bouton est rendu, et qu'une seconde
+  tabulation SORT de l'ensemble.
+
+  ⚠️ **UN DÉCLENCHEUR NON FOCUSABLE EN DEVIENT UN, ET C'EST VOULU** — une aide qu'on ne peut pas
+  atteindre au clavier n'aide qu'une partie des gens. Un `span` reçoit un `tabIndex` ; un élément
+  déjà focusable (bouton, lien, champ) n'est pas touché, et un `tabIndex` donné par l'appelant est
+  respecté. Trois tests couvrent les trois cas, parce que la règle est invisible dans le balisage.
+
+  ⚠️ **LES GESTIONNAIRES SONT COMPOSÉS, PAS REMPLACÉS.** `cloneElement` écrase les props qu'il
+  reçoit : poser `onMouseEnter` sur un déclencheur qui en avait déjà un le ferait disparaître en
+  silence — la bulle s'ouvrirait, et l'action attendue par l'appelant ne se ferait plus, sans aucune
+  erreur. Celui de l'appelant passe en premier.
+
+- ⚠️ **ÉCHAP FERME LA BULLE, ET C'EST UN AJOUT** (2026-09-10). Le Figma ne dessine que « ouverte » et
+  « fermée ». Sans Échap, une bulle ouverte au clavier recouvre ce qui l'entoure jusqu'au prochain
+  changement de focus — et une bulle à texte de soutien fait 320 px de large. L'écoute est posée sur
+  le DOCUMENT, pas sur le déclencheur : la touche doit fonctionner même si le focus a bougé.
+
+- ⚠️ **LE RECOUVREMENT DE LA FLÈCHE EST DEUX NOMBRES DIFFÉRENTS, et c'est de la géométrie**
+  (2026-09-10). À la verticale la flèche s'enfonce de 8,51471 − 6 = 2,5147 px. Tournée d'un quart de
+  tour, elle pivote autour de son CENTRE alors que sa boîte garde la largeur NON tournée (16) : son
+  centre est à 8 px du bord, plus une demi-hauteur de 4,2574 — elle dépasserait de 12,2574 et doit
+  s'enfoncer de 6,2574. Un seul nombre pour les quatre côtés mesurait 9,74 px sur les côtés contre
+  5,99 en haut, et paraissait cohérent.
+
+- ⚠️ **`box-sizing: border-box` PORTE LA LARGEUR DE 320 PX** (2026-09-10). Le Figma cale la bulle à
+  texte de soutien sur 320 px TOTAL. En `content-box` — le défaut de CSS, et ce dépôt n'a aucune
+  remise à zéro globale — les 12 px de padding s'ajoutent de chaque côté : mesurée, la bulle sortait
+  à **344 px**. Et 344 ressemble à 320. Le contrôle vérifie les DEUX, la largeur et le modèle de
+  boîte, parce que « corriger » la largeur à 296 ferait disparaître le symptôme sans la cause.
+
+- ⚠️ **L'OMBRE DE L'INFO-BULLE EST UN `filter`, ET C'EST LA FLÈCHE QUI L'IMPOSE** (2026-09-10,
+  demande produit). Un `box-shadow` ombre la BOÎTE : il dessinerait un rectangle autour de la bulle
+  ET de sa flèche, en laissant la flèche plate. `drop-shadow()` suit la silhouette PEINTE.
+
+  Le prix : aucun de nos jetons `--zds-shadow-*` n'est réutilisable, ils portent un étalement négatif
+  que `drop-shadow()` ne sait pas exprimer — d'où `--zds-shadow-tooltip-filter`. Sa teinte est aussi
+  une SUBSTITUTION délibérée : le Figma la pose en `rgba(16, 24, 40, …)`, une couleur d'une
+  collection TIERCE, là où toute notre rampe d'ombres est en noir. À 8 % d'opacité sur du blanc,
+  l'écart mesure 2,3 niveaux sur 255.
+
+- ⚠️ **LE HELP ICON EST L'UN DES CINQ DESSINS QUE LE CATALOGUE ÉCARTE** (2026-09-10). Deux
+  générations de `help-circle-01` cohabitent dans le Figma sous le même nom : le catalogue publie la
+  silhouette REMPLIE, et le cadre de l'info-bulle cite le nœud `3167:12028`, le tracé au CONTOUR
+  rangé dans `ZEST_ICONS_EN_CONFLIT`. Un `<HelpCircle01 />` rendrait donc l'autre dessin.
+
+  Le composite va le chercher PAR SON NUMÉRO DE NŒUD — aucun troisième exemplaire du tracé — avec un
+  repli si l'arbitrage le fait un jour monter dans le catalogue publié. `HelpCircle01` n'est employé
+  nulle part aujourd'hui, donc cet arbitrage ne coûte rien en code.
+
+  ⚠️ **ET L'EN-TÊTE DU CATALOGUE AFFIRME QUELQUE CHOSE DE FAUX** : il dit que « la page Icônes les
+  montre à côté de ceux qui gagnent, pour qu'on tranche en regardant ». Elle ne les montre pas.
+  `ZEST_ICONS_EN_CONFLIT` est exporté de `src/index.ts` et rendu par aucune page. **À faire, ou à
+  cesser de promettre.**
+
+- ⚠️ **`verify:info-bulles` ÉTAIT AVEUGLE À UNE INVERSION DE PLACEMENT, ET C'EST UNE MUTATION QUI L'A
+  DIT** (2026-09-10). Échanger `left: 50%` contre `right: 50%` sur `top-right` envoie la bulle du
+  côté opposé, et le contrôle restait vert : le retrait de 12 px est mesuré depuis le bord de la
+  BULLE, donc il vaut 12 où que la bulle se trouve.
+
+  L'invariant qui manquait est le SÉMANTIQUE — **la flèche doit pointer sur le centre du
+  déclencheur** — et il est désormais mesuré sur chaque placement. Les deux sont gardés : le retrait
+  décrit la bulle, le centrage décrit sa RELATION au déclencheur.
+
+  ⚠️ **ET UNE AUTRE MUTATION A EU L'AIR DE NE PAS MORDRE ALORS QU'ELLE N'AVAIT PAS ÉTÉ CHARGÉE.**
+  Deux mutations CSS ressortaient vertes à 10 s d'attente et rouges à 14 : le rechargement à chaud de
+  Vite ne les avait pas appliquées. *Avant de conclure qu'un contrôle est aveugle, lire la règle
+  SERVIE dans le DOM.* Sur ces deux mutations, une seule l'était réellement.
+
+- ⚠️ **UN JETON DÉCLARÉ ET JAMAIS CITÉ ÉCHAPPE À TOUS LES CONTRÔLES** (2026-09-10).
+  `--zds-color-tooltip-supporting-text` existait déjà, porté du thème de référence, et valait
+  `gray-300` — là où le Figma de Zest donne `navy-20`. Le redéclarer a créé un DOUBLON silencieux :
+  deux déclarations d'une même propriété, la première morte.
+
+  Personne n'avait vu la mauvaise valeur parce que rien ne la CITAIT : `verify:tokens` résout les
+  jetons qu'un composant emploie. Ses quatre voisins du même bloc étaient dans le même cas — **des
+  ports, pas des relevés**. Les trois `toggle-*` ont été relus le 2026-09-11 : **les trois étaient
+  faux**. Seul `slider-handle-*` reste invérifié, et il attend le curseur.
+
+- ⚠️ **LE PROVISOIRE `.zds-doc-bulle` PEIGNAIT LA MAUVAISE COULEUR DEPUIS LE JOUR OÙ IL A ÉTÉ ÉCRIT**
+  (2026-09-10). Son fond citait `bg-primary-solid`, qui aboutit sur `gray-950` (#0a0d12) ; la
+  maquette peint la bulle en `Bleu marine/100` (#21304e). Deux noirs différents, et le mauvais.
+  `docs.css` n'étant pas une feuille de composant, `verify:tokens` ne l'a jamais lu.
+
+  La leçon vaut plus que le correctif : **un dessin fait à côté d'un composant absent ne se contente
+  pas de vieillir, il peut être faux dès le premier jour, et rien ne le surveille.** Le même soupçon
+  porte sur les trois provisoires qui restent dans ce bloc.
+
+- ⚠️ **RETIRER LE `title` DU BOUTON D'AJOUT ÉTAIT INVISIBLE AUX 25 TESTS DE L'AVATAR** (2026-09-10).
+  Tous sont restés verts : aucun ne gardait le provisoire. Le remplacement n'apparaissait que dans le
+  diff — exactement la régression par remplacement que rien ne voit. Deux tests ont été ajoutés
+  après coup, et ils affirment les DEUX sens : la bulle native a disparu, et l'`aria-label` est
+  resté. Sans le second, retirer le libellé « puisque la bulle le dit » passerait sans bruit, et le
+  bouton s'annoncerait « bouton » — une info-bulle n'existe qu'au survol.
+
+- ⚠️ **UN DÉLIMITEUR DE COMMENTAIRE EN TROP DANS `theme.css` SUPPRIME LA DÉCLARATION QUI LE SUIT**
+  (2026-09-10). Un `*` suivi d'un `/` surnuméraire refermait le commentaire du bloc AVATAR en son
+  milieu : le paragraphe d'après devenait du CSS invalide, et la récupération d'erreur du navigateur
+  **saute jusqu'au prochain `;`**. Ce qui a disparu n'est donc pas le paragraphe, mais
+  `--zds-color-avatar-bg`, la déclaration d'après. Un `var()` sur un jeton inexistant ne peint rien,
+  sans erreur ni avertissement : les trois avatars en pastille — picto, initiales, masque — sont
+  sortis **transparents**.
+
+  `tsc`, les 69 tests, `verify:tokens` et `verify:avatars` étaient tous verts. C'est Micka qui l'a vu
+  à l'œil, et c'est le genre de défaut qui donne un résultat plausible : un rond blanc bordé
+  ressemble à un choix.
+
+  Trois choses à en garder :
+
+  · **chercher AU-DESSUS du jeton manquant, pas à son endroit.** Le fichier se lit parfaitement à la
+    ligne de la déclaration disparue ; le dégât est en amont d'elle ;
+  · **compter les ouvertures contre les fermetures ne suffit pas**, même si ça a suffi ici (60 contre
+    61). Le comptage est aveugle au cas « un commentaire, du texte, un second commentaire » : ça
+    s'équilibre et il reste pourtant du texte dehors. `verify:foundations` retire donc les
+    commentaires comme le fait un navigateur, puis exige que tout ce qui reste dans `:root` soit une
+    déclaration. Les deux cas sont éprouvés par mutation, avec un troisième — un commentaire jamais
+    refermé — où le contrôle **refuse de conclure** au lieu de passer ;
+  · **une sonde géométrique ne voit pas une couleur absente.** `verify:avatars` était vert parce que
+    rien n'avait bougé. Il mesure désormais le fond de la pastille ET exige que celui d'une photo
+    reste transparent : sans cette seconde moitié, le contrôle passerait sur une page où plus rien
+    n'est peint — deux fois du vide comparé à lui-même.
+
+  Effet de bord mesuré : `dist/index.css` est passé de 58,39 à 58,02 Ko en réparant, parce que le
+  texte orphelin était **embarqué tel quel dans le CSS publié**.
+
+- ⚠️ **TROIS VÉRIFICATIONS AVANT CHAQUE COMMIT, ET C'EST UNE HABITUDE, PAS UN RÉFLEXE AU CAS PAR
+  CAS** (2026-09-10, demande produit). Les jetons sémantiques (`verify:tokens`), l'application des
+  FOUNDATIONS et l'absence du nom du fournisseur tiers (`verify:foundations`, écrit ce jour-là).
+
+  **La raison est que les deux défauts qui ont motivé la règle étaient invisibles là où ils
+  étaient écrits.** Les 13 sauts de couche du premier badge rendaient juste, passaient `tsc`, les
+  44 tests et les deux contrôles de jetons existants — l'audit qui les a trouvés était manuel, et
+  personne ne l'aurait lancé sur un changement qui « ne touche pas aux couleurs ». Le nom du
+  fournisseur, lui, est revenu deux fois dans les notes pendant qu'on le retirait des pages. Un
+  contrôle qu'on ne lance que quand on le soupçonne ne trouve que ce qu'on soupçonne.
+
+  Ce que `verify:foundations` cherche et ce qu'il laisse passer :
+
+  · il ne signale que les valeurs brutes **qu'un jeton nomme déjà**, et **par famille de
+    propriété** — l'échelle d'espacement pour `padding` / `margin` / `gap`, celle des rayons pour
+    `border-radius`, celle du texte pour `font-size` et `line-height`. Comparer un padding à tous
+    les jetons confondus reprocherait un `padding: 10px` au nom d'un jeton de RAYON, ce qui ne veut
+    rien dire : deux jetons qui partagent une valeur ne partagent pas un sens — c'est déjà le
+    raisonnement de la CATÉGORIE dans `verify:tokens` ;
+  · une valeur **hors échelle** passe en silence, et c'est voulu : les 10 px de padding du badge,
+    ses 3 px de rayon de croix, les filets sous-pixel de l'avatar sont des relevés du Figma, il n'y
+    a rien à citer à leur place. Le contrôle attrape l'oubli, pas l'exception ;
+  · **une exception énumérée**, comme `GRIS_ADMIS` dans `verify:tokens` : le `padding: 2px` du
+    biseau des boutons pleins est une ÉPAISSEUR de trait, pas un espacement, et citer
+    `--zds-space-xxs` là serait exactement la confusion que le contrôle existe pour empêcher. Il
+    **échoue aussi si l'exception cesse d'être employée** — une dispense ne survit pas à son
+    bénéficiaire ;
+  · le motif du nom du fournisseur est **reconstitué à l'exécution**. Un contrôle qui écrirait la
+    chaîne qu'il interdit se trouverait lui-même et rougirait à chaque passage. Les binaires sont
+    écartés : les octets d'un WebP peuvent épeler n'importe quoi, et les 282 avatars produiraient
+    un faux positif par lot.
+
+  Les quatre mutations qui prouvent qu'il mord ont été jouées : un `margin: 8px` dans le badge,
+  un `border-radius` / `font-size` / `line-height` bruts, le biseau du bouton passé à 1 px, et le
+  nom du fournisseur remis dans une page. Chacune fait sortir 1.
+
+- ⚠️ **UNE ANOMALIE DU FIGMA EST REPRODUITE DANS LE BADGE, EN TAILLE `sm`** (2026-09-10). Un
+  `Badge color` ou un `Badge modern` de taille `sm` portant une icône gagne 2 px du côté OPPOSÉ à
+  l'icône — 8 au lieu de 6 — et tombe alors à la largeur exacte du `Pill color`, alors que ces
+  deux habillages ne se distinguent QUE par leur padding. Les autres tailles ne le font pas.
+  Vraisemblablement des variantes recopiées depuis le pill sans réajuster le padding.
+
+  Reproduite plutôt que corrigée : les maquettes font foi, et une correction silencieuse aurait
+  fait diverger le code et le Figma sans laisser de trace. Elle est **épinglée** dans
+  `verify:badges`, donc **la corriger dans le Figma fera échouer le contrôle** — c'est le rappel
+  qu'il faudra retirer les deux règles CSS et la section de la page avec elle.
+
+- **La géométrie du badge est une TABLE, et la table a été prouvée** (2026-09-10). Quatre règles —
+  hauteur = interligne + 2 × padding ; le côté du LIBELLÉ porte le padding de base du type ; le
+  côté d'une PIÈCE le perd de 2 px sur le pill et le garde sur les deux autres, sauf l'icône qui
+  le perd sur les deux ; la croix ne suit pas l'échelle (3, 4, 6). Un script a recalculé les
+  largeurs ET les hauteurs des **477 symboles** du cadre depuis ces règles : les 477 tombent
+  juste, au pixel. C'est ce modèle que `verify:badges` vérifie dans le navigateur.
+
+- ⚠️ **LE COMPOSANT AVATAR EXISTAIT, ET CE DÉPÔT AFFIRMAIT LE CONTRAIRE** (2026-09-10). Le
+  `CLAUDE.md`, le README et la page Foundations écrivaient tous les trois qu'il n'y avait pas de
+  composant `Avatar` dans le V2.0 et que c'était « délibéré ». Le relevé s'était arrêté sur le
+  cadre `3857:23794` — la banque de 282 photos — et n'avait pas cherché plus loin. Le composant
+  vit dans **cinq cadres**, il a six tailles, quatre contenus, une bordure, trois statuts, un
+  groupe et un avatar-libellé.
+
+  ⚠️ **Un cadre qui répond à une question ne prouve pas qu'aucun autre n'y répond mieux.** C'est la
+  leçon, et elle vaut pour les prochains relevés : la banque de photos était une réponse plausible
+  à « où sont les avatars », donc personne n'a cherché la suivante.
+
+- ⚠️ **LES INITIALES ENTRENT DANS LE SYSTÈME, ET UNE RÈGLE EN GRAS EST ABROGÉE** (2026-09-10). La
+  page Foundations écrivait « chez Zest, un avatar est une photo ou un picto — jamais des
+  initiales », avec une planche marquée en rouge et un paragraphe d'arguments. Le V2.0 les dessine
+  dans les six tailles ; l'équipe produit a tranché.
+
+  Ce qui remplace l'interdiction est un **ordre** : photo > initiales > picto. Le raisonnement
+  d'origine n'était pas faux — deux lettres désignent mal — il était trop absolu : elles désignent
+  mieux qu'un pictogramme quand on connaît le nom. Le composant dérive donc son contenu de ce
+  qu'on lui donne au lieu d'exiger trois interrupteurs.
+
+  ⚠️ **L'ANONYME PASSE DEVANT TOUT, y compris une photo présente**, et il interdit le point de
+  statut. Ce n'est pas une préférence : il sert les réponses anonymisées d'une campagne de
+  feedback, et si une photo pouvait le battre, une photo suffirait à lever l'anonymat de quelqu'un
+  qui l'a demandé.
+
+  L'échelle de tailles proposée par la page — 24, 32, 40, 48, 64, 96 — était **fausse**. Le Figma
+  donne 24, 32, 40, 48, **56**, 64.
+
+- **Le statut de l'avatar est ABSENT par défaut** (2026-09-10), sur décision produit : la
+  production ne gère pas encore cet affichage, c'est une anticipation. Le composant n'en dessine
+  aucun sans qu'on passe `status`, et la page ne le montre que dans sa propre section.
+  `verify:avatars` vérifie qu'il reste absent de la majorité des avatars de la page — sans quoi
+  elle laisserait croire à un défaut par défaut.
+
+  ⚠️ **LES TROIS POINTS TIENNENT LES 3:1, ET DEUX ONT ÉTÉ FONCÉS POUR ÇA.** Sur décision produit du
+  2026-09-10, le seuil de la WCAG 1.4.11 est exigé et non plus toléré : le disque d'un point de
+  statut porte une information, donc sa couleur doit se distinguer du fond.
+
+  | | avant | après | sur blanc |
+  |---|---|---|---|
+  | En ligne | `success-600` | inchangé | 3,59 |
+  | Hors ligne | `navy-40` — 1,44 | **`navy-70`** | 3,67 |
+  | Commentaire sensible | `error-200` — 1,42 | **`error-500`** | 3,76 |
+
+  ⚠️ **UNE OBJECTION QUE J'AVAIS FAITE ÉTAIT TROP LARGE.** J'avais écrit que foncer le gris ferait
+  lire « hors ligne » comme un état ACTIF, et Micka l'avait acceptée. C'est vrai d'un `navy-80` ou
+  d'un `navy-100` ; ce n'est pas vrai de `navy-70`, un gris moyen qui se lit toujours comme une
+  absence de couleur à côté du vert. L'objection valait pour l'ampleur du geste, pas pour le geste
+  — et elle a coûté un aller-retour.
+
+  ⚠️ **LE DISQUE SENSIBLE ET SON PICTO NE POUVAIENT PAS TENIR ENSEMBLE.** Le Figma peint un picto
+  `Rouge/200` sur un disque `Rouge/40` : le picto tient bien 3,40 sur son disque, mais le disque ne
+  tient que 1,42 sur du blanc. Et un disque assez foncé pour tenir 3:1 ne laisse plus passer aucun
+  rouge — au palier 500, un `error-600` tombe à 1,29. **Les deux exigences s'excluent sur la même
+  teinte.** Le disque monte donc au 500 et le picto devient BLANC, à 3,76 : c'est la forme
+  conventionnelle d'une alerte, et elle aligne ce point sur les deux autres. À répercuter dans le
+  Figma, qui vient justement de repeindre ce picto en rouge.
+
+- **Le gris du statut hors ligne est une substitution mesurée** (2026-09-10). Le Figma le peint
+  `utility-neutral-300` (#d4d4d4), d'une collection tierce. Le plus proche chez Zest était
+  `gray-300` (ΔE 1,99), écarté parce qu'il est dans la rampe grise que le contrôle interdit, et
+  `navy-40` (ΔE 4,03) a servi un temps — avant d'être abandonné faute de contraste. `navy-70` est
+  le palier le plus CLAIR des neutres de Zest qui tienne 3:1, donc le plus proche de l'intention.
+
+- ⚠️ **LE DÉPÔT ANNONÇAIT « 121 ICÔNES » EN NEUF ENDROITS ALORS QU'IL Y EN AVAIT 133**
+  (2026-09-10). La dérive est antérieure à l'ajout des deux icônes du statut : douze icônes avaient
+  été ajoutées sans que la prose suive. Les neuf mentions sont passées à **135**. Le nombre est
+  recopié à la main dans six fichiers — c'est exactement le piège que ce dépôt documente pour les
+  pages qui recopient une valeur au lieu de la lire.
+
+- ⚠️ **LES TROIS TEINTES CLAIRES DU BADGE DESCENDENT DE DEUX CRANS** (2026-09-10). Telles que le
+  Figma les peignait, turquoise, tilleul et jaune ne tenaient aucun de leurs deux seuils : libellé
+  3,77 / 4,05 / 4,35 pour 4,50, et **pièce** 2,55 / 2,34 / 2,69 pour 3,00. Le Figma les avait déjà
+  foncées d'un cran pour deux d'entre elles ; ça ne suffisait pas.
+
+  Un cran de plus sur la pièce ET sur le texte fait passer les six mesures :
+
+  | Couleur | Pièce | Libellé |
+  |---|---|---|
+  | turquoise | 600 → **700** (2,55 → 3,77) | 700 → **800** (3,77 → 5,69) |
+  | tilleul | 700 → **800** (2,34 → 4,05) | 800 → **900** (4,05 → 7,00) |
+  | jaune | 700 → **800** (2,69 → 4,35) | 800 → **900** (4,35 → 7,59) |
+
+  ⚠️ **LE RAPPORT PIÈCE/LIBELLÉ EST PRÉSERVÉ**, et c'est ce qui rend l'arbitrage propre : la
+  nouvelle valeur de pièce est l'ANCIENNE valeur de libellé. Les treize couleurs partagent donc la
+  même règle — la pièce est un cran plus claire que le libellé — et ces trois-là sont simplement
+  assises deux crans plus bas. Ce ne sont plus des exceptions, et `verify:badges` ne porte plus
+  aucun contraste épinglé : les seuils eux-mêmes les gardent.
+
+  ⚠️ **ON N'A TOUCHÉ QUE CE QUI BLOQUAIT.** Les dix autres couleurs tiennent leurs deux seuils
+  (libellé 4,69 à 12,58 ; pièce 3,31 à 6,84) et gardent leurs paliers. Les aligner « par
+  cohérence » aurait assombri dix couleurs justes pour rien. Le FOND ne bouge pas non plus : il
+  reste au palier 50, donc ces badges restent aussi pâles que les autres — et l'objection écrite
+  la veille, « un tilleul au 900 n'est plus du tilleul », portait sur un APLAT saturé sous du texte
+  blanc, où c'est le fond qui porte l'identité de la teinte. La bordure ne bouge pas : elle est
+  décorative, un badge n'étant pas une commande.
+
+- ⚠️ **LA RÈGLE DES CALQUES ÉTAIT ÉCRITE MAIS VÉRIFIÉE PAR RIEN** (2026-09-10). Un composant ne
+  cite que le calque des rôles (3) ou celui des jetons de composant (4) — jamais une rampe brute
+  (1), jamais une palette utilitaire (2). Un audit des cinq feuilles de composant a trouvé
+  **13 citations en faute**, toutes dans le premier badge : le fond du survol de sa croix, écrit
+  en `var(--zds-color-brand-100)`, `var(--zds-color-navy-30)` et huit `var(--zds-color-utility-*-100)`.
+  Des valeurs justes, un rendu juste, et un défaut que rien ne voyait — ni le typage, ni les 44
+  tests, ni les deux vérifications de `verify:tokens`, qui ne regardaient que la rampe grise et les
+  doublons de rôle.
+
+  La réparation est la partie instructive : **quatre des treize n'ont demandé aucun jeton neuf**,
+  `bg-brand-secondary` et ses trois voisins portant déjà exactement le palier 100 de leur rampe. Le
+  navy était un piège — le seul rôle qui porte `navy-30` est `border-secondary`, un rôle de
+  BORDURE, et l'employer pour peindre un aplat aurait été la confusion même que la seconde
+  vérification existe pour empêcher. Les neuf autres ont pris un jeton de composant.
+
+  `verify:tokens` porte désormais un **troisième contrôle**, avec son témoin : il échoue si un
+  composant cite un calque 1 ou 2.
+
+- **La liste de navigation à droite des pages de doc** (2026-09-10), par `parameters.docs.toc`.
+  ⚠️ Son `headingSelector` n'est pas un détail : Storybook ne liste que les `h3` par défaut, et sur
+  une page dont les chapitres sont en `h1` et les sections en `h2`, la liste s'affichait avec UNE
+  entrée — elle avait l'air de marcher. ⚠️ Elle est **globale**, et pas par choix : le conteneur de
+  doc de Storybook 8.6 ne lit `toc` que dans les paramètres du PROJET, un `<Meta parameters>` par
+  page n'activant rien — vérifié dans le navigateur sur trois pages. Demandée pour les badges et
+  les boutons, elle est donc posée sur les quinze pages.
+
+- ⚠️ **LES QUATRE PIÈCES DU BADGE NE FONT QU'UNE COULEUR — le palier 600 — et seul le LIBELLÉ est
+  au 700** (2026-09-10). Relevé sur quatre symboles de trois habillages : chacun ne cite que deux
+  valeurs de couleur, `Zest/200` pour sa pièce et `Zest/300` pour son libellé.
+
+  Un premier jet peignait les pièces en `currentColor`, donc à la couleur du libellé : un cran trop
+  sombre partout, et sur un `modern` carrément navy — **treize badges identiques là où la maquette
+  en dessine treize colorés**. Le typage, les 44 tests et la sonde de géométrie passaient tous : le
+  badge se rendait parfaitement. C'est la planche des treize couleurs, dessinée en restructurant la
+  page, qui l'a montré. `verify:badges` compare désormais chaque icône et chaque croix à la teinte
+  MESURÉE du point de sa couleur — 126 comparaisons — pour que ça ne revienne pas.
+
+  C'est aussi ce qui a corrigé une lecture fausse des 108 symboles absents du cadre. Ils sont tous
+  des `Badge modern` dans les douze couleurs autres que Gray, mais **seuls 36 sont légitimes** —
+  ceux sans aucune pièce, qui n'ont rien à colorer. Les 72 autres, `X close` et `Icon trailing`,
+  sont un TROU de la maquette : leur unique spécimen Gray peint bien sa pièce en `Couleurs/Gris/200`.
+  **À dessiner dans le Figma.**
+
+- **Le badge nomme ses couleurs avec les mots du THÈME, pas ceux du Figma** (2026-09-10).
+  `horizon`, `lime`, `yellow` et non `Bleu horizon`, `Vert tilleul`, `Jaune` : le thème les
+  déclare ainsi depuis le portage, et traduire à chaque aller-retour entre une classe CSS et un
+  jeton coûterait plus que ça ne rapporte. La page « Badges » affiche les deux vocabulaires côte à
+  côte, et c'est le seul endroit où la correspondance a besoin d'être visible.
+
+- **Les quatre emplacements du badge sont des propriétés INDÉPENDANTES**, là où le Figma les range
+  sur un axe unique et donc exclusif (2026-09-10). C'est l'inverse du choix fait sur `Button`,
+  dont les onze hiérarchies sont une liste plate, et la différence est réelle : un jeu de
+  variantes Figma ne sait pas exprimer « deux emplacements optionnels » sans multiplier les
+  variantes par quatre. L'exclusivité est une contrainte de l'OUTIL, pas une règle du produit — et
+  un badge qui porte à la fois un point d'état et une croix de retrait est une pièce courante.
+  Rien n'est inventé au passage : chaque emplacement porte sa géométrie relevée.
+
+  ⚠️ Deux cas que le Figma ne dessine pas ont dû être tranchés ici : quand un point ET une icône
+  de tête sont présents, le padding suit le POINT, qui est la pièce la plus au bord ; quand une
+  icône de fin ET une croix sont présentes, il suit la CROIX. Ce sont des choix, et deux tests les
+  fixent.
+
+- **L'anneau de focus de la croix du badge est un AJOUT** (2026-09-10). Le cadre `_Badge close X`
+  ne dessine que `Default` et `Hover`. Une commande qu'on ne voit pas quand on l'atteint au
+  clavier ne s'emploie pas sans souris : l'anneau reprend la recette du `CloseButton`, à l'octet.
+  À répercuter dans le Figma.
+
+- ⚠️ **Un symbole du `_Badge close X` est MAL ÉTIQUETÉ** (2026-09-10). La variante `Color=Orange`
+  peint `Couleurs/Rose/200` (#dd2590) : c'est du ROSE. Aucun symbole n'y porte l'étiquette `Rose`,
+  et `Color=Warning` peint bien l'orange. C'est l'étiquette qui est fausse, pas le dessin — le
+  même piège que les cinq codes de drapeau. Le code nomme cette couleur `rose`. **Le Figma reste à
+  corriger.**
+
+- **Cinq fonds de badge citent un RÔLE et non un jeton de composant** (2026-09-10), et c'est
+  `verify:tokens` qui l'a établi plutôt qu'une relecture : `bg-brand-primary`, `bg-error-primary`,
+  `bg-warning-primary`, `bg-success-primary` et `bg-primary` portent exactement les valeurs que le
+  premier jet allait redéclarer. Les rôles `bg-*-primary` sont les paliers 50 des rampes, donc
+  exactement le fond doux que le badge peint. Le message du contrôle laisse entendre que les fonds
+  sont dispensés : la dispense ne vaut que là où AUCUN rôle ne nomme la valeur, ce qui est le cas
+  des huit couleurs utilitaires.
+
+- ⚠️ **Les bordures des boutons restent celles du Figma, sous les 3:1, et c'est un compromis
+  ASSUMÉ** (2026-09-09). `border-primary` (navy-40, `#D3D7DE`) pour les neutres,
+  `border-error-subtle` (error-300) pour le destructif. Mesuré en navigateur, le trait PEINT — donc
+  composé sous le contour de 18 % du relief — tient **2,17:1** et **2,87:1** sur du blanc, contre
+  les 3:1 que la WCAG 1.4.11 demande à ce qui délimite une commande. Et l'aplat ne rattrape rien :
+  navy-20 sur blanc fait 1,11:1.
+
+  Un premier jet avait remonté ces bordures à `navy-70` (3,67:1) et `border-error` (3,76:1), qui
+  tiennent le seuil ; l'équipe produit a préféré la **fidélité au Figma**, le dessin s'alourdissant
+  visiblement. Le libellé tient 11,82:1 : le bouton reste identifiable, c'est sa LIMITE qui ne
+  l'est pas.
+
+  ⚠️ La page « Boutons » continue de mesurer et d'afficher ces trois valeurs **en rouge**. Un
+  compromis assumé se documente, il ne se cache pas — et si on revient dessus un jour, les deux
+  paliers qui tiennent le seuil sont écrits ci-dessus.
+- **Le relief skéuomorphique est COMPLET sur toutes les pièces** (2026-09-09), contour de 1 px
+  compris, et il est peint PAR-DESSUS la bordure — l'ordre du Figma, qui pose son style d'effet sur
+  un calque au-dessus du cadre. Conséquence à connaître : sur une pièce encadrée, la bordure peinte
+  n'est pas la bordure déclarée. navy-40 sous 18 % de noir donne `#ADB0B6`. C'est pour ça que la
+  planche de contraste lit le `box-shadow` CALCULÉ et compose ses couches, au lieu de lire le
+  jeton.
+- **Le biseau des aplats est un DÉGRADÉ, pas un liseré plat** (2026-09-09). Le liseré clair d'un
+  bouton plein s'allume en haut et s'éteint en bas : il simule une lumière venant du dessus. Il est
+  posé en pseudo-élément masqué — un `border` CSS ne porte pas de dégradé, et une vraie bordure de
+  2 px ferait passer un `md` de 40 à 44 px.
+
+  ⚠️ **Les deux bornes du dégradé sont À CONFIRMER.** Le MCP Figma rapporte ce contour comme PLAT
+  (`rgba(255,255,255,0.12)`) sur deux lectures, `forceCode` compris, et `get_metadata` ne montre
+  aucun calque de dégradé : l'outil l'aplatit, ou il l'est. La borne haute vient de cette valeur
+  relevée ; l'extinction complète en bas est la recette standard, pas un relevé. Les jetons
+  `--zds-color-button-bevel-from` et `-to` isolent les deux valeurs à corriger.
+- **Les composants ne citent que les couleurs de Zest, et c'est contrôlé** (2026-09-09).
+  `yarn verify:tokens` résout chaque jeton cité par une feuille de composant jusqu'à sa valeur et
+  échoue si l'un aboutit dans la rampe `gray-*` que Zest laisse de côté. Il porte un témoin —
+  `bg-secondary`, qui doit être détecté — et refuse de conclure si le témoin ne mord pas. Vert sur
+  les quatre composants, 90 citations résolues.
+- ⚠️ **Le Primary descend d'un palier par rapport au Figma** (2026-09-09). Le Figma peint le
+  Primary AU REPOS en `Bleu/100` — notre `brand-500`, `#4481FF`. Mesuré, du blanc dessus tient
+  **3,60:1**, sous le seuil AA de 4,5, et son propre survol tient 4,54 : le bouton était donc plus
+  lisible au survol qu'au repos. Chaque état descend d'un palier — repos sur `bg-brand-solid`
+  (600, 4,54:1), survol sur `bg-brand-solid-hover` (700, 6,08:1). Ce n'est pas seulement une
+  correction d'accessibilité : **le destructif était DÉJÀ sur le palier 600 au repos**, donc le
+  Figma se contredisait entre ses deux familles et le décalage les aligne. ⚠️ **À répercuter dans
+  le Figma.**
+- **« Destructif » est une liste plate de onze valeurs, pas un drapeau** (2026-09-09). La famille
+  destructive du Figma ne reprend que quatre des sept hiérarchies : il n'existe ni
+  `secondary-white` destructif, ni `tertiary-gray` destructif. Un booléen `destructive` rendrait
+  exprimables quatre combinaisons que personne n'a dessinées, et le composant devrait inventer
+  quoi peindre. Une union plate laisse le typage refuser.
+- **Le chargement n'est pas un `disabled`** (2026-09-09). Un `disabled` sort le bouton de l'ordre
+  de tabulation : le focus est perdu à l'instant où l'on presse « Envoyer » et retombe sur le
+  `body`, en haut du document. Le composant pose `aria-disabled`, qui annonce l'indisponibilité
+  sans retirer la pièce, et bloque l'activation en avalant le clic — Entrée et Espace passent par
+  le même garde, puisque les deux déclenchent un clic.
+- **La bordure du `UtilityButton` cite le jeton de Zest, pas celui du Figma** (2026-09-09). Le
+  Figma la peint `#D4D4D4`, en dur dans l'état par défaut et liée à `Colors/Border/` — la
+  collection anglaise résiduelle, antérieure au calque sémantique de Zest — au survol. Zest, c'est
+  `Couleurs/Bordure/border-primary`, `#D3D7DE`, et c'est bien ce que le `Button` principal
+  emploie. Mesuré, l'écart est de 1,48:1 contre 1,44:1 : l'œil ne le voit pas, c'est le
+  vocabulaire qui est en jeu. Même piège que les icônes de fichier. ⚠️ **À corriger dans le
+  Figma.**
+
 - **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 :