Design tokens avec Tailwind CSS v4

Le problème que ça résout

Avant Tailwind v4, la palette de couleurs vivait dans `tailwind.config.js`, sous forme d’objet JS (`theme.extend.colors`). Ça fonctionnait, mais dès qu’il fallait gérer un dark mode avec des teintes différentes, ou réutiliser une couleur en dehors de Tailwind (dans du CSS custom, un canvas, un composant tiers), la même valeur finissait dupliquée à plusieurs endroits.

Ce qui change avec `@theme`

Tailwind v4 déplace la configuration du JS vers le CSS. Les tokens deviennent de vraies custom properties, déclarées directement dans le fichier de styles :

@theme inline {
  --color-primary: oklch(0.55 0.18 250);
  --color-primary-foreground: oklch(0.98 0 0);
  --radius-md: 0.5rem;
}

L’intérêt, c’est que `--color-primary` devient une vraie variable CSS accessible partout : dans une classe Tailwind (`bg-primary`), dans du CSS écrit à la main, ou même en JS via `getComputedStyle`. Une seule source de vérité au lieu de trois.

Le vrai avantage : le thème sombre

Là où ça devient intéressant, c’est pour gérer clair/sombre proprement. Plutôt que de dupliquer chaque classe avec un préfixe `dark:`, on redéfinit les mêmes variables dans un bloc `.dark` :

:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
}

Le composant qui utilise `bg-background text-foreground` n’a besoin d’aucune logique conditionnelle : il suit la variable, et la variable change selon la classe posée sur `<html>`. Sur un projet avec beaucoup de composants, ça évite d’écrire `dark:` sur chaque élément coloré.

Un piège à connaître

Un token mal nommé, ou avec une valeur de chroma trop poussée (en OKLCH, la teinte peut vite devenir criarde), se propage instantanément partout où il est utilisé — contrairement à une classe Tailwind isolée qu’on corrige à un seul endroit. Mieux vaut tester les valeurs en clair et en sombre avant de les committer, plutôt que de les découvrir cassées trois écrans plus loin.