Communitygithub.com

UI差分

プルリクエストのビジュアル・UI・UXへの影響を一目で確認できます。ベースとヘッドのコミットでWebアプリの該当ページをレンダリングし、スクリーンショットをピクセル単位で比較、正確なスタイル変更(色、余白、タイポグラフィ、コントラスト)を測定し、デザイナーやレビュアー向けの平易なサマリーを生成、プルリクエストにBefore/After画像をコメントまたは説明として投稿します。「スクリーンショットをPRに追加」「このPRの見た目は?」「ビジュアル差分」「before/after」「デザインレビュー」「CSSの変更で何か壊れた?」「UIの変更を見せて」「ビジュアルリグレッションチェック」といったリクエストに最適です。

UI差分 とは?

このスキルは、プルリクエストのフロントエンド変更による視覚的な影響を自動的に評価・報告するツールです。開発者が「このPRはどのように見えるか」をレビュアーに伝えたいときや、デザインレビューを依頼したいときに使用します。主な機能は、PRのベースブランチとヘッドブランチの両方でWebアプリをレンダリングし、全画面・ズーム画像をキャプチャ、ピクセルレベルの差分を計算、実際のスタイルプロパティ(色、サイズ、間隔、フォント、コントラスト)の変化を測定、そして視覚的な変更点を自然言語でまとめたサマリーを生成し、Before/After画像とともにPRにコメントまたは説明として投稿します。React、Next.js、Vue、Nuxt、Svelte、Angular、Astro、プレーンHTMLなど、ローカル開発サーバーで動作するあらゆるWebアプリに対応しています。Storybookと組み合わせてコンポーネント単位の差分も取得でき、デスクトップ・モバイル両方のビューポート、ライト/ダークモードに対応。アクセシビリティ違反(axe-core)の自動チェックも行います。このスキルはClaude Code / Codex環境で動作し、gh、git、Node.js、Playwrightを内部的に使用します。ユーザーはどのページをチェックするか、変更の意味を解釈するか、投稿先を決めるといった判断を行う必要があります。

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

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

UI差分 は何をしますか?

レビュアーはCSSの差分を読めても、実際の見た目を確認できません。このスキルは、PRのベースとヘッドでアプリをレンダリングし、比較し、Before/After画像をPRに投稿します。さらに、ユーザーにとって何が変わったかを、測定値に基づいた短いサマリーで示します。

機械的な作業は単一のスクリプトで行われます。あなたの役割は、判断が必要な部分です:どのページをチェックするか、変更の意味、どこに投稿するか。

$SKILLはこのSKILL.mdを含むディレクトリを指します。例:SKILL=/path/to/skills/ui-diffのように一度設定します。すべての出力はリポジトリルートの.ui-diff/に書き込まれ、スクリプトはこれをローカルで.gitignoreするため、追跡されるファイルは変更されません。

1. コンテキスト

gh pr view --json number,url,baseRefName,headRefOid,body 2>/dev/null; git status --short

リポジトリルートに.ui-diff.jsonがあれば読み込みます。ルート、開発コマンド、マスク、認証情報が含まれている可能性があります(references/config.md参照)。

レンダリングするヘッドはユーザーの操作内容によって異なります:

  • PRに投稿する場合: --head <headRefOid> を指定して、プッシュされた内容を正確にレンダリングします。そうしないと、未コミットのローカル編集がPRを主張するレポートに含まれてしまいます。ワーキングツリーがダーティまたは未プッシュのコミットがある場合は、その変更が反映されないことを伝えます。
  • 作業中の確認(「これで正しく見えるか?」)の場合: ワーキングツリーを使用します(デフォルト、--headなし)。レポートには「+ 未コミットの変更」と表示されます。

2. ページの選択

node $SKILL/scripts/routes.cjs --base <base> --log   # run.shに渡す場合は --head <sha> を追加

変更されたファイルをルートにマッピングします:ページファイル、変更されたレイアウト下のルート、変更されたコンポーネントをインポートするページ(エイリアスとワークスペースパッケージを辿る)、ホームおよびアプリ全体のスタイルに関連するいくつかのページ。各ルートの理由と信頼度、needsExample(動的ルートで補完できないもの)、unmatched(配置できなかったUIファイル)をJSONで出力します。これを開始リストとして使用し、references/route-mapping.mdを参考に判断を適用します:差分がサポートしない低信頼度の選択は除外し、needsExampleのIDを探し、unmatchedファイルは自分で配置します。UI関連の変更がない場合(すべてのファイルが ignored)、その旨を伝えて停止します。空のレポートは生成しないでください。

Storybookプロジェクト(.storybook/フォルダまたは storybook スクリプトがある場合):変更が主にコンポーネントである場合は、run.sh --storybook を使用してページの代わりにストーリーの差分を取得します。これにより、変更されたファイルから自動的にストーリーが選択されます。ルート、レイアウト、アプリレベルのスタイルの場合は、ページを使用します。詳細は references/route-mapping.md のStorybookセクションを参照してください。

どのルートをキャプチャするか、その理由を1〜2行でユーザーに伝え、続行します。ルートが見つからない場合、または動的ルートに必要なIDが見つからない場合にのみ質問してください。影響を受けるがキャプチャされないルート(多すぎてチェックできない、ログインが必要、モーダル状態が必要など)を追跡します。これらはサマリーに含め、「視覚的変更なし」が安全確認と誤解されないようにします。

3. 実行

bash $SKILL/scripts/run.sh --routes "/,/pricing" [--head <sha>] [--base <ref>] \
  [--viewports "desktop:1440x900,mobile:iPhone 13"] [--schemes light,dark] [--dev "<cmd with {port}>"]

(--auto-routes は routes.cjs が選択したルートを理由とともに追加します。修正する必要がない場合に使用します。)

一度の実行で:

  • 初回使用時にツールをインストールします(~/.cache/ui-diff にPlaywright + Chromium、約1分;プロジェクトの依存関係には影響しません);
  • git worktreeを使用してベースとヘッド(--head が指定された場合)をチェックアウトし、追跡されていない .env* ファイルをコピーします;
  • lockfileが一致する場合はインストール済みの依存関係を再利用し、それ以外の場合はインストールします。チェックアウトごとにビルドキャッシュがあります;
  • 空いているポートで両方の開発サーバーを独自のプロセスグループで起動します。その後、それらのサーバーのみが停止され、ユーザーの他のサーバーには影響しません;
  • すべてのルート×ビューポートをキャプチャします。モバイルは実際のデバイスエミュレーション(タッチ、モバイルUA)を使用します。アニメーションはフリーズされ、フレームワークの開発オーバーレイは非表示になります;
  • スクリーンショットをピクセル差分します(results.json、全ページおよびズーム画像)、および計算されたスタイルの差分(measured.md)を実行します。

Storybookモード(--storybook、または --stories "button--primary,card--*" で自分で選択)は、開発サーバーの代わりにStorybookを起動し、選択したストーリーとその理由をログに記録し、結果をストーリーIDで命名します。一致するストーリーがない場合は終了し、IDを提案します。

{"changed":2,"added":1,"unchanged":3,...} のようなカウントを出力します。デフォルト:base = PRのベースブランチ(それ以外はデフォルトブランチ)、viewports = デスクトップ1440×900 + iPhone 13、ライトモード。テーマ、色、トークンに変更がある場合は --schemes light,dark を追加します。

失敗した場合、エラーはどのステップで失敗したか、そのログの場所(.ui-diff/server-*.log、install-*.log、capture-*.log)を示します。一般的な原因は、不足している環境変数、誤った開発コマンド(--dev を渡す)、またはワーキングツリーにインストールされていない依存関係です。原因を修正して再実行してください。片側だけスキップしないでください。

4. 結果の読み取りとサマリーの作成

最初に .ui-diff/report/measured.md を読み取ります。「考えられる問題」で始まる場合は、まずそれらを確認します:クリップされたテキスト、横スクロール、重なり、画面外のコントロール、小さいモバイルタップターゲット、およびヘッドで新しく発生したaxe-coreアクセシビリティ違反。これらはヒューリスティックなので、各ズーム画像(report/issues/)を開いて判断します。実際の問題は「一見の価値あり」に先頭に配置し、意図的と思われるものは削除またはトーンを和らげます。measured.md の残りの部分は測定された事実です:要素全体でグループ化された計算スタイルの変更、サイズ変更された要素、レイアウトのシフト、コピーの変更、および新しいWCAGコントラスト違反。次に、ズーム画像(report/zoom/*__after.png と __before.png)と差分オーバーレイを、任意のファイルまたは画像表示ツールで開き、それらの事実がコンテキストでどのように見えるかを確認します。画像を表示できない場合は、measured.md だけからサマリーを作成し、スクリーンショットがレビューされなかったことを伝えます。results.json の warnings(HTTPエラー、フレームワークエラーオーバーレイ、キャッチされない例外)も確認します。

Figmaリンクが指定されている場合(または .ui-diff.json のルートに figma がある場合)?ヘッドをデザインフレームと比較します。references/figma.md に従ってください。

コードを読まないデザイナーやPM向けに .ui-diff/report/summary.md を作成します:

**変更内容**
- **料金カード** — CTAボタンがピル型に(radius 4 → 999px)、パディング増加(8×14 → 12×20px);Proカードがハイライト表示(2px `#2563EB` ボーダー、`#EFF6FF` 背景)に「Most popular」ラベル。
- **ヘッダー(全ページ)** — ナビゲーションリンクが青 `#2563EB` からグレー `#9CA3AF` に。

**一見の価値あり**
- ⚠️ ナビゲーションリンクのコントラストが白背景で2.5:1(以前は5.2:1);本文テキストは4.5:1必要。
- ⚠️ `/settings` はどのファイルも変更されていないのに変化あり — 新しい `Button` のパディングを継承し、「Save」/「Cancel」がモバイルで折り返し。

**未チェック:** `/admin/*`(ログイン必要)、アカウント削除モーダル。

ガイドライン:

  • 測定値を measured.md から色、サイズ、間隔に使用します。ピクセルから推定しないでください。画像で見えるが measured.md にないもの(画像、キャンバス、SVGコンテンツ)は、見たまま説明します。
  • 大きなピクセル変更率と「shifted … layout shift」行は、通常、すべてが変更されたのではなく、コンテンツが押し下げられたことを意味します。そのように説明します。
  • 「一見の価値あり」は意図しない可能性が高い変更を先頭に:ファイルが変更されていないのに変更されたページ、1つのビューポートだけで壊れている、オーバーフロー、消えた要素、ページエラー。次にコントラスト違反と小さいタップターゲット(モバイルで約44px未満)。
  • 「変更された」とは言っても「意図的に変更された」とは言いません。何が変更されたかは見えても、理由は見えません。
  • 比例性を保ちます。1色の調整には1つの箇条書き。

次に、node $SKILL/scripts/viewer.cjs --report .ui-diff/report を実行してローカルレビューページ(report/index.html:スライダー、サイドバイサイド、差分オーバーレイ、上部にサマリー)を更新し、ユーザーに開くよう提案します(macOSは open、Linuxは xdg-open)。

5. 公開

投稿は共有PRに書き込み、ブランチをプッシュします。まずユーザーにサマリーを表示して確認を取ります。ただし、ユーザーのリクエストがすでに投稿を指示している場合は除きます。その後:

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   # または --mode description
  • publish.sh は画像を ui-diff-assets ブランチにプッシュします(1つのコミット、公開のたびに置き換え)。一時クローンから実行されます。画像はGitHub上でインライン表示され、プライベートリポジトリでも読み取りアクセスを持つすべてのユーザーに対して表示されます。
    • 終了コード3 はプッシュアクセスがないことを意味します(通常はフォークからのPR)。手動モードに切り替えます。
    • リポジトリが公開であると通知された場合、スクリーンショットが公開されることをユーザーに伝えます。storageState が実アカウントとしてログインしている場合に最も重要です。投稿前に確認を得ます。
  • post.cjs は、以前のui-diffコメントまたは説明セクションを新しいもので置き換え、新しいものを重ねません。説明の他の部分はそのまま残ります。
  • comment.cjs に --approval を追加するのは、.ui-diff.json に "requireApproval": true がある場合のみです(リポジトリがデザインレビューワークフローを実行している場合)。「デザイン承認済み」ボックスを追加します。
  • 手動モード(アセットブランチがない、またはプッシュアクセスがない場合):--base-url なしで comment.cjs を実行し、その後 open .ui-diff/report を実行します。ユーザーが画像をPRコメントボックスにドラッグします(GitHubにはそのアップロード用のAPIはありません)。どの画像がどこにあるかをユーザーに伝えます。
  • まだPRがない場合: .ui-diff/comment.md を保持し、PRが開かれたときに説明に配置することを提案します。

6. 終了処理

リンク、カウント、および「一見の価値あり」項目を報告します。開発コマンド、ルート、マスク、動的IDを自分で特定した場合は、.ui-diff.json に保存して次回の実行が1ステップで済むように提案します。PRがマージまたはクローズされたら、bash $SKILL/scripts/prune.sh <pr> を実行してアセットブランチから画像を削除します(誰かがまだコメントを必要とする可能性がある場合は事前に確認します)。

関連スキル