joo6077/système-de-design

Pièges

1. Interdiction des valeurs concrètes dans les noms de tokens — blue-500, primary-blue ✗ → color.text.primary, color.background.brand ✓. Si la valeur change, le nom devient obsolète, ce qui fait immédiatement échouer le rebranding ou le passage en mode sombre.

2. Ne pas utiliser les primitives sans sémantique — Lier color.green.500 directement à un composant empêche le changement de thème. Il faut impérativement passer par les trois couches : primitive → sémantique (alias) → composant.

3. Ne pas intégrer le mode sombre dans le nom du token — color-dark-text-primary, color-light-surface ✗. Cela force le consommateur à être conditionnel au thème. La bonne pratique consiste à mapper des valeurs par mode sur un seul token sémantique.

4. Interdiction des valeurs arbitraires sans échelle — L’accumulation de valeurs arbitraires comme 10px, 14px, 18px, 22px pour l’espacement ou le rayon fait s’effondrer le système. Définissez d’abord une échelle finie (2/4/8/12/16/24/32) et rejetez toute valeur en dehors.

5. Ne pas réutiliser les tokens de composant comme s’ils étaient globaux — Utiliser button.primary.background dans un autre composant augmente le couplage. Ne promouvez en sémantique globale que ce qui est nécessaire à plusieurs composants.

6. La typographie doit être fournie en tokens groupés plutôt qu’en valeurs individuelles — Utiliser font-size-14 et line-height-20 séparément entraîne des erreurs de combinaison. Proposez d’abord des tokens de style sémantique groupant taille/poids/interlignage, comme font.body.medium.

7. La base d’espacement doit être documentée — Si vous n’utilisez pas la base 4px, documentez impérativement la justification. La cohérence de l’utilisation d’une échelle autorisée est plus importante que le nombre de base lui-même.

8. Règles de nommage DTCG — Ne pas utiliser { } . dans les noms de tokens ou de groupes ; ne pas commencer un nom par $ (le préfixe $ est réservé aux clés d’attributs comme $value et $type). La hiérarchie se crée par imbrication de groupes JSON. Le point . n’apparaît que dans les références pour relier les noms de groupes ({color.text.primary}), et n’est pas un caractère dans le nom lui-même. Source : DTCG Format Module 2025.10.

9. Interdiction de générer du code par pile — Cette compétence ne produit que des principes et des spécifications de tokens. Ne générez pas directement du code Flutter / React / CSS. Déléguez cela au plugin de l’outil correspondant.

10. Utilisation de l’héritage de groupes $extends (DTCG) — Le mot-clé $extends ajouté dans DTCG 2025.10 permet l’héritage par fusion profonde entre groupes. Ne répétez pas les mêmes valeurs primitives dans plusieurs groupes sémantiques ; créez un groupe commun et référencez-le avec $extends. Les références circulaires sont interdites et doivent être détectées par le parseur. Source : research-log §A.

11. Les exemples HTML :root CSS doivent correspondre aux fichiers existants du design-kit — Si à l’étape 4 vous incluez un extrait HTML pour spécifier les tokens, les valeurs --color-*: ...; dans :root doivent correspondre aux variables CSS des fichiers HTML existants dans design-kit/docs/ ou design-kit/templates/. Toute incohérence de valeur est le début d’une fragmentation du système et a été une cause réelle de rejet (AR-06). Lors de l’ajout de nouvelles variables, mettez à jour simultanément les fichiers existants ou spécifiez la raison de l’incohérence.

12. Recommandation OKLCH pour les primitives de couleur — Tailwind CSS v4 (annoncé le 22-01-2025, dernière version stable v4.3.3 au 16-07-2026) a changé sa palette par défaut de rgb à oklch, et shadcn/ui v4 a également migré de HSL à oklch(). OKLCH offre des rampes uniformes sur les axes de légèreté perceptive (L), chroma (C) et teinte (H), et permet d’exploiter le large gamut P3 pour dépasser les limites du sRGB. Lors de la définition des primitives, privilégiez la notation oklch(L% C H) et, si nécessaire pour les navigateurs anciens, ajoutez le hex sRGB en fallback. Support navigateur : Safari 16.4+, Chrome 111+, Firefox 128+ (identique à la couverture de Tailwind v4). Attention Figma : La documentation Figma liste les modèles de couleur Hex, HSB, HSL, CSS et RGB, mais pas OKLCH (About color models). Aucune phrase n’indique explicitement que Figma Variables ne peut pas gérer OKLCH, alors ne l’affirmez pas ; lors du transfert vers Figma, il est de coutume d’ajouter une approximation hex (comme dans Obra shadcn kit). Sources : Tailwind v4 blog, Tailwind v4.3.3, shadcn Tailwind v4, Evil Martians OKLCH, MDN oklch().

13. Enumerate-before-Act — Lister exhaustivement avant toute modification de tokens — Lors d’une demande d’amélioration d’un système existant (ex. « support du dark mode », « nettoie les tokens sémantiques »), avant toute édition, énumérez dans cet ordre : (1) liste complète des fichiers de tokens existants + nombre par catégorie, (2) répartition par niveau Tier 1 primitive / Tier 2 sémantique / Tier 3 composant, (3) catégories manquantes, violations de nommage, éléments non adaptés au dark mode — présentez-les sous forme de liste de violations, (4) après approbation de l’utilisateur, éditez. Évitez l’anti-pattern qui consiste à ne modifier qu’une partie et à dire « vous n’avez plus qu’à suivre » (insights-report #1 « Proactive quality gaps », skill-design-guide §5.5 Enumerate-before-Act).

14. Respect du schéma DTCG v1 — les alias sont des références entre accolades — Le Design Tokens Community Group a publié le 28-10-2025 le Design Tokens Format Module 2025.10 comme premier rapport stable « Final Community Group Report » (DTCG v1). Le format JSON utilise les préfixes $value, $type, $description ; les objets groupe (sans $value) peuvent définir une valeur $type par défaut pour le groupe. $extensions est réservé aux métadonnées des outils. $schema n’apparaît pas dans la liste des attributs de groupe du rapport final 2025.10 — si un outil l’utilise comme extension, mentionnez-le distinctement de la spécification DTCG.

    Notation des alias (point fréquent d’erreur) : La syntaxe de référence de la spécification est une chaîne entourée d’accolades {group.token}. La règle 8 interdit { } dans les noms de tokens car les accolades sont réservées pour envelopper les références — elles sont donc obligatoires dans la valeur de la référence. Les deux règles ne se contredisent pas. Une chaîne en notation point sans accolades ("color.background.surface") est interprétée comme une simple chaîne, pas comme une référence. Une référence entre accolades ne peut pointer que vers un token complet (objet avec $value). Pour référencer une propriété individuelle à l’intérieur d’une valeur de token, utilisez $ref au format JSON Pointer (RFC 6901) avec #/chemin/vers/cible.

    {
      "color": {
        "brand": { "$type": "color", "$value": { "colorSpace": "srgb", "components": [0, 0.4, 0.8], "hex": "#0066cc" } },
        "surface": { "$value": "{color.brand}" }
      }
    }
    

    Interdits : les clés value/type héritées (sans préfixe), tout préfixe $ personnalisé, les alias en notation point sans accolades. Une valeur de token de couleur doit être un objet avec colorSpace, components, éventuellement hex et alpha — la forme chaîne hexadécimale seule n’est pas dans la spécification. Les outils en aval comme Tokens Studio, Style Dictionary et zeroheight attendent ce format. Sources : Annonce W3C DTCG v1 du 28-10-2025, Rapport final W3C, DTCG Format Module (drafts), Tokens Studio DTCG vs Legacy.

15. Ne pas remplacer les couleurs existantes d’une application par une nouvelle palette (Visual Source of Truth Precedence) — Lors de l’introduction de tokens dans un projet qui a déjà un système de couleurs fonctionnel, ne créez pas une nouvelle palette « meilleure » basée sur la recherche. Extrayez d’abord exhaustivement les valeurs réellement utilisées et présentez-les, puis enveloppez ces valeurs dans des tokens comme solution de base. Modifier les valeurs elles-mêmes est une proposition distincte qui nécessite l’approbation de l’utilisateur. Si l’utilisateur a des maquettes validées dans le navigateur (enregistrées dans .design/approvals/), celles-ci priment sur la palette du projet — normaliser la valeur approuvée en une seule teinte ou un token d’accent existant est une régression. Tableau des priorités : ../../references/visual-change-protocol.md §1.

    Mauvais : "J’ai défini un token pour la couleur de fond" (sans lire le fond existant de l’app, création d’une nouvelle rampe neutre)
             → "La couleur de fond est encore bizarre, il doit bien y avoir des couleurs déjà utilisées non ?"
    Mauvais : accolé à un accent de maquette approuvée → remplacement par le token d’accent du projet → "Pourquoi utiliser une couleur différente ?"
    Bon : extraction exhaustive des valeurs existantes → présentées sous forme de tableau → "Je vais envelopper ces valeurs dans des tokens sémantiques. Faites-moi savoir si des ajustements sont nécessaires."
    

16. Une demande de modification partielle ne concerne que ce token — ne pas ajuster les valeurs environnantes simultanément — Pour une demande comme « assombrir juste cette bordure » ou « assombrir d’un cran seulement la surface », n’ajustez pas les autres tokens (fond, remplissage, texte, rayon, élévation) même pour préserver la cohérence de la rampe. Avant l’édition, laissez une liste modification / conservation. Après l’édition, vérifiez que les valeurs de la liste de conservation n’ont pas changé. Si un token non ciblé a changé, annulez et réappliquez uniquement le changement demandé. Pour un rollback partiel (ex. « la couleur est bonne, mais restaure juste le dégradé d’avant »), ne restaurez que l’axe spécifié. Détails : ../../references/visual-change-protocol.md §2.

17. Ne définir que les catégories de tokens demandées — interdiction d’étendre arbitrairement le scaffolding complet du système (réponse aux insights-report #1 mauvaise interprétation du périmètre, #3 sur-conception). Si l’on vous demande seulement « fais-moi une palette de couleurs » ou « définis une échelle d’espacement », définissez uniquement cette catégorie. N’ajoutez pas en une fois toute l’architecture (typographie, rayon, élévation, mouvement) sans qu’elle soit demandée. L’exigence d’un « système de tokens complet » (3 couches, contrainte sémantique dans les autres Gotchas) s’applique à l’intérieur de la catégorie demandée, et ne signifie pas une extension arbitraire des catégories elles-mêmes. En cas de doute sur le périmètre, ne devinez pas ; demandez en une ligne : « Je définis seulement les couleurs, ou je mets en place toute l’architecture des tokens ? ». Si vous estimez qu’une extension a de la valeur, ne l’incluez pas dans le livrable ; formulez-la comme une proposition séparée du type : « Je recommande aussi de mettre en place les tokens de typographie et d’espacement — on continue ? ». Il en va de même pour la construction complète des trois couches (primitive → sémantique → composant) : selon les recherches 2026, la plupart des équipes se contentent de deux couches (primitive + sémantique), et la couche composant n’est nécessaire que dans les entreprises de grande taille. Ne produisez pas trois couches par défaut sans justification de la demande ou de l’échelle. Sources : zeroheight Design Systems Report 2026 (deux couches sont la norme en pratique, trois couches complètes ne concernent qu’environ la moitié des équipes), material-design.md:281 (adoption progressive).

Processus

Étape 1 : Détection du système de design du projet

Parcourez la racine du projet à la recherche de fichiers de tokens/thèmes :

# Motifs de recherche (indépendants de la pile)
**/theme/**
**/tokens/**
**/design/**
**/styles/**
**/colors.*
**/typography.*

• Trouvé : HAS_DS=true, analyser la structure de tokens existante
• Non trouvé : HAS_DS=false, mode proposition d’un nouveau système de tokens

Étape 2 : Conception d’une architecture de tokens en 3 couches

Tous les tokens sont séparés en 3 couches. Ne sautez pas de couche.

Couche 1 — Primitive (référentiel de valeurs)
  Ex. : color.palette.green.500 = #22c55e
        space.scale.4 = 4px

Couche 2 — Sémantique (alias de rôle/intention)
  Ex. : color.text.success → {color.palette.green.500}
        color.background.surface → {color.palette.neutral.50}  (mode clair)
        color.background.surface → {color.palette.neutral.900} (mode sombre)

Couche 3 — Composant (surcharge d’exception pour un composant)
  Ex. : button.primary.background → {color.background.brand}
        card.border.radius → {radius.md}
  ※ Ne promouvoir en couche 2 que lorsque cela devient commun à plusieurs composants

Critères de nécessité/optionnalité par catégorie et exemples de noms sémantiques :

Catégorie	Obligatoire	Exemples sémantiques	Référence d’échelle
Couleur	Obligatoire	text.primary, text.secondary, text.disabled, background.surface, background.brand, border.default, border.subtle	—
Typographie	Obligatoire	font.display.lg, font.heading.md, font.body.sm, font.label.xs (taille+poids+interlignage groupés)	Échelle modulaire recommandée (1.125 Major Second à 1.618 Golden Ratio). Fluide : clamp(min, préférée, max)
Espacement	Obligatoire	space.xs(4), space.sm(8), space.md(16), space.lg(24), space.xl(32), space.2xl(48)	Base 4px. Espacement fluide : envisager une échelle continue basée sur clamp()
Rayon	Obligatoire	radius.none(0), radius.sm(4), radius.md(8), radius.lg(16), radius.full(9999)	Échelle finie
Élévation	Optionnel	elevation.level-0 ~ level-4 (valeurs d’ombre)	—
Mouvement	Optionnel	motion.duration.fast(100ms), motion.duration.normal(200ms), motion.easing.standard	—

Note — Material 3 Expressive (annoncé en mai 2025) : La documentation officielle de Material indique que M3 Expressive s’appuie sur 46 études et plus de 18 000 participants pour offrir une gamme de couleurs plus large, des couleurs dynamiques, une personnalisation et un système physique de mouvement basé sur des ressorts (spring). Créer une palette tonale (tonal palette) par couleur via HCT et assigner ces tons à des rôles de couleur (color role) n’est pas une fonctionnalité exclusive d’Expressive mais une description de l’ensemble du système de couleurs M3. Les polices variables comme Roboto Flex sont une option d’expression et ne font pas partie de l’échelle typographique M3. Faire correspondre les tons des palettes tonales aux primitives et les rôles de couleur aux alias sémantiques est une convention de ce dépôt pour sa structure en 3 couches, non une règle officielle. Sources : Start building with Material 3 Expressive, Color system, Typography, Motion (consulté le 28-09-2026).

Étape 3 : HAS_DS=true → Analyse du système existant

Comparez les tokens existants à l’architecture en 3 couches et produisez un rapport :

• Couche manquante : élément liant directement une primitive à un composant
• Violation de nommage : token dont le nom contient une valeur (blue-500, color-dark-*)
• Absence de mode sombre : token sémantique de couleur sans alias de mode
• Hors échelle : utilisation d’une valeur arbitraire en dehors de l’échelle autorisée
• Mauvais usage des tokens de composant : token de composant réutilisé dans un autre composant
• Problème de séparation typographique : lorsqu’on ne fournit que des tokens individuels pour taille/poids/interlignage

Étape 4 : HAS_DS=false → Génération de la spécification des tokens

Générez la spécification des tokens au format templates/design-tokens.md. Présentez à l’utilisateur les choix par catégorie dans cet ordre et obtenez un accord :

1. Palette de couleurs de marque (primitive) – valider
2. Tokens de couleur sémantique – inclure les deux mappings clair/sombre
3. Échelle d’espacement (base 4px par défaut, documenter la raison en cas de changement)
4. Tokens de style typographique groupés
5. Échelle de rayon
6. Élévation/mouvement (si nécessaire)

Étape 5 : Vérification des livrables

• Vérifier que toutes les catégories obligatoires sont séparées en 3 couches
• Vérifier que les tokens sémantiques sont définis comme des alias de primitives (pas de valeur directe ✗)
• Vérifier que les mappings clair/sombre existent pour chaque token sémantique de couleur
• Vérifier qu’aucune valeur arbitraire en dehors de l’échelle autorisée n’est présente
• Vérifier que les tokens de composant, s’ils existent, sont limités au périmètre de ce composant
• Vérification de la cohérence des variables CSS :root (Gotcha #11) — si le livrable inclut un extrait HTML :root, le confronter aux valeurs des fichiers HTML existants dans design-kit/docs/ et design-kit/templates/. En cas d’incohérence, mettre à jour les fichiers existants simultanément ou documenter la raison.
• Guide du pipeline Figma Variables → Tokens Studio → Style Dictionary v5 — Lors de la génération des spécifications, guidez l’utilisateur vers le pipeline suivant : Figma Variables (primitives + sémantiques) → export JSON DTCG par Tokens Studio → conversion par Style Dictionary v5 par plateforme → synchronisation Git. Recommandez l’activation de Code Syntax, l’utilisation du champ Description, et la limitation du périmètre (Scope). La version v5 nécessite Node.js 22 ou supérieur ; elle n’accepte plus les références pointant vers des valeurs non-token, les références suffixées par .value, ni les modifications de syntaxe de référence — ces trois points doivent être vérifiés en priorité lors de la migration depuis v4. La vulnérabilité de pollution du prototype des objets de sortie convertTokenData a été corrigée dans la v5.5.5 (20-09-2026) ; n’utilisez pas de version antérieure. Sources : research-log §I, Style Dictionary v5.0.0, v5.5.5, Migration v5.
• Guide de la typographie fluide — Lors de la définition des tokens de typographie, en plus des tailles fixes, proposez une échelle fluide basée sur clamp(min, préférée, max). Recommandez un rapport d’échelle modulaire (1.125 Major Second à 1.618 Golden Ratio) adapté au projet, et référencez l’approche Utopia (interpolation entre deux échelles pour petit/grand écran). Source : research-log §E.
• Guide de l’espacement fluide — Pour les tokens d’espacement, proposez en plus du fixe les options Fluide (clamp()) et Adaptatif (changement par point d’arrêt). Spécifiez la règle Interne ≤ Externe (marge interne de l’élément ≤ marge externe). Source : research-log §F.

Références

• references/token-principles.md — Détail des principes de conception de tokens
• templates/design-tokens.md — Format de sortie des spécifications de tokens
• ../../references/visual-change-protocol.md — Priorité visuelle, isolement des modifications partielles (SSOT)