UI 品質ワークベンチ
このスキルを使用して、ローカルの UI 走査 モジュールを実行します。ブラウザのワーカー内でデザイン画像と実装スクリーンショットを比較し、可視的な差異をレビュー候補としてグループ化し、人間の確認とエクスポートをサポートします。
アナライザはヒューリスティックです。その出力を 候補 または 可能性のある不一致 と呼び、人が意図されたデザイン、ルート、状態、コンテンツ、ビューポートを確認するまでは、未レビューの結果を確定した不具合として提示しないでください。
ワークベンチの起動
-
このスキルのディレクトリを選択した
SKILL.mdから解決します。リポジトリルートを想定したり、インストール場所をハードコードしないでください。 -
セッション内での初回起動前に、バンドルとローカルソースブリッジを確認します。
python3 <skill-directory>/scripts/serve_workbench.py --check -
サーバーを長時間実行プロセスとして起動します。
python3 <skill-directory>/scripts/serve_workbench.pyランチャーは、
event: "ready"、protocol: 2、動的なループバックURL、およびプロセスメタデータを含む1行のJSONを出力します。返されたURLをそのまま使用してください。そのフラグメントには、ブラウザアプリが使用する起動ごとのトークンが含まれています。 -
ブラウザ制御が利用可能で、ユーザーがインターフェースのオープンを希望する場合は、そのURLに移動します。それ以外の場合は、URLをユーザーに渡します。
-
ワークベンチの使用中はプロセスを起動したままにします。ユーザーが閉じるように要求した場合、またはセッションで不要になった場合は、
Ctrl+Cで停止します。
起動が EPERM または明示的なループバックソケット制限で失敗した場合は、ローカル実行権限を要求し、同じコマンドを再試行してください。バインドアドレスを変更したり、ホストされたコピーに置き換えたり、ローカルイメージを他の場所にアップロードしたりしないでください。
ソースの選択
ワークベンチには、1つのデザイン画像と1つの実装画像が必要です。各ソースの変更は以前の結果を無効にします。いずれかのソースを交換した後は、監査を再実行してください。
- ローカル画像: クリックして選択するか、PNG、JPEG、またはWebPを対応するデザイン/実装エリアにドラッグ＆ドロップします。デコード、ラスター比較、グループ化はローカルブラウザセッション内に留まります。
- Figmaフレーム: 1つの
node-idを含むFigmaのdesignまたはfileURLと、個人アクセストークン（PAT）を提供するか、FIGMA_ACCESS_TOKENを指定してランチャーを起動します。これにより、FigmaのAPIを通じてそのフレームのPNGレンダリングがインポートされます。ファイルを参照したり、Figmaログインを継承したりしません。 - Webキャプチャ: HTTP(S) URL、ビューポートサイズ、およびオプションのレンダリング待機時間を提供します。ブリッジは一時的なヘッドレスChrome/Chromium/Edgeプロファイルを起動し、そのビューポートをキャプチャします。ユーザーのブラウザプロファイル、クッキー、拡張機能、認証済みセッションを継承しません。
FigmaのインポートまたはWebキャプチャの操作またはトラブルシューティングを行う前に、references/source-imports.md をお読みください。
監査の実行とレビュー
- 両方のソースが、可能な限り同じルート、UI状態、ロケール、コンテンツ、ビューポート、スクロール位置を表していることを確認します。
- 表示されている正規化プレビューを確認します。エンジンは、より幅の広いソースをターゲット幅として使用し、それを1倍に保ち、より狭いソースのみをその幅に比例して拡大し、両方の画像を左上で揃えます。どちらのソースも引き伸ばしたりトリミングしたりせず、残った下部の高さの差は比較に残ります。
- 監査を開始します。ローカル分類の前に、ワーカーは正規化されたラスターが直接比較に適しているかどうかを確認します。比較可能性が低いペアは、候補を生成せずに停止します。中程度の比較可能性のペアは、明示的な警告とともに続行します。これは控えめなヒューリスティックゲートであり、確率や、どちらの画像が正しいかという意味的な判断ではありません。
- ビジュアル比較、リスト、詳細パネルで候補を検査します。片側のみの透明コンテンツは、領域の有無/レイアウトの差異としてのみ報告されます。曖昧なメディアまたはコンテンツの変更には、色、テキスト、アイコン、またはジオメトリの欠陥に強制する代わりに、中立的な表現が使用されます。アンチエイリアシング、フォントの読み込み、アニメーション、動的データ、レスポンシブ動作、または古いデザインが差異を説明しているかどうかを確認します。
- 確認された候補のみを確定します。実際の差異を意図的に無視する場合、または誤検知を却下する場合は、理由が必要です。
- 重要度と優先度を独立して割り当て、レビュー済みリストをエクスポートします。ピクセル領域や色距離だけで優先度を推測しないでください。
分類、優先順位付け、レビューステータスの変更、またはエクスポートするものを決定する際は、references/audit-model.md をお読みください。プライバシー、サポートされている統合、キャプチャ動作、または分析上の制限について説明する前に、references/v0-boundaries.md をお読みください。
主張を正確に保つ
- 比較エンジンは、固定コミット
beac836ba3c81b9a1d40bac8fe75af08444ab742におけるSemineChen/yangaoから、ユーザーから報告された著者の許可のもとに適合されています。THIRD_PARTY_NOTICES.md を参照してください。 - Figmaインポートには、PATとFigmaへのアウトバウンドアクセスが必要です。これはOAuth、アカウントリンク、デザイントークンの抽出、または一般的なFigmaファイルの解析ではありません。
- Webキャプチャは、隔離された現在のビューポートのスクリーンショットです。これは全ページのステッチ、インタラクティブブラウジング、ログイン状態の継承、DOM検査、または計算されたスタイルの抽出ではありません。
- ローカルブラウザ処理はセキュリティ認証ではありません。Figmaインポートは必然的にPATをFigmaに送信し、選択したフレームをダウンロードします。Webページキャプチャは必然的に指定されたURLを要求します。
- 比較可能性ゲートには、OCR、DOM、または製品セマンティクスはありません。大きく異なる入力を停止し、局所的な変更について警告することはできますが、2つの画面が同じルート/状態を表していることや、権威のある側を特定することはできません。
- UI 走査 は実装されたモジュールです。計画されているインタラクションエクスペリエンス、アクセシビリティ、またはコラボレーションモジュールがすでに実行されていると主張しないでください。