| 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を「好み」ではなく、再現条件と画像証拠で検査する。観測、修正、再検証を一つの閉じたループとして扱い、証拠が不足する状態を完了と呼ばない。
非交渉ルール
- 実ブラウザで確認する。DOM/CSSの静的読解だけで合否を決めない。
- 検査開始前に対象URL、ルート、状態、基準viewport、ブラウザ、zoom、themeを固定する。
- Issueには必ず再現条件、Observation、Impact、Expected、Evidenceを含める。
- severityは影響で決める。修正難易度、工数、好みで下げない。
- 修正前の証拠がない問題を「修正済み」にしない。修正後は同一条件で比較する。
- 一つのbatchで複数の独立原因を混ぜない。各batch後に再描画し、回帰を確認する。
- 未確認viewport、未確認状態、推測原因を合格として扱わない。
- ユーザーまたは責任者の明示承認なしにIssueをwaive/deferしない。
- 実装者の自己採点と独立レビューを混ぜない。同一セッション、同一実装担当者、自己採点を見たレビューは
blind と呼ばない。
adapted は合格理由ではない。source固有の物・記号・関係をgeneric shapeへ簡略化したものは、独立レビューで意味的同等性が確認されない限り missing/deviation として扱う。- UI欠陥、source fidelity、本番準備を一つの平均点や
complete に畳み込まない。3判定を独立して報告する。
- 証拠量を品質と混同しない。採用証拠は圧縮し、反復デバッグ画像は最終bundleから分離する。
参照ファイル
本ファイルだけで必須フローを実行できる。詳細が必要な時だけ次を読む。参照ファイルと本ファイルが競合する場合は、本ファイルのviewport、証拠、severity、batch、再検証、完了基準を優先する。
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として先に修正する。
- Overlap / clipping / overflow / missing content
- Spacing / rhythm
- Alignment / grid / baseline
- Typography / wrapping / line-height / optical centering
- Color / contrast / interactive states
- 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に制限する。
- P0を先に処理する。P0は原則1 Issueで1 batch。同じ変更で不可分な同根P0だけまとめてよい。
- batch前に対象Issue、変更ファイル、期待する見た目、target case、regression caseを宣言する。
- 最小差分で修正する。無関係なリファクタ、デザイン変更、依存更新を混ぜない。
- 修正直後にtarget caseを同一条件で再現し、after証拠を保存する。
- targetが通ったら、影響componentが現れる全必須viewportと隣接状態を回帰確認する。
- 新規P0/P1、別viewportの崩れ、意図しない差分が出たらbatchを失敗として記録し、次batchへ進まず修正またはrevert方針を決める。
- 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 のように各面をそのまま併記する。
最終報告
次の順で簡潔に報告する。
- 判定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
- Scopeと実行したviewport/browser/state
- Issue集計: P0/P1/P2のfound、fixed、open、deferred
- detail inventory coverage、implementer/blind score、disposition不一致とhandoff
- production checklist: image budget、CTA link map、tablet、a11y
- 修正batchと検証結果
- contact sheet、Evidence Index、主要before/afterへのパス
- 未検証範囲、制約、明示承認されたdeferred
外部基準としてWCAG 2.2を使う場合は、該当Success CriterionをIssueのExpectedに記載する: https://www.w3.org/TR/WCAG22/。
