Communitygithub.com

ui-diff

Affiche l'impact visuel / UI / UX d'une pull request. Génère les pages concernées aux commits de base et de tête, pixel-diff les captures, mesure les changements de style exacts (couleurs, espacement, typographie, contraste), rédige un résumé simple pour les designers et relecteurs, et publie les images avant/après dans la PR.

Qu'est-ce que ui-diff ?

Le skill ui-diff automatise l'analyse visuelle des pull requests pour les applications web. Il capture les pages affectées aux commits de base et de tête (head), génère un pixel-diff précis, et mesure les changements de style réels (couleurs, espacements, typographie, contraste). Le résultat est un résumé en langage naturel, accompagné d'images avant/après, directement posté dans la PR. Ce skill fonctionne avec tout framework web utilisant un serveur de développement local : React, Next.js, Vue, Nuxt, Svelte, Angular, Astro ou HTML pur. L'utilisateur peut déclencher l'analyse par des phrases simples comme "ajoute des captures d'écran à ma PR", "à quoi ressemble cette PR", "diff visuel", "avant/après", "revue de design", ou "vérification de régression visuelle". La logique métier inclut la sélection intelligente des routes, la gestion des dépendances via des worktrees git, le support des storybooks, et la publication sécurisée des images (avec option de mode manuel pour les forks). Le skill s'adapte aussi aux thèmes clair/sombre, aux viewports multiples (desktop, mobile), et peut comparer avec des maquettes Figma.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/davidamunga/ui-diff/tree/main/skills/ui-diff

Demander à votre IA préférée

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

Documentation

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 --head est 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.md pour les couleurs, tailles et espacements. Ne les estimez pas à partir des pixels. Si quelque chose est visible dans les images mais pas dans measured.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.sh pousse les images vers une branche ui-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 storageState est connecté avec un vrai compte. Obtenez un accord avant de publier.
  • post.cjs remplace 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.cjs uniquement si .ui-diff.json contient "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.cjs sans --base-url, puis open .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.md et 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).

Skills associés