ADR-018 — Migration des références sémantiques vers la notation Radix

Date : 2026-05-29 Statut : ✅ Actif Décideurs : Design System Lead Type: token Chemin logique: decisions/ADR-018-migration-references-primitives-radix.md Lecture avant: AGENTS.md, DESIGN.md, .claude/rules/tokens-system.md Relations: tokens/semantic.json, tokens/primitives.json, site/build.js, decisions/ADR-008-radix-colors.md, decisions/ADR-017-correction-contraste-text-disabled.md

Contexte

ADR-017 documentait une incohérence structurelle entre tokens/semantic.json et tokens/primitives.json comme hors scope. Cet ADR la résout.

L'incohérence

tokens/semantic.json utilisait une notation Tailwind-like pour référencer les primitives :

"primary": { "value": "{color.blue.700}" }

Mais tokens/primitives.json expose les couleurs sous un chemin Radix incompatible :

primitive.color.blue.11  (pas color.blue.700)

Les références dans semantic.json ne se résolvaient donc dans aucun token resolver standard (Style Dictionary, Tokens Studio). site/build.js contournait ce problème en hardcodant toutes les valeurs résolues dans un objet SEM.

Les trois cas sans équivalent Radix

En établissant la table de correspondance, trois valeurs n'ont pas d'équivalent exact dans l'échelle Radix gray (steps 1–12) :

Décision

1. Ajout d'une palette neutral dans primitives.json

Ajout de trois entrées sous primitive.color.neutral :

Ces trois valeurs sont les seules qui ne peuvent pas être directement référencées depuis l'échelle gray Radix existante. Toutes les autres valeurs neutres utilisées dans semantic.json résolvent vers des steps gray Radix exacts.

2. Migration de semantic.json — notation {primitive.color.X.Y}

Toutes les références couleur de semantic.json migrent vers la notation Radix :

Aucune valeur résolue ne change — la migration est purement structurelle.

3. Correction du commentaire dans site/build.js

Le commentaire décrivant la notation Tailwind-like est mis à jour pour refléter la notation Radix. Les valeurs hardcodées dans l'objet SEM restent inchangées (résolution dynamique hors scope — voir section *Alternatives rejetées*).

Hors scope — tokens non-couleur

semantic.json contient aussi des références non-couleur ({space.4}, {fontSize.md}, {radius.sm}, etc.) qui ne se résolvent pas dans primitives.json (lequel ne contient que des couleurs). Ces références constituent une seconde incohérence structurelle, distincte de l'incohérence Tailwind/Radix.

Elles ne sont pas traitées dans cet ADR :

• Elles n'ont pas d'impact sur l'accessibilité ou la conformité
• Leur correction nécessite d'ajouter des primitives d'espacement, typographie et rayon
• Un ADR dédié (ADR-019) est à créer si le projet évolue vers une résolution dynamique

Alternatives rejetées

Conséquences

Aucun changement visuel — toutes les valeurs résolues restent identiques.

Pour les token resolvers (Style Dictionary, Tokens Studio) :

• Les références {primitive.color.X.Y} se résolvent maintenant correctement
• Le pipeline de compilation tokens peut être activé sans modification manuelle

Pour les agents IA :

• Un agent lisant semantic.json peut tracer chaque token jusqu'à sa valeur primitive

via une référence non ambiguë

• Plus de dépendance à un mapping implicite Tailwind→Radix

Dette technique restante :

• site/build.js hardcode toujours les valeurs résolues dans l'objet SEM
• Les tokens non-couleur dans semantic.json référencent des primitives inexistantes
• Ces deux points sont documentés mais non bloquants pour le fonctionnement actuel du site

Table de correspondance complète Tailwind→Radix

Pour référence, la table complète des équivalences utilisées dans ce projet :