Des design systems qui survivent au chaos client : tokens, variables et une passation sans surprises | Blanche

Les retours client en fin de projet ne sont pas un bug du process — c’est le process.

Si vous construisez des design systems pour des projets clients, vous connaissez le scénario : le système est impeccable à la semaine trois, puis la semaine sept débarque avec « juste un bouton spécial », une nouvelle landing page « qui ne peut pas ressembler au reste », et un exec qui veut que le hero fasse « plus premium ». D’un coup, votre bibliothèque de composants bien propre devient un musée d’exceptions.

Cet article est un playbook d’agence pratique pour construire des design systems qui survivent à plusieurs parties prenantes, plusieurs outils et des demandes de changement tardives — sans transformer votre codebase en cimetière d’overrides ponctuels.

Un design system, ce n’est pas ce que vous livrez. C’est ce que vous pouvez continuer à livrer quand le client change d’avis.

Pourquoi les projets clients cassent les design systems (et comment s’y préparer)

Le chaos client ne casse pas les systèmes parce que les clients sont déraisonnables. Il casse les systèmes parce que les agences livrent souvent des systèmes qui sont :

Centrés sur les assets (une librairie Figma) plutôt que centrés sur un contrat (des règles claires que la production applique)
Trop orientés composants avant que les fondations ne soient stables (tokens, échelle typographique, espacements)
Sous-documentés au moment précis où plus de monde a besoin de clarté (handoff + QA)
Sans gouvernance (pas de versioning, pas de circuit de revue, pas de « non ») donc les variantes se multiplient

La taxe du « cas spécial » est bien réelle

À chaque fois que vous acceptez un one-off sans décision au niveau du système, vous payez :

Dette design : les designers cessent de faire confiance à la librairie parce que la réalité diverge.
Dette engineering : les overrides s’accumulent ; les refactors deviennent risqués.
Dette client : le client apprend que « demander assez fort » crée de nouvelles variantes.

À retenir concrètement : traitez chaque demande comme :

Un changement de token (à l’échelle du système),
Une variante de composant (réutilisable), ou
Une exception spécifique à une page (timeboxée, documentée et volontairement isolée).

Si ce n’est pas l’un de ces trois cas, ce n’est pas une demande — c’est de l’ambiguïté.

Des fondations token-first (et les pièges fréquents)

Les tokens sont la seule abstraction qui survit de façon fiable aux frontières d’outils : Figma → CSS → Webflow → React/Vue → templates email → pages marketing.

Mais la plupart des équipes structurent les tokens d’une manière qui rend la traduction pénible. La solution : séparer ce qu’est une valeur de ce qu’elle signifie.

Utilisez un modèle de tokens à deux couches : primitive + sémantique

Les tokens primitifs sont la palette brute et les échelles.

color.blue.500: #2563EB
space.4: 16px
font.size.2: 14px

Les tokens sémantiques décrivent l’intention (et se mappent sur des primitifs).

color.text.default → color.neutral.900
color.bg.surface → color.neutral.0
color.border.subtle → color.neutral.200
space.section.paddingY → space.12

Pourquoi c’est crucial en contexte client :

Les clients changent les couleurs de marque. Si vous avez codé en dur « Primary Blue », vous refactorez des composants.
Les clients ajoutent un dark mode plus tard. Les tokens sémantiques permettent de changer les valeurs sans réécrire l’UI.
Plusieurs produits/marques sous une même maison client deviennent possibles sans dupliquer des librairies.

Si vos composants référencent directement des primitifs, vous n’avez pas un système — vous avez un thème.

Une structure de tokens qui se mappe proprement de Figma à la prod

Une taxonomie de tokens pragmatique qui marche bien en agence :

Couleur
- Primitifs : color.neutral.*, color.brand.*, color.red.*
- Sémantiques : color.text.*, color.bg.*, color.border.*, color.action.*, color.feedback.*
Typographie
- Primitifs : font.family.*, font.size.*, font.weight.*, lineHeight.*, letterSpacing.*
- Sémantiques (recommandé) : type.body.sm, type.body.md, type.heading.lg comme styles composés
Espacement + dimensions
- space.* pour marges/padding
- size.* pour dimensions fixes (avatars, icônes, conteneurs)
Rayon, ombre, motion
- radius.*, shadow.*, motion.duration.*, motion.easing.*

Pièges courants des tokens qui provoquent des régressions

Nommer les tokens d’après l’UI : color.buttonPrimary devient un piège quand la marque ajoute « secondary » et « tertiary ». Utilisez plutôt l’intention sémantique.
Pas de couche sémantique : les composants pointent vers des primitifs ; chaque évolution de marque déclenche des edits de composants.
Unités incohérentes : mélanger px, rem et des valeurs arbitraires casse la prédictibilité.
Trop de paliers : une échelle d’espacement à 24 niveaux semble « flexible » jusqu’à ce que personne ne sache choisir la bonne valeur.

À retenir concrètement : pour l’espacement, la plupart des systèmes d’agence s’en sortent très bien avec 8–12 paliers (par ex. base 4px avec quelques sauts plus grands). Assumez un parti pris.

Des outils qui rendent les workflows tokens réels

Figma Variables : à traiter comme source de vérité pour les tokens sémantiques.
Tokens Studio for Figma : utile quand vous avez besoin de pipelines d’export et de gestion multi-thèmes.
Style Dictionary (Amazon) : une méthode éprouvée pour compiler des tokens en sorties CSS/JS/JSON.

Si vous êtes sur des projets très Webflow, vous pouvez quand même garder la discipline token : les tokens deviennent des variables CSS dans une feuille de style globale et sont référencés via des classes utilitaires ou des styles de composants.

Variables CSS + contrats de composants (comment éviter les « cas spéciaux »)

Les tokens ne fonctionnent que si la production les impose. Votre couche d’application, ce sont les variables CSS et les contrats de composants.

Stratégie de variables CSS : des variables sémantiques à la périphérie

Un pattern simple :

Primitifs : --color-neutral-900, --space-4, --radius-2
Sémantiques : --text-default, --bg-surface, --border-subtle, --action-primary-bg

Ensuite, les composants n’utilisent que des variables sémantiques :

color: var(--text-default);
background: var(--bg-surface);
border-color: var(--border-subtle);

Quand le client veut un nouveau look « premium », vous ajustez les mappings sémantiques — pas 37 composants.

Contrats de composants : définir ce qui est autorisé

Un contrat de composant est un accord écrit et appliqué :

Props/inputs (variantes, tailles)
États (hover, focus, disabled, loading)
Exigences d’accessibilité
Règles d’usage des tokens (pas de hex brut, pas d’espacements ad hoc)

Exemple : contrat Button

Variantes : primary | secondary | ghost | destructive
Tailles : sm | md | lg
États : default | hover | active | focus-visible | disabled | loading
Règles :
- Le padding utilise --space-*
- Le border radius utilise --radius-*
- Le focus ring utilise --focus-ring-color et --focus-ring-width

À retenir concrètement : si une demande ne rentre pas dans le contrat, elle déclenche une décision système — pas un override rapide.

Tuer le « one-off » avec un cadre de décision

Quand quelqu’un demande un cas spécial, faites-le passer par ceci :

Est-ce un nouveau token sémantique ? (ex. nouvelle couleur de surface pour une campagne)
Est-ce une nouvelle variante ? (réutilisable à au moins 2–3 endroits)
Est-ce spécifique à une page et temporaire ? (override timeboxé avec date d’expiration explicite)

Si ce n’est aucun de ces cas, c’est probablement une préférence subjective. Recadrez avec des options :

« On peut obtenir ce ressenti en ajustant les surfaces sémantiques + la rampe typographique (à l’échelle du système). »
« On peut ajouter une variante ‘marketing’ pour ce composant, mais il faudra faire de la QA sur les breakpoints et les états. »
« On peut faire une exception de page, mais elle ne sera pas supportée dans les templates futurs. »

Votre job n’est pas de dire non. Votre job est de rendre les arbitrages explicites.

L’accessibilité fait partie du contrat, pas d’une QA de fin

Le chaos client se manifeste souvent par « rends-le plus clair » ou « rends-le plus subtil », ce qui peut détruire le contraste et les styles de focus.

Intégrez ceci dans les contrats :

Objectifs minimum de contraste (WCAG 2.2 AA par défaut)
Styles :focus-visible requis (ne jamais supprimer ; seulement restyler)
Minimum de zone cliquable (44px pour les cibles tactiles quand applicable)
Préférences de motion (prefers-reduced-motion)

Outils utiles :

Stark (Figma + navigateur)
axe DevTools
Lighthouse

Workflow de passation : docs, QA et ownership (la passation « sans surprises »)

Une bonne passation, ce n’est pas « voilà le Figma ». C’est une carte partagée des décisions.

La règle de passation en agence : livrer le système comme un produit

Traitez le design system comme un livrable avec :

Un numéro de version
Des release notes
Un changelog des mises à jour de tokens et des changements de composants
Un endroit unique où trouver la vérité (docs)

C’est comme ça que vous évitez que les threads Slack deviennent le système.

Quoi documenter (docs minimum viables du système)

Vous n’avez pas besoin d’un site de 200 pages. Vous avez besoin de clarté sur :

Fondations
- Listes de tokens (sémantiques + primitifs)
- Rampe typographique et recommandations d’usage
- Échelle d’espacement et règles de layout
Composants
- Variantes, états, et exemples do/don’t
- Notes d’accessibilité
- Règles de contenu (ex. libellés de boutons, empty states)
Patterns
- Formulaires, modales, navigation, tableaux
- Règles de comportement responsive

Outils de docs qui marchent bien dans la réalité agence :

Zeroheight (documentation de design system)
Notion (rapide, client-friendly)
Storybook (engineering-first, excellent pour les contrats)

Un workflow QA qui détecte les régressions avant le client

Une stack QA pragmatique :

Régression visuelle : Chromatic (Storybook) ou Percy
Tests au niveau composant : tests de composants Playwright (quand applicable)
Checks accessibilité : axe en CI sur les parcours clés
Checks responsive : breakpoints définis + checklist (pas « ça a l’air ok sur mon laptop »)

À retenir concrètement : définissez une page « golden path » qui inclut chaque état de composant qui compte. Quand les tokens changent, vous validez d’abord cette page.

Ownership : qui approuve quoi ?

En projet client, un ownership flou est la cause de la dérive des systèmes.

Définissez trois rôles :

System Owner (Agence) : décision finale sur les tokens et les contrats
Product Owner (Client) : priorise les demandes et accepte les arbitrages
Implementer (Dev lead) : impose l’usage des variables et bloque les valeurs ad hoc

Gouvernance : versioning, revues et quand dire « non » aux nouvelles variantes

La gouvernance paraît lourde jusqu’à ce que vous ayez livré votre troisième « secondary secondary button ».

Versionnez votre système comme un logiciel

Utilisez le semantic versioning pour le package du système (même si ce n’est pas littéralement un package npm) :

MAJOR : breaking changes (renommages de tokens, changements de contrat)
MINOR : nouveaux composants/variantes (rétrocompatibles)
PATCH : corrections (petits correctifs de style/accessibilité)

Publiez des release notes qui répondent à :

Qu’est-ce qui a changé ?
Pourquoi ?
Que doivent faire les équipes différemment ?

Un process de revue léger qui évite la prolifération de variantes

Adoptez un « Variant Gate » simple :

La demande inclut des captures + des cas d’usage
Prouver la réutilisabilité (où d’autre cela apparaîtra ?)
Vérifier l’adéquation tokens (peut-on résoudre via des tokens ?)
Revue accessibilité
Ajouter aux docs + à la matrice QA

Si ça ne passe pas le gate, ça devient :

Une exception de page (timeboxée), ou
Une demande rejetée avec une explication et une alternative.

Quand dire « non » (et quoi dire à la place)

Dites non quand :

Une variante ne résout que la préférence d’une seule page
Elle introduit des espacements/typos incohérents hors de l’échelle
Elle casse le contraste/le comportement de focus
Elle duplique une variante existante avec des micro-ajustements

Quoi dire :

« On peut obtenir ce résultat en ajustant les tokens sémantiques, ce qui garde le système cohérent. »
« Si on ajoute ça, il faudra le supporter sur les états, breakpoints et templates futurs. Est-ce que ça vaut le coup ? »
« Timeboxons ça comme une exception de campagne et on réévalue après performance/retours. »

Templates et checklists à copier

Utilisez-les comme artefacts internes d’agence. Ils sont conçus pour réduire l’ambiguïté et accélérer les décisions.

Template de définition de design token

Nom du token : color.text.default
Type : color
Description : texte principal sur surfaces par défaut
Mappe vers (light) : color.neutral.900
Mappe vers (dark) : color.neutral.50
Usage : body text, labels, headings
Ne pas utiliser pour : disabled text, placeholder text

Template de contrat de composant

Composant : Button
Objectif : actions primaires et secondaires
Variantes : primary / secondary / ghost / destructive
Tailles : sm / md / lg
États :
- default
- hover
- active
- focus-visible
- disabled
- loading
Règles de contenu :
- label max 24 caractères
- éviter la ponctuation
Accessibilité :
- focus ring requis
- zone cliquable min 44px
Règles tokens :
- pas de valeurs hex
- espacement depuis space.*

Checklist de passation sans surprises (agence → dev)

Tokens
- Tokens sémantiques définis pour text/bg/border/action/feedback
- Nommage des tokens cohérent et documenté
- Les Variables Figma correspondent aux noms de variables de prod (ou une table de mapping existe)
Composants
- Chaque composant a des variantes + états définis
- Exigences d’accessibilité listées
- Comportement responsive spécifié
Application en production
- Variables CSS implémentées globalement
- Linting/guardrails en place (quand possible)
- Pas de hex brut / d’espacements arbitraires dans le code des composants
QA
- Baseline de régression visuelle capturée
- Parcours clés testés avec axe/Lighthouse
- Page golden path créée pour une validation rapide
Gouvernance
- Numéro de version attribué
- Changelog démarré
- Owner + circuit d’approbation documentés

Checklist d’intake des demandes client (évite les « drive-by variants »)

Quel est l’objectif business ?
Où cela sera utilisé (URLs/écrans) ?
Est-ce un changement de token, une variante, ou une exception de page ?
Quelle est l’échéance et à quoi renonce-t-on ?
Est-ce que ça impacte l’accessibilité ?
Qui approuve le changement du système ?

Conclusion : construire des systèmes qui anticipent le changement — et restent cohérents malgré tout

Le travail client est chaotique parce que les entreprises sont chaotiques. La victoire, ce n’est pas d’éliminer le changement ; c’est de construire un design system capable d’absorber le changement sans perdre son intégrité.

Si vous voulez un système qui tient :

Démarrez token-first avec un modèle primitive + sémantique
Imposez les tokens en production avec des variables CSS
Définissez des contrats de composants qui rendent les exceptions explicites
Faites une passation sans surprises avec docs, QA et ownership
Gouvernez les demandes avec versioning et un variant gate — et habituez-vous à dire « pas comme ça »

Si vous voulez, partagez votre stack actuelle (Figma + Webflow ? React + Storybook ? mixte ?) et les patterns de demandes client que vous voyez le plus souvent. Je peux adapter un schéma de tokens, une convention de nommage des variables et un workflow de gouvernance qui colle à votre modèle de delivery.