Design System Architect

Design System Architect

Tu construis un design system qui sert vraiment en production : le plus petit ensemble de primitives capable de composer tous les écrans du produit. Moins, mais mieux.

Quand l'utiliser

• Tu démarres un produit et tu veux une base propre avant le premier écran.
• L'UI existante a 14 gris, 6 tailles de bouton et des marges au pixel près : il faut consolider.
• Tu veux passer d'une maquette Figma à un système codé réutilisable.
• Tu dois ajouter un dark mode sans dupliquer le design.

Ce que le skill produit

1. Audit de l'existant : couleurs, tailles de texte, espacements et composants recensés, doublons signalés.
2. Tokens fondation : palette, échelle typographique fluide, espacements sur grille 4/8 px, rayons, ombres, durées d'animation.
3. Tokens sémantiques : bg, bg-elev, fg, fg-dim, accent, line, danger, etc., mappés par thème.
4. Primitives : Button, Input, Field, Text, Stack, Grid, Card, Modal, Toast, Menu, avec props, états et non-objectifs.
5. Patterns : tableau de données, formulaire multi-étapes, état vide, skeleton, en-tête de page, barre de filtres.
6. Gouvernance : propriétaire des tokens, changelog, versionnage semver, règle "pas de composant sans spec".

Méthode

1. Inventorie l'existant (ou les maquettes) et liste chaque valeur brute utilisée.
2. Regroupe les valeurs proches et réduis : vise 8 à 10 tailles de texte max, 10 à 12 pas d'espacement.
3. Définis les tokens fondation, puis la couche sémantique par thème (clair et sombre).
4. Vérifie les contrastes de chaque paire sémantique avant d'aller plus loin.
5. Spécifie les primitives : rôle, props, états, variantes (3 maximum), à faire / à ne pas faire.
6. Compose les patterns uniquement à partir des primitives. Si un pattern exige une nouvelle primitive, justifie-la.
7. Rédige les règles de gouvernance et la structure de fichiers, puis livre un plan de migration écran par écran.

Couches de tokens

• Fondation : valeurs brutes, jamais utilisées directement dans un composant. Ex. --blue-600, --space-4.
• Sémantique : intention, identique entre thèmes. Ex. --accent, --fg-dim, --bg-elev.
• Composant : optionnelle, pour les cas locaux. Ex. --button-bg, --card-radius.
• Règle : un composant ne lit que la couche juste au-dessus de lui. Jamais de saut vers la fondation.

Règles de conception

• Espacements : multiples de 4 px (4, 8, 12, 16, 24, 32, 48, 64, 96).
• Typo : échelle fluide en clamp(), corps de texte à 16 px minimum, interlignage 1.5 pour le texte courant, 1.1 à 1.2 pour les titres.
• Contraste WCAG AA : 4.5:1 pour le texte normal, 3:1 pour le texte large (24 px, ou 18.66 px gras) et les éléments d'interface.
• Cibles tactiles : 44 x 44 px minimum.
• Au-delà de 3 variantes, découpe le composant. 5 variantes, c'est un signal d'alarme.
• Chaque primitive documente ses états : default, hover, focus-visible, active, disabled, loading, error.
• Clair et sombre sont deux thèmes des mêmes tokens, jamais deux designs.

Structure de fichiers

src/
  styles/tokens.css        (fondation + sémantique, :root et [data-theme="dark"])
  components/ui/           (primitives)
  components/patterns/     (compositions)
  lib/cn.ts                (fusion de classes)
tailwind.config.ts         (lit les variables CSS)
docs/CHANGELOG.md

Checklist avant livraison

• Aucune couleur ou taille en dur dans les composants.
• Toutes les paires texte/fond passent AA en clair et en sombre.
• Chaque primitive a ses 7 états documentés et un focus visible.
• Aucune primitive ne dépasse 3 variantes.
• Les patterns n'utilisent que des primitives existantes.
• Changelog et numéro de version initialisés.
• Plan de migration priorisé livré.

À éviter

• Créer 40 composants avant d'avoir un seul écran réel à couvrir.
• Nommer les tokens par leur valeur (--blue, --gray-light) au lieu de leur rôle.
• Mettre de la logique métier dans une primitive (un UserButton n'est pas une primitive).
• Dessiner le dark mode à part au lieu de remapper la couche sémantique.
• Traiter l'accessibilité comme une relecture finale au lieu d'une contrainte de départ.

Exemple

Couche sémantique minimale, deux thèmes, mêmes noms :

:root {
  --bg: var(--neutral-0);
  --bg-elev: var(--neutral-50);
  --fg: var(--neutral-900);
  --fg-dim: var(--neutral-600);
  --line: var(--neutral-200);
  --accent: var(--blue-600);
}
[data-theme="dark"] {
  --bg: var(--neutral-950);
  --bg-elev: var(--neutral-900);
  --fg: var(--neutral-50);
  --fg-dim: var(--neutral-400);
  --line: var(--neutral-800);
  --accent: var(--blue-400);
}

Prompts de démarrage

• "Audite l'UI de ce repo et propose une couche de tokens sémantiques avec la liste des doublons à supprimer."
• "Crée la base d'un design system pour une app SaaS en Next.js + Tailwind, clair et sombre."
• "Spécifie les primitives Button, Input et Card : props, états, variantes et non-objectifs."
• "Refactore la page /settings pour n'utiliser que les primitives du design system."
• "Rédige les règles de gouvernance et le plan de migration de notre UI actuelle."