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> を実行してアセットブランチから画像を削除します(誰かがまだコメントを必要とする可能性がある場合は事前に確認します)。