visual-qa-pixel-polish

name	visual-qa-pixel-polish
description	Web UIを実ブラウザとスクリーンショットで検査し、viewport・状態ごとの重なり、欠け、overflow、余白、整列、タイポグラフィ、色、コントラスト、hover・focus・disabledの視認性を、再現可能な証拠付きIssue Logへ落とし、修正batchと再検証まで実施する。実装済みUIの見た目を監査・修正したい時、リリース前のVisual QA、pixel polish、レスポンシブ崩れの検出に使う。mockup-to-codeでは、最終gate前の独立blind source reviewと、verdict後のUI/production readiness監査に使う。

Visual QA: Pixel Polish

実装済みUIを「好み」ではなく、再現条件と画像証拠で検査する。観測、修正、再検証を一つの閉じたループとして扱い、証拠が不足する状態を完了と呼ばない。

非交渉ルール

1. 実ブラウザで確認する。DOM/CSSの静的読解だけで合否を決めない。
2. 検査開始前に対象URL、ルート、状態、基準viewport、ブラウザ、zoom、themeを固定する。
3. Issueには必ず再現条件、Observation、Impact、Expected、Evidenceを含める。
4. severityは影響で決める。修正難易度、工数、好みで下げない。
5. 修正前の証拠がない問題を「修正済み」にしない。修正後は同一条件で比較する。
6. 一つのbatchで複数の独立原因を混ぜない。各batch後に再描画し、回帰を確認する。
7. 未確認viewport、未確認状態、推測原因を合格として扱わない。
8. ユーザーまたは責任者の明示承認なしにIssueをwaive/deferしない。
9. 実装者の自己採点と独立レビューを混ぜない。同一セッション、同一実装担当者、自己採点を見たレビューは blind と呼ばない。
10. adapted は合格理由ではない。source固有の物・記号・関係をgeneric shapeへ簡略化したものは、独立レビューで意味的同等性が確認されない限り missing/deviation として扱う。
11. UI欠陥、source fidelity、本番準備を一つの平均点や complete に畳み込まない。3判定を独立して報告する。
12. 証拠量を品質と混同しない。採用証拠は圧縮し、反復デバッグ画像は最終bundleから分離する。

参照ファイル

本ファイルだけで必須フローを実行できる。詳細が必要な時だけ次を読む。参照ファイルと本ファイルが競合する場合は、本ファイルのviewport、証拠、severity、batch、再検証、完了基準を優先する。

• checklist.md: OverlapからLegibilityまでの詳細パス
• issue-log-template.md: Issue Logと画像命名の雛形
• viewport-matrix.md: viewport、zoom、browserの拡張候補
• spacing-scale.md: 既存トークンがない場合の暫定余白基準
• typography-tuning.md: 文字組みの原因切り分け
• color-contrast.md: WCAGベースの測定
• css-root-causes.md: 症状からCSS原因を絞る辞書

0. スコープを固定する

開始時に次を記録する。

• 対象URLとルート一覧
• 対象コンポーネント、操作、状態: default、hover、focus、active、disabled、loading、empty、error、open/closed
• 対象ブラウザとtheme
• 既知の対象外と、その承認者またはユーザーの明示指示
• 実装変更の可否。review-onlyならIssue Log作成までで止める
• 目的: prototype visual QA | source comparison | production release。複数ならそれぞれの判定を出す
• 実装担当者、自己採点者、blind reviewer。独立reviewerを確保できない場合はblind reviewを not-run とする

対象外指定がなければ、画面に到達できる主要ルートと、その主要操作状態を対象にする。認証、データ、環境の不足で到達できない状態は推測せず、未検証として報告する。

1. Viewportテスト契約

必須マトリクス

少なくとも次の3条件を100% zoomで検査する。

Case	viewport	目的
V1	375x812	mobile基準、折返し、固定UI衝突、横overflow
V2	768x1024	tablet境界、grid/flex切替、ナビゲーション
V3	1440x900	desktop基準、container、余白、整列

さらに次を追加する。

• 主要breakpointの直前と直後。例: breakpointが768pxなら767pxと768px
• 対象プロダクトが明示する最小・最大対応幅
• text zoom 200%またはbrowser zoom 200%の主要ルート。使用した方式を記録する
• 崩れ探索用の125% zoom。基準viewportのうち少なくともmobileとdesktopで実施する
• Safari固有リスクがある、またはSafariが対応対象ならSafariのmobile相当とdesktop基準

production readinessを判定する場合は、tabletを768x1024の縦だけで代表させず、1024x768の横も追加する。breakpoint前後を含め、両向きで主要CTA、ナビゲーション、画像crop、本文行長を操作・目視確認する。

viewport名だけで証拠にしない。各runで実測した innerWidth x innerHeight、browser、zoom、device scale factorまたはDPR、theme、URL、状態、取得時刻をEvidence Indexへ記録する。ブラウザUIやDevToolsの開閉で実測値が変わった場合は実測値を正とする。

各viewportで必ず確認する項目

• 横スクロール、clipping、重なり、sticky/fixed要素との衝突
• header、main、footerと主要sectionの開始・終了
• 主要CTA、フォーム、メニュー、modal、tooltipの操作状態
• 長文、エラー、多桁数値、日英混在など可変コンテンツへの耐性
• focusの可視性と、固定要素によるfocus対象の隠れ

2. 証拠契約

検査開始時にEvidence Indexを作り、画像とIssueを一対多で追跡できるようにする。

必須証拠

• 各必須viewport・主要ルートのbaseline全景スクリーンショット
• 各Issueのcontext画像とclose-up画像
• box model、overflow、stacking context、contrastなど原因確認が必要な場合のDevTools画像または測定値
• 修正後の同一URL・同一状態・同一実測viewport・同一zoomによるafter画像
• batch後の回帰確認結果。問題なしの場合も、確認したcase IDを記録する

ファイル名は {route}_{state}_{issue-or-baseline}_{viewport}_{zoom}_{browser}_{before|after}.{png|webp|jpg} とする。画像加工で欠陥を隠さない。切り抜きはcontext画像への参照を残す。スクリーンショットを保存できない場合は完了とせず、制約と代替証拠を報告する。

Evidence Indexの最小列:

evidence_id | case_id | URL/route | state | measured viewport | zoom | browser | theme | before/after | file path | related issue

証拠圧縮とreview bundle

• 各route/viewportの全景を、case ID・実測viewport・stateが読めるcontact sheetへまとめ、最初のreview索引にする
• completion bundleはcontact sheet、各open/fixed Issueのcontext/close-up、必要な測定値、最終回帰だけを含める
• PNG losslessはpixel/contrastなど数値判定に必要なcropだけに使う。目視用全景・cropはWebPまたは高品質JPEGを標準とし、寸法と圧縮条件を記録する
• discarded iteration、重複全景、DevTools探索画像は debug/ へ分離する。Issueの根拠になったものだけcompletion bundleへ昇格する
• contact sheetは索引であり、欠陥を隠す縮小画像を唯一の根拠にしない。Issueから原寸context/close-upへ辿れるようにする

3. Source-specific detail inventoryとblind crop review

参照カンプ、仕様画像、またはmockup-to-code handoffがある場合に実施する。全景の印象だけで終わらせず、sourceを見て先にdetail inventoryを作る。出力を見てから都合よく項目を減らさない。

inventoryの最小列:

detail_id | source section/crop | source固有の物・copy・motif・関係 | semantic role | criticality | output crop | implementer disposition | blind disposition | issue/handoff

• source固有 は「装飾」「写真」のような一般語ではなく、端末、ノート、人物シルエット、多重流線、固有アイコン、copyの強弱、要素間の位置関係まで列挙する
• 各項目を matched | equivalent | adapted | missing | not-applicable で記録する。not-applicable には仕様根拠、adapted には媒体差と意味保存の説明が必要
• 固有device/icon/motifをgeneric shapeへ置換、複数の独立場面を一枚の共通素材へ統合、前景HTMLまでgenerated-media maskに含めた場合は自動で adapted 合格にしない
• criticalな adapted/missing はblind reviewが needs-work。非criticalな adapted も、意味・識別性・構図上の役割が保たれたことを独立reviewerが承認して初めてacceptedにできる

blind reviewerには、正規化したsource crop、同条件の最終output crop、detail IDだけを渡す。実装者スコア、box/pixel pass率、waiver、adapted 宣言、実装説明は判定後まで渡さない。crop順序を固定またはランダム化し、contact sheetには採点を誘導する語を入れない。reviewerはinventory coverage、各detail disposition、セクションスコア、観測理由を返す。

実装者は自己採点を残してよいが implementer score と明記する。blind scoreとの差が1/10点（10/100点）以上、またはdispositionが不一致なら低い判定を採用してIssue/handoffを開く。独立reviewerがいない場合、source reviewは not-run であり自己採点で代用しない。

4. 検査パス

各caseを次の順で一巡する。前段のP0を発見したら記録し、重大な操作不能が後段検査を妨げる場合はそのcaseをblockedとして先に修正する。

1. Overlap / clipping / overflow / missing content
2. Spacing / rhythm
3. Alignment / grid / baseline
4. Typography / wrapping / line-height / optical centering
5. Color / contrast / interactive states
6. Legibility / hierarchy / variable-content stress

詳細観点は checklist.md を使う。デザインシステムや受入仕様がある場合はそれをExpectedの第一根拠にし、なければ同種コンポーネントの一貫性、既存トークン、WCAG、参照ファイルの順で根拠を選ぶ。

5. P0-P2判定契約

Severity	判定条件	リリース扱い
P0	内容や操作が失われる。押せない、読めない、見えない、重大な重なり・欠け・横overflow、modal/menu/focusが隠れて主要タスクを完了できない	release blocker。最優先で単独修正し、該当caseと必須マトリクスを再検証する
P1	タスクは完了できるが、仕様・デザインシステム・可読性基準から明確に外れる。顕著な余白・整列・折返し・タイポ・コントラスト・状態差の破綻	完了前に修正必須。未修正ならneeds-work
P2	可読性や操作性を損なわない軽微な不統一、1px級の光学調整、仕上げ	修正するか、ユーザー/責任者の明示承認でdeferする

迷う場合は、同じ条件で再現し、ユーザータスクへの影響とExpectedの根拠を追加してから決める。複数条件でseverityが異なる場合は最も重い再現結果をIssueのseverityとする。同一根本原因でも影響が異なる場合は、最も重いIssueを親にして影響範囲を列挙する。

6. Issue Log契約

Issueごとに次を埋める。空欄のIssueは修正batchへ入れない。

• ID、Severity、Status
• URL、画面、component、状態、再現手順
• case ID、実測viewport、zoom、browser、theme
• Observation: 観測事実だけを書く
• Impact: 可読性、操作性、理解、品質への影響を書く
• Expected: 仕様、トークン、同種要素、WCAGなど根拠付きで書く
• Evidence: beforeのcontext、close-up、必要な測定値
• Suspected cause: 推測であることを明示する
• Fix scope: 最小の変更面と影響候補
• Verification: 再実行するtarget caseとregression case

同じ根本原因の反復はcomponent Issueにまとめ、影響ルートとcaseを列挙する。見た目が似ていても根本原因が別なら分ける。

7. 修正batch契約

修正権限がある場合だけ実施する。1 batchは「一つの根本原因」かつ最大3 Issueに制限する。

1. P0を先に処理する。P0は原則1 Issueで1 batch。同じ変更で不可分な同根P0だけまとめてよい。
2. batch前に対象Issue、変更ファイル、期待する見た目、target case、regression caseを宣言する。
3. 最小差分で修正する。無関係なリファクタ、デザイン変更、依存更新を混ぜない。
4. 修正直後にtarget caseを同一条件で再現し、after証拠を保存する。
5. targetが通ったら、影響componentが現れる全必須viewportと隣接状態を回帰確認する。
6. 新規P0/P1、別viewportの崩れ、意図しない差分が出たらbatchを失敗として記録し、次batchへ進まず修正またはrevert方針を決める。
7. batchの結果を passed | failed | blocked で記録する。画像を見ずにpassedにしない。

8. 再検証契約

Issueをfixedにするには、次をすべて満たす。

• before条件で問題が再現できていた
• afterでObservationが解消し、Expectedを満たした
• 同一componentの必須viewportで回帰がない
• 関連するhover、focus、disabled、open/closed、errorなど隣接状態で回帰がない
• before/afterと回帰caseがEvidence Indexから辿れる

全batch終了後に、変更を加えた最終状態で必須マトリクスを最初から通す。途中batchのスクリーンショットを最終合格証拠として流用しない。

9. mockup-to-code後段QA接続契約

mockup-to-code との接続は役割で分ける。独立blind source reviewは忠実度QAの証拠が固定された後・最終completion gateの前に行い、その結果をgateへ返す。UI pixel-polishとproduction readinessはcompletion verdict後に行う。入力として、最終render、対象URL、manifest、crop-pair/box/pixel evidence、利用可能なverdict、既知の残差を受け取る。

このスキルが担当するのは、その最終実装に残るUI欠陥の検出と修正だけである。

• 担当する: responsive崩れ、overflow、重なり、可読性、操作状態、実装一貫性、ブラウザ差、可変コンテンツ耐性
• 担当しない: comp忠実度の採点、bbox/pixel差の再判定、asset生成・分解、manifestの作り直し、mockup-to-code verdictの上書き
• 忠実度QAが未完了、またはverdictがblockedなら開始しない。元工程へ返す
• 本QAで見つけた欠陥がcompとの差に由来していても、忠実度Issueへ自己変換しない。UI欠陥として証拠化し、必要なら元工程へのhandoffを付ける
• pixel polishの変更がcomp忠実度に影響し得る場合は、変更後にmockup-to-code側の該当fidelity gateを再実行するようhandoffし、その結果がない限り両工程完了とは報告しない

detail inventoryとblind crop reviewはmockup-to-code verdictを上書きするためではなく、自己採点やcoverageの空洞を独立に検出する監査面である。disposition不一致は source-review handoff として元工程へ返し、Visual UI Issueと混同しない。generated mediaやadaptedを理由にsource固有detailをinventoryから除外しない。

10. Production readiness別判定

production release が目的に含まれる場合だけ ready | not-ready | blocked を判定する。Visual UIがcompleteでも自動的にreadyにはしない。少なくとも次を別checklistとして証拠化する。

• 画像配信: 全画像のformat・実バイト・表示寸法・intrinsic寸法・loading・srcset/sizes・適用可能なwidth/heightをinventory化する。明示されたperformance budgetとLCP方針がなく、FV以外の遅延読込や適正サイズ配信を確認できない場合は not-ready
• CTA/導線: primary/secondary CTAとnavigationのlink mapを作り、期待destinationと実際のresolved URLを照合する。#、空href、placeholder、JS no-op、意図しない同一ページanchorは実リンクとして数えない。外部環境不足で到達確認できなければ blocked または not-ready
• tablet: 768x1024と1024x768、主要breakpoint前後で操作を含む証拠を残す。単なるwidth sweepやoverflowなしだけでは合格にしない
• a11y: automated scanに加え、keyboard順序、focus visible/obscured、主要コントラスト、200% text/browser zoom、見出し・landmark・名前/role/valueを手動確認する。ツール未実行や主要項目未測定を「配慮済み」で代用しない

予算や期待URLが未定なら推測で合格させず not-ready: contract missing とする。prototype scopeで判定を依頼されていない場合は not-assessed とし、ready と同義に扱わない。

11. 完了基準

Visual UI判定は、次をすべて満たす場合だけ complete と報告する。

• スコープ内の必須ルート、状態、viewport matrixを最終状態で実行済み
• openのP0/P1が0件
• P2はfixed、またはユーザー/責任者がIssue単位で明示承認したdeferredのみ
• 全fixed Issueに同一条件のbefore/after証拠がある
• 全batchがpassedで、最終回帰に新規P0/P1がない
• Evidence Index、Issue Log、batch log、未検証範囲が相互参照できる
• browser、認証、データなどの制約で必須caseが欠けていない

一つでも欠ける場合は needs-work または blocked とし、欠けたcase、未解決Issue、必要な次アクションを列挙する。確認できた範囲だけをもって全体完了としない。

source参照がある場合は、これとは別にblind source reviewを pass | needs-work | not-run で報告する。production releaseが目的なら、さらにProduction readinessが ready でなければ全体を「release complete」と呼ばない。prototypeでは Visual UI: complete / Source: not-run / Production: not-assessed のように各面をそのまま併記する。

最終報告

次の順で簡潔に報告する。

1. 判定3面: Visual UI: complete | needs-work | blocked、Blind source review: pass | needs-work | not-run | not-applicable、Production readiness: ready | not-ready | blocked | not-assessed
2. Scopeと実行したviewport/browser/state
3. Issue集計: P0/P1/P2のfound、fixed、open、deferred
4. detail inventory coverage、implementer/blind score、disposition不一致とhandoff
5. production checklist: image budget、CTA link map、tablet、a11y
6. 修正batchと検証結果
7. contact sheet、Evidence Index、主要before/afterへのパス
8. 未検証範囲、制約、明示承認されたdeferred

外部基準としてWCAG 2.2を使う場合は、該当Success CriterionをIssueのExpectedに記載する: https://www.w3.org/TR/WCAG22/。