@starterlib/tokens 0.10.13 → 0.11.0

package/README.md

@@ -151,6 +151,21 @@ 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).
 
+### Police de titre, optionnelle
+
+Source Serif 4 (SIL OFL 1.1), dans sa PROPRE feuille : les styles `titre-1` a `titre-4` et
+`affichage` lisent `var(--st-police-titre, var(--st-police-base))`, et seule cette feuille declare le
+jeton. Qui ne la charge pas garde ses titres dans la police de base, sans un octet de plus.
+
+```css
+@import '@starterlib/tokens/styles/polices.css';
+@import '@starterlib/tokens/styles/polices-titres.css';
+```
+
+Meme regime que les autres : `font-display: optional`, repli metrise sur Times New Roman et ses
+clones (`Source Serif 4 Repli`), metriques relues sur le fichier livre par `tools/verifier-police.mjs`.
+Ne pas la PRECHARGER sur un ecran anonyme sous seuil : la recette dit quand et comment.
+
 ## Styles typographiques
 
 Des styles composites (taille, interligne, graisse, approche, chiffres ; jamais de
@@ -198,6 +213,8 @@ import { themeClair, themeSombre, rapportDeContraste, apca } from '@starterlib/t
 
 - `themeClair` et `themeSombre` : les couleurs semantiques, chacune une `CouleurHex`
   (`#${string}`) : `primaire: 'bleu'` ne compile pas (lot 158) ; `ombres`, `voile`.
+- `aliasDeRole` : les roles dont la valeur par defaut est celle d'un autre (`erreur` vaut
+  `danger`, P08-03) ; la feuille les ecrit `var()` de leur cible, le fichier DTCG en reference.
 - `primitives`, `definitionsDesPrimitives` : les rampes, ENGENDREES en OKLCH
   (`oklchVersHex`, `hexVersOklch`), jamais recopiees.
 - `espacement`, `typographie`, `rayon`, `epaisseur`, `largeur`, `hauteurDeCommande`,
@@ -233,9 +250,86 @@ import jetons from '@starterlib/tokens/styles/starter-tokens.tokens.json' with {
 | `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.
+Une couleur s'ecrit en sRGB (`colorSpace`, `components` de 0 a 1) avec son `hex` en repli ; un role
+alias (`erreur`, `surErreur`, `erreurDiscret`, `surErreurDiscret`) en reference de sa cible,
+`{couleur.clair.danger}`. 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 2 bis — marque
+
+Une application obtient son identite par des **valeurs**, jamais par une feuille ecrite a la main :
+une marque pose, pour chaque theme, la valeur de roles semantiques (`fond`, `surface`,
+`surfaceEnfoncee`, `surfaceSelection`, `bordure`, `bordureForte`, `bordureForteElevee`, `texte`,
+`texteDiscret`, `primaire`, `accent`, les tons de statut, `positif`, `negatif`... : tout nom de
+`JetonsDeCouleur`). Le moteur rejoue sur le theme qui en resulte TOUTES les gardes de la feuille par
+defaut, dans les deux themes : paires de contraste (4,5:1 texte, 3:1 non textuel) au rendu normal et
+sous contraste renforce, focus a deux voies sur chaque surface, ecarts de surface perceptibles,
+jetons exemptes perceptibles. Conforme, il engendre `starter-tokens-<nom>.css`, a charger **apres**
+`starter-tokens.css` ; sinon il refuse, chaque paire fautive nommee.
+
+```json
+{
+  "nom": "ma-marque",
+  "clair": {
+    "fond": "#ffffff",
+    "surface": "#ffffff",
+    "bordure": "#e1e6ec",
+    "bordureForte": "#7b8794"
+  },
+  "sombre": { "bordureForte": "#5d6982", "bordureForteElevee": "#7e848b" },
+  "exemptions": [
+    {
+      "ecart": ["surface", "fond"],
+      "theme": "clair",
+      "raison": "Fond = surface = blanc : une carte posee sur le fond se detache par son filet."
+    }
+  ]
+}
+```
+
+```bash
+starter-web jetons --marque marque.json   # ecrit dist/<spa>/browser/starter-tokens-ma-marque.css
+```
+
+`starter-web verify` (etape `jetons`) rejoue la marque a chaque verification tant qu'un fichier
+`marque.json`, `marque.ts` ou `marque.mjs` est a la racine de la SPA. En TypeScript :
+`defautsDeLaMarque(valeurs)`, `feuilleDeMarque(valeurs)`, `jetonsDtcgDeMarque(valeurs)` et
+`themeDeMarque(valeurs, theme)` dans `@starterlib/tokens/moteur`.
+
+Ce qu'une marque **peut** changer : la valeur des roles, et elle seule. Ce qu'elle **ne peut pas**
+changer : la structure (les noms de jetons), les echelles, les rayons et les hauteurs, qui restent des
+reglages de niveau 3 ou des decisions du socle.
+
+- **`bordureForteElevee`**, le contour d'un champ pose sur une surface elevee (dialogue, menu,
+  popover, conteneur haut), vaut `bordureForte` s'il n'est pas pose ; il est exige a 3:1 sur la
+  surface elevee, le conteneur haut et la surface. La feuille de marque fait lire ce role par
+  `st-dialog-container`, `st-dialog-content`, `st-menu` et `st-popover` ; sans marque, rien ne change
+  (la feuille par defaut ne le declare pas).
+- **`erreur`** (P08-03), avec `surErreur`, `erreurDiscret` et `surErreurDiscret` : la couleur d'une
+  faute ou d'un echec (champ invalide, recapitulatif, refus, envoi echoue), distincte de `danger`
+  (destruction, urgence). Sans valeur, ils valent ceux de `danger` (dans la marque aussi : une
+  marque qui pose `danger` peint l'erreur de son danger) ; poses, ils sont declares et tenus aux
+  memes paires que le danger, AA dans les deux themes. La marque d'exemple pose l'erreur a
+  l'encre du texte sur papier gris : une faute sans rouge. Recensement des usages et migration :
+  [`docs/recettes/erreur-et-danger.md`](../../docs/recettes/erreur-et-danger.md).
+- **`essai`** (P08-04), avec `surEssai`, `essaiDiscret` et `surEssaiDiscret` : l'environnement
+  d'essai (donnees fictives), sur la famille violette (`primitives.violet`, teinte 294, chroma
+  0,11 : pas 600 en clair, 300 en sombre, papier 50 et 900). Une marque le pose a sa valeur ; ses
+  paires sont celles d'un statut. Aucun composant ne le prend sans demande (recette
+  [`docs/recettes/environnement-d-essai.md`](../../docs/recettes/environnement-d-essai.md)).
+- **Exemption** : un ecart de surface sous son seuil (la liste `ecartsDeMarque`, qui ajoute la
+  surface sur le fond aux ecarts du socle) s'assume par une raison ecrite (40 caracteres au moins),
+  pour un theme ou les deux ; le filet (`bordure`) doit alors etre perceptible sur l'une des deux
+  surfaces au moins.
+- **Paires** : une marque peut en exiger de plus (`paires`) et en exclure (`pairesExclues`, raison
+  ecrite), a condition que l'exclusion echoue vraiment dans un theme.
+- **Contraste renforce, contraste force, impression** : la feuille de marque reporte les alias du
+  socle resolus dans la marque, les couleurs systeme des roles poses, et les derogations d'impression
+  (une encre ne fait que foncer).
+
+Exemple du socle : `styles/starter-tokens-exemple-blanc.css` (et `exemple-blanc.tokens.json`), fond
+blanc et gris froids, erreur a l'encre du texte, que le banc applique par son reglage « Marque ».
 
 ## Niveau 3 — reglages de composant
 
@@ -291,6 +385,34 @@ verifiees ne garantissent plus rien.
 ⚠️ **Un reglage ne descend pas sous un plancher d'accessibilite.** Un jour de
 calendrier reste au-dessus de la cible minimale, quoi qu'on pose.
 
+### Reglage d'affichage : `--st-prefixe-de-ton`
+
+`masque` (defaut) ou `visible` (P08-03). Le prefixe qui dit le ton d'un message EN MOTS
+(« Erreur : », « Avertissement : ») est toujours lu par les lecteurs d'ecran ; sous `visible`, il
+s'affiche aussi devant le message d'un champ (`st-inline-message`), d'une banniere (`st-banner`)
+et devant chaque ligne du recapitulatif d'erreurs (`st-error-summary`, a la place de la puce) :
+une faute se lit au mot, sans la couleur.
+
+```css
+/* Toute l'application */
+:root {
+  --st-prefixe-de-ton: visible;
+}
+
+/* Ou le remettre a masque sur une zone (une alerte critique qui porte son propre mot) */
+.alerte-critique {
+  --st-prefixe-de-ton: masque;
+}
+```
+
+Comme les reglages ci-dessus, le socle ne le declare jamais. Il ne le lit pas par `var()` : des
+requetes de style, `@container style(--st-prefixe-de-ton: visible)` (feuille des jetons pour la
+classe `.st-prefixe-de-ton`, feuille du recapitulatif pour ses lignes), rendent le prefixe visible la
+ou le reglage s'herite, aussitot pose, sans script. C'est pourquoi il n'est
+pas au catalogue `jetonsDeComposant` (des valeurs lues avec un repli, plafonnees par D8). Requete
+de style : Chrome 111, Safari 18, Firefox 151 (Baseline depuis mai 2026) ; en deca, au plancher du
+socle (Safari 17.5, Firefox 129 a 150), le prefixe reste masque, et lu.
+
 ## Garde de non-derive
 
 Le CSS est **engendre**, jamais ecrit a la main — la feuille, les partiels des