Des tokens Figma au code : les brancher dans Tailwind CSS v4 avec @theme

Le chaînon manquant entre design et code

Dans un précédent article, on a vu comment structurer ses design tokens dans Figma : des valeurs brutes (les primitives) et des noms qui décrivent leur usage (les tokens sémantiques). Reste la question que tout le monde se pose ensuite : comment ces tokens arrivent-ils dans le code ?

Avec Tailwind CSS v4, la réponse est devenue beaucoup plus simple. Fini le fichier tailwind.config.js : la configuration se fait directement en CSS, avec des variables. Exactement le format dans lequel on pense déjà ses tokens.

1. Déclarer ses tokens dans @theme

/* app/globals.css */
@import "tailwindcss";

@theme {
	--color-primary: #6b21a8;
	--color-primary-hover: #581c87;

	--font-display: "Satoshi", sans-serif;

	--radius-card: 1rem;
	--shadow-card: 0 8px 24px rgb(0 0 0 / 0.08);
}

Ces quatre lignes génèrent directement des classes utilisables dans le HTML :

<article class="rounded-card shadow-card">
	<h2 class="font-display text-primary">Mon projet</h2>
	<a class="bg-primary hover:bg-primary-hover" href="/projets">Voir</a>
</article>

Le préfixe de la variable détermine le type de classes créées. Les plus utiles :

2. Faire correspondre les noms Figma et les noms CSS

C'est là que la rigueur côté Figma paie. Si tes variables Figma s'appellent color/primary et radius/card, leur traduction en CSS est mécanique : on remplace les / par des -, et on ajoute le préfixe attendu par Tailwind.

Pour les gros design systems, un plugin Figma d'export de variables (comme Tokens Studio) permet de générer un fichier JSON ou CSS, puis de l'intégrer automatiquement. Pour un site vitrine ou un portfolio, une copie manuelle soignée reste souvent plus simple.

3. Gérer le mode sombre avec @theme inline

Dans Figma, un mode sombre se gère avec les modes d'une collection de variables : un même token color/background vaut blanc en mode clair et presque noir en mode sombre. On reproduit exactement cette logique en CSS.

On déclare d'abord des variables CSS classiques, qui changent selon le mode :

:root {
	--background: #ffffff;
	--foreground: #171717;
	--primary: #6b21a8;
}

.dark {
	--background: #0a0a0a;
	--foreground: #ededed;
	--primary: #c084fc;
}

Puis on les expose à Tailwind avec @theme inline :

@theme inline {
	--color-background: var(--background);
	--color-foreground: var(--foreground);
	--color-primary: var(--primary);
}

Le mot-clé inline est important : il indique à Tailwind d'utiliser directement var(--primary) dans les classes générées, au lieu de figer la valeur. Résultat, bg-primary change de couleur tout seul quand on passe en mode sombre. Aucune classe dark: à ajouter dans le HTML.

C'est d'ailleurs le principe utilisé sur ce portfolio, avec une petite variante : les variables changent dans un bloc @media (prefers-color-scheme: dark) plutôt que sur une classe .dark. Le site suit ainsi automatiquement le réglage du système du visiteur.

4. Repartir d'une palette propre

Par défaut, Tailwind fournit une palette complète (red-500, slate-200...). Si ton design system définit ses propres couleurs, ces classes par défaut deviennent un piège : un développeur pressé utilisera bg-purple-700 au lieu de bg-primary, et la cohérence disparaît.

On peut retirer toutes les couleurs par défaut d'une seule ligne :

@theme {
	--color-*: initial;

	--color-primary: #6b21a8;
	--color-neutral-100: #f5f5f5;
	--color-neutral-900: #171717;
}

Seules tes couleurs restent disponibles. L'autocomplétion de l'éditeur ne propose plus que les tokens du design system : c'est le meilleur garde-fou possible.

En résumé

Les tokens définis dans Figma deviennent la source unique de vérité, du premier écran de maquette jusqu'à la dernière classe CSS. Et quand la couleur principale change, on modifie une seule ligne.