tmj-90/design-system

Construire un design system systématique

Le skill brand décide de l'identité ; le skill frontend-design décide de l'apparence d'une surface. Ce pack décide comment structurer cette apparence pour qu'elle passe à l'échelle : une architecture à trois couches de tokens avec une source de vérité unique, des spécifications de composants couvrant chaque état, et des vérifications qui empêchent le retour de valeurs brutes. Chargez une référence quand vous avez besoin de profondeur :

Sujet	Référence
Couches, nommage, mode sombre, JSON DTCG, migration depuis des tokens plats	references/token-architecture.md
Variantes, tailles et matrices d'états pour bouton/input/carte/badge/alerte/dialogue/tableau	references/component-specs.md
Priorité des états, anneaux de focus, motifs erreur/chargement, ARIA par état	references/states-and-variants.md

L'architecture en un souffle

/* PRIMITIF — valeurs brutes, sans signification. Changent rarement. */
--blue-600: oklch(55% 0.2 264);
/* SÉMANTIQUE — objectif. La couture du thème : light/dark/brand ne surcharge que cette couche. */
--color-primary: var(--blue-600);
/* COMPOSANT — boutons par composant, référençant les tokens sémantiques. */
--button-bg: var(--color-primary);

Les composants consomment des tokens composants ou sémantiques — jamais un primitif, jamais une valeur littérale. Les thèmes (sombre, contraste élevé, une seconde marque) redirigent les tokens sémantiques et rien d'autre.

Source de vérité. Si le dépôt conserve les tokens au format JSON W3C DTCG (Design Tokens Community Group) — le format a atteint sa première version stable, 2025.10, en octobre 2025 — ces fichiers sont la source : les tokens portent $value et $type, les alias s'écrivent {color.blue.600}, et un outil de build (Style Dictionary ou l'équivalent du dépôt) génère les variables CSS, le thème Tailwind et les valeurs natives. Modifiez le JSON et regénérez ; ne modifiez jamais manuellement la sortie générée. Si le dépôt n'a que des propriétés CSS personnalisées, celles-ci sont la source. N'introduisez pas de seconde source.

Étapes

1. Lisez ce qui existe. search_lore pour les ADR du design system ; trouvez les fichiers de tokens (*.tokens.json, tokens/, theme.ts, blocs :root, config Tailwind), la commande de build qui génère les sorties, et deux composants frères. Étendez le système existant dans son idiome ; n'ajoutez jamais un système concurrent.
2. Auditez avant d'ajouter. Comptez les littéraux dans les styles des composants (commandes ci-dessous). Chaque fuite que vous touchez est soit remplacée par un token existant, soit justifie un nouveau token.
3. Placez chaque nouveau token dans sa couche. Primitif uniquement pour une valeur brute vraiment nouvelle ; sémantique pour un nouvel objectif (--color-surface-raised, --space-section) ; composant uniquement quand un composant doit diverger. Les noms décrivent l'objectif, pas l'apparence (--color-danger, pas --color-red). Primitifs de couleur en oklch (usage courant), type dans une échelle fluide clamp(), espacement sur une unité de base (4px ou 8px).
4. Thématisez à la couture sémantique. Le mode sombre et les autres thèmes surchargent les tokens sémantiques dans un seul bloc ([data-theme="dark"], .dark ou @media (prefers-color-scheme: dark), selon le dépôt) et définissent color-scheme pour que les contrôles natifs et les barres de défilement suivent. Un thème qui surcharge un token primitif ou composant signifie que la couture est au mauvais endroit.
5. Vérifiez le contraste par thème. Pour chaque paire sémantique avant-plan/arrière-plan réellement utilisée (texte sur surface, texte sur primaire, bordure sur surface, indicateur de focus sur surface), calculez le ratio de contraste WCAG dans chaque thème : 4.5:1 pour le texte courant, 3:1 pour le grand texte, les limites d'interface et les indicateurs de focus. La luminosité oklch n'est pas le ratio WCAG — calculez-le (un script, le vérificateur du dépôt, ou un test). Enregistrez le tableau.
6. Spécifiez les composants complètement. Variantes, tailles (hauteur explicite, padding, token de police), et la matrice d'états — défaut, survol, focus-visible, actif, désactivé, chargement, erreur, plus sélectionné/coché le cas échéant — avec l'ARIA que chaque état expose. Priorité quand plusieurs s'appliquent : désactivé > chargement > erreur > actif > focus > survol > défaut. Le focus est toujours visible (anneau :focus-visible avec --color-ring, jamais outline: none seul). Détails : les références.
7. Recommander un système pour un nouveau produit : raisonnez à partir du produit, pas d'un kit — (a) motif et densité (marketing, tableau de bord dense en données, flux transactionnel), (b) direction (déléguez à brand), (c) posture de la palette (rôles sémantiques incluant succès/avertissement/danger/info ; mode sombre uniquement si les utilisateurs en ont besoin), (d) objectifs d'accessibilité et de performance énoncés dès le départ. Produisez une brève justification ainsi que l'échafaudage des tokens et composants ; déléguez l'exécution visuelle à frontend-design.
8. Vérifiez et documentez. Regénérez les sorties de tokens si le dépôt les construit et confirmez que le diff correspond uniquement à ce que vous vouliez ; exécutez lint, type-check et tests ; exécutez les vérifications de fuites ; affichez les composants modifiés dans chaque thème via les tests de composants ou de captures d'écran du dépôt, là où ils existent. Enregistrez les preuves par critère d'acceptation avec le skill record-evidence (nombre de fuites avant/après, tableau de contraste), puis arrêtez-vous.

Vérifications de fuites

Exécutez sur les fichiers de composants et de styles modifiés (excluez les fichiers de tokens eux-mêmes) :

• couleurs brutes : grep -rEn '#[0-9a-fA-F]{3,8}\b|rgba?\(|hsla?\(|oklch\(' src/components
• tailles de police brutes : grep -rEn 'font-size:\s*[0-9.]+px' src/components
• primitifs référencés depuis les composants : grep -rEn 'var\(--(gray|blue|red|green)-[0-9]+' src/components
• valeurs arbitraires Tailwind là où des tokens existent : grep -rEn '\[(#|[0-9]+px)' src/components

Ajustez les chemins et les noms de primitifs au dépôt. De nouvelles correspondances dans votre diff sont des défauts que le constructeur doit corriger, sauf si la ligne est elle-même une définition de token ; un réviseur les liste comme (optionnel) sauf si l'un d'eux casse un critère d'acceptation ou le contraste d'un thème.

Terminé quand

Aucun nouveau littéral ou référence primitive dans les composants ; chaque thème ne surcharge que les tokens sémantiques ; le tableau de contraste passe dans chaque thème ; la matrice d'états de chaque composant touché est implémentée avec un focus visible ; les sorties générées correspondent à la source.

Capturez les connaissances

L'architecture de tokens d'un dépôt — la séparation des couches, la convention de nommage, la couture du mode sombre, ou une règle "ne jamais référencer un primitif dans un composant" — est exactement le fait dont le prochain agent a besoin avant de commencer. Ce genre de fait est une connaissance (lore). Capturez-le via le protocole de capture de connaissances dans votre brief (CLAUDE.factory.md, étape 11 "Memory contribution") : appelez le Memory MCP suggest_lore une fois à la fin de votre travail — conventions réutilisables, pièges, décisions et limites uniquement, jamais de trivia par ticket.