Synchronisation du système de design
Aperçu
Lorsqu'un système de design existe déjà dans le code, l'outil de conception doit le refléter, non le réinventer.
- Importer copie les jetons du code et les composants choisis par la personne dans l'outil, sous les mêmes noms.
- Exporter prend les modifications apportées au guide de l'outil et les ramène dans le code sous la forme d'un diff révisé.
Un petit fichier à la racine du projet, design-sync.json, mémorise ce qui a été synchronisé pour la dernière fois. Le code reste la source de vérité jusqu'à ce que la personne décide autrement : les modifications sont d'abord dessinées dans l'outil puis atterrissent dans le code via un export approuvé.
Quand l'utiliser
- Une tâche de conception va démarrer dans un projet dont le système de design est dans le code et sans guide dans l'outil.
craft-setupetcraftdélèguent à cette compétence. - « Importer / intégrer notre système de design (jetons, composants) dans Paper / Figma / l'outil de conception. »
- « Appliquer / pousser / synchroniser les modifications du guide vers le code. »
Quand NE PAS l'utiliser
- Pas de système de design dans le code :
craft-system(mode création). - Une révision, des options ou une petite modification dans un tel projet : ces compétences travaillent à partir du code tel qu'il est.
- Une valeur de jeton unique dictée par la personne (« mettre l'accent en #3d7f69 dans le code ») : modifiez-la directement, mettez à jour
design-sync.jsonpour ce nom, indiquez ce qu'elle affecte.
Avant de commencer
- Lisez
DESIGN.md(Brand indique où se trouve le système) etdesign-sync.jsons'ils existent. - Choisissez l'adaptateur de votre outil dans
references/adapters/(paper.md,figma.md,html.md). Si aucun adaptateur ne correspond à votre outil, faites les mêmes actions dans votre outil et dites lesquelles vous avez adaptées manuellement. Sans outil de conception du tout, construisez en HTML (html.md). Si vous n'avez qu'une image, dites que les valeurs lues sont des estimations.
design-sync.json
{
"source": "packages/ui/tokens.css",
"tool": "paper: fichier 'Fieldnote', page 'Guide'",
"naming": "Noms des propriétés CSS personnalisées tels qu'écrits dans la source",
"synced": "2026-11-15",
"tokens": { "--color-accent": "#2e6b57", "--radius-md": "10px" },
"components": { "Button": "dessiné", "Badge": "dessiné", "Input": "dans le code uniquement" }
}
tokenscontient les valeurs acceptées des deux côtés lors de la dernière synchronisation, et uniquement celles-ci.- L'import d'un composant modifie uniquement sa propre entrée
components.
Importer (code → outil de conception)
-
Détecter avec les signaux. Trouvez la source de vérité pour les valeurs (la source des jetons, pas une sortie générée) et la règle de nommage que l'outil utilisera. Deux packages UI → listez les deux et demandez lequel est la source.
-
Inventorier, puis s'arrêter. Utilisez le format d'inventaire :
- jetons par rôle, avec compteurs et chemins ;
- composants (groupés avec compteurs lorsqu'il y en a plus d'environ 15) ;
- documents de guide ;
- lacunes ;
- conflits : tout nom qui existe déjà dans l'outil avec une valeur différente, et tout type de jeton que l'outil ne peut pas contenir.
Demandez quels composants dessiner maintenant, en suggérant 3 à 6 pour les prochains écrans, et comment résoudre chaque conflit. Ne dessinez jamais tout par défaut.
-
Construire dans l'outil après les réponses :
- enregistrez les jetons sous la règle de nommage ; ne remplacez jamais une valeur d'outil que la personne n'a pas résolue ;
- créez une page de guide des fondations, avec les documents de guide comme légende ;
- créez un index des composants : nom, chemin du code, statut (
dessiné/dans le code uniquement), avec les variantes renseignées une fois dessinées ; - dessinez les composants choisis avec leur matrice d'états, en utilisant les valeurs du code. Un état que le code ne définit pas est dessiné et étiqueté « proposé ».
-
Auto-vérification. Rendez le guide. Si le code peut afficher le composant (Storybook, page de démonstration), comparez à la même taille. Sinon, dites que les valeurs ont été lues depuis le code, sans rendu.
-
Enregistrer :
- écrivez
design-sync.json(toutes les valeurs des jetons sont désormais égales des deux côtés, ainsi que les statuts des composants) ; - dans
DESIGN.md, Brand obtient « Source du système de design :<chemin>; le guide le reflète », et le journal des décisions reçoit une ligne d'import datée ; - s'il n'y a pas de
DESIGN.md, créez-en un dont la première ligne est<!-- enregistrement de synchronisation uniquement : exécutez craft-setup pour le brief -->avec juste Brand et le journal des décisions.crafttraite unDESIGN.mdsans section Produit comme manquant.
- écrivez
Import d'un composant unique (depuis craft)
La personne a déjà accepté de refléter le système, donc il n'y a pas d'arrêt d'inventaire :
- dessinez ce composant ;
- mettez son entrée
componentsàdessiné; - laissez
tokensinchangé.
Si l'outil n'a pas encore de guide, ou si la personne n'a jamais accepté un import (ou l'a refusé), demandez une fois : « Input existe uniquement dans le code. L'importer d'abord dans le guide ? »
Exporter (outil de conception → code)
-
Lire les valeurs du guide (adaptateur) et les valeurs du code, par nom.
-
Classer chaque nom avec
design-sync.jsonet le format de diff :- égales maintenant → en synchronisation ;
- guide modifié → proposer ;
- code modifié → proposer de rafraîchir le guide ;
- les deux modifiés → montrer les trois valeurs et demander laquelle l'emporte.
Sans
design-sync.json, listez chaque différence et demandez la direction pour chacune. -
Proposer les modifications des fichiers source (jamais une sortie générée) : fichier et ligne, ce que chacune affecte, et le contraste pour les couleurs. Les états « proposés » et les polices de substitution ne sont pas des modifications à exporter. S'arrêter.
-
Appliquer uniquement ce qui a été approuvé, mettez à jour le guide pour toute décision en faveur du code, et exécutez les vérifications du projet (lint, typage, tests, tests visuels), ou dites qu'il n'y en a pas.
-
Enregistrer :
- mettez à jour
design-sync.jsonavec les valeurs désormais égales des deux côtés ; - ajoutez une ligne datée au journal des décisions dans
DESIGN.md; - ajoutez les conflits ouverts aux questions ouvertes.
- mettez à jour
Règles
| Règle | Pourquoi |
|---|---|
| Mêmes noms dans le code et l'outil, selon une seule règle de nommage écrite | Un nom par décision ; pas de mappage qui dérive |
design-sync.json n'enregistre que les valeurs acceptées | Sans la dernière valeur acceptée, « qui l'a modifiée ? » est une supposition |
| Inventorier et choisir avant de dessiner ; conflits listés là | Les gros packages et les jetons existants de l'outil nécessitent l'avis de la personne |
| Valeurs issues du code, jamais de captures d'écran | Les captures d'écran arrondissent les couleurs et les tailles |
| États manquants dessinés comme « proposé » | Le guide ne doit pas prétendre que le code fait ce qu'il ne fait pas |
| Exporter propose, puis s'arrête ; modifie la source, pas la sortie générée | Le code est livré aux utilisateurs ; un fichier généré est écrasé par la prochaine compilation |
| Les deux modifiés → demander | Écraser l'un ou l'autre côté perd la décision de quelqu'un |
| Le code est la source de vérité jusqu'à ce que la personne dise autrement | Correspond à « le code l'emporte sur un brief obsolète » |
Terminé lorsque
- Import : inventaire et conflits résolus ; composants choisis dessinés ; guide rendu (ou « non rendu » précisé) ;
design-sync.jsonetDESIGN.mdécrits. - Un composant : dessiné, avec son statut mis à jour.
- Export : modifications approuvées appliquées, vérifications exécutées (ou « aucune » précisé),
design-sync.jsonmis à jour, conflits décidés ou ouverts.
Erreurs courantes
| Pensée | Réalité |
|---|---|
| « Le code a le système, donc la configuration n'a besoin que du brief » | Proposez l'import, sinon l'outil n'aura jamais de guide et les écrans dériveront du code. |
| « Je vais construire les fondations et un index, les composants plus tard » | Montrez l'inventaire et demandez quels composants dessiner maintenant. |
« Je vais renommer --sand-200 en un nom de rôle lors de l'import » | Gardez le nom du code ; proposez un rôle comme question ouverte. |
« L'outil a déjà --color-accent, je vais le mettre à jour » | C'est un conflit pour l'arrêt d'inventaire, pas une réécriture silencieuse. |
| « Le guide et le code diffèrent, donc le guide est obsolète » | Vérifiez design-sync.json : il peut s'agir d'une modification non exportée de la personne. |
| « Le diff est minuscule, je vais simplement l'appliquer » | Proposez, arrêtez-vous, puis appliquez et exécutez les vérifications du projet. |