@starterlib/tokens 0.8.0 → 0.9.1

package/README.md

@@ -20,8 +20,8 @@ pnpm add @starterlib/tokens
 ```
 
 Elle pose les variables `--st-*` sur `:root`, le theme sombre sous
-`[data-theme='sombre']` et sous `prefers-color-scheme: dark`, et reduit les
-durees sous `prefers-reduced-motion`. `color-scheme` suit le theme effectif :
+`[data-theme='sombre']` et sous `prefers-color-scheme: dark`, et eteint le
+mouvement sous `prefers-reduced-motion` (voir « Mouvement »). `color-scheme` suit le theme effectif :
 les controles natifs, les barres de defilement et le remplissage automatique
 restent dans le bon theme meme quand l'utilisateur force un theme contraire a
 son systeme.
@@ -35,6 +35,45 @@ Elle obeit aussi a la PERSONNE, pas seulement au theme :
   hauteur que `st-app-shell` mesure sur son en-tete collant, pour qu'un arret de
   tabulation ne remonte jamais dessous (WCAG 2.4.11). Sans coquille, zero.
 
+Elle publie aussi les classes qu'un gabarit d'APPLICATION ecrit lui-meme (lot 156) :
+
+- `.st-vh` — un texte pour les seuls lecteurs d'ecran
+  (`<span class="st-vh">, 5 non lus</span>`), masque a l'oeil et garde dans le nom
+  accessible ; `.st-vh-focalisable` le montre quand il recoit le focus (un lien d'evitement).
+  Emise dans la portee d'un composant, la classe n'atteignait jamais un element ecrit par
+  l'appelant : le texte s'affichait en clair ;
+- `.st-hors-impression`, `.st-impression-seulement` — ce qui ne s'imprime pas, et l'inverse ;
+- `.st-formulaire` — le rythme vertical d'un formulaire, porte par le conteneur.
+
+## Mouvement
+
+Une table FERMEE (01 §6, D9, D24), emise en variables :
+
+| Famille              | Jetons                                                                    | Sous mouvement reduit |
+| -------------------- | ------------------------------------------------------------------------- | --------------------- |
+| `--st-duree-*`       | `instantane` 0, `rapide` 120, `normale` 200, `lente` 320, `longue` 480 ms | 0 ms                  |
+| `--st-courbe-*`      | `standard`, `entrant`, `sortant` (plus `linear`)                          | —                     |
+| `--st-deplacement-*` | `court` 0.25rem, `moyen` 0.5rem, `long` 1rem                              | 0                     |
+| `--st-cadence-*`     | `vive` 900, `normale` 1400, `respiration` 1600 ms                         | **conservees**        |
+| `--st-cadence-min`   | 600 ms, plancher d'une boucle d'attente                                   | —                     |
+
+- Une entree est une opacite PLUS un deplacement, jamais une echelle ; une sortie est
+  un fondu. Le fondu d'une couche lit `--st-duree-normale` : il n'y a pas de reglage
+  de fondu (D8).
+- Trois voies eteignent le mouvement, toutes dans la feuille : la preference du
+  systeme (sauf `data-mouvement="complet"` sur `<html>`), l'attribut
+  `data-mouvement="reduit"` (pose par `StMouvement` de `@starterlib/core`), et le gel
+  d'une image `data-gel` (pose le temps d'un rendu au changement de theme ou de
+  langue). Une feuille de composant n'ecrit donc JAMAIS
+  `@media (prefers-reduced-motion)` autour d'une transition : elle lit les jetons.
+- Les cadences ne s'eteignent jamais : sous mouvement reduit, une boucle d'attente
+  passe de la rotation a la respiration (mixin `sous-mouvement-reduit` du partiel
+  `ruptures`), elle ne se fige pas.
+- Les DELAIS et les TENUES (200 ms avant un chargement, 400 ms minimum une fois
+  montre, 2 s de confirmation...) ne sont pas du mouvement : ils vivent en TypeScript
+  seulement, dans `rythme` (`rythme.delai.*`, `rythme.tenue.*`, D3), jamais emis,
+  jamais mis a zero.
+
 ## Points de rupture
 
 Un partiel Sass, engendre comme la feuille, et la meme echelle en TypeScript :
@@ -68,16 +107,118 @@ Le theme se force par attribut, et l'attribut l'emporte dans les deux sens :
 <html data-theme="sombre"></html>
 ```
 
+Chaque couleur est UNE declaration `light-dark(clair, sombre)` : le theme effectif
+est porte par `color-scheme`, que `:root`, `prefers-color-scheme` et l'attribut
+posent. L'attribut vaut donc aussi sur un **ilot** : une carte `data-theme="sombre"`
+dans une page claire rend ses couleurs sombres, sans classe ni variable de plus.
+
+```html
+<section data-theme="sombre">…</section>
+```
+
+La densite se regle de meme, par attribut, sur la page ou sur une zone :
+
+```html
+<main data-densite="compacte">…</main>
+<!-- confortable (defaut) | compacte | dense -->
+```
+
+Elle regle la hauteur des commandes (44, 36 ou 32 px), les rembourrages et
+l'interligne des lignes de tableau ; sous `pointer: coarse`, la cible tactile ne
+descend jamais sous 44 px.
+
+## Polices
+
+Inter et JetBrains Mono, **auto-hebergees** (SIL OFL 1.1) : aucune adresse tierce,
+`font-src 'self'` suffit.
+
+```css
+@import '@starterlib/tokens/styles/polices.css';
+```
+
+```html
+<link
+  rel="preload"
+  href="/polices/inter-latin-wght-normal.woff2"
+  as="font"
+  type="font/woff2"
+  crossorigin
+/>
+```
+
+`font-display: optional` et un repli METRISE (memes hauteur de ligne et chasse
+moyenne, calcules sur le fichier livre) : la page ne saute pas quand la police
+arrive. Recette complete, budget et correspondance avec les planches :
+[docs/recettes/police.md](../../docs/recettes/police.md).
+
+## Styles typographiques
+
+Des styles composites (taille, interligne, graisse, approche, chiffres ; jamais de
+couleur), par un seul mixin engendre :
+
+```scss
+@use '@starterlib/tokens/styles/typographie' as typo;
+
+h2 {
+  @include typo.style('titre-2');
+}
+// un nom inconnu echoue a la compilation
+```
+
+`stylesTypographiques` donne la meme table en TypeScript. Les tailles vont de `2xs`
+(reserve aux capitales) a `6xl`, chacune avec son interligne ; les chiffres passent
+par deux contrats (`--st-chiffres-alignes`, `--st-chiffres-references`).
+
+⚠️ **Un nom diverge entre le TypeScript et la feuille** : les piles de polices s'appellent
+`typographie.famille.base` et `typographie.famille.mono` en TypeScript, et `--st-police-base` et
+`--st-police-mono` dans la feuille (et `police.base`, `police.mono` dans le fichier DTCG). La feuille
+nomme ce que l'ecran charge ; le TypeScript garde le vocabulaire de l'echelle typographique.
+
 ## API TypeScript
 
 ```ts
-import { themes, contraste, echelles } from '@starterlib/tokens';
+import { themeClair, themeSombre, primitives, rapportDeContraste, apca } from '@starterlib/tokens';
 ```
 
-- `themes.clair` et `themes.sombre` : couleurs semantiques.
-- `echelles` : espacement, typographie, rayons, ombres, durees, plans.
+- `themeClair` et `themeSombre` : les couleurs semantiques, chacune une `CouleurHex`
+  (`#${string}`) : `primaire: 'bleu'` ne compile pas (lot 158) ; `ombres`, `voile`.
+- `primitives`, `definitionsDesPrimitives` : les rampes, ENGENDREES en OKLCH
+  (`oklchVersHex`, `hexVersOklch`), jamais recopiees.
+- `espacement`, `typographie`, `rayon`, `epaisseur`, `largeur`, `hauteurDeCommande`,
+  `densite`, `focus`, `plan`, `duree`, `courbe`, `deplacement`, `cadence`,
+  `cadenceMinimale` : les echelles ; `mouvementReduit` et `mouvementGele` : ce que
+  la feuille met a zero.
+- `rythme` (`delai`, `tenue`) : les delais et tenues que les composants lisent en
+  TypeScript (D3).
+- `stylesTypographiques`, `policesDuSocle` : typographie et polices.
 - `RUPTURES` : les points de rupture en px, en rem et en requete de media.
-- `contraste(a, b)` : rapport WCAG, employe par les tests du depot.
+- `rapportDeContraste(a, b)` (WCAG), `apca(texte, fond)` (Lc, APCA 0.0.98G-4g),
+  `composer(premierPlan, fond)` : employes par les tests du depot.
+- `rolesDesPrimitives()` : quel role porte quel pas (le nuancier le lit).
+- `jetonsDtcg()` : les jetons au format DTCG (ci-dessous).
+
+## Format DTCG
+
+`styles/starter-tokens.tokens.json` porte les jetons au format du W3C Design Tokens Community Group
+(« Design Tokens Format Module », version stable 2025.10), pour un outil de design ou un autre
+moteur de rendu qui ne lit pas le TypeScript :
+
+```ts
+import jetons from '@starterlib/tokens/styles/starter-tokens.tokens.json' with { type: 'json' };
+```
+
+| Groupe                     | Contenu                             | `$type`      |
+| -------------------------- | ----------------------------------- | ------------ |
+| `couleur.clair`, `.sombre` | les couleurs semantiques des themes | `color`      |
+| `espacement`, `rayon`      | les echelles, en `{ value, unit }`  | `dimension`  |
+| `taille`, `interligne`     | l'echelle typographique             | `dimension`  |
+| `graisse`                  | 400, 500, 600, 700                  | `fontWeight` |
+| `police`                   | les piles de polices, en listes     | `fontFamily` |
+| `duree`                    | les durees du mouvement, en ms      | `duration`   |
+
+Une couleur s'ecrit en sRGB (`colorSpace`, `components` de 0 a 1) avec son `hex` en repli. Les
+ombres, les courbes, les cadences et les derogations (contraste renforce, impression, mouvement
+reduit) n'y sont pas : ce sont des regles de la feuille, pas des valeurs a recopier ailleurs.
 
 ## Niveau 3 — reglages de composant
 
@@ -97,17 +238,17 @@ style. Elles sont listees en commentaire en tete de la feuille engendree, et dan
 }
 ```
 
-| Reglage                       | Defaut                     | Pour                                       |
-| ----------------------------- | -------------------------- | ------------------------------------------ |
-| `--st-commande-hauteur`       | `--st-cible-tactile-min`   | hauteur minimale des boutons et des champs |
-| `--st-commande-rayon`         | `--st-rayon-md`            | identite de marque                         |
-| `--st-surface-rayon`          | `--st-rayon-md`            | carte, dialogue, menu, popover             |
-| `--st-tableau-cellule-bloc`   | `--st-espacement-3`        | densite verticale d'un tableau             |
-| `--st-tableau-cellule-ligne`  | `--st-espacement-3`        | densite horizontale                        |
-| `--st-tableau-largeur-case`   | `3rem`                     | colonne des cases a cocher                 |
-| `--st-calendrier-jour-taille` | `--st-cible-tactile-min`   | calendrier dense                           |
-| `--st-anim-chargement`        | propre a chaque indicateur | rythme d'un indicateur d'activite          |
-| `--st-anim-respiration`       | `1600ms`                   | rythme sous mouvement reduit               |
+| Reglage                       | Defaut                                        | Pour                                                            |
+| ----------------------------- | --------------------------------------------- | --------------------------------------------------------------- |
+| `--st-commande-hauteur`       | `--st-cible-tactile-min`                      | hauteur minimale des boutons et des champs                      |
+| `--st-commande-rayon`         | `--st-rayon-md`                               | identite de marque                                              |
+| `--st-surface-rayon`          | `--st-rayon-md`                               | carte, dialogue, menu, popover                                  |
+| `--st-tableau-cellule-bloc`   | `--st-espacement-3`                           | densite verticale d'un tableau                                  |
+| `--st-tableau-cellule-ligne`  | `--st-espacement-3`                           | densite horizontale                                             |
+| `--st-tableau-largeur-case`   | `3rem`                                        | colonne des cases a cocher                                      |
+| `--st-calendrier-jour-taille` | `--st-cible-tactile-min`                      | calendrier dense                                                |
+| `--st-anim-chargement`        | `--st-cadence-vive` ou `--st-cadence-normale` | rythme d'un indicateur d'activite (plancher `--st-cadence-min`) |
+| `--st-anim-respiration`       | `--st-cadence-respiration`                    | rythme sous mouvement reduit (plancher `--st-cadence-min`)      |
 
 ⚠️ **Le socle ne les DECLARE jamais** : il les lit au point d'usage, avec un
 repli. Une declaration sur l'hote d'un composant l'emporterait sur la valeur
@@ -124,12 +265,30 @@ calendrier reste au-dessus de la cible minimale, quoi qu'on pose.
 
 ## Garde de non-derive
 
-Le CSS est **engendre**, jamais ecrit a la main — la feuille comme le partiel
-des ruptures. `pnpm tokens:css:check` echoue si un fichier livre ne correspond
-plus aux jetons TypeScript — meme principe que le controle de contrat cote
-backend.
+Le CSS est **engendre**, jamais ecrit a la main — la feuille, les partiels des
+ruptures et de la typographie, la feuille des polices, et le fichier DTCG. Les outils lisent les
+jetons sur leurs SOURCES (`tools/jetons-sources.mjs`, Node 24 retire les types a l'import) : ni
+`ng build` prealable, ni course avec `dist/` (`rm -rf dist && pnpm tokens:css:check` reste vert,
+lot 158). `pnpm tokens:css:check`
+echoue si un fichier livre ne correspond plus aux jetons TypeScript — meme
+principe que le controle de contrat cote backend —, si une metrique de police
+declaree n'est plus celle du fichier livre (`tools/verifier-police.mjs`), ou si
+le nuancier de la planche 11 corrige par le registre ne correspond plus au moteur
+(`tools/ecarts-du-nuancier.mjs`).
 
 ## Accessibilite
 
-25 paires semantiques sont verifiees en AA dans les deux themes par les tests du
-paquet. Toute exemption porte une raison ecrite et reste perceptible.
+Les tests du paquet verifient, dans les deux themes :
+
+- chaque paire de `pairesDeContraste` en AA (4,5:1 pour le texte, 3:1 pour les
+  filets et les indicateurs), avec son score APCA ; chaque exemption
+  (`exemptesDeContraste`) et chaque paire exclue (`pairesExclues`) porte sa raison
+  ecrite ;
+- l'ecart perceptible entre surfaces voisines (repos, survol, actif, conteneurs) ;
+- l'anneau de focus sur chaque surface de `surfacesDuFocus` : l'anneau OU le lisere
+  tient 3:1 ;
+- les alias de `prefers-contrast: more` et les couleurs systeme de
+  `forced-colors`.
+
+Aucun compte n'est ecrit a la main ici : `node tools/compter-jetons.mjs` les donne
+depuis le paquet construit (D14).