CommunityImagegithub.com

avant-après

Génère une image avec un tableau de captures d'écran avant/après montrant chaque changement visuel de la branche courante par rapport à une branche de base.

Qu'est-ce que avant-après ?

Cette compétence produit une image PNG unique contenant un tableau comparatif avant/après de toutes les modifications visuelles introduites par une branche. Elle capture chaque écran, composant et état depuis une compilation locale de la branche de base et de la branche courante, dans des conditions strictement identiques (données, viewport, thème). Un seuil de détection de pixels vérifie que chaque paire diffère réellement. Elle est idéale pour les revues de code, les pull requests ou les designers souhaitant visualiser l'impact visuel des changements. Supporte les environnements locaux via scripts Playwright, les thèmes sombres, les états de données et d'interaction, et peut être utilisée avec Git, GitHub CLI et les outils de développement courants.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/MagnusBrogie/agent-skills/tree/HEAD/before-after

Installed? Explore more Image skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Demander à votre IA préférée

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

Documentation

Avant et après

Produire un PNG : un tableau avec une ligne par changement visuel, et dans chaque ligne le nom du changement, une note d'une ligne, la capture de la base et la capture de la branche. Un lecteur qui n'a pas vu le code doit pouvoir distinguer sur l'image seule ce qui a changé d'aspect et où.

L'image ne vaut que par sa liste de changements. Un tableau qui montre trois changements sur cinq, ou qui montre une différence causée par des données différentes plutôt que par le code, trompe le lecteur. La majeure partie du travail consiste à trouver chaque changement visuel et à capturer chaque paire pour que seul le code diffère.

Où vont les images. Tout ce que cette compétence produit est stocké dans le dossier Documents de l'utilisateur, dans ~/Documents/before-after/<dépôt>/<branche>/ : les captures, le manifeste, une copie de shots.mjs et le fichier final before-after.png. Les scripts choisissent eux-mêmes ce dossier et ne prennent aucun chemin de sortie ; un utilisateur qui souhaite une autre racine que ~/Documents/before-after définit la variable d'environnement BEFORE_AFTER_DIR, qui lui appartient, pas à vous. N'écrivez pas les images ailleurs, et ne les déplacez ni ne les copiez ensuite ; le scratchpad est uniquement pour l'arbre de travail de base et pour la rédaction de shots.mjs. Une exécution ultérieure pour la même branche réutilise le dossier.

Deux scripts se trouvent dans scripts/ à côté de ce fichier : capture.mjs prend les captures, et compose.mjs construit et vérifie le tableau. Chacun documente son format d'entrée dans son en-tête. Lisez les deux en-têtes avant de commencer.

Notes locales. Si un fichier nommé LOCAL.md se trouve à côté de ce fichier, lisez-le avant de commencer. Il contient les valeurs par défaut de l'utilisateur pour les projets sur lesquels il travaille (commandes, hôtes, comptes, chemins) et ne fait pas partie de la compétence publiée. Lorsqu'il couvre le projet concerné, il compte comme faisant partie des instructions du projet ; sinon, ignorez-le.

1. Rassembler les changements

Sans branche de base donnée, utilisez la base de la pull request (gh pr view --json baseRefName --jq .baseRefName), sinon la branche par défaut (git symbolic-ref --short refs/remotes/origin/HEAD), sinon origin/main. Préférez la référence de suivi distant. Incluez le travail non commit :

base=$(git merge-base <base> HEAD)
git diff --stat "$base"; git diff "$base"; git status --short   # lire aussi les fichiers non suivis
git log --oneline "$base"..HEAD

Lisez également la description de la pull request et le ticket, s'il y en a. Ils indiquent souvent quels écrans sont concernés par le changement et incluent des captures que les gens s'attendent à voir.

2. Lister chaque changement visuel

Tracez chaque hunk vers l'extérieur jusqu'à ce qu'un utilisateur voit :

  • Code de la vue, styles, tokens, icônes, copie, traductions. Chacun de ces éléments est un candidat. Pour le code partagé (un composant UI, un helper de formatage, un token CSS), recherchez ses appelants et listez chaque écran qui le rend. Un changement dans du code partagé est généralement visible à plus d'endroits que la branche ne le prévoyait.
  • États de données. Pour chaque écran, lisez les branches que le code modifié emprunte : chargé, chargement, vide, erreur, valeur manquante, zéro et négatif, texte long, un élément et plusieurs, chaque mode ou paramètre. Ne conservez que les états dont le rendu est modifié par le diff.
  • États d'interaction. Survol, focus, appuyé, désactivé, sélectionné ; un popover, menu, feuille ou dialogue ouvert ; un champ affichant une erreur de validation. Ceux-ci nécessitent des étapes avant la capture (étape 4).
  • Écrans que la branche ajoute ou supprime. Ceux-ci n'ont qu'un seul côté ; la ligne montre un espace réservé pour l'autre.
  • Environnements que le projet prend en charge, là où le changement pourrait avoir un aspect différent : thème sombre, largeurs mobile et desktop, une autre locale.

Classez les candidats dans trois listes :

  1. Visuel : quelque chose à l'écran diffère. Ceux-ci deviennent des lignes.
  2. Non visuel : le changement n'affecte que l'arbre d'accessibilité, les attributs, le texte réservé aux lecteurs d'écran, le comportement ou la structure du code. Ce ne sont pas des lignes. Nommez-les dans le rapport, pour que le lecteur sache qu'ils ont été considérés et non oubliés. Si l'utilisateur veut les montrer quand même, une ligne peut contenir un extrait de l'arbre d'accessibilité capturé en image, étiqueté comme tel.
  3. Incertain : changements de balisage ou de classe qui sont censés être invisibles mais pourraient déplacer ou recolorer quelque chose (un nouvel élément wrapper, une classe de positionnement, un helper changé). Capturez-les, et laissez la vérification pixel décider.

Un changement de mouvement (une animation, une transition, son timing) ne peut pas être montré dans une image fixe. Mettez-le sous "Non montré" dans le rapport et dites comment le voir.

Regroupez les lignes de manière pertinente : une ligne par aspect distinct, pas par site d'appel. Si dix écrans utilisent la cellule modifiée de la même manière, montrez-en un ou deux et nommez les autres dans la note. Visez un tableau que quelqu'un lira vraiment ; au-delà d'environ douze lignes, créez une deuxième image par zone et dites-le.

Si les listes visuelle et incertaine sont toutes deux vides, arrêtez-vous ici. Dites à l'utilisateur que la branche n'a aucun changement visuel, listez ce qui a été considéré et pourquoi chaque élément n'est pas visuel, et ne produisez aucune image. Si seuls des éléments incertains existent et que chaque paire s'avère identique, le résultat est le même, et les paires identiques sont la preuve : rapportez-les comme vérifiées et inchangées.

3. Compiler la base et la branche localement

Capturez les deux côtés à partir de compilations locales, jamais à partir d'un déploiement : un déploiement est en retard par rapport à l'arbre de travail et ne peut pas montrer le travail non commit.

  • Branche : l'arbre de travail actuel, compilé après la dernière modification.

  • Base : un arbre de travail séparé à la base de merge, pour que l'arbre de travail de l'utilisateur ne soit jamais touché. Ne changez jamais de branche ou ne stashez pas dans le checkout de l'utilisateur.

    git worktree add --detach <scratchpad>/before-after-base "$base"
    

    Installez les dépendances là-bas. Un lien symbolique vers le répertoire de dépendances du checkout principal est acceptable uniquement si le diff ne touche pas au fichier de verrouillage. Supprimez l'arbre de travail lorsque vous avez terminé (git worktree remove).

Utilisez les commandes documentées du projet (lisez son README, AGENTS.md, CLAUDE.md, les docs de développement et toute compétence run). Les deux côtés doivent communiquer avec le même backend de staging ou de test, jamais la production. S'il n'est pas clair quelle commande cible quel backend, lisez la configuration de build, et si le doute persiste, arrêtez-vous et demandez. Avant de capturer quoi que ce soit, vérifiez l'hôte d'une requête API réelle de chaque côté.

Préférez la compilation de production du projet servie statiquement (un build suivi d'un preview ou d'un serveur statique) à son serveur de développement. Un serveur de développement ajoute des clients de rechargement à chaud et des superpositions, peut nécessiter un processus de surveillance par arbre de travail, et peut rendre différemment de ce qui est livré. Si vous compilez avec un outil qui n'est pas la commande de build du projet lui-même, vérifiez que la page s'affiche : un projet peut post-traiter son bundle. Une compilation peut aussi vider ou écraser un répertoire de sortie dans l'arbre de travail de l'utilisateur. Ce sont des fichiers générés, mais dites dans le rapport ce que vous avez reconstruit, et remettez en place ce que la configuration de développement attend si la compilation l'a supprimé.

Avant de faire confiance à une capture, confirmez que les deux compilations diffèrent : lisez le balisage de l'élément modifié de chaque côté et voyez le changement du diff dedans. Deux serveurs qui servent le même code donnent des paires identiques qui ne prouvent rien.

Choisissez comment servir les deux compilations :

  • Les deux à la fois, sur deux ports libres. C'est le plus simple, et les deux captures d'une paire sont prises à quelques secondes d'intervalle. Cela fonctionne lorsque les écrans ne nécessitent pas de connexion, ou lorsque la connexion survit à un changement de port. Les cookies sont partagés entre les ports sur le même hôte, mais le stockage local ne l'est pas, et un backend peut n'accepter que certaines origines. Vérifiez qu'un écran connecté se charge réellement sur le deuxième port avant de vous y fier.
  • L'un après l'autre, sur le même port. Servez la base sur le port habituel du projet, capturez avec --side=before, arrêtez-la, servez la branche sur ce port, et capturez avec --side=after. L'état de connexion enregistré et les origines autorisées s'appliquent alors aux deux. Les captures sont espacées de plusieurs minutes, donc les données doivent être mockées ou connues pour être stables.

Si le projet a un catalogue de composants (Storybook, une application "workshop" ou similaire) et que le changement se trouve dans un composant partagé, le capturer là est plus économique et plus stable que dans l'application complète, et ne nécessite généralement pas de connexion. Capturez néanmoins au moins un écran réel par changement là où vous le pouvez, afin que l'image le montre dans son contexte. Si un écran réel ne peut pas être atteint (par exemple, pas de connexion de test), dites-le sous "Non montré".

4. Capturer chaque paire dans des conditions identiques

Écrivez un shots.mjs dans le scratchpad, dans le format donné dans l'en-tête de scripts/capture.mjs, et exécutez-le depuis la racine du projet, afin que Playwright se résolve et que le dossier de sortie obtienne le bon nom de dépôt et de branche :

node <cette compétence>/scripts/capture.mjs <scratchpad>/shots.mjs --before=http://localhost:<p1> --after=http://localhost:<p2>

Le script exécute les mêmes étapes sur les deux URL. Il utilise le Chrome installé, un facteur d'échelle d'appareil de 2 et un mouvement réduit. Il désactive les transitions, réinitialise les animations infinies (un shimmer, un spinner) à leur première image et termine les animations finies, attend les polices et le réseau se stabilise, et fige l'horloge si vous lui donnez une heure. Il écrit shots/<slug>.before.png, shots/<slug>.after.png et le manifest.json pour l'étape 5 dans le dossier Documents décrit ci-dessus, copie shots.mjs à cet endroit et affiche le chemin du dossier comme dernière ligne. --only=<slug> recapture une seule ligne. Une capture échouée laisse <slug>.<side>.FAILED.png de l'intégralité du viewport, ce qui montre à quoi ressemblait la page à la place.

Si la configuration de test de bout en bout du projet a un état de connexion enregistré, passez-le comme storageState (lisez la documentation du projet pour savoir comment il est créé). Dans Orca, le navigateur intégré (la compétence orca-cli) fonctionne aussi pour une paire ou deux, mais un script rend les paires reproductibles.

Ce que vous devez bien faire dans shots.mjs :

  • Mêmes données des deux côtés. Les données en direct dérivent entre deux captures : les prix changent, les listes se réordonnent. Préférez mocker les réponses dont l'écran dépend dans le mock de la capture : capturez une charge utile réelle depuis le staging et servez les deux côtés avec elle. Deux limites :
    • Si la branche modifie la requête ou la forme de la réponse (un nouvel endpoint, un nouveau champ, un décodeur changé), une charge utile ne peut pas servir les deux côtés. Donnez à chaque côté la charge utile que son code attend, construite à partir des mêmes valeurs sous-jacentes, et dites-le dans le sous-titre.
    • Les données qui arrivent via un WebSocket ou des événements envoyés par le serveur ne sont pas touchées par page.route. Utilisez page.routeWebSocket, ou choisissez un écran ou un moment où le flux est calme, ou masquez l'élément en direct s'il n'est pas le sujet.
  • Atteindre l'état délibérément. Les états de chargement, d'erreur et de valeur manquante se produisent rarement sur des comptes de test : produisez-les dans mock (retardez une réponse, échouez-la, mettez un champ à null). Dérivez les chemins de requête et les noms de champs du code, pas en devinant. Atteignez les états d'interaction dans steps (survol, focus, clic pour ouvrir).
  • Recadrer sur le changement avec contexte. Définissez target sur le plus petit élément qui montre le changement et reste reconnaissable comme faisant partie de son écran : la carte, le tableau, la feuille, pas la page entière. Visez un recadrage d'au maximum environ 650 px CSS de large : c'est ce qui tient côte à côte en taille réelle. Un recadrage plus large est empilé (avant au-dessus d'après), et un recadrage plus large qu'environ 1300 px CSS est réduit, donc son texte devient plus difficile à lire. Utilisez la même cible des deux côtés pour que les recadrages soient alignés.
  • Masquer ce qui n'est pas le sujet et bouge constamment (un ticker, une horloge, un avatar qui se charge tard) avec une balise style dans steps, des deux côtés.

5. Composer et vérifier

node <cette compétence>/scripts/compose.mjs <dossier>/manifest.json [--diff] [--stack]

L'image est écrite à côté du manifeste sous le nom before-after.png, et son chemin est la dernière ligne de sortie. --diff ajoute une image par ligne avec les pixels modifiés en magenta. Utilisez-le lorsque le changement est petit ou subtil (espacement, une couleur, un glyphe) ; omettez-le lorsque le changement est évident. Lorsque les deux captures d'une ligne diffèrent en taille, la comparaison est alignée dans le coin supérieur gauche, donc tout après le décalage compte comme changé ; la ligne le dit, et l'image de différence n'est alors qu'un guide approximatif.

Le script dessine les deux captures d'une ligne à la même échelle. Il imprime la part de pixels changés par ligne et comment chaque ligne a été disposée, et se termine avec le code 3 si une paire est identique. Ensuite :

  1. Une paire identique signifie que la capture a manqué le changement (mauvais état, mauvais écran, un cache, une compilation de base qui n'est pas réellement la base) ou que le changement n'est pas visuel. Trouvez lequel. Corrigez la capture, ou retirez la ligne du manifeste et déplacez l'élément dans la liste non visuelle comme "vérifié, aucun pixel ne diffère". Ne livrez jamais une ligne avec une paire identique.
  2. Regardez l'image (lisez le PNG) et vérifiez chaque ligne : la différence que vous voyez est celle que la note décrit, et rien d'autre ne diffère. Une différence qui n'est pas expliquée par le diff (un prix différent, une ligne manquante, un décalage de mise en page ailleurs) est une dérive de données ou une régression inattendue. Recapturez, ou signalez-la à l'utilisateur comme une régression possible. Ne la cachez pas.
  3. Vérifiez que le texte dans chaque capture peut être lu. Agissez sur tout avertissement "le texte peut être illisible" du script : recadrez plus étroitement et recapturez cette ligne avec --only.
  4. Si l'image est très longue, divisez-la par zone : créez un sous-dossier par zone à l'intérieur du dossier de la branche, chacun avec son propre manifest.json dont les chemins pointent vers ../shots/..., et composez chacun.

6. Rapport

Donnez à l'utilisateur :

  • Le chemin absolu complet du PNG.
  • Les lignes, une par ligne.
  • Non montré : les changements non visuels, les éléments incertains que la vérification pixel a trouvés inchangés, les changements de mouvement, les changements visuels que vous n'avez pas pu capturer (et pourquoi), et les sites d'appel laissés de côté comme doublons d'une ligne qui est montrée.
  • Tout ce qui est inattendu que la vérification pixel ou votre propre inspection a révélé.
  • Comment les paires ont été produites (données de staging réelles, ou quelles réponses ont été mockées ; un catalogue ou l'application réelle), afin que le lecteur sache ce que les images prouvent.

Arrêtez les serveurs de développement que vous avez démarrés et supprimez l'arbre de travail de base. Les captures, la copie de shots.mjs et le manifeste restent dans le dossier de sortie, afin qu'une exécution ultérieure puisse recapturer une seule ligne avec --only.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Skills associés