Communitygithub.com

craft-sync

Utiliser lorsqu'une tâche de conception va démarrer dans un projet dont le système de design vit déjà dans le code (package UI, jetons de design, bibliothèque de composants) mais pas dans l'outil de conception, lorsqu'on vous demande d'importer ou d'intégrer le système de design, les jetons ou les composants dans l'outil de conception, ou d'appliquer, pousser ou synchroniser les modifications du guide de l'outil vers le code.

Qu'est-ce que craft-sync ?

Cette compétence synchronise un système de design existant dans le code avec un outil de conception (Paper, Figma, HTML), en évitant de le réinventer. Elle propose deux flux : **Importer** (code → outil) pour copier les jetons et les composants sélectionnés sous les mêmes noms, et **Exporter** (outil → code) pour transformer les modifications du guide en une proposition de diff validée. Le fichier `design-sync.json` sert de référence partagée des valeurs acceptées, garantissant que le code reste la source de vérité jusqu’à validation contraire. Idéale pour les projets disposant d’un système de design codifié, elle gère les conflits de noms, propose des états « proposés » pour les variantes manquantes, et exécute les vérifications du projet avant d’appliquer les changements. Ne pas utiliser en l’absence de système de design dans le code ou pour de simples modifications ponctuelles.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/diego3g/craft/tree/HEAD/skills/craft-sync

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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-setup et craft dé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.json pour ce nom, indiquez ce qu'elle affecte.

Avant de commencer

  1. Lisez DESIGN.md (Brand indique où se trouve le système) et design-sync.json s'ils existent.
  2. 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" }
}
  • tokens contient 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)

  1. 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.

  2. 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.

  3. 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é ».
  4. 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.

  5. 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. craft traite un DESIGN.md sans section Produit comme manquant.

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 tokens inchangé.

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)

  1. Lire les valeurs du guide (adaptateur) et les valeurs du code, par nom.

  2. Classer chaque nom avec design-sync.json et 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.

  3. 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.

  4. 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.

  5. Enregistrer :

    • mettez à jour design-sync.json avec 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.

Règles

RèglePourquoi
Mêmes noms dans le code et l'outil, selon une seule règle de nommage écriteUn nom par décision ; pas de mappage qui dérive
design-sync.json n'enregistre que les valeurs acceptéesSans 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'écranLes 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éeLe 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 autrementCorrespond à « 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.json et DESIGN.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.json mis à jour, conflits décidés ou ouverts.

Erreurs courantes

PenséeRé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.

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

Skills associés