Tokens

Les tokens sont la source de vérité visuelle du design system. Toute couleur, taille, typo, ombre ou durée partagée vient de @sodinix/tokens.

Architecture en 3 couches

Les tokens sont empilés en trois couches. Chaque couche ne peut référencer que celle du dessous — c'est une règle d'étanchéité : un composant ne lit jamais une primitive directement.

Couche 1 — primitives

primitives.json — la palette brute, rangée sous une clé racine ax (→ variables préfixées --ax-*). Couleurs en oklch, échelles 50→950, plus une palette data-viz dédiée (--ax-dv-*).

--ax-color-brand-400      --ax-spacing-4      --ax-dv-cat-1
--ax-color-neutral-950    --ax-radius-md      --ax-font-size-lg

Couche 2 — sémantique

L'intention d'usage — la seule couche que les composants consomment.

--background   --primary   --muted-foreground   --border   --ring
--space-block  --radius-surface  --motion-ease-enter

Couche 3 — rôles

roles.typography.json — les rôles typographiques : chaque rôle compose une typo complète (famille, taille, graisse, interligne, interlettrage) et s'applique d'un coup via l'utilitaire text-role-h1, text-role-body-md…

Les rôles scopés à un composant restent possibles mais conditionnels — la surcharge multi-marque suffit dans la grande majorité des cas.

Documentation & validation

Chaque token porte un $description qui en explique l'intention. La référence complète est générée automatiquement, et une étape de CI vérifie la conformité, l'étanchéité des couches et la convention de nommage.

Génération

bun run build --filter=@sodinix/tokens

Sorties (packages/tokens/dist/) :

Thèmes

Le thème bascule via une classe sur un ancêtre — .dark pour le sombre, .hc pour le high-contrast (contrastes AAA) :

<html class="dark">
  <!-- les composants suivent automatiquement -->
</html>