@starterlib/tokens 0.10.14 → 0.11.0

package/types/starterlib-tokens-moteur.d.ts

@@ -5,7 +5,7 @@
  * « code » n'ont pas la meme clarte percue, et deux statuts au meme pas n'ont
  * pas le meme contraste. En OKLCH, la clarte `l` est perceptuelle : deux pas de
  * meme `l` tiennent le meme contraste sur une meme surface, quelle que soit leur
- * teinte. C'est ce qui permet d'engendrer six familles chromatiques par une
+ * teinte. C'est ce qui permet d'engendrer sept familles chromatiques par une
  * seule table de clartes (`primitives.ts`).
  *
  * Le moteur ne fait que convertir. L'hexadecimal reste ce que consomment la
@@ -58,7 +58,7 @@ export declare function oklchEnCss({ l, c, h }: Oklch): string;
  * donnees (graphique sequentiel, carte de chaleur) sur une rampe.
  *
  * Chaque couleur est DEFINIE en OKLCH et son hexadecimal est DERIVE par le
- * moteur (`oklch.ts`). Les six familles chromatiques partagent une seule table de
+ * moteur (`oklch.ts`). Les sept familles chromatiques partagent une seule table de
  * clartes : un `succes 600` et un `danger 600` ont la meme clarte, donc le meme
  * contraste sur une meme surface (01 §2, principe P3). Une famille se definit par
  * deux nombres, sa teinte et sa chroma maximale.
@@ -77,11 +77,11 @@ export type PasNeutre = (typeof PAS_NEUTRES)[number];
 /** Rangs de la palette categorielle. */
 export declare const RANGS_DE_SERIE: readonly [1, 2, 3, 4, 5, 6];
 export type RangDeSerie = (typeof RANGS_DE_SERIE)[number];
-/** Clarte OKLCH de chaque pas, commune aux six familles chromatiques. */
+/** Clarte OKLCH de chaque pas, commune aux sept familles chromatiques. */
 export declare const L_PAS: Readonly<Record<PasDeRampe, number>>;
 /** Part de la chroma maximale de la famille, par pas : la couleur culmine au pas 600. */
 export declare const C_PAS: Readonly<Record<PasDeRampe, number>>;
-export type NomDeFamille = 'bleu' | 'azur' | 'or' | 'vert' | 'ambre' | 'rouge';
+export type NomDeFamille = 'bleu' | 'azur' | 'or' | 'vert' | 'ambre' | 'rouge' | 'violet';
 export interface FamilleChromatique {
   /** Teinte OKLCH, en degres. */
   readonly teinte: number;
@@ -115,9 +115,10 @@ export type RampesDuNuancier<V> = {
   readonly vert: Readonly<Record<PasDeRampe, V>>;
   readonly ambre: Readonly<Record<PasDeRampe, V>>;
   readonly rouge: Readonly<Record<PasDeRampe, V>>;
+  readonly violet: Readonly<Record<PasDeRampe, V>>;
   readonly serie: Readonly<Record<RangDeSerie, V>>;
 };
-/** Les 85 primitives avec leur definition : ce que le nuancier du banc affiche. */
+/** Les 96 primitives avec leur definition : ce que le nuancier du banc affiche. */
 export declare const definitionsDesPrimitives: RampesDuNuancier<DefinitionDePrimitive>;
 export type NomDeRampe = keyof typeof definitionsDesPrimitives;
 /** Les primitives en hexadecimal : la forme que le theme et la feuille consomment. */
@@ -546,6 +547,18 @@ export interface JetonsDeCouleur {
   readonly dangerDiscret: CouleurHex;
   readonly surDangerDiscret: CouleurHex;
   readonly dangerDiscretCourant: CouleurHex;
+  readonly erreur: CouleurHex;
+  readonly surErreur: CouleurHex;
+  readonly erreurDiscret: CouleurHex;
+  readonly surErreurDiscret: CouleurHex;
+  readonly essai: CouleurHex;
+  readonly surEssai: CouleurHex;
+  readonly essaiDiscret: CouleurHex;
+  readonly surEssaiDiscret: CouleurHex;
+  readonly serie1: CouleurHex;
+  readonly serie2: CouleurHex;
+  readonly serie3: CouleurHex;
+  readonly serie4: CouleurHex;
   readonly positif: CouleurHex;
   readonly negatif: CouleurHex;
 }
@@ -560,6 +573,14 @@ export declare const themeClair: JetonsDeCouleur;
  */
 export declare const themeSombre: JetonsDeCouleur;
 export declare const themes: Readonly<Record<NomDeTheme, JetonsDeCouleur>>;
+/**
+ * Roles ALIAS (P08-03) : leur valeur par defaut est celle d'un autre role, et la feuille l'ecrit
+ * `var(--st-couleur-<cible>)` au lieu d'une copie. Une application qui change `danger` change donc
+ * l'erreur avec lui, tant qu'elle (ou sa marque) ne pose pas `erreur` : le rendu des autres
+ * consommateurs du socle reste celui d'avant le role. Les valeurs des themes sont celles de la
+ * cible, et un essai le verifie.
+ */
+export declare const aliasDeRole: Readonly<Partial<Record<NomDeJeton, NomDeJeton>>>;
 /**
  * Les paires que le contraste doit tenir, dans les DEUX themes. Elles sont
  * declarees ici, et non dans le test, pour qu'un jeton ajoute sans sa paire saute
@@ -660,7 +681,10 @@ export declare function rolesDesPrimitives(): ReadonlyMap<string, readonly strin
  * dans la recette `docs/recettes/police.md`, pas dans le socle.
  *
  * ⚠️ Un style ne pose JAMAIS de couleur : la couleur est un role semantique, le
- * style une forme. Il ne pose la famille que pour la chasse fixe.
+ * style une forme. Il ne pose la famille que pour la chasse fixe, et pour les titres :
+ * `var(--st-police-titre, var(--st-police-base))`. Le jeton de titre n'est declare que par la
+ * feuille OPTIONNELLE `styles/polices-titres.css` : sans elle, un titre garde la police de base,
+ * et l'application ne charge aucun octet de plus.
  */
 type Graisse = keyof typeof typographie.graisse;
 type Interlettrage = keyof typeof typographie.interlettrage;
@@ -678,7 +702,8 @@ export interface StyleComposite {
    */
   readonly interlettrage: Interlettrage | 'approche';
   readonly chiffres?: keyof typeof typographie.chiffres;
-  readonly famille?: 'mono';
+  /** `mono` : la chasse fixe ; `titre` : la police de titre si sa feuille est chargee. */
+  readonly famille?: 'mono' | 'titre';
   /** Micro-libelles en capitales : la casse fait partie de la forme. */
   readonly capitales?: true;
   readonly usage: string;
@@ -752,30 +777,35 @@ export declare const stylesTypographiques: {
     readonly interligne: "md";
     readonly graisse: "semi";
     readonly interlettrage: "approche";
+    readonly famille: "titre";
     readonly usage: "intertitre, titre de dialogue et de carte (18/24)";
   };
   readonly 'titre-3': {
     readonly taille: "xl";
     readonly graisse: "semi";
     readonly interlettrage: "approche";
+    readonly famille: "titre";
     readonly usage: "titre de section";
   };
   readonly 'titre-2': {
     readonly taille: "2xl";
     readonly graisse: "semi";
     readonly interlettrage: "approche";
+    readonly famille: "titre";
     readonly usage: "titre de bloc majeur";
   };
   readonly 'titre-1': {
     readonly taille: "3xl";
     readonly graisse: "semi";
     readonly interlettrage: "approche";
+    readonly famille: "titre";
     readonly usage: "titre de page (h1 de 32 px, D18)";
   };
   readonly affichage: {
     readonly taille: "4xl";
     readonly graisse: "semi";
     readonly interlettrage: "approche";
+    readonly famille: "titre";
     readonly usage: "annonce, titre d ecran de marque";
   };
   readonly 'affichage-grand': {
@@ -911,6 +941,17 @@ export interface PoliceDuSocle {
   };
 }
 export declare const policesDuSocle: readonly PoliceDuSocle[];
+/**
+ * Police de TITRE, OPTIONNELLE (niveau 2 bis) : Source Serif 4 (SIL OFL 1.1), axe de graisse seul,
+ * auto-hebergee comme les autres. Livree dans sa PROPRE feuille, `styles/polices-titres.css`, qui
+ * declare aussi le jeton `--st-police-titre` : les styles `titre-*` et `affichage` le lisent avec la
+ * police de base en repli. Qui ne charge pas la feuille garde ses titres dans la police de base et ne
+ * paie aucun octet ; qui la charge ne la precharge pas sur un ecran anonyme sous seuil (ADR 0031) :
+ * `font-display: optional` et le repli metrise excluent tout decalage a son arrivee.
+ */
+export declare const policesDeTitre: readonly PoliceDuSocle[];
+/** La pile du jeton `--st-police-titre`, posee par la feuille des titres. */
+export declare const pileDeTitre = "'Source Serif 4 Variable', 'Source Serif 4 Repli', Georgia, serif";
 /** Surcharges du repli, en pourcentage, arrondies au centieme. */
 export interface SurchargesDuRepli {
   readonly sizeAdjust: string;
@@ -926,12 +967,12 @@ export interface SurchargesDuRepli {
 export declare function surchargesDuRepli(police: PoliceDuSocle): SurchargesDuRepli;
 /** Les fichiers a precharger par l'hote, dans l'ordre. */
 export declare function fichiersAPrecharger(): readonly string[];
+export declare function feuilleDesPolices(): string;
 /**
- * La feuille `styles/polices.css`. Les adresses sont RELATIVES a la feuille
- * (`./polices/…`) : l'outil de construction de l'hote les reecrit et les sert de
- * sa propre origine.
+ * La feuille OPTIONNELLE `styles/polices-titres.css` : les faces de la police de titre, son repli
+ * metrise, et le jeton `--st-police-titre` qu'elles servent. Adresses relatives, comme les autres.
  */
-export declare function feuilleDesPolices(): string;
+export declare function feuilleDesPolicesDeTitre(): string;
 /**
  * Niveau 3 — jetons de composant. Les quelques reglages qu'une application peut
  * poser sans forker une feuille de style.
@@ -1012,8 +1053,11 @@ export declare function enKebab(valeur: string): string;
 export declare function nomDeCouleur(jeton: NomDeJeton): string;
 /** Jetons invariants : ils ne dependent pas du theme. */
 export declare function cssDesEchelles(): string;
-/** Couleurs, ombres et voile : une declaration chacun, en `light-dark()`. */
-export declare function cssDuTheme(): string;
+/**
+ * Couleurs, ombres et voile : une declaration chacun, en `light-dark()` ; un role alias en `var()`
+ * de sa cible, sauf `litteral` (le repli du partiel Sass).
+ */
+export declare function cssDuTheme(litteral?: boolean): string;
 /**
  * Mouvement reduit (01 §6, 03 P5) : toute duree non nulle ET tout deplacement a zero.
  * Une couche apparait alors en place et d'un coup, sans qu'aucun composant sache
@@ -1106,6 +1150,8 @@ export declare const encresDAplat: readonly NomDeJeton[];
 export declare const derogationsDImpression: Readonly<Partial<Record<NomDeJeton, string>>>;
 /** Tailles en points a l'impression : le rem y vaut 12 pt, l'echelle se resserre. */
 export declare const taillesDImpression: Readonly<Record<keyof typeof typographie.taille, string>>;
+/** Le reglage d'affichage du prefixe de ton (P08-03) : `masque` (defaut, sans le poser) ou `visible`. */
+export declare const REGLAGE_DU_PREFIXE_DE_TON = "--st-prefixe-de-ton";
 /**
  * Feuille complete.
  *
@@ -1168,9 +1214,143 @@ export declare function nombreDeJetonsDeCouleur(jetons?: JetonsDeCouleur): numbe
  * | `police`                   | `typographie.famille`          | `fontFamily` |
  * | `duree`                    | `duree`                        | `duration`   |
  *
+ * Un role ALIAS (`aliasDeRole`, P08-03 : `erreur` vaut `danger` par defaut) part en reference DTCG,
+ * `{couleur.clair.danger}` : un outil le resout, et il suit sa cible comme la feuille.
+ *
  * Ce qui ne part pas : les ombres, courbes, cadences et derogations (contraste renforce, impression,
  * mouvement reduit) sont des REGLES de la feuille, pas des valeurs a recopier ailleurs.
  */
 export declare function jetonsDtcg(): string;
+/**
+ * Niveau 2 bis — la MARQUE : un theme de marque generique, par valeurs.
+ *
+ * Une application obtient son identite par des VALEURS, jamais par une feuille ecrite a la main : le
+ * README des jetons n'ouvre aucune couleur au niveau 3. Une marque pose, pour chaque theme, la valeur
+ * de roles semantiques ; le moteur rejoue sur le theme qui en resulte TOUTES les gardes de la feuille
+ * par defaut (paires de contraste, ecarts de surface, focus a deux voies, contraste renforce,
+ * impression), et seulement s'il est conforme, engendre une feuille `starter-tokens-<nom>.css` a
+ * charger APRES `starter-tokens.css`.
+ *
+ * Ce qu'une marque change : la valeur des roles (couleurs). Ce qu'elle ne change pas : la structure
+ * (noms des jetons), les rayons, les hauteurs, les echelles — des reglages de niveau 3 ou des
+ * decisions du socle.
+ *
+ * ⚠️ **La feuille par defaut ne bouge pas d'un octet.** Le role `bordureForteElevee` (le contour d'un
+ * champ pose sur une surface elevee : dialogue, menu, popover, conteneur haut) n'y est pas declare, et
+ * la substitution qui le fait lire par les conteneurs eleves vit dans la feuille de MARQUE : sans
+ * marque, un champ dans un dialogue garde exactement le contour d'aujourd'hui, contraste renforce
+ * compris ; avec une marque, il prend le contour que la marque a prouve a 3:1 sur ces surfaces.
+ */
+/** Les roles qu'une marque peut poser : les jetons semantiques, plus le contour sur surface elevee. */
+export type RoleDeMarque = NomDeJeton | 'bordureForteElevee';
+/** Les valeurs d'un theme de la marque : un sous-ensemble des roles, en hexadecimal `#rrggbb`. */
+export type CouleursDeMarque = Readonly<Partial<Record<RoleDeMarque, CouleurHex>>>;
+/** Le theme complet d'une marque : celui du socle, ecrase par les valeurs de la marque. */
+export type JetonsDeMarque = JetonsDeCouleur & {
+  readonly bordureForteElevee: CouleurHex;
+};
+/**
+ * Un ecart de surface que la marque assume sous son seuil, avec son motif : la separation est alors
+ * portee par le FILET, que le moteur exige perceptible (`SEUIL_DE_PERCEPTIBILITE`) sur l'une des deux
+ * surfaces au moins. Sans `theme`, l'exemption vaut dans les deux.
+ */
+export interface ExemptionDeMarque {
+  readonly ecart: readonly [RoleDeMarque, RoleDeMarque];
+  readonly theme?: NomDeTheme;
+  readonly raison: string;
+}
+/** Une paire de plus, exigee par la marque (un usage qui lui est propre). */
+export interface PaireDeMarque {
+  readonly premierPlan: RoleDeMarque;
+  readonly arrierePlans: readonly RoleDeMarque[];
+  readonly nature: NatureDuTexte;
+}
+/**
+ * Une paire de la marque qu'on pourrait croire permise et qui ne l'est pas : elle doit ECHOUER dans un
+ * theme au moins (une exclusion qui tient redevient une paire), et la regle d'usage est ecrite.
+ */
+export interface PaireExclueDeMarque {
+  readonly premierPlan: RoleDeMarque;
+  readonly arrierePlan: RoleDeMarque;
+  readonly raison: string;
+}
+export interface ValeursDeMarque {
+  /** `exemple-blanc` : nomme la feuille `starter-tokens-<nom>.css` et le fichier `<nom>.tokens.json`. */
+  readonly nom: string;
+  readonly description?: string;
+  readonly clair: CouleursDeMarque;
+  readonly sombre: CouleursDeMarque;
+  /** Familles de primitives propres a la marque, pour le fichier DTCG : `{ violet: { 600: '#…' } }`. */
+  readonly primitives?: Readonly<Record<string, Readonly<Record<string, CouleurHex>>>>;
+  readonly exemptions?: readonly ExemptionDeMarque[];
+  readonly paires?: readonly PaireDeMarque[];
+  readonly pairesExclues?: readonly PaireExclueDeMarque[];
+}
+/** Une marque qui ne tient pas ses gardes : chaque defaut nomme la paire ou la valeur fautive. */
+export declare class MarqueNonConforme extends Error {
+  readonly defauts: readonly string[];
+  constructor(nom: string, defauts: readonly string[]);
+}
+/**
+ * Les paires que toute marque doit tenir : celles du socle, plus le contour sur les surfaces elevees
+ * (3:1, WCAG 1.4.11) — sur la surface aussi, une carte posee dans un dialogue portant ses champs.
+ */
+export declare const pairesDuContourEleve: readonly PaireDeMarque[];
+/**
+ * Les ecarts de surface d'une marque : ceux du socle, plus la surface sur le fond (une carte se
+ * detache de la page). La feuille par defaut le tient deja (1,05:1) ; une marque a fond blanc ne le
+ * peut pas, et l'assume par une exemption ecrite, le filet portant la separation.
+ */
+export declare const ecartsDeMarque: readonly {
+  readonly devant: RoleDeMarque;
+  readonly derriere: RoleDeMarque;
+  readonly minimum: number;
+  readonly pourquoi: string;
+}[];
+/** Les conteneurs eleves du socle : leurs champs lisent `bordureForteElevee` (feuille de marque seulement). */
+export declare const conteneursEleves: readonly string[];
+/**
+ * Le theme complet d'une marque, valeurs en minuscules ; `bordureForteElevee` vaut `bordureForte`
+ * s'il manque, et un role ALIAS non pose (`erreur`...) vaut sa cible DANS LA MARQUE : une marque qui
+ * pose `danger` sans `erreur` peint l'erreur de son danger, comme la feuille (`var()`) le fera.
+ */
+export declare function themeDeMarque(valeurs: ValeursDeMarque, theme: NomDeTheme): JetonsDeMarque;
+/**
+ * Le theme d'une marque sous `prefers-contrast: more` : les alias du socle resolus dans la MARQUE, les
+ * encres foncees du socle la ou la marque n'a pas pose le role, le contour eleve au texte discret.
+ */
+export declare function themeDeMarqueSousContrasteRenforce(valeurs: ValeursDeMarque, theme: NomDeTheme): JetonsDeMarque;
+/**
+ * Les defauts d'une marque, vides si elle est conforme. Chaque defaut nomme la paire ou la valeur
+ * fautive, son rapport et son minimum : c'est ce que la commande `starter-web jetons --marque` et les
+ * essais impriment. Rejoue, dans les deux themes, ce que la feuille par defaut tient :
+ *
+ * - les paires de contraste (4,5:1 texte, 3:1 non textuel), avec celles de la marque et sans ses
+ *   exclusions, au rendu normal ET sous `prefers-contrast: more` ;
+ * - le focus a deux voies sur chaque surface (l'anneau ou son lisere a 3:1), aux deux rendus ;
+ * - les ecarts de surface perceptibles, sauf exemption ecrite, auquel cas le filet doit l'etre ;
+ * - les jetons exemptes du socle (`bordure`, `texteDesactive`) restent perceptibles sur la surface ;
+ * - une paire exclue echoue vraiment dans un theme au moins.
+ */
+export declare function defautsDeLaMarque(entree: unknown): readonly string[];
+/**
+ * La feuille d'une marque, a charger APRES `starter-tokens.css` : les couleurs que la marque change,
+ * le contour des conteneurs eleves, puis ses propres blocs de contraste renforce, de contraste force et
+ * d'impression (venue apres la feuille du socle, sa racine ecraserait sinon ceux du socle pour les
+ * roles qu'elle pose). Leve `MarqueNonConforme` si une garde echoue.
+ */
+export declare function feuilleDeMarque(valeurs: ValeursDeMarque): string;
+/** Le fichier DTCG d'une marque : ses deux themes complets, et ses primitives s'il y en a. */
+export declare function jetonsDtcgDeMarque(valeurs: ValeursDeMarque): string;
+/**
+ * La marque d'EXEMPLE du socle (« exemple-blanc ») : fond blanc et gris froids d'une charte sobre
+ * (fond = surface, filet, contour, retrait, gris de selection, contour sombre). Elle prouve le
+ * mecanisme dans les essais et au banc : l'exemption « fond = surface » portee par le filet, le retrait
+ * sous le seuil du socle, et un contour sombre trop faible pour les surfaces elevees, que le role
+ * `bordureForteElevee` releve. Elle pose aussi l'ERREUR a l'encre du texte, sur papier gris (P08-03) :
+ * une faute se lit par l'encre, la croix cerclee et le mot, le rouge restant a `danger`. Elle ne porte
+ * la marque d'aucun produit.
+ */
+export declare const marqueExempleBlanc: ValeursDeMarque;
 
 export {};

package/types/starterlib-tokens.d.ts

@@ -27,6 +27,11 @@ export declare const delai: {
   readonly attente: 200;
   /** Balayer une barre d'outils ne fait pas clignoter chaque infobulle. */
   readonly survol: 300;
+  /**
+   * Une pause de frappe : ce qui suit la saisie (la jauge de force du mot de passe) attend la fin d'un
+   * groupe de touches, et ne change ni ne s'annonce a chaque touche.
+   */
+  readonly frappe: 300;
   /**
    * Ajoute a la plus longue transition avant de retirer une couche sans avoir vu
    * `transitionend` (onglet en arriere-plan, transition annulee).
@@ -72,6 +77,11 @@ export declare const rythme: {
     readonly attente: 200;
     /** Balayer une barre d'outils ne fait pas clignoter chaque infobulle. */
     readonly survol: 300;
+    /**
+     * Une pause de frappe : ce qui suit la saisie (la jauge de force du mot de passe) attend la fin d'un
+     * groupe de touches, et ne change ni ne s'annonce a chaque touche.
+     */
+    readonly frappe: 300;
     /**
      * Ajoute a la plus longue transition avant de retirer une couche sans avoir vu
      * `transitionend` (onglet en arriere-plan, transition annulee).