Design Tokens dans Symfony : traiter votre charte graphique comme une donnée structurée

Chaque projet web accumule, au fil du temps, une dette visuelle silencieuse : des valeurs hexadécimales éparpillées dans quarante fichiers CSS, des surcharges Bootstrap bricolées, des modes sombres ajoutés à la va-vite avec des @media en cascade. Résultat : la moindre refonte devient un chantier à risque, et maintenir une cohérence graphique sur plusieurs applications tourne au cauchemar.

La réponse à ce problème existe depuis plusieurs années dans le monde du design system : les design tokens. Ce qui est plus récent, c'est leur intégration native côté PHP/Symfony, sans passer par Node.js. C'est précisément ce que propose le bundle open-source UI Kernel de Symfinity.

Le problème concret : pourquoi les valeurs « en dur » ne scalent pas

Imaginez un projet Symfony administrant plusieurs clients. Chaque client a sa couleur primaire, son échelle de typographie, ses arrondis. Sans abstraction, votre CSS ressemble vite à :

/* Client A */
.btn-primary { background: #1a73e8; }
/* Client B — ajouté 6 mois plus tard */
.btn-primary { background: #e63946; }

Le jour où un client change son identité visuelle, vous faites un grep -r dans le dépôt et priez pour n'avoir rien oublié. Le jour où vous ajoutez un mode sombre, vous doublez le volume de CSS à maintenir.

Les design tokens coupent ce nœud gordien : on nomme les intentions (--color-primary, --space-md, --radius-lg) et les composants référencent ces noms, jamais les valeurs brutes. Changer le token suffit à propager la modification partout.

OKLCH : pourquoi l'espace colorimétrique change la donne

L'article original insiste sur un point souvent négligé : tous les espaces colorimétriques ne se valent pas pour générer des palettes programmatiques.

• RGB / HSL sont simples à calculer, mais les variations de luminosité perçue sont incohérentes. Un jaune à 50 % de luminosité HSL paraît visuellement bien plus clair qu'un bleu à la même valeur.
• OKLCH (Oklab Lightness Chroma Hue) est un espace perceptuellement uniforme : un écart de 10 points sur l'axe L produit le même saut visuel, quelle que soit la teinte.

En pratique, cela signifie qu'on peut générer automatiquement une palette accessible (ratio de contraste WCAG valide) à partir d'une seule couleur de marque, sans ajustement manuel teinte par teinte. C'est exactement ce que fait UI Kernel : résoudre la palette en PHP, puis émettre les custom properties CSS correspondantes.

// Exemple conceptuel de résolution de token en PHP
$tokens = $kernel->resolve([
    'color-primary' => 'oklch(55% 0.2 250)',
]);
// Génère --color-primary, --color-primary-light, --color-primary-dark...

UI Kernel : l'infrastructure Symfony pour vos tokens

Le cœur du projet symfinity/ui-kernel repose sur une idée simple : les tokens sont de la donnée structurée, pas de la configuration CSS statique. Ils vivent en PHP, sont validés au boot du conteneur, et sont émis sous forme de CSS custom properties consommables par Twig et par vos feuilles de style de composants.

Ce que ça change concrètement

Résolution PHP, pas Node. Pas besoin de Webpack Encore, de Vite ou de pipeline npm pour que vos tokens soient disponibles. L'AssetMapper de Symfony suffit. Pour les équipes qui veulent rester « PHP-first », c'est un gain organisationnel significatif.

Validation au niveau du conteneur. Un token mal défini (mauvaise syntaxe OKLCH, référence circulaire) lève une exception à la compilation du container, pas en production devant l'utilisateur.

Thématisation multi-tenant propre. Chaque tenant peut surcharger un sous-ensemble de tokens via la configuration Symfony standard. La mécanique de cascade CSS custom properties fait le reste :

:root {
  --color-primary: oklch(55% 0.2 250); /* thème par défaut */
}
[data-theme="client-b"] {
  --color-primary: oklch(52% 0.28 15); /* surcharge tenant */
}

Intégration Twig. Les tokens sont accessibles dans les templates via des helpers Twig, ce qui permet de générer des attributs style inline ou des classes utilitaires sans sortir de l'écosystème Symfony.

Mode sombre sans dette

L'un des cas d'usage les plus convaincants est le mode sombre. Avec des tokens sémantiques (--color-surface, --color-text, --color-border), le mode sombre se réduit à une surcharge de tokens sous un sélecteur :

@media (prefers-color-scheme: dark) {
  :root {
    --color-surface: oklch(20% 0.01 250);
    --color-text:    oklch(92% 0.01 250);
  }
}

Pas de duplication de règles CSS. Pas de classes .dark:bg-gray-800 à ajouter sur chaque élément. Juste une redéfinition de la couche sémantique.

Quand adopter cette approche ?

Cette architecture est particulièrement pertinente pour :

• Les agences gérant plusieurs clients sur une base de code commune.
• Les éditeurs de logiciels PHP proposant un backoffice multi-tenant.
• Les projets long-terme où la cohérence graphique doit survivre à plusieurs générations de développeurs.

Elle l'est moins pour un site vitrine one-shot où la simplicité d'un fichier CSS monolithique reste un choix défendable.

Conclusion

Traiter votre charte graphique comme une donnée structurée plutôt que comme de la configuration CSS en dur, c'est appliquer aux interfaces les mêmes principes que ceux qu'on applique depuis des années aux données métier : typage, validation, centralisation, réutilisabilité.

UI Kernel ne révolutionne pas Symfony — il applique ses conventions (configuration, conteneur, AssetMapper) à un problème que la communauté PHP a trop longtemps traité comme secondaire. Le résultat : des refontes qui se mesurent en heures, des modes sombres qui ne cassent pas l'accessibilité, et une cohérence visuelle maintenable dans la durée.

📖 Article source : UI Kernel: Design Tokens as Symfony infrastructure — Wolf for Symfinity, dev.to