UI diff
Les relecteurs peuvent lire un diff CSS, mais pas le voir. Ce skill génère l'application aux commits de base et de tête de la PR, les compare, et place les images avant/après sur la PR. À côté, il rédige un court résumé de ce qui a changé pour les utilisateurs, appuyé par des valeurs mesurées.
Le travail mécanique est un script unique. Votre rôle concerne les parties qui nécessitent du jugement : quelles pages vérifier, ce que les changements signifient, et où les publier.
$SKILL ci-dessous désigne le répertoire qui contient ce SKILL.md. Définissez-le une fois, par ex.
SKILL=/chemin/vers/skills/ui-diff. Tout est écrit dans .ui-diff/ à la racine du dépôt,
que le script ignore localement via .gitignore, donc rien ne change dans le suivi.
1. Contexte
gh pr view --json number,url,baseRefName,headRefOid,body 2>/dev/null; git status --short
Lisez .ui-diff.json à la racine du dépôt s'il existe. Il peut contenir les routes, la commande de développement,
les masques et l'authentification (voir references/config.md).
Quelle tête (head) générer dépend de ce que fait l'utilisateur :
- Publication sur une PR : générez exactement ce qui a été poussé en passant
--head <headRefOid>. Sinon, les modifications locales non commit se retrouveraient dans un rapport qui prétend montrer la PR. Si l'arbre de travail est sale ou contient des commits non poussés, mentionnez que ces changements n'apparaîtront pas. - Vérification de son travail en cours ("est-ce que ça a l'air correct ?") : utilisez l'arbre de travail
(par défaut, sans
--head). Le rapport l'indique comme "+ changements non commit".
2. Choisir les pages
node $SKILL/scripts/routes.cjs --base <base> --log # ajoutez --head <sha> si vous le passerez à run.sh
Il associe les fichiers modifiés aux routes : fichiers de page, routes sous une mise en page modifiée, pages qui
importent un composant modifié (en suivant les alias et les packages d'espace de travail), ainsi que l'accueil et
quelques pages bien liées pour les styles globaux. Il imprime du JSON avec pour chaque route ses raisons et sa
confiance, needsExample (routes dynamiques qu'il ne peut pas remplir), et unmatched (fichiers UI qu'il n'a pas
pu placer). Traitez-le comme une liste de départ et appliquez votre jugement en utilisant
references/route-mapping.md : supprimez les choix de faible confiance que le diff ne justifie pas, trouvez des
ids pour needsExample, et placez vous-même les fichiers unmatched. Si rien de lié à l'UI n'a changé (tous les
fichiers sont ignored), dites-le et arrêtez. Ne produisez pas de rapport vide.
Projets Storybook (dossier .storybook/ ou script storybook) : lorsque le changement concerne surtout des
composants, différenciez leurs stories plutôt que les pages avec run.sh --storybook ; il choisit les stories
à partir des fichiers modifiés lui-même. Restez sur les pages pour les routes, les mises en page et les styles
globaux. Voir la section Storybook de references/route-mapping.md.
Dites à l'utilisateur en une ou deux lignes quelles routes vous allez capturer et pourquoi, puis continuez. Ne demandez que lorsque vous ne trouvez aucune route, ou lorsqu'une route dynamique nécessite un id que vous ne trouvez pas. Gardez la trace des routes qui sont affectées mais non capturées (trop nombreuses à vérifier, nécessite une connexion, un état modal). Elles iront dans le résumé pour que "aucun changement visuel" ne soit pas interprété comme un feu vert.
3. Exécution
bash $SKILL/scripts/run.sh --routes "/,/pricing" [--head <sha>] [--base <ref>] \
[--viewports "desktop:1440x900,mobile:iPhone 13"] [--schemes light,dark] [--dev "<cmd avec {port}>"]
(--auto-routes ajoute les routes sélectionnées par routes.cjs, avec les raisons ; utilisez-le lorsque
vous n'avez pas de corrections à apporter.)
En une seule exécution, il :
- installe les outils au premier usage (Playwright + Chromium dans
~/.cache/ui-diff, environ une minute ; les dépendances du projet ne sont pas touchées) ; - extrait la base, et la tête si
--headest donné, dans des worktrees git, et copie les fichiers.env*non suivis dans ceux-ci ; - réutilise les dépendances installées lorsque le fichier lockfile correspond, avec des caches de build par extraction, et installe sinon ;
- démarre les deux serveurs de développement sur des ports libres dans leurs propres groupes de processus. Seuls ceux-ci sont arrêtés ensuite, donc les autres serveurs de l'utilisateur ne sont jamais touchés ;
- capture chaque route × viewport. Le mobile utilise une émulation réelle (tactile, UA mobile). Les animations sont figées et les superpositions de développement du framework sont masquées ;
- pixel-diff les captures (
results.json, images pleine page et zoom) et exécute un diff de style calculé (measured.md).
Mode Storybook (--storybook, ou --stories "button--primary,card--*" pour les choisir vous-même)
démarre Storybook au lieu du serveur de développement, enregistre les stories sélectionnées et pourquoi,
et nomme les résultats par id de story. Si aucune story ne correspond, il se termine et suggère des ids.
Il affiche des compteurs comme {"changed":2,"added":1,"unchanged":3,...}. Valeurs par défaut : base = la
branche de base de la PR (sinon la branche par défaut), viewports = desktop 1440×900 + iPhone 13, mode clair.
Ajoutez --schemes light,dark lorsque le changement touche le thème, les couleurs ou les tokens.
En cas d'échec, l'erreur indique quelle étape a échoué et où se trouve son journal (.ui-diff/server-*.log,
install-*.log, capture-*.log). Les causes habituelles sont une variable d'environnement manquante, une
mauvaise commande de développement (passez --dev), ou des dépendances non installées dans l'arbre de travail.
Corrigez la cause et relancez. Ne sautez aucun côté.
4. Lire les résultats et rédiger le résumé
Lisez d'abord .ui-diff/report/measured.md. S'il commence par Problèmes potentiels, vérifiez-les en
premier : texte tronqué, défilement latéral, chevauchement, contrôles hors écran, petites cibles tactiles sur
mobile et violations d'accessibilité axe-core nouvelles sur la tête. Ce sont des heuristiques, donc ouvrez
chaque image zoom (report/issues/) et jugez. Mettez en avant celles qui "méritent un coup d'œil" pour les
vraies, et supprimez ou atténuez celles qui semblent intentionnelles. Le reste de measured.md contient des
faits mesurés : changements de style calculé regroupés par éléments, éléments redimensionnés, décalages de
mise en page, modifications de texte, et nouvelles défaillances de contraste WCAG. Ouvrez ensuite les images
zoom (report/zoom/*__after.png et __before.png) et les superpositions de diff avec l'outil de visualisation
de fichiers ou d'images dont vous disposez pour voir comment ces faits se présentent en contexte. Si vous ne
pouvez pas visualiser les images, rédigez le résumé à partir de measured.md seul et dites que les captures
n'ont pas été examinées. Vérifiez aussi results.json pour les warnings : erreurs HTTP, superpositions
d'erreurs du framework, exceptions non capturées.
Lien Figma fourni (ou une route dans .ui-diff.json a figma) ? Comparez également la tête avec le
cadre de design. Suivez references/figma.md.
Écrivez .ui-diff/report/summary.md pour un designer ou un chef de produit qui ne lira pas le code :
**Ce qui a changé**
- **Cartes de tarifs** — Les boutons CTA sont maintenant des pilules (rayon 4 → 999px) avec plus de marges
internes (8×14 → 12×20px) ; la carte Pro est mise en évidence (bordure 2px `#2563EB`, fond `#EFF6FF`)
avec un label "Le plus populaire".
- **En-tête (toutes les pages)** — Les liens de navigation sont passés du bleu `#2563EB` au gris `#9CA3AF`.
**À surveiller**
- ⚠️ Les liens de navigation ont maintenant un contraste de 2,5:1 sur fond blanc (était 5,2:1) ; le texte
courant nécessite 4,5:1.
- ⚠️ `/settings` a changé mais aucun de ses fichiers n'a été modifié — il hérite du nouveau padding du
`Button`, et "Enregistrer"/"Annuler" passent à la ligne sur mobile.
**Non vérifié :** `/admin/*` (nécessite connexion), la modale de suppression de compte.
Directives :
- Utilisez les valeurs mesurées de
measured.mdpour les couleurs, tailles et espacements. Ne les estimez pas à partir des pixels. Si quelque chose est visible dans les images mais pas dansmeasured.md(images, canvas, contenu SVG), décrivez-le tel que vu. - Un pourcentage élevé de changement de pixels avec des lignes "décalage de … mise en page" signifie généralement que le contenu a été poussé vers le bas, pas que tout a changé. Expliquez-le ainsi.
- Placez en tête de la section "à surveiller" les changements probablement involontaires : pages qui ont changé sans que leurs fichiers aient changé, dysfonctionnement à un seul viewport, débordement, éléments disparus, erreurs de page. Ensuite les défaillances de contraste et les petites cibles tactiles (moins d'environ 44px sur mobile).
- Dites "a changé", pas "a été intentionnellement changé". Vous pouvez voir ce qui a changé, pas pourquoi.
- Restez proportionné. Une modification d'une seule couleur donne une seule puce.
Exécutez ensuite node $SKILL/scripts/viewer.cjs --report .ui-diff/report pour actualiser la page de
relecture locale (report/index.html : curseur, côte à côte, superposition de diff, résumé en haut) et
proposez de l'ouvrir pour l'utilisateur (open sur macOS, xdg-open sur Linux).
5. Publication
Publier écrit dans une PR partagée et pousse une branche. Montrez d'abord le résumé à l'utilisateur et demandez confirmation, sauf si sa demande disait déjà de publier. Ensuite :
PREFIX=$(bash $SKILL/scripts/publish.sh .ui-diff/report <pr> <head-short-sha>)
node $SKILL/scripts/comment.cjs --report .ui-diff/report --base-url "$PREFIX" \
--summary .ui-diff/report/summary.md --out .ui-diff/comment.md
node $SKILL/scripts/post.cjs --pr <pr> --body .ui-diff/comment.md --mode comment # ou --mode description
publish.shpousse les images vers une brancheui-diff-assets(un commit, remplacé à chaque publication) à partir d'un clone jetable. Les images s'affichent ensuite en ligne sur GitHub, y compris dans les dépôts privés pour toute personne ayant un accès en lecture.- Code de sortie 3 signifie pas d'accès en poussée (typiquement une PR depuis un fork). Passez en mode manuel.
- Si le dépôt est public, informez l'utilisateur que les captures d'écran seront publiques. C'est
particulièrement important lorsque
storageStateest connecté avec un vrai compte. Obtenez un accord avant de publier.
post.cjsremplace le commentaire ou la section de description ui-diff précédent au lieu d'en ajouter de nouveaux. Tout le reste de la description est conservé tel quel.- Ajoutez
--approvalàcomment.cjsuniquement si.ui-diff.jsoncontient"requireApproval": true(le dépôt utilise le workflow de relecture de design) : cela ajoute une case "Design approuvé". - Mode manuel (pas de branche d'actifs, ou pas d'accès en poussée) : exécutez
comment.cjssans--base-url, puisopen .ui-diff/report. L'utilisateur glisse les images dans la zone de commentaire de la PR (GitHub n'a pas d'API pour ce téléchargement). Dites-lui quelle image va où. - Pas encore de PR : conservez
.ui-diff/comment.mdet proposez de le mettre dans la description lorsque la PR sera ouverte.
6. Finalisation
Rendez compte avec le lien, les compteurs et les éléments "à surveiller". Si vous avez déterminé vous-même
la commande de développement, les routes, les masques ou les ids dynamiques, proposez de les enregistrer dans
.ui-diff.json pour que la prochaine exécution soit en une seule étape. Une fois une PR fusionnée ou fermée,
bash $SKILL/scripts/prune.sh <pr> supprime ses images de la branche d'actifs (demandez d'abord si quelqu'un
pourrait encore avoir besoin de son commentaire).