Jetons

Chaque jeton est une propriété personnalisée de :root nommée --phil-*, dans l'un de trois fichiers : css/tokens/dimensions.css, css/tokens/palette.css et css/tokens/colors.css, chacun dans sa couche. Le CSS est la source ; dist/tokens.json donne les mêmes jetons aux outils de conception, au format du Design Tokens Community Group — voir Les jetons en JSON.

Les échelles

Chaque échelle est calculée à partir d'une unité et d'un multiplicateur global : un site change une échelle entière d'un coup.

Les autres dimensions : --phil-leading-tight et --phil-leading-md, --phil-measure (65ch) et --phil-measure-narrow (36ch), les piles de polices --phil-font-sans, --phil-font-serif et --phil-font-mono — celles du système, rien de téléchargé —, --phil-focus-width et --phil-focus-offset, les durées --phil-duration-sm, -md, -lg et -loop, et les courbes --phil-ease-out et --phil-ease-in-out.

La palette

Sept teintes — neutral, brand, red, green, amber, blue, violet — de onze tons chacune, numérotés selon leur clarté OKLCH : --phil-brand-40 est oklch(0.40 …). Les neutres ajoutent 99, le presque blanc de la page.

Puisque le numéro est la clarté, la différence de deux numéros donne le contraste, quelles que soient les teintes :

Chaque chroma est propre à sa teinte, tenu dans la gamme sRGB à chaque clarté : un ton paraît le même sur chaque écran.

Les rôles de couleur

Les composants lisent des rôles, jamais la palette. Chaque rôle est light-dark(<light tone>, <dark tone>).

La grille

Six rôles — brand, neutral, danger (rouge), success (vert), warning (ambre), info (bleu) — ont chacun six couleurs : un remplissage, une bordure et la couleur sur ce remplissage, chacun discret (une teinte légère) ou fort (plein).

.isNotice {
    color: var(--phil-color-info-on-quiet);
    background: var(--phil-color-info-fill-quiet);
    border: 1px solid var(--phil-color-info-border-loud);
}

Les jetons en JSON

dist/tokens.json contient les jetons au format du W3C Design Tokens Community Group (2025.10), que lisent et écrivent les outils de conception. Il est produit à partir du CSS, qui reste la source, par la même commande que le fichier unique :

php bin/build.php    # from the package, after a change under css/

Les tests le comparent à un export des sources et échouent tant qu'il est périmé : l'intégration continue attrape un changement du CSS sans son JSON. Le paquet npm l'exporte en @phil/ux-css/tokens.json.

Chaque jeton porte, sous l'extension ca.ph-il.phil-ux, sa propriété personnalisée et son CSS tel qu'il est écrit, pour qu'un outil qui réécrit du CSS garde les formules :

"sm": {
    "$type": "dimension",
    "$value": {"value": 0.75, "unit": "rem"},
    "$extensions": {
        "ca.ph-il.phil-ux": {"property": "--phil-space-sm", "css": "calc(var(--phil-space-unit) * 0.75)"}
    }
}

Une valeur pour laquelle le format n'a pas de type est laissée de côté, et nommée dans l'extension du fichier : --phil-measure et --phil-measure-narrow, en ch, et --phil-mix-hover et --phil-mix-active, en pourcentage. calc() n'est calculé que là où il est une simple arithmétique d'une unité — +, -, *, /, parenthèses et var() —, dans des bornes sur sa longueur, ses morceaux et la profondeur de var() ; Token\DesignTokens fait l'export et Token\Calc l'arithmétique, pour un site qui exporte ses propres surcharges :

use Phil\UxCss\Token\DesignTokens;
use Phil\UxCss\Token\TokenSheet;

$sources = [...DesignTokens::sources('vendor/phil/ux-css/css'), 'assets/theme.css'];
$json = DesignTokens::fromSheet(TokenSheet::fromFiles(...$sources))->toJson();