Porte de Prévisualisation UI

Que fait Porte de Prévisualisation UI ?

Chaque modification d'écran passe par quatre phases. Ne sautez pas de phase parce que le changement semble petit ; les images sont ce que les relecteurs approuvent.

1. Inspecter l'état actuel
2. Prévisualiser et obtenir l'approbation (avant de commencer le travail)
3. Implémenter
4. Vérifier que le résultat correspond à la prévisualisation approuvée (après la fin du travail)

Exception : un correctif de bogue qui ne modifie pas l'écran prévu peut sauter la phase 2. Si les utilisateurs peuvent encore voir une différence, signalez les images avant/après avec le correctif. Afficher un écran, une boîte de dialogue, une feuille ou un message différent d'avant constitue un changement d'écran, pas cette exception – même s'il réutilise un composant existant. Obtenez d'abord l'approbation de la phase 2.

Quand cela s'applique

• Appliquez-le sans qu'on vous le demande. Les utilisateurs ne devraient jamais avoir à nommer cette compétence.
• Vérifiez chaque tour, pas seulement le premier. Une conversation qui a commencé comme une demande d'assistance, de recherche, de révision ou un rapport de bogue se transforme souvent en « et si l'écran faisait X ? » à mi-parcours ; à partir de ce tour, cette compétence s'applique.
• « Qu'en pensez-vous ? », « des idées ? » et « à quoi cela ressemblerait-il ? » à propos d'un écran comptent comme des propositions.
• Une fois commencé, continuez à le suivre dans les tours suivants jusqu'à ce que le changement approuvé soit vérifié (phase 4) ou que l'utilisateur abandonne le changement.
• Une proposition répondue uniquement en prose ou dans un tableau de cas est incomplète. Joignez l'image avant/après dans la même réponse, ou dites pourquoi elle ne peut pas encore être faite et quand elle le sera.
• Pendant qu'un changement d'UI est en attente d'approbation ou en cours, les rapports d'avancement, les listes d'options et les questions à son sujet doivent également joindre à nouveau son image avant/après ou donner le chemin de l'image. Ne décrivez jamais l'écran modifié uniquement en prose.

Les compétences sont généralement sélectionnées par tour à partir de leur description, donc les tours en milieu de conversation peuvent être manqués. agent-instructions.md à côté de ce fichier est une courte règle à ajouter à AGENTS.md / CLAUDE.md pour que l'agent revérifie à chaque tour.

1. Inspecter l'état actuel

Ne proposez jamais de mémoire ou de suppositions.

• Capturez l'écran réel à partir d'un serveur de développement en cours d'exécution ou d'une build. La fenêtre d'affichage par défaut est mobile 375px de large ; ajoutez le bureau lorsque le changement affecte également les mises en page de bureau.
• Lisez le code qui le rend : structure des onglets/itinéraires, composants, copie actuelle.
• Enregistrez les preuves sous forme chemin/vers/fichier:ligne plus la capture. Chaque affirmation sur l'UI actuelle doit pointer vers l'un d'eux.
• Préférez les composants, motifs et copies existants. Si un nouveau motif est nécessaire, indiquez pourquoi les existants ne conviennent pas.

Capturez avec scripts/capture.mjs (voir Scripts) pour que la photo avant, la prévisualisation et la photo de vérification partagent la même fenêtre d'affichage, échelle et état des données.

Inventaire des cas (faites-le spontanément, avant la première prévisualisation)

L'approbateur ne devrait jamais avoir à demander « et après avoir tapé dessus ? » ou « et s'il y a des données ? ». Avant d'envoyer une prévisualisation, listez chaque cas que le changement touche, à partir du code et de l'application réelle :

• États de l'écran modifié : vide / a des données / beaucoup d'éléments (troncature, « voir tout ») / chargement / erreur / verrouillé par plan, rôle ou permission / autres configurations (mono vs multi-magasins, indicateurs de fonctionnalités).
• Chaque écran atteint à partir d'un contrôle nouveau ou modifié : formulaires, sélecteurs, boîtes de dialogue, erreurs de validation, annuler/retour, confirmation, succès, échec.
• Après l'action : à quoi ressemble l'écran d'origine une fois l'action terminée (nouvel élément apparaît, compteurs changent), et comment annuler ou modifier.
• Autres endroits qui affichent les mêmes données : listes, écrans de détail, historique, rapports, exports, autres plateformes (bureau, Web, LINE, côté client). Marquez chacun comme modifié / inchangé-mais-affiche-de-nouvelles-données / non affecté.

Envoyez l'inventaire sous forme de tableau avec la première prévisualisation : cas, ce que l'utilisateur voit, composant existant réutilisé et état de l'image (jointe / nécessite des données de test – comment elle sera préparée / hors de portée – pourquoi). Les prévisualisations peuvent arriver par lots, mais le premier message montre toujours l'inventaire complet, et l'approbation d'une image n'implique jamais l'approbation de cas non encore montrés. Proposez des valeurs par défaut sensées pour les décisions ouvertes au lieu de seulement lister des questions.

2. Prévisualiser et obtenir l'approbation

Avant d'écrire le code d'implémentation, montrez à l'approbateur une image avant/après côte à côte et un court résumé, puis attendez un OK explicite.

Règles d'image :

• Avant à gauche, après à droite, dans une seule image.
• Encadrez chaque zone modifiée : rouge sur l'avant, vert sur l'après.
• Appairez les cadres : chaque modification obtient un cadre des deux côtés à l'endroit correspondant. Pour un ajout, marquez le point d'insertion sur l'avant avec un marqueur fin dans l'espace ("pad": 0, petit h) ; pour une suppression, marquez l'espace sur l'après. Ne cadrez jamais un voisin non lié (par exemple la ligne en dessous) pour remplacer un élément manquant.
• Prenez les coordonnées des cadres à partir de la sortie de capture.mjs --selector (ou des rectangles d'éléments mesurés avec Playwright dans un test e2e lorsque l'état nécessite une interaction, par exemple une boîte de dialogue qui s'ouvre après une saisie), pas à l'œil. Regardez l'image composée avant de l'envoyer pour confirmer que chaque cadre repose sur sa cible.
• Même fenêtre d'affichage, position de défilement et données d'exemple des deux côtés.
• Si l'écran se ramifie par état (données présentes/absentes, erreur, vide, par rôle ou par configuration), montrez une paire avant/après pour chaque état que la modification touche. Un état que vous n'avez pas montré n'est pas approuvé. Faites une image par état ; ne mettez jamais plusieurs paires dans une même image.
• Un écran réel atteint uniquement par mise en scène (code temporairement modifié pour l'ouvrir) doit porter "staged" dans la spécification pour que l'image le mentionne.
• Vérification avant envoi : compose.mjs rejette les spécifications qui enfreignent ces règles et imprime une liste de contrôle. Ouvrez l'image, répondez à chaque élément et mettez les réponses dans le message (voir les modèles). Si un élément échoue, corrigez et recomposez ; n'expliquez jamais un élément échoué en texte à la place.
• Suivez la politique d'image ci-dessous.

Politique d'image

L'utilisateur ou le projet décide si les maquettes sont autorisées. Recherchez le choix dans la demande ou les instructions du projet (AGENTS.md, CLAUDE.md, docs de contribution). Si rien n'est indiqué, utilisez real-only. Ne passez jamais à mockup-allowed de votre propre chef parce que la capture est difficile ; demandez plutôt.

• real-only (par défaut) : les deux côtés sont des captures plein écran de l'application réelle en cours d'exécution. Construisez le côté après sur une branche prototype ou derrière un indicateur de fonctionnalité et capturez-le. N'utilisez jamais de fragments recadrés ou collés, de maquettes redessinées à partir du code ou à la main (y compris les images générées), de captures qui coupent une ligne en deux, ou de données fictives qui diffèrent de ce que l'application réelle affiche.
• mockup-allowed : le côté après peut être une maquette uniquement lorsque l'utilisateur ou le projet l'autorise explicitement. Le côté avant reste une capture réelle. Marquez chaque panneau de maquette avec "mockup": true dans la spécification compose pour que l'image le montre, et indiquez-le dans la demande d'approbation. Une maquette ne compte jamais comme preuve de phase 4 : la vérification utilise toujours une capture réelle de l'écran implémenté.

Une règle de projet plus stricte l'emporte toujours sur une préférence utilisateur plus laxiste ; si elles entrent en conflit, signalez-le et suivez la règle du projet.

Résumé (utilisez references/templates.md) :

• Où : quel écran/onglet et où sur celui-ci le changement apparaît
• Ce qui devient possible, par type d'utilisateur (par exemple administrateur, client)
• Ce qui ne change pas, et les plateformes/surfaces affectées

L'approbation couvre exactement ce qui a été montré. Tout ce qui est en dehors nécessite une nouvelle prévisualisation.

3. Implémenter

Construisez selon la prévisualisation approuvée. Si l'implémentation force un écart visible (mise en page, copie, comportement, nouvel impact plateforme), arrêtez-vous et revenez à la phase 2 avec une prévisualisation mise à jour plutôt que de livrer la différence.

Cela inclut les petites modifications de copie et les correctifs apportés en réponse à une révision de code : si un correctif modifie ce que les utilisateurs voient au-delà des images approuvées, arrêtez-vous et obtenez d'abord une nouvelle prévisualisation approuvée. Le signaler après coup en texte ne compte pas.

4. Vérifier par rapport à la prévisualisation approuvée

Ne signalez pas l'achèvement à partir du seul diff de code.

1. Recapturez l'écran implémenté avec les mêmes paramètres de capture et le même état que ceux utilisés pour la prévisualisation.
2. Composez une image de vérification : prévisualisation approuvée | résultat réel. Encadrez chaque changement promis ; encadrez chaque différence par rapport à la prévisualisation approuvée en ambre, même un petit décalage. Une différence décrite uniquement en texte n'est pas vérifiée.
3. Vérifiez, point par point :
   • chaque changement promis est présent et correspond à la prévisualisation ;
   • tout ce qui est listé comme « ne change pas » est inchangé ;
   • rien en dehors des zones encadrées n'a bougé, n'a fait de retour à la ligne ou n'a débordé ;
   • l'interaction modifiée fonctionne réellement lorsqu'elle est exercée, pas seulement rendue. Les tests e2e réussis confirment le comportement uniquement ; ils ne remplacent pas la vérification d'image pour chaque état qui devrait sembler inchangé.
4. Décidez :
   • Correspondance : signalez avec l'image de vérification et le résultat de la liste de contrôle.
   • Léger écart dans l'intention approuvée : corrigez, recapturez, revérifiez.
   • Écart qui modifie ce qui a été approuvé : signalez-le et obtenez à nouveau l'approbation.

Listez séparément tout ce que vous n'avez pas pu vérifier (une plateforme, un appareil, des données réelles) au lieu de le déclarer terminé.

Scripts

Les deux scripts nécessitent Node 18+ et Playwright (npm i -D playwright && npx playwright install chromium). Définissez PLAYWRIGHT_MODULE sur un chemin de module pour réutiliser une installation existante.

Capturez un écran et obtenez les coordonnées des cadres pour les éléments :

node scripts/capture.mjs --url http://localhost:3000/menu --out before.png \
  --width 375 --selector ".category-tabs" --selector ".menu-list"

Cela imprime les rectangles des sélecteurs en pixels CSS, prêts à être collés comme boxes.

Composez des panneaux à partir d'une spécification JSON :

node scripts/compose.mjs spec.json

Le format de la spécification, les tons et la disposition de vérification sont dans references/compose-spec.md.