@starterlib/tokens 0.9.1 → 0.10.0

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

@@ -0,0 +1,1123 @@
+/**
+ * Moteur OKLCH, sans dependance.
+ *
+ * Une rampe de couleurs ne se raisonne pas en hexadecimal : deux gris de meme
+ * « 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
+ * seule table de clartes (`primitives.ts`).
+ *
+ * Le moteur ne fait que convertir. L'hexadecimal reste ce que consomment la
+ * feuille engendree et le calcul de contraste : une couleur OKLCH est une
+ * DEFINITION, le hex est DERIVE.
+ *
+ * Matrices : OKLab de Bjorn Ottosson (2020), sur sRGB D65.
+ */
+/** Une couleur en OKLCH : clarte 0..1, chroma >= 0, teinte en degres 0..360. */
+export interface Oklch {
+  readonly l: number;
+  readonly c: number;
+  readonly h: number;
+}
+/** Resultat d'une conversion vers sRGB : le hex, et si la chroma a du etre rabattue. */
+/**
+ * Une couleur hexadecimale sRGB (`#rrggbb`) : la seule forme qu'un jeton de couleur accepte (lot 158).
+ * `primaire: 'bleu'` ne compile plus : chaque champ de `JetonsDeCouleur` est une `CouleurHex`.
+ */
+export type CouleurHex = `#${string}`;
+export interface ConversionSrgb {
+  readonly hex: CouleurHex;
+  readonly rabattue: boolean;
+  /** Chroma effectivement rendue (egale a la chroma demandee sauf rabattement). */
+  readonly chroma: number;
+}
+/**
+ * OKLCH vers sRGB, avec RABATTEMENT de chroma : une couleur hors du gamut sRGB
+ * garde sa clarte et sa teinte, et perd la chroma qu'aucun ecran sRGB ne rend.
+ * Couper un canal a la place changerait la clarte, donc le contraste, sans le
+ * dire. Le rabattement est signale (`rabattue`) pour que les tests le voient.
+ */
+export declare function oklchVersSrgb(couleur: Oklch): ConversionSrgb;
+/** OKLCH vers hex sRGB (`#rrggbb`), chroma rabattue dans le gamut si besoin. */
+export declare function oklchVersHex(couleur: Oklch): CouleurHex;
+/**
+ * Hex sRGB vers OKLCH. Un gris a une chroma nulle et une teinte sans objet :
+ * elle vaut alors 0, par convention.
+ */
+export declare function hexVersOklch(hex: string): Oklch;
+/** Ecriture CSS d'une couleur OKLCH, pour la documentation et le banc. */
+export declare function oklchEnCss({ l, c, h }: Oklch): string;
+/**
+ * Niveau 1 — primitives. Palette brute, sans intention d'usage.
+ *
+ * ⚠️ Aucun composant ne consomme ce niveau : il passe par le niveau semantique
+ * (`theme.ts`), sinon un changement de nuance se propage a l'aveugle. La regle
+ * est outillee : `no-restricted-imports` refuse `primitives` dans `packages/ui`.
+ * Le niveau reste exporte, parce qu'une SPA peut construire une echelle de
+ * 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
+ * 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.
+ *
+ * Les rampes de la planche 11 de Claude Design ne sont PAS reprises ici : 11 de
+ * ses 13 neutres et 7 de ses 11 bleus y sont faux, avec des clartes CIELAB
+ * presentees comme OKLCH (audit Claude Design §3.6). Le moteur reste la source ;
+ * les valeurs claires SEMANTIQUES du rendu (D17) vivent dans `theme.ts`.
+ */
+/** Pas des rampes chromatiques, du plus clair au plus sombre. */
+export declare const PAS_DE_RAMPE: readonly [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950];
+export type PasDeRampe = (typeof PAS_DE_RAMPE)[number];
+/** Pas de la rampe neutre : ceux des rampes, plus 0 (le blanc) et 150 (le creux). */
+export declare const PAS_NEUTRES: readonly [0, 50, 100, 150, 200, 300, 400, 500, 600, 700, 800, 900, 950];
+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. */
+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 interface FamilleChromatique {
+  /** Teinte OKLCH, en degres. */
+  readonly teinte: number;
+  /** Chroma du pas le plus sature (600). */
+  readonly chromaMax: number;
+  /** Seule derogation a la table des clartes, ecrite et testee. */
+  readonly exception?: Partial<Record<PasDeRampe, number>>;
+  /** A quoi sert la famille. */
+  readonly vocation: string;
+}
+export declare const FAMILLES: Readonly<Record<NomDeFamille, FamilleChromatique>>;
+/** Une primitive : sa definition OKLCH, son hex derive, et si le gamut l'a rabattue. */
+export interface DefinitionDePrimitive {
+  readonly oklch: Oklch;
+  readonly hex: CouleurHex;
+  readonly rabattue: boolean;
+}
+/** Definition OKLCH d'un pas d'une famille chromatique. */
+export declare function definitionDuPas(famille: NomDeFamille, pas: PasDeRampe): Oklch;
+/** Les 85 primitives avec leur definition : ce que le nuancier du banc affiche. */
+export declare const definitionsDesPrimitives: {
+  readonly neutre: Readonly<Record<0 | 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950 | 150, DefinitionDePrimitive>>;
+  readonly bleu: Readonly<Record<50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950, DefinitionDePrimitive>>;
+  readonly azur: Readonly<Record<50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950, DefinitionDePrimitive>>;
+  readonly or: Readonly<Record<50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950, DefinitionDePrimitive>>;
+  readonly vert: Readonly<Record<50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950, DefinitionDePrimitive>>;
+  readonly ambre: Readonly<Record<50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950, DefinitionDePrimitive>>;
+  readonly rouge: Readonly<Record<50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950, DefinitionDePrimitive>>;
+  readonly serie: Readonly<Record<3 | 1 | 2 | 4 | 5 | 6, DefinitionDePrimitive>>;
+};
+export type NomDeRampe = keyof typeof definitionsDesPrimitives;
+/** Les primitives en hexadecimal : la forme que le theme et la feuille consomment. */
+export declare const primitives: {
+  readonly neutre: Readonly<Record<0 | 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950 | 150, `#${string}`>>;
+  readonly bleu: Readonly<Record<50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950, `#${string}`>>;
+  readonly azur: Readonly<Record<50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950, `#${string}`>>;
+  readonly or: Readonly<Record<50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950, `#${string}`>>;
+  readonly vert: Readonly<Record<50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950, `#${string}`>>;
+  readonly ambre: Readonly<Record<50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950, `#${string}`>>;
+  readonly rouge: Readonly<Record<50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950, `#${string}`>>;
+  readonly serie: Readonly<Record<3 | 1 | 2 | 4 | 5 | 6, `#${string}`>>;
+};
+/**
+ * Echelles non chromatiques. Elles ne changent pas entre le theme clair et le
+ * theme sombre : une distance ni une graisse ne dependent de la luminosite. Les
+ * ombres, elles, dependent du theme : elles vivent dans `theme.ts`.
+ */
+/**
+ * Pas de 4 px, plus trois demi-pas et le quart de pas `demi` (2 px).
+ *
+ * Les demi-pas (`1-5` = 6 px, `2-5` = 10 px, `3-5` = 14 px) sont ceux que les
+ * planches de Claude Design RENDENT (D21) : le padding de 14 px des champs, l'ecart
+ * de 6 px d'une pastille. Les arrondir a la grille de 4 decalerait tout de 2 px, et
+ * la garde de conformite (G1) le verrait. Une valeur hors echelle reste un defaut.
+ */
+export declare const espacement: {
+  readonly '0': "0";
+  readonly '1': "0.25rem";
+  readonly '2': "0.5rem";
+  readonly '3': "0.75rem";
+  readonly '4': "1rem";
+  readonly '5': "1.25rem";
+  readonly '6': "1.5rem";
+  readonly '8': "2rem";
+  readonly '10': "2.5rem";
+  readonly '12': "3rem";
+  readonly '16': "4rem";
+  readonly '20': "5rem";
+  readonly '24': "6rem";
+  readonly demi: "0.125rem";
+  readonly '1-5': "0.375rem";
+  readonly '2-5': "0.625rem";
+  readonly '3-5': "0.875rem";
+};
+/**
+ * Rayons. Correspondance ecrite (01 §5.2) : commande = `md`, carte = `lg`,
+ * surface flottante = `md`, dialogue = `lg`, badge = `sm`, case = `xs`,
+ * pastille et avatar = `pleine`. Les planches rendent 4 / 8 / 12 / pleine.
+ */
+export declare const rayon: {
+  readonly none: "0";
+  readonly xs: "0.125rem";
+  readonly sm: "0.25rem";
+  readonly md: "0.5rem";
+  readonly lg: "0.75rem";
+  readonly xl: "1rem";
+  readonly pleine: "9999px";
+};
+/** Cles de l'echelle typographique, de la plus petite a la plus grande. */
+export declare const CLES_DE_TAILLE: readonly ["2xs", "xs", "sm", "md", "lg", "xl", "2xl", "3xl", "4xl", "5xl", "6xl"];
+export type CleDeTaille = (typeof CLES_DE_TAILLE)[number];
+/**
+ * Typographie (D18, D19). Echelle alignee sur le rendu de Claude Design : onze
+ * tailles, chacune avec SON interligne en rem — deux composants qui posent la
+ * meme taille ont la meme ligne.
+ *
+ * ⚠️ `2xs` (11 px) est RESERVE aux micro-libelles en capitales (`micro-capitales`,
+ * `surtitre`) : c'est le plancher absolu du socle, un texte de 9 ou 10 px est
+ * refuse (ecart EA-32). `xs` (12 px) est le plancher d'un texte courant.
+ */
+export declare const typographie: {
+  readonly famille: {
+    readonly base: "'Inter Variable', 'Inter Repli', system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif";
+    readonly mono: "'JetBrains Mono Variable', 'JetBrains Mono Repli', ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, monospace";
+  };
+  readonly taille: {
+    readonly '2xs': "0.6875rem";
+    readonly xs: "0.75rem";
+    readonly sm: "0.875rem";
+    readonly md: "1rem";
+    readonly lg: "1.125rem";
+    readonly xl: "1.25rem";
+    readonly '2xl': "1.5rem";
+    readonly '3xl': "2rem";
+    readonly '4xl': "2.5rem";
+    readonly '5xl': "3rem";
+    readonly '6xl': "3.5rem";
+  };
+  readonly interligne: {
+    readonly '2xs': "0.875rem";
+    readonly xs: "1rem";
+    readonly sm: "1.25rem";
+    readonly md: "1.5rem";
+    readonly lg: "1.75rem";
+    readonly xl: "1.75rem";
+    readonly '2xl': "2rem";
+    readonly '3xl': "2.5rem";
+    readonly '4xl': "3rem";
+    readonly '5xl': "3.5rem";
+    readonly '6xl': "4rem";
+  };
+  readonly graisse: {
+    readonly normale: "400";
+    readonly moyenne: "500";
+    readonly semi: "600";
+    readonly grasse: "700";
+  };
+  /**
+   * Interlettrage des TEXTES. Les titres ont en plus une approche negative par
+   * taille, portee par leur style composite (`styles/_typographie.scss`) : elle
+   * n'est pas un reglage, elle suit la taille.
+   */
+  readonly interlettrage: {
+    readonly serre: "-0.01em";
+    readonly normal: "normal";
+    readonly large: "0.02em";
+    readonly capitales: "0.05em";
+    readonly etiquette: "0.04em";
+    readonly surtitre: "0.1em";
+  };
+  /**
+   * Approche des TITRES, par taille : negative, et d'autant plus serree que le corps
+   * grandit (DESIGN.md, echelle D18). Un jeton par taille employee par un titre :
+   * ecrite dans le partiel en litteral, elle echappait a la garde « aucun
+   * letter-spacing en dur » et a l'impression.
+   */
+  readonly approche: {
+    readonly lg: "-0.005em";
+    readonly xl: "-0.01em";
+    readonly '2xl': "-0.015em";
+    readonly '3xl': "-0.02em";
+    readonly '4xl': "-0.025em";
+    readonly '6xl': "-0.03em";
+  };
+  /**
+   * Deux contrats de chiffres (01 §4.4). `alignes` : tout ce qui s'aligne en
+   * colonne (montant, date, compteur, minuteur). `references` : tout ce qui se
+   * recopie ou se dicte (IBAN, code, telephone) — le zero y est barre.
+   */
+  readonly chiffres: {
+    readonly alignes: "tabular-nums lining-nums";
+    readonly references: "tabular-nums lining-nums slashed-zero";
+  };
+};
+/**
+ * Durees de transition (01 §6, D9) : la table est FERMEE. Au-dela de 250 ms une
+ * commande parait lente ; `lente` et `longue` sont reservees aux grandes surfaces
+ * (tiroir, feuille inferieure, entree de page). Ni `eclair` ni `ample` (D9, D24) :
+ * l'appui lit `rapide`, la feuille inferieure lit `lente` ou `longue`.
+ *
+ * ⚠️ Toute duree non nulle passe a ZERO sous mouvement reduit, et sous le gel
+ * d'une image (changement de theme ou de langue) : la feuille de jetons tranche,
+ * aucune feuille de composant n'ecrit `@media (prefers-reduced-motion)` autour
+ * d'une transition. Une duree ajoutee plus tard entre dans cette table ET dans le
+ * bloc de mise a zero — qui est engendre depuis elle.
+ *
+ * Le fondu d'une couche lit `normale` (D8) : il n'y a pas de reglage de fondu.
+ */
+export declare const duree: {
+  readonly instantane: "0ms";
+  readonly rapide: "120ms";
+  readonly normale: "200ms";
+  readonly lente: "320ms";
+  readonly longue: "480ms";
+};
+/**
+ * Distances d'entree (01 §6) : d'ou arrive ce qui apparait. Une entree est une
+ * opacite PLUS un deplacement, jamais une echelle (D9) : c'est le seul motif que
+ * le mouvement reduit sait eteindre sans rien casser — distance a zero, la couche
+ * apparait en place.
+ *
+ * - `court` : menu, popover, liste deroulante (4 px, a peine le temps de le voir) ;
+ * - `moyen` : message ephemere, banniere (8 px) ;
+ * - `long` : tiroir partiel, page (16 px).
+ */
+export declare const deplacement: {
+  readonly court: "0.25rem";
+  readonly moyen: "0.5rem";
+  readonly long: "1rem";
+};
+/**
+ * Cadences des boucles d'attente (01 §6, D24) : rotation de l'indicateur (`vive`),
+ * pulsation du squelette et va-et-vient de la progression (`normale`), respiration
+ * qui remplace le mouvement (`respiration`).
+ *
+ * ⚠️ **Hors de l'echelle des durees, et c'est le point.** `--st-duree-*` passe a
+ * zero sous mouvement reduit : un indicateur d'activite cable dessus se figerait,
+ * et l'ecran passerait pour bloque. Les cadences ne passent JAMAIS a zero ; les
+ * feuilles les lisent par `--st-anim-chargement` et `--st-anim-respiration`, deux
+ * reglages dont le repli est une cadence.
+ */
+export declare const cadence: {
+  readonly vive: "900ms";
+  readonly normale: "1400ms";
+  readonly respiration: "1600ms";
+};
+/**
+ * Plancher d'une cadence (01 §6, regle 4) : une application peut RALENTIR une
+ * boucle d'attente, jamais l'eteindre ni la rendre frenetique. Les indicateurs
+ * lisent `max(<reglage>, var(--st-cadence-min))` : un `0ms` pose a la racine est
+ * refuse, et une boucle sous 600 ms clignoterait plus qu'elle n'informe.
+ */
+export declare const cadenceMinimale = "600ms";
+export declare const courbe: {
+  readonly standard: "cubic-bezier(0.2, 0, 0, 1)";
+  readonly entrant: "cubic-bezier(0, 0, 0, 1)";
+  readonly sortant: "cubic-bezier(0.3, 0, 1, 1)";
+};
+/**
+ * Plans d'empilement, reduits a ce qui s'applique vraiment (01 §5.5). Le CDK
+ * empile menus, popovers, infobulles, tiroirs et dialogues par l'ORDRE du DOM dans
+ * son conteneur, qui lit `superposition` : un plan par surface ne pilotait rien.
+ * Un `z-index` ecrit a la main dans un composant est un defaut.
+ */
+export declare const plan: {
+  readonly base: "0";
+  readonly contenuEleve: "10";
+  readonly entete: "100";
+  readonly superposition: "300";
+  readonly notification: "600";
+  readonly evitement: "700";
+};
+/** Cible tactile minimale. Sous 44 px, l'echec de pointage devient courant. */
+export declare const cibleTactileMinimale = "44px";
+/**
+ * Cible de pointage minimale (WCAG 2.5.8, niveau AA). C'est un PLANCHER, pas un
+ * confort : la cible tactile reste la regle pour ce qui se touche.
+ */
+export declare const cibleMinimale = "24px";
+/**
+ * Epaisseurs de trait. `fine` separe, `moyenne` signale, `forte` designe (marqueur
+ * de selection de 3 px). `intermediaire` (1,5 px) est le filet des cases a cocher
+ * et `epaisse` (4 px) le connecteur du stepper, tous deux rendus par les planches
+ * (D21). `capillaire` est emise a part : 1 px, et un vrai pixel d'ecran (0,5 px) sur
+ * les dalles haute densite.
+ */
+export declare const epaisseur: {
+  readonly fine: "1px";
+  readonly intermediaire: "1.5px";
+  readonly moyenne: "2px";
+  readonly forte: "3px";
+  readonly epaisse: "4px";
+};
+/** Filet d'un pixel d'ecran : `1px`, `0.5px` a 2 dppx, `1px` sous contraste force et a l'impression. */
+export declare const epaisseurCapillaire: {
+  readonly base: "1px";
+  readonly hauteDensite: "0.5px";
+};
+/**
+ * Largeurs de mise en page (D2, D21). Deux mesures de lecture (`etroite`,
+ * `normale`, en `ch`), puis les largeurs d'objets reels : la page (90rem, le
+ * contenu de la planche 6), la navigation et son rail replie, la carte
+ * d'authentification (450 px, planche 8), les trois dialogues, le tiroir, le menu, la
+ * couche, trois largeurs de champ a cles ordonnees et la colonne de texte d'une ligne de reglage.
+ */
+export declare const largeur: {
+  readonly etroite: "45ch";
+  readonly normale: "70ch";
+  readonly page: "90rem";
+  readonly navigation: "16rem";
+  readonly rail: "4.5rem";
+  readonly 'carte-auth': "28.125rem";
+  readonly 'dialogue-sm': "24rem";
+  readonly 'dialogue-md': "32rem";
+  readonly 'dialogue-lg': "48rem";
+  readonly tiroir: "28rem";
+  readonly menu: "12rem";
+  readonly couche: "28rem";
+  readonly 'champ-sm': "8rem";
+  readonly 'champ-md': "12rem";
+  readonly 'champ-lg': "16rem";
+  readonly colonne: "18rem";
+};
+/**
+ * Hauteurs de commande (D4) : pas de `xs`, le plancher est 32 px au pointeur fin
+ * et 44 px au doigt. `--st-hauteur-commande-defaut` suit la densite.
+ */
+export declare const hauteurDeCommande: {
+  readonly sm: "2rem";
+  readonly md: "2.25rem";
+  readonly lg: "2.5rem";
+  readonly xl: "2.75rem";
+  readonly '2xl': "3.25rem";
+};
+/** Les trois densites (01 §5.6, D10, D29). `confortable` est le defaut, sans attribut. */
+export declare const MODES_DE_DENSITE: readonly ["confortable", "dense", "compacte"];
+export type ModeDeDensite = (typeof MODES_DE_DENSITE)[number];
+/**
+ * Variables de densite, par mode. Une densite est un MODE, pas quatre reglages :
+ * la hauteur de commande, la respiration des cellules, la taille du texte des
+ * listes, la case de calendrier et la hauteur de ligne de liste derivent ensemble.
+ * En compacte, le texte descend a 12 px et jamais moins (D10 amende).
+ */
+export declare const densite: Readonly<Record<ModeDeDensite, Readonly<Record<string, string>>>>;
+/**
+ * Focus a deux voies (01 §3.3) : anneau exterieur + lisere qui le detache d'un
+ * fond colore. Sous `prefers-contrast: more`, l'anneau passe a `forte` (3 px).
+ */
+export declare const focus: {
+  readonly epaisseur: "var(--st-epaisseur-moyenne)";
+  readonly decalage: "var(--st-epaisseur-moyenne)";
+  readonly lisere: "var(--st-epaisseur-moyenne)";
+};
+/**
+ * Calcul de contraste : WCAG 2.x (la norme opposable) et APCA (la perception).
+ * Il vit dans les jetons, et non dans les tests, parce qu'une SPA peut avoir a
+ * verifier une couleur fournie a l'execution (theme d'un client, statut colore
+ * par une donnee).
+ *
+ * WCAG decide ; APCA informe. Une paire peut tenir 4,5:1 et fatiguer l'oeil
+ * (texte fin gris sur gris clair) : le temoin APCA le signale sans faire echouer
+ * la garde, parce qu'APCA n'est pas une norme (WCAG 3 est un brouillon).
+ */
+export interface Rvb {
+  readonly r: number;
+  readonly g: number;
+  readonly b: number;
+}
+/** Couleur avec son opacite, entre 0 (transparente) et 1 (opaque). */
+export interface Rvba extends Rvb {
+  readonly a: number;
+}
+/**
+ * Lit `#rgb`, `#rrggbb`, `rgb(...)` et `rgba(...)` (les deux ecritures). Leve
+ * sur toute autre forme : une couleur illisible ne doit pas se transformer en
+ * noir par defaut.
+ */
+export declare function lireCouleur(texte: string): Rvba;
+/**
+ * Couleur OPAQUE, en composantes. Une couleur translucide leve : son contraste
+ * depend du fond sur lequel elle se pose, il faut d'abord la `composer()`.
+ */
+export declare function versRvb(couleur: string): Rvb;
+/**
+ * Pose une couleur (translucide ou non) sur un fond opaque, comme le moteur de
+ * rendu : `rgb(0 0 0 / 0.2)` sur `#ffffff` donne `#cccccc`. C'est ce qui rend
+ * mesurable une ombre, un voile ou un filet teinte.
+ */
+export declare function composer(premierPlan: string, fond: string): string;
+/** Luminance relative WCAG, entre 0 (noir) et 1 (blanc). */
+export declare function luminanceRelative(couleur: string | Rvb): number;
+/** Rapport de contraste, entre 1 et 21. L'ordre des arguments est indifferent. */
+export declare function rapportDeContraste(a: string | Rvb, b: string | Rvb): number;
+export type NiveauContraste = 'AA' | 'AAA';
+export type NatureDuTexte = 'courant' | 'grand' | 'composant';
+/**
+ * Seuils WCAG. `composant` couvre les bordures, icones et limites de champ :
+ * la norme 1.4.11 leur demande 3:1, pas 4.5:1.
+ */
+export declare function seuilExige(niveau: NiveauContraste, nature: NatureDuTexte): number;
+export declare function respecteLeContraste(premierPlan: string, arrierePlan: string, niveau?: NiveauContraste, nature?: NatureDuTexte): boolean;
+/**
+ * Contraste perceptuel APCA, en Lc. Le signe dit la polarite : positif pour un
+ * texte sombre sur fond clair, negatif pour un texte clair sur fond sombre.
+ * Reperes : 106,0 (noir sur blanc), -107,9 (blanc sur noir), 75,6 (`#1234b0` sur
+ * `#e9e4d0`). L'ORDRE des arguments compte, contrairement a WCAG.
+ *
+ * Seuils d'usage (01 §3.2, jamais bloquants) : 75 pour un texte courant, 60
+ * pour 18 px et plus, 15 pour un filet.
+ */
+export declare function apca(texte: string, fond: string): number;
+/**
+ * Niveau 2 — jetons semantiques. C'est le SEUL niveau que les composants
+ * consomment. Le nom dit le role, jamais la couleur : `danger` reste `danger`
+ * si la charte passe du rouge a l'orange.
+ *
+ * Noms, structure, derivation sombre et statuts : `docs/design-cible/01` §3.
+ * Valeurs CLAIRES : celles du rendu de Claude Design (decision D17, ADR 0005),
+ * bouton principal en systeme A (`primaire #003181`, survol `#1948a5`).
+ */
+export interface JetonsDeCouleur {
+  readonly fond: CouleurHex;
+  readonly surface: CouleurHex;
+  readonly surfaceElevee: CouleurHex;
+  readonly surfaceEnfoncee: CouleurHex;
+  readonly surfaceConteneurBas: CouleurHex;
+  readonly surfaceConteneurHaut: CouleurHex;
+  readonly surfaceSurvol: CouleurHex;
+  readonly surfaceSurvolElevee: CouleurHex;
+  readonly surfaceCouranteElevee: CouleurHex;
+  readonly surfaceActive: CouleurHex;
+  readonly surfaceSelection: CouleurHex;
+  readonly surfaceInverse: CouleurHex;
+  readonly surfaceMarque: CouleurHex;
+  readonly texte: CouleurHex;
+  readonly texteDiscret: CouleurHex;
+  readonly texteAttenue: CouleurHex;
+  readonly texteDesactive: CouleurHex;
+  readonly texteInverse: CouleurHex;
+  readonly textePrimaire: CouleurHex;
+  readonly texteSurMarque: CouleurHex;
+  readonly texteSurMarqueDiscret: CouleurHex;
+  readonly bordure: CouleurHex;
+  readonly bordureForte: CouleurHex;
+  readonly bordureSelection: CouleurHex;
+  readonly anneauFocus: CouleurHex;
+  readonly lisereFocus: CouleurHex;
+  readonly selection: CouleurHex;
+  readonly surSelection: CouleurHex;
+  readonly primaire: CouleurHex;
+  readonly primaireSurvol: CouleurHex;
+  readonly primaireActif: CouleurHex;
+  readonly surPrimaire: CouleurHex;
+  readonly primaireDiscret: CouleurHex;
+  readonly surPrimaireDiscret: CouleurHex;
+  readonly primaireAttenue: CouleurHex;
+  readonly surPrimaireAttenue: CouleurHex;
+  readonly accent: CouleurHex;
+  readonly accentSurvol: CouleurHex;
+  readonly surAccent: CouleurHex;
+  readonly accentDiscret: CouleurHex;
+  readonly surAccentDiscret: CouleurHex;
+  readonly information: CouleurHex;
+  readonly surInformation: CouleurHex;
+  readonly informationDiscret: CouleurHex;
+  readonly surInformationDiscret: CouleurHex;
+  readonly succes: CouleurHex;
+  readonly surSucces: CouleurHex;
+  readonly succesDiscret: CouleurHex;
+  readonly surSuccesDiscret: CouleurHex;
+  readonly avertissement: CouleurHex;
+  readonly surAvertissement: CouleurHex;
+  readonly avertissementDiscret: CouleurHex;
+  readonly surAvertissementDiscret: CouleurHex;
+  readonly danger: CouleurHex;
+  readonly dangerSurvol: CouleurHex;
+  readonly dangerActif: CouleurHex;
+  readonly surDanger: CouleurHex;
+  readonly dangerDiscret: CouleurHex;
+  readonly surDangerDiscret: CouleurHex;
+  readonly dangerDiscretCourant: CouleurHex;
+  readonly positif: CouleurHex;
+  readonly negatif: CouleurHex;
+}
+export type NomDeJeton = keyof JetonsDeCouleur;
+export type NomDeTheme = 'clair' | 'sombre';
+export declare const themeClair: JetonsDeCouleur;
+/**
+ * Derivation du sombre (01 §3.1, ecrite et testee) : les surfaces montent vers
+ * l'encre, le texte descend vers le clair, les accents passent au pas 300 (lisible
+ * sur encre a 9:1), les `*Discret` au pas 900 et leurs `sur*` au pas 100, le survol
+ * d'un accent s'eclaircit. Ne change pas : `bordureForte` (3:1 sur les deux).
+ */
+export declare const themeSombre: JetonsDeCouleur;
+export declare const themes: Readonly<Record<NomDeTheme, JetonsDeCouleur>>;
+/**
+ * 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
+ * aux yeux : le test verifie aussi que chaque couleur de premier plan est couverte.
+ * Aucun compte n'est ecrit nulle part : il se lit sur `pairesDeContraste.length`.
+ *
+ * ⚠️ La nature se declare selon l'USAGE le plus exigeant, jamais selon la vocation
+ * premiere de la couleur : `succes` est aussi du TEXTE (`st-inline-message`), il se
+ * mesure donc a 4,5:1 et non a 3:1 (audit de la vague 2, UX-7).
+ */
+export interface PaireDeContraste {
+  readonly premierPlan: NomDeJeton;
+  readonly arrierePlan: NomDeJeton;
+  readonly nature: NatureDuTexte;
+}
+export declare const pairesDeContraste: readonly PaireDeContraste[];
+/**
+ * Jetons volontairement HORS du controle de contraste, avec leur raison.
+ * Une exemption non ecrite est un oubli ; ecrite, elle se discute.
+ */
+export interface Exemption {
+  readonly jeton: NomDeJeton;
+  readonly raison: string;
+}
+export declare const exemptesDeContraste: readonly Exemption[];
+/**
+ * Paires qu'on pourrait croire permises et qui NE LE SONT PAS : elles echouent dans
+ * au moins un theme, et la regle d'usage est ecrite a la place. Le test verifie
+ * qu'elles echouent vraiment — une exclusion qui passe doit redevenir une paire.
+ */
+export interface PaireExclue {
+  readonly premierPlan: NomDeJeton;
+  readonly arrierePlan: NomDeJeton;
+  readonly raison: string;
+}
+export declare const pairesExclues: readonly PaireExclue[];
+/** Seuil de perceptibilite des jetons exemptes : ils n'ont pas de minimum
+ * normatif, mais un separateur invisible ne separe rien. */
+export declare const SEUIL_DE_PERCEPTIBILITE = 1.2;
+/**
+ * Ecarts de SURFACE qui doivent rester perceptibles (01 §3.4, remesure sur les
+ * valeurs du rendu). Les minimums suivent le rendu de D17 : `surfaceActive` sur
+ * `surfaceSurvol` vaut 1,11:1 en clair (#dde3ee sur #e9eefa), la ou `01` visait
+ * 1,25 ; l'enfonce se lit aussi par le curseur et la transition.
+ */
+export interface EcartDeSurface {
+  readonly devant: NomDeJeton;
+  readonly derriere: NomDeJeton;
+  readonly minimum: number;
+  readonly pourquoi: string;
+}
+export declare const ecartsDeSurface: readonly EcartDeSurface[];
+/**
+ * Focus a deux voies (01 §3.3) : sur chaque surface ou un focus peut se poser,
+ * l'anneau OU son lisere tient 3:1. Un anneau d'une seule couleur ne le peut pas
+ * (1,94:1 sur `primaire`) : le lisere est donc la regle PAR DEFAUT de `_focus.scss`.
+ */
+export declare const surfacesDuFocus: readonly NomDeJeton[];
+/** Les cinq couches d'elevation (01 §5.4), du papier pose au dialogue. */
+export declare const COUCHES: readonly ["repos", "survol", "surelevee", "flottante", "modale"];
+export type NomDeCouche = (typeof COUCHES)[number];
+/** Une couche d'ombre : sa geometrie, et sa couleur dans chaque theme. */
+export interface CoucheDOmbre {
+  readonly geometrie: string;
+  readonly couleur: Readonly<Record<NomDeTheme, string>>;
+}
+/**
+ * Ombres de couche : celles que les planches RENDENT (valeurs du rendu, D17).
+ * Repos, survol, surelevee et flottante sont les ombres noires a 5-10 % des
+ * planches 2 a 16 ; modale est l'ombre teintee d'encre de la planche 5, identique
+ * a `01` §5.4. Le seul modele sombre au pixel (planche 6.3) pose les MEMES ombres
+ * qu'en clair : en sombre, l'elevation se lit d'abord par la surface qui s'eclaircit
+ * et par le filet (01 P4), l'ombre ne fait que la confirmer.
+ */
+export declare const ombres: Readonly<Record<NomDeCouche, readonly CoucheDOmbre[]>>;
+/** Voile pose derriere un dialogue ou un tiroir (planche 5, 01 §5.4). */
+export declare const voile: Readonly<Record<NomDeTheme, string>>;
+/** Teinte des ombres internes des composants (ombre de defilement d'un tableau). */
+export declare const couleurDOmbre: Readonly<Record<NomDeTheme, string>>;
+/** L'ombre d'une couche, telle qu'un theme la rend. */
+export declare function ombreDuTheme(couche: NomDeCouche, theme: NomDeTheme): string;
+/**
+ * Pour chaque primitive employee par un theme, les jetons qui la lisent :
+ * `bleu.700 -> clair: bordureSelection, primaireSurvol`. ENGENDRE depuis les
+ * themes, et non ecrit a cote : le nuancier du banc l'affiche, et une valeur
+ * recopiee a la main finirait par mentir (la planche 11 en est la preuve).
+ */
+export declare function rolesDesPrimitives(): ReadonlyMap<string, readonly string[]>;
+/**
+ * Styles typographiques composites (01 §4.3, D5, D15, D18) : une composition
+ * GARANTIE de taille, interligne, graisse, interlettrage et chiffres. Deux titres
+ * de page, l'un dans une carte et l'autre dans un dialogue, ne peuvent plus
+ * diverger d'un demi-point.
+ *
+ * Une seule notation, `@include st.style('titre-2')` (D15), dans le partiel Sass
+ * ENGENDRE `styles/_typographie.scss`. Aucun nom Material 3 (`headline-sm`,
+ * `label-md`) : la correspondance avec les planches de Claude Design est ecrite
+ * 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.
+ */
+type Graisse = keyof typeof typographie.graisse;
+type Interlettrage = keyof typeof typographie.interlettrage;
+export interface StyleComposite {
+  readonly taille: CleDeTaille;
+  /**
+   * Interligne d'une autre cle que la taille : une EXCEPTION ecrite. La seule est
+   * `titre-4`, 18/24 (D18), la ou l'interligne de `lg` vaut 28.
+   */
+  readonly interligne?: CleDeTaille;
+  readonly graisse: Graisse;
+  /**
+   * Nom d'interlettrage du theme, ou `approche` : l'approche negative d'un titre, lue
+   * dans `typographie.approche` a la cle de sa TAILLE (jamais un litteral en em).
+   */
+  readonly interlettrage: Interlettrage | 'approche';
+  readonly chiffres?: keyof typeof typographie.chiffres;
+  readonly famille?: 'mono';
+  /** Micro-libelles en capitales : la casse fait partie de la forme. */
+  readonly capitales?: true;
+  readonly usage: string;
+}
+/** Les styles du socle. L'ordre est celui de la documentation. */
+export declare const stylesTypographiques: {
+  readonly corps: {
+    readonly taille: "md";
+    readonly graisse: "normale";
+    readonly interlettrage: "normal";
+    readonly usage: "texte courant";
+  };
+  readonly 'corps-petit': {
+    readonly taille: "sm";
+    readonly graisse: "normale";
+    readonly interlettrage: "normal";
+    readonly usage: "texte secondaire";
+  };
+  readonly 'corps-fort': {
+    readonly taille: "md";
+    readonly graisse: "semi";
+    readonly interlettrage: "normal";
+    readonly usage: "intitule de ligne, valeur secondaire (D5)";
+  };
+  readonly 'corps-grand': {
+    readonly taille: "lg";
+    readonly graisse: "normale";
+    readonly interlettrage: "normal";
+    readonly usage: "texte d introduction, mention juridique (18/28, DESIGN.md body-lg)";
+  };
+  readonly legende: {
+    readonly taille: "xs";
+    readonly graisse: "moyenne";
+    readonly interlettrage: "large";
+    readonly usage: "legende, etiquette de badge";
+  };
+  readonly libelle: {
+    readonly taille: "sm";
+    readonly graisse: "moyenne";
+    readonly interlettrage: "normal";
+    readonly usage: "libelle de champ, onglet (D18 : 14/500)";
+  };
+  readonly commande: {
+    readonly taille: "sm";
+    readonly graisse: "semi";
+    readonly interlettrage: "normal";
+    readonly usage: "libelle de bouton de 44 px (14/20 600, majorite des planches)";
+  };
+  readonly etiquette: {
+    readonly taille: "xs";
+    readonly graisse: "semi";
+    readonly interlettrage: "etiquette";
+    readonly usage: "en-tete de colonne, etiquette de statut (12/16 600, DESIGN.md label-md)";
+  };
+  readonly 'micro-capitales': {
+    readonly taille: "2xs";
+    readonly graisse: "semi";
+    readonly interlettrage: "capitales";
+    readonly capitales: true;
+    readonly usage: "en-tete de colonne, terme de liste, statut en capitales (seul lecteur de 2xs)";
+  };
+  readonly surtitre: {
+    readonly taille: "2xs";
+    readonly graisse: "semi";
+    readonly interlettrage: "surtitre";
+    readonly capitales: true;
+    readonly usage: "surtitre de page ou de section, en capitales espacees";
+  };
+  readonly 'titre-4': {
+    readonly taille: "lg";
+    readonly interligne: "md";
+    readonly graisse: "semi";
+    readonly interlettrage: "approche";
+    readonly usage: "intertitre, titre de dialogue et de carte (18/24)";
+  };
+  readonly 'titre-3': {
+    readonly taille: "xl";
+    readonly graisse: "semi";
+    readonly interlettrage: "approche";
+    readonly usage: "titre de section";
+  };
+  readonly 'titre-2': {
+    readonly taille: "2xl";
+    readonly graisse: "semi";
+    readonly interlettrage: "approche";
+    readonly usage: "titre de bloc majeur";
+  };
+  readonly 'titre-1': {
+    readonly taille: "3xl";
+    readonly graisse: "semi";
+    readonly interlettrage: "approche";
+    readonly usage: "titre de page (h1 de 32 px, D18)";
+  };
+  readonly affichage: {
+    readonly taille: "4xl";
+    readonly graisse: "semi";
+    readonly interlettrage: "approche";
+    readonly usage: "annonce, titre d ecran de marque";
+  };
+  readonly 'affichage-grand': {
+    readonly taille: "6xl";
+    readonly graisse: "semi";
+    readonly interlettrage: "approche";
+    readonly usage: "grand chiffre de tableau de bord (56/64, DESIGN.md display-lg)";
+  };
+  readonly 'chiffre-cle': {
+    readonly taille: "3xl";
+    readonly graisse: "semi";
+    readonly interlettrage: "approche";
+    readonly chiffres: "alignes";
+    readonly usage: "valeur de st-stat";
+  };
+  readonly montant: {
+    readonly taille: "md";
+    readonly graisse: "moyenne";
+    readonly interlettrage: "normal";
+    readonly chiffres: "alignes";
+    readonly usage: "st-money, cellule numerique";
+  };
+  readonly 'montant-hero': {
+    readonly taille: "4xl";
+    readonly graisse: "semi";
+    readonly interlettrage: "approche";
+    readonly chiffres: "alignes";
+    readonly usage: "solde de compte (40/48, planche 2)";
+  };
+  readonly reference: {
+    readonly taille: "sm";
+    readonly graisse: "normale";
+    readonly interlettrage: "large";
+    readonly chiffres: "references";
+    readonly famille: "mono";
+    readonly usage: "IBAN, identifiant, reference de virement";
+  };
+  readonly code: {
+    readonly taille: "sm";
+    readonly graisse: "normale";
+    readonly interlettrage: "normal";
+    readonly chiffres: "references";
+    readonly famille: "mono";
+    readonly usage: "st-code";
+  };
+};
+export type NomDeStyle = keyof typeof stylesTypographiques;
+/** La valeur (en em ou `normal`) de l'interlettrage d'un style, resolue dans l'echelle. */
+export declare function interlettrageDuStyle(nom: NomDeStyle): string;
+/** Les declarations d'un style, telles que le partiel les ecrit. */
+export declare function declarationsDuStyle(nom: NomDeStyle): readonly string[];
+/**
+ * Le partiel Sass `_typographie.scss`, ENGENDRE comme la feuille de jetons et
+ * garde par `pnpm tokens:css:check`. Un nom inconnu echoue a la COMPILATION
+ * (`@error`) : une faute de frappe ne laisse pas un titre sans style.
+ *
+ * ```scss
+ * @use '@starterlib/tokens/styles/typographie' as typo;
+ * h2 { @include typo.style('titre-2'); }
+ * ```
+ */
+export declare function partielDeTypographie(): string;
+/**
+ * Polices du socle (D19) : Inter Variable et JetBrains Mono Variable, AUTO-HEBERGEES
+ * (licence SIL OFL 1.1, fichiers copies depuis `@fontsource-variable/*` aux versions
+ * epinglees). Aucune adresse tierce : `font-src 'self'` suffit sous CSP stricte, et
+ * aucune adresse IP ne part chez un fournisseur de polices.
+ *
+ * La feuille `styles/polices.css` est ENGENDREE d'ici et livree a part : elle
+ * n'est importee par aucune autre feuille du socle. Le banc et la coquille la
+ * chargent par defaut ; une SPA l'ajoute par la recette `docs/recettes/police.md`.
+ *
+ * `font-display: optional` : la police n'est employee que si elle est deja la
+ * (cache, ou prechargee dans la fenetre de blocage d'une centaine de millisecondes) ;
+ * sinon le REPLI METRISE s'affiche et la page ne bouge plus. Le repli est une
+ * police locale dont les surcharges (`size-adjust`, `ascent-override`...) sont
+ * CALCULEES sur les metriques du fichier livre : meme hauteur de ligne, meme
+ * chasse moyenne, aucun decalage de mise en page. `tools/verifier-police.mjs`
+ * relit les fichiers et echoue si une metrique ci-dessous a derive.
+ */
+/** Metriques d'une police, en unites de sa grille (`unitesParEm`). */
+export interface MetriquesDePolice {
+  readonly unitesParEm: number;
+  readonly ascendante: number;
+  /** Positive : la profondeur sous la ligne de base. */
+  readonly descendante: number;
+  readonly interligneAjoute: number;
+  /**
+   * Chasse moyenne ponderee par la frequence des lettres d'un texte courant
+   * (espace compris), a la maniere de Capsize : c'est elle qui regle `size-adjust`.
+   */
+  readonly chasseMoyenne: number;
+}
+export interface FichierDePolice {
+  /** Nom du fichier sous `styles/polices/`. */
+  readonly fichier: string;
+  readonly unicodeRange: string;
+  /** Le seul fichier que le premier ecran peint : c'est lui qu'on precharge. */
+  readonly aPrecharger: boolean;
+}
+export interface PoliceDuSocle {
+  readonly famille: string;
+  readonly graisses: string;
+  readonly paquet: string;
+  readonly fichiers: readonly FichierDePolice[];
+  readonly metriques: MetriquesDePolice;
+  readonly repli: {
+    readonly famille: string;
+    /** Polices locales aux metriques IDENTIQUES entre elles (clones metriques). */
+    readonly locales: readonly string[];
+    readonly metriques: MetriquesDePolice;
+  };
+}
+export declare const policesDuSocle: readonly PoliceDuSocle[];
+/** Surcharges du repli, en pourcentage, arrondies au centieme. */
+export interface SurchargesDuRepli {
+  readonly sizeAdjust: string;
+  readonly ascentOverride: string;
+  readonly descentOverride: string;
+  readonly lineGapOverride: string;
+}
+/**
+ * Le calcul de Capsize : le repli est agrandi pour que sa chasse moyenne egale
+ * celle de la police, puis ses ascendante, descendante et interligne sont ramenes
+ * a ceux de la police, divises par ce meme agrandissement.
+ */
+export declare function surchargesDuRepli(police: PoliceDuSocle): SurchargesDuRepli;
+/** Les fichiers a precharger par l'hote, dans l'ordre. */
+export declare function fichiersAPrecharger(): readonly 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.
+ */
+export declare function feuilleDesPolices(): string;
+/**
+ * Niveau 3 — jetons de composant. Les quelques reglages qu'une application peut
+ * poser sans forker une feuille de style.
+ *
+ * ⚠️ **Un jeton de composant est une PROMESSE PUBLIQUE.** Il se tient aussi
+ * longtemps que le composant existe : le catalogue reste donc court (moins de
+ * quinze entrees, 01 §8 et D8), et chaque entree repond a un besoin reel —
+ * densite, identite de marque, rythme d'attente. Tout le reste passe par le
+ * niveau semantique, ou n'a pas a etre ouvert.
+ *
+ * ⚠️ **Ils ne sont PAS declares sur l'hote du composant, et c'est le coeur du
+ * mecanisme.** Une valeur declaree sur `:host` l'emporte sur celle qu'un ancetre
+ * herite : l'application poserait son reglage a la racine, et le composant
+ * continuerait d'afficher le sien. Les feuilles du socle les lisent donc au
+ * POINT D'USAGE, avec un repli :
+ *
+ * ```scss
+ * min-block-size: var(--st-commande-hauteur, var(--st-hauteur-commande-defaut));
+ * ```
+ *
+ * L'application, elle, les pose ou elle veut — a la racine, sur une zone, sur
+ * une instance :
+ *
+ * ```css
+ * .tableau-dense { --st-tableau-cellule-bloc: var(--st-espacement-1); }
+ * ```
+ *
+ * ⚠️ **Aucune couleur ici.** Une couleur se change au niveau semantique, sinon
+ * le meme bleu a deux sources de verite, et les paires de contraste verifiees ne
+ * garantissent plus rien. `--st-carte-fond` a ete retire pour cette raison (0.9).
+ *
+ * Une variable interne pilotee par une entree — `--st-icone-taille`,
+ * `--st-avatar-taille` — n'est pas un jeton de composant : elle est declaree sur
+ * l'hote, elle n'est pas dans ce catalogue, et elle peut changer sans preavis
+ * (liste : `variablesInternes`).
+ */
+export interface JetonDeComposant {
+  /** Nom complet de la propriete CSS, prefixe compris. */
+  readonly nom: string;
+  /** Ce que le socle emploie quand l'application ne pose rien. */
+  readonly repli: string;
+  /** A quoi il sert, et pour qui. */
+  readonly role: string;
+  /** Les composants qui le lisent (verifie par la garde des feuilles). */
+  readonly lecteurs: readonly string[];
+}
+export declare const jetonsDeComposant: readonly JetonDeComposant[];
+/**
+ * Contrats d'HOTE (D7, D16) : poses par un composant sur la page pour qu'une
+ * autre feuille les lise. Ils ne sont ni des jetons de la feuille, ni des
+ * reglages d'application.
+ */
+export declare const contratsDHote: readonly string[];
+/**
+ * Variables internes legitimes (D13) : declarees sur l'hote du composant qui les
+ * lit, pilotees par ses entrees, hors catalogue et sans promesse.
+ */
+export declare const variablesInternes: readonly string[];
+/** Vrai si la propriete fait partie du catalogue public. */
+export declare function estJetonDeComposant(nom: string): boolean;
+/**
+ * Les proprietes CSS personnalisees sont ENGENDREES depuis les jetons
+ * TypeScript, jamais ecrites a la main en parallele. Deux sources de verite
+ * pour une meme couleur finissent toujours par diverger ; ici la derive est
+ * impossible, et la CI verifie que le fichier livre correspond au code.
+ *
+ * ⚠️ **Une seule declaration par couleur**, en `light-dark(clair, sombre)`. Le
+ * theme ne recopie plus trente couleurs dans quatre blocs qui se battent a la
+ * specificite : il pose `color-scheme`, et chaque couleur se resout d'elle-meme
+ * la ou elle est EMPLOYEE. C'est ce qui rend possibles les ILOTS de theme : un
+ * conteneur `[data-theme='sombre']` dans une page claire rend ses descendants en
+ * sombre, avec les memes jetons (carte sombre de la planche 6.3).
+ * Plancher navigateur : `light-dark()` est Baseline 2024 (Chrome 123, Safari 17.5,
+ * Firefox 120) — voir `docs/matrice-compatibilite.md`.
+ */
+export declare const PREFIXE = "--st";
+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;
+/**
+ * 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
+ * qu'il est sous mouvement reduit : il consomme les jetons, la feuille tranche.
+ *
+ * ⚠️ **Les cadences n'y figurent pas, et c'est voulu** : une boucle d'attente
+ * figee ferait croire a un ecran bloque. Sous mouvement reduit, les indicateurs
+ * passent de la rotation a la respiration (une pulsation d'opacite), par le mixin
+ * `sous-mouvement-reduit` du partiel `ruptures`.
+ *
+ * `0rem` et non `0` : un deplacement se lit dans `calc(-1 * var(...))`, et un zero
+ * sans unite y deviendrait un nombre, que `translate` refuse.
+ */
+export declare const mouvementReduit: Readonly<Record<string, string>>;
+/**
+ * Gel d'une image (03 §2.6 d) : au changement de theme ou de langue, `StTheme` et
+ * `StLangue` posent `data-gel` sur `<html>` jusqu'au rendu suivant. Toutes les
+ * durees a zero : cent vingt millisecondes de boutons en retard sur un fond deja
+ * change se liraient comme un defaut. Aucun `!important`, aucun
+ * `* { transition: none }` : chaque transition lit les jetons, geler les jetons gele
+ * tout — et les boucles d'attente, sur leurs cadences, continuent.
+ */
+export declare const mouvementGele: Readonly<Record<string, string>>;
+/**
+ * `prefers-contrast: more` (01 §7.1) : chaque jeton prend la valeur d'un jeton plus
+ * contraste DU MEME THEME. Chaque niveau monte d'un cran, et la hierarchie reste :
+ * le texte attenue devient le texte discret, pas le texte.
+ *
+ * ⚠️ La valeur est ecrite en `light-dark()` et non en `var()` : des alias en chaine
+ * (`attenue -> discret -> texte`) se resolvent l'un par l'autre sur le meme element,
+ * et tout le texte finirait au niveau 1.
+ *
+ * Le creux (`surfaceEnfoncee`) ne bascule PAS vers la surface active, contrairement a
+ * `01` : un filet de champ y tombait a 2,93:1 (#7e848b sur #dde3ee). Le filet fort
+ * monte a la place au niveau du texte discret (7,29 et 5,10:1 sur la surface active).
+ */
+export declare const aliasDeContrasteRenforceParJeton: Readonly<Partial<Record<NomDeJeton, NomDeJeton>>>;
+/**
+ * Encres de statut FONCEES d'un pas sous `prefers-contrast: more`, par theme.
+ *
+ * ⚠️ Le survol y devient la surface active (`surfaceSurvol -> surfaceActive`), plus
+ * sombre en clair : `succes` y tombait a 4,37:1 et `avertissement` a 4,45:1, sous le
+ * seuil que le mode est cense renforcer (revue E2-E5, 103 paires parcourues a travers
+ * la table). Les encres du pas 700 — celles de l'impression — tiennent 5,98 et
+ * 6,49:1 ; le sombre garde ses valeurs, deja au-dessus.
+ */
+export declare const encresDeContrasteRenforce: Readonly<Partial<Record<NomDeJeton, Readonly<Record<NomDeTheme, string>>>>>;
+/**
+ * Le theme tel que `prefers-contrast: more` le rend : chaque alias resolu dans le
+ * theme, puis les encres foncees. C'est ce que les paires de contraste doivent tenir
+ * sous ce mode, et ce que la garde parcourt.
+ */
+export declare function themeSousContrasteRenforce(theme: NomDeTheme): JetonsDeCouleur;
+/** Les alias de `prefers-contrast: more`, tels que la feuille les ecrit. */
+export declare const aliasDeContrasteRenforce: Readonly<Record<string, string>>;
+/**
+ * `forced-colors: active` : les jetons dont la couleur systeme vaut dans TOUS leurs
+ * emplois (01 §7.2). Chromium GARDE une couleur systeme posee par l'auteur (il ne
+ * force que les autres) et peint une plaque `Canvas` derriere chaque texte : un
+ * alias est donc une decision, pas une documentation.
+ *
+ * ⚠️ **Aucun alias pour les encres posees sur un aplat** (`surPrimaire`, `surDanger`,
+ * `surSucces`...). Envoyees vers `Canvas`, elles rendaient le libelle du bouton
+ * primaire, du bouton danger et les chiffres d'une pastille INVISIBLES : texte
+ * `Canvas` sur la plaque `Canvas` (revue E2-E5, banc sous contraste force). Sans
+ * alias, le navigateur les force lui-meme (`CanvasText`, `ButtonText`), lisibles sur
+ * la plaque. Les aplats (`primaire`, `danger`...) gardent une couleur systeme de
+ * PREMIER PLAN : une barre de progression ou un point de statut, qui n'ont pas de
+ * texte, restent visibles sur `Canvas`.
+ *
+ * ⚠️ **`surfaceSelection` va vers `Canvas`, pas vers `Highlight`** : une ligne
+ * choisie (tableau, arbre, lien courant) garde son texte `CanvasText` ou `LinkText`,
+ * qui tombait sous 2:1 sur `Highlight`. La selection se lit par le filet
+ * `bordureSelection` (`Highlight`), par `aria-selected` et par la coche ; un
+ * composant qui veut l'aplat le pose lui-meme, en paire `Highlight`/`HighlightText`
+ * sous `forced-color-adjust: none` (jour choisi, segment, ligne d'arbre).
+ */
+export declare const couleursSysteme: Readonly<Record<string, readonly NomDeJeton[]>>;
+/**
+ * Les encres posees sur un aplat plein : jamais aliasees sous contraste force (voir
+ * `couleursSysteme`). Exportees pour que la garde le verifie.
+ */
+export declare const encresDAplat: readonly NomDeJeton[];
+/**
+ * Impression (01 §7.3) : le theme clair, avec des derogations d'ENCRE. Un filet a
+ * 1,4:1 disparait sur une imprimante laser ; un aplat de statut ne s'imprime pas,
+ * l'icone et le texte portent le statut. Une derogation d'encre ne peut que FONCER
+ * (clarte OKLCH inferieure ou egale a l'ecran) ; seuls les fonds passent au blanc.
+ */
+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>>;
+/**
+ * Feuille complete.
+ *
+ * Ordre et specificite : TOUTES les regles de theme et de derogation portent la
+ * meme specificite (0,1,0) — `:root` et `[data-theme…]` — et l'emportent par
+ * l'ORDRE. Plus aucune derogation ne se bat contre un selecteur de theme a
+ * (0,2,0) : il n'y en a plus.
+ *
+ * ⚠️ `color-scheme` suit le theme EFFECTIF, il n'est pas pose une fois pour
+ * toutes a `light dark` : ce dernier laisse le navigateur decider seul, si bien
+ * qu'un theme clair force sur un systeme sombre gardait des barres de
+ * defilement, des champs natifs et un remplissage automatique sombres.
+ */
+export declare function feuilleDeJetons(): string;
+/** Nombre de jetons de couleur semantiques : le compte vient du code, jamais d'une prose. */
+export declare function nombreDeJetonsDeCouleur(jetons?: JetonsDeCouleur): number;
+/**
+ * Les jetons au format du W3C Design Tokens Community Group (DTCG, « Design Tokens Format Module »,
+ * version stable 2025.10) : `styles/starter-tokens.tokens.json`, ENGENDRE comme la feuille CSS et
+ * garde par le meme `tools/generer-css.mjs --verifier` (lot 158). C'est la forme qu'un outil de
+ * design ou un autre moteur de rendu lit sans connaitre le TypeScript du socle.
+ *
+ * Ce qui part, et dans quel type DTCG :
+ *
+ * | Groupe                     | Source                         | `$type`      |
+ * | -------------------------- | ------------------------------ | ------------ |
+ * | `couleur.clair`, `.sombre` | `themeClair`, `themeSombre`    | `color`      |
+ * | `espacement`, `rayon`      | echelles                       | `dimension`  |
+ * | `taille`, `interligne`     | `typographie`                  | `dimension`  |
+ * | `graisse`                  | `typographie.graisse`          | `fontWeight` |
+ * | `police`                   | `typographie.famille`          | `fontFamily` |
+ * | `duree`                    | `duree`                        | `duration`   |
+ *
+ * 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;
+
+export {};