Tableau d'états Figma
Un tableau d'états est une section Figma qui dispose tous les états possibles d'une fonctionnalité sur un seul canvas. Les groupes sont répartis par appareil, onglet ou sujet. Chaque carte comporte "ID · nom", "déclencheur ; résultat" et un écran produit. Le dernier groupe, Vérification des lacunes (en zh-TW : 缺漏檢查), liste les états que le prototype n'a pas encore mais que la fonctionnalité devrait avoir. Les concepteurs, développeurs, QA et chefs de produit l'utilisent tous comme leur liste de référence commune des états.
Le code du projet est généralement un prototype construit avec des données factices, non connecté à un véritable backend. Par conséquent, ne séparez pas les états en "implémenté / pas encore implémenté". Posez une seule question : le prototype construit-il cet état ? Les cartes n'ont que trois balises :
- Prototype (en zh-TW : 原型) : le prototype a cette branche. Dessinez l'écran réel ; pas d'étiquette de balise
- Dans les specs (en zh-TW : 規格有寫) : mentionné dans les critères d'acceptation, les spécifications, les maquettes ou les traductions i18n inutilisées, mais le prototype ne le construit pas. Va dans la vérification des lacunes
- Suggéré (en zh-TW : 建議補) : ni les spécifications ni le prototype ne le mentionnent ; déduit de preuves dans le code ou du type de fonctionnalité. Va dans la vérification des lacunes
Fonctionne pour n'importe quelle stack et n'importe quel produit. board-format.md est la source de vérité pour les spécifications du tableau.
Langue. Rédigez la matrice, les noms des cartes, les descriptions, le texte des wireframes et le rapport dans la langue de l'utilisateur. Les libellés fixes du tableau (balises, vérification des lacunes, résumé de couverture, en-têtes de wireframes, noms des calques) proviennent de BOARD.lang : 'zh-TW' lorsque l'utilisateur travaille en chinois traditionnel, 'en' sinon. Les autres langues conservent les libellés en anglais avec le texte des cartes dans la langue de l'utilisateur.
Cette compétence gère le flux global, le tableau et l'audit. Les autres tâches sont déléguées à d'autres compétences dans le même plugin :
| Tâche | Utiliser | Quand |
|---|---|---|
| Garde d'échelle | scale-guard.md | Lire avant l'étape 1 |
| Liaison à un système de design | figma-library-binding | Confirmer à l'étape 1, utiliser à l'étape 5 |
| Inventaire des états, trouver les lacunes | state-discovery | Étape 2 |
| Reconstruire les écrans depuis le code | code-to-figma | Étape 5, sur la Route B |
Les fichiers propres à cette compétence :
- board-format.md : disposition du tableau, tailles de police, balises et règles d'ID des cartes. Lire avant de dessiner quoi que ce soit
- board-skeleton.js : construit le squelette du tableau et les wireframes de lacunes à partir de la matrice. Utilisé à l'étape 4
- screenshot-slots.js : ajuste les captures d'écran de navigateur téléchargées dans les cartes. Utilisé à l'étape 5 sur la Route C
- audit.js : audit du tableau. Utilisé à l'étape 6
Si le projet a sa propre compétence de règles d'interface utilisateur (par exemple, la compétence de directives d'interface utilisateur du projet), suivez-la pour les jetons, la dénomination et l'acceptation des écrans produits.
Étapes
1. Confirmer les entrées
Demandez tout ce qui manque :
- Source du code : dépôt, branche, point d'entrée de la fonctionnalité (route, page, écran ou composant)
- Source des règles : critères d'acceptation Jira, PRD, Confluence, documentation des codes d'erreur. S'il n'y en a pas, écrivez "Aucun" ; la vérification des lacunes aura plus de cartes
- Cible : fichier et page Figma ; une nouvelle section, ou une mise à jour d'un tableau d'états existant. Pour les tableaux d'entraînement, ou les tableaux à partager avec d'autres, utilisez le fichier d'entraînement partagé de l'équipe (règles dans board-format.md "Fichier d'entraînement partagé"). Si la cible est un fichier existant, demandez également à l'utilisateur de signaler son utilisation mémoire actuelle (scale-guard.md)
- Dimensions : selon quels axes les états varient (largeur de l'appareil, état de connexion, rôle, onglet, volume de données, séquence d'interaction…), et la largeur de la fenêtre d'affichage pour chaque appareil
- Source des écrans produits : composants dans le fichier cible ou une bibliothèque, ou un prototype en cours / serveur de développement. S'il n'y en a pas, vous ne pouvez dessiner que des wireframes ; dites-le clairement
- Bibliothèque du système de design : à quelles bibliothèques les écrans produits doivent être liés (figma-library-binding). Si aucune, écrivez "Aucune"
Dès que vous avez le lien Figma, faites deux choses d'abord. N'attendez pas que l'inventaire soit terminé pour découvrir que vous ne pouvez pas dessiner dans le fichier :
- Confirmer l'accès en lecture et écriture :
create_session, puis exécutez unuse_figmaen lecture seule (lister les pages et les nœuds de premier niveau). Si cela signale "impossible d'accéder au fichier demandé", utilisezwhoamipour voir quel compte est connecté au MCP, et donnez deux options à l'utilisateur : partager le fichier avec ce compte avec les droits d'édition, ou se connecter avec un compte ayant accès dans les paramètres du connecteur (après changement, les fichiers du compte d'origine ne peuvent pas être ouverts) - Estimer le budget d'appels : suivez scale-guard.md "Budget d'appels MCP" pour estimer le nombre d'appels nécessaires pour cette exécution, et comparez-le avec les sièges du plan du fichier cible dans
whoami. Si ce n'est pas suffisant, dites-le d'abord et laissez l'utilisateur choisir : Route C (captures d'écran du navigateur dans les cartes, environ 3 appels pour l'ensemble du tableau ; étape 5), diviser en lots, changer de fichier, ou faire moins de comparaisons
Terminé quand : les six éléments ont une valeur claire, ou l'utilisateur a explicitement dit qu'ils ne s'appliquent pas ; le fichier cible est lisible ; le budget d'appels est suffisant, ou l'utilisateur a choisi comment diviser le travail.
2. Inventorier les états et construire la matrice d'états
Construisez la matrice avec state-discovery. Attribuez les ID des cartes à l'avance, en suivant les règles de board-format.md.
Ne dessinez pas tant que l'utilisateur n'a pas confirmé la matrice. La répartition des groupes, les cartes à fusionner et les cartes Suggérées à conserver sont toutes décidées à cette étape ; les modifier après le dessin coûte beaucoup plus cher. S'il y a plus de 150 cartes Prototype, suivez scale-guard.md et demandez à l'utilisateur de décider s'il faut fusionner des cartes, diviser des pages ou diviser des fichiers. Ne dessinez pas tant qu'ils n'ont pas décidé.
3. Préparer les données pour chaque carte
- Prototype : reproduisez-le avec des données factices fixes ou une histoire Storybook. Ajoutez les données manquantes dans le calque factice ; n'ajoutez pas de branches aux composants juste pour les captures d'écran.
- Dans les specs, Suggéré : le prototype n'a pas d'écran, donc aucune donnée n'est nécessaire ; dessinez un wireframe. Pour les cartes Dans les specs, écrivez dans le wireframe ce que la spécification exige et où cela est indiqué.
Terminé quand : chaque carte Prototype a des données reproductibles, ou est clairement marquée "Illustratif dans Figma uniquement".
4. Construire le squelette du tableau
Chargez d'abord les deux compétences du plugin Figma, figma-use et figma-generate-design (dans Claude Code : figma:figma-use / figma:figma-generate-design ; sans le plugin Figma, utilisez get_figma_skill pour lire skill://figma/figma-use/SKILL.md et ainsi de suite, avec un préfixe resource: dans skillNames).
Si la cible est un fichier existant, demandez à l'utilisateur d'enregistrer une version avant d'écrire. La même chose s'applique avant de supprimer ou de reconstruire des cartes que vous avez construites vous-même. Si la page cible ne contient rien d'autre que ce que vous avez construit (un tout nouveau fichier, une page vierge), vous pouvez ignorer la sauvegarde ; dites-le dans le rapport.
Pour un nouveau tableau d'états, utilisez board-skeleton.js : remplissez la matrice confirmée à l'étape 2 dans BOARD en haut, et collez l'intégralité du script dans un seul appel use_figma. En suivant board-format.md, il construit la section (nommée "-<Fonctionnalité>", placée à droite du contenu existant sur la page) → titre du tableau, sous-titre, résumé de la couverture (calculé automatiquement) → groupes → Scénarios → cartes. Le dernier groupe est la vérification des lacunes, avec ses wireframes dessinés. Les écrans des cartes Prototype commencent comme des emplacements réservés avec placeholder = true ; le script retourne le slotId de chaque carte, que vous transmettez lors de la construction des écrans à l'étape 5. Dans un fichier partagé, utilisez une page par fonctionnalité et définissez BOARD.pageName sur le nom de la page. Définissez BOARD.lang selon "Langue" ci-dessus, et le tag de chaque carte de lacune sur 'spec' (Dans les specs) ou 'suggested' (Suggéré).
Lors de la mise à jour d'un tableau d'états existant, n'exécutez pas le script squelette. Utilisez plutôt ces règles :
- Relisez le nœud cible avant chaque mutation ; le concepteur a peut-être déplacé ou divisé des éléments à la main
- Modifiez uniquement les cartes concernées. Conservez leurs ID ; les nouvelles cartes continuent après le dernier numéro de leur groupe
- Une fois que le prototype construit l'état d'une carte de la vérification des lacunes, déplacez la carte vers le groupe auquel elle appartient, supprimez la balise, donnez-lui un nouvel ID, et notez l'ancien ID G dans la description
- Recalculez les nombres dans le résumé de la couverture
- Conservez la langue existante du tableau pour les libellés que vous ajoutez, même si l'utilisateur écrit maintenant dans une autre langue ; un tableau avec des libellés mixtes est difficile à lire
- Ne touchez pas à la zone de notes du concepteur à droite ni à la section Feedback
Terminé quand : chaque carte Prototype a un emplacement réservé et un slotId ; tous les wireframes de la vérification des lacunes sont dessinés.
5. Construire les écrans dans Figma
Utilisez use_figma pour construire des calques natifs et les placer dans les emplacements réservés de l'étape 4. send_code_to_figma importe un calque de code et ne produit pas de calques de design modifiables, donc cela ne fonctionne pas pour les tableaux d'états.
Sur la Route B, suivez code-to-figma "Règles strictes pour l'écriture dans Figma" et n'envoyez qu'un seul écran à la fois. Avec plus de 100 cartes Prototype ou plus de 20 images uniques, demandez à l'utilisateur de signaler l'utilisation mémoire après chaque groupe, en suivant scale-guard.md. Si vous rencontrez une condition d'arrêt de scale-guard.md pendant l'écriture (y compris la limite d'appels atteinte), arrêtez-vous et ne réessayez pas.
Choisissez d'abord une route et confirmez-la avec l'utilisateur :
- Route A : copier les maquettes (par défaut). À utiliser lorsque le fichier ou la bibliothèque cible contient des écrans de maquette complets. Vous pouvez lier des variables et conserver la disposition automatique.
- Route B : reconstruire à partir du code du projet. À utiliser lorsque le fichier cible n'a pas de maquettes à copier, ou lorsque l'utilisateur demande de reconstruire à partir du code plutôt que de coller des maquettes. Suivez code-to-figma et passez
slotIdà__alBuild; l'écran produit va dans l'emplacement réservé de la carte. Actuellement, uniquement pour les interfaces Web. - Route C : captures d'écran du navigateur. Chaque carte Prototype affiche une capture d'écran de l'application en cours d'exécution ; rien n'est reconstruit. L'ensemble du tableau prend environ 3 appels comptés, quel que soit le nombre de cartes, alors proposez-le lorsque le budget d'appels ne peut pas couvrir la Route B (plans Starter, sièges Viewer et Collab), ou lorsque l'utilisateur a seulement besoin de la liste des états et de la vérification des lacunes. Les écrans sont des images, pas des calques modifiables ; dites-le lorsque vous le proposez et à nouveau dans le rapport. Interfaces Web uniquement. Les étapes sont sous "Route C" ci-dessous.
Sur les Routes A et B, les écrans produits doivent suivre screen-structure.md : cadre racine de l'écran Largeur fixe = W ; disposition automatique pour les conteneurs dont les enfants sont disposés ; pas de groupes ; éléments d'interface répétés en tant que composants (variantes pour différents états) ; les conteneurs de carrousel sont clipés et jamais en Hug ; le texte long Fill + hauteur automatique. Les cartes de la vérification des lacunes (Dans les specs, Suggéré) suivent les spécifications de wireframe dans board-format.md ; ne dessinez pas de fausse interface utilisateur produit.
Les étapes 1 à 3 ci-dessous concernent la Route A :
- Trouvez les écrans et les composants : si le fichier cible a déjà des écrans de maquette complets, préférez les copier et modifier l'état (changer les variantes, masquer les calques) ; c'est le plus proche du produit. Ensuite, utilisez
search_design_systemet les composants locaux. Ce n'est que si aucun n'existe que vous construisez des calques locaux à partir de la structure et des styles du code. Liez les couleurs, les tailles de police et l'espacement aux variables du projet. Lorsque les maquettes et le code ne sont pas d'accord, suivez le code et notez-le dans la description.- Si la police du produit ne peut pas se charger dans l'environnement d'exécution Figma (par exemple Arial), ne modifiez pas le texte existant. Pour le nouveau texte, utilisez une police avec des largeurs compatibles (Arial → Arimo), et listez où vous l'avez utilisée dans le rapport.
- Construisez d'abord un écran représentatif par appareil, et comparez sa capture d'écran avec le prototype ou l'écran en direct : ne continuez que lorsque le texte, l'espacement, le rayon des coins et les jetons sont tous corrects. S'il n'y a rien à comparer, dites dans le rapport que ces écrans n'ont pas été comparés.
- Générez les cartes Prototype restantes à partir de l'écran représentatif par clone ou instance plus remplacements, en modifiant uniquement ce qui diffère dans cet état.
Route C :
- Capture : suivez web-capture.md étapes 1 à 3 avec
shotOnly: truedans la configuration. Il écritshot/<ID>.jpgen 2x et ignore l'arbre de disposition. Lisezstats.json: un avertissement concernant 4096px signifie que l'écran est trop long pour une seule image ; capturez-le plutôt comme plusieurs cartes de hauteur de fenêtre - Regardez chaque capture d'écran localement avant de la télécharger. C'est l'étape de comparaison sur la Route C : un mauvais état, un spinner qui n'a jamais fini ou une barre d'outils de développement laissée dans la capture ne coûte rien à corriger ici
- Téléchargement : appelez
upload_assetsavecnodeIdsdéfini sur lesslotIds des cartes dans l'ordre des cartes (au maximum 60 par appel). Écrivez les submitUrls dans un fichier, une par ligne, et envoyez les captures d'écran dans le même ordre :python3 al-upload.py urls.txt capture/shot/C01.jpg capture/shot/C02.jpg. Siupload_assetsne remplit pas les emplacements, appelez-le aveccurrentPageIdetcountà la place ; les captures d'écran atterrissent sur la page en tant que calques nommés<ID>.jpg, et l'étape suivante les déplace dans leurs cartes. Ne renommez pas les fichiers - Exécutez screenshot-slots.js avec
SECTION_IDremplacé, dans le même appeluse_figmaque audit.js (étape 6) : enveloppez chacun dans une fonction asynchrone, appelez-les dans l'ordre, puisawait section.screenshot()sur la section du tableau avant de retourner les deux résultats, afin que l'image du tableau revienne avec le même appel. Il dimensionne chaque emplacement à sa capture d'écran et retourneplaced,missingetskipped. Téléchargez à nouveau pour les cartes dansmissing - Pour transformer une carte de capture d'écran en calques modifiables plus tard, reconstruisez cette carte avec la Route B et passez le même
slotId; la construction remplace l'image
Terminé quand : vous avez regardé une capture d'écran de chaque écran représentatif par appareil, et elle correspond au prototype, ou vous avez noté qu'il n'y avait rien à comparer. La Route B doit également satisfaire aux critères d'achèvement de code-to-figma. Sur la Route C, chaque carte Prototype est dans placed, ou le rapport liste celles qui ne le sont pas.
6. Audit
- Exécutez les deux scripts d'audit, en remplaçant
SECTION_IDpar la section cible. Collez les deux dans le même appeluse_figma(enveloppez chacun dans une fonction asynchrone, appelez-les dans l'ordre et retournez les deux résultats) pour économiser un appel du budget :- audit.js : le tableau. Vérifie si les groupes ont un titre et une description, les ID de cartes en double, si les cartes...
[Suite tronquée pour la traduction]