visual-qa

ビジュアル QA

ビジョンモデルを使って、スクリーンショットをデザイン意図と照らし合わせてセルフレビューします。リリース前に、余白の問題、配置のずれ、色の不統一、レスポンシブ対応の不具合、アクセシビリティの不足を見つけます。

使用するタイミング

• ユーザーから「このデザインをレビューして」や「このスクリーンショットを確認して」と頼まれたとき
• ページやコンポーネントを構築した後、リリースする前
• 実装とモックアップ／参考デザインを比較したいとき
• ユーザーから「これでよさそう？」や「どこがおかしい？」と聞かれたとき
• ビルドワークフローにおける自動デザイン QA のステップ

基本理念

• まずスクリーンショットを確認し、それから評価します。 コードだけでなく、実際にレンダリングされた出力を必ず確認します。
• 具体的に伝えます。 「余白が変です」では役に立ちません。「見出しと段落の間隔は 32px ですが、周囲の余白のリズムに合わせるなら 16px にするべきです」なら役に立ちます。
• 影響度を優先します。 すべてのピクセルが重要なわけではありません。ユーザーが実際に気づく点に注目します。
• デザイン意図を参照します。 デザイントークン、モックアップ、明示されたデザイン目標と比較します。

---

レビュー方法

ステップ 1：スクリーンショットを撮る

次のいずれかの方法でスクリーンショットを取得します。

ブラウザツールを使用：

browser: screenshot (captures the current page)

node による画面キャプチャを使用（利用可能な場合）：

nodes: screen_record

Peekaboo を使用（macOS）：

exec: peekaboo screenshot

ユーザーから提供： ユーザーがスクリーンショットを直接貼り付けたり、添付したりする場合があります。

ステップ 2：ビジョンで分析する

image ツールを使ってスクリーンショットを分析します。

image: [path or URL to screenshot]
prompt: "Review this UI screenshot for design quality..."

ステップ 3：構造化レビュー

次のカテゴリを優先度の高い順に、スクリーンショットと照らし合わせて分析します。

---

レビューカテゴリ

1. レイアウトと余白

確認項目：

• 余白のリズムが一貫しているか（すべてがスペーシンググリッドに沿っているか）
• 配置 — 揃えるべき要素が実際に揃っているか
• 類似するコンポーネント間でパディングが一貫しているか
• コンテナの幅と最大幅
• レスポンシブ動作（複数のビューポートのスクリーンショットがある場合）

よくある問題：

• カード内のパディングが一貫していない（例：上部が 24px、左右が 16px）
• 要素がグリッドからわずかにずれている（16px ではなく 15px）
• テキストが隣接する要素と揃っていない
• セクション間の垂直方向の余白が大きく異なる

2. タイポグラフィ

確認項目：

• 階層 — 見出し、本文、キャプションの区別が明確か
• 行の長さ — 本文は 1 行あたり 45～75 文字に収めるべきです
• 行間 — フォントサイズに対して狭すぎたり、広すぎたりしないか
• フォントの太さ — 同じ役割に同じ太さが一貫して使われているか
• オーファン／ウィドウ — 見出しの行に単語が 1 つだけ残っていないか

よくある問題：

• 見出しらしく見えない見出し（太さ／サイズが本文に近すぎる）
• 本文の行の長さが 80 文字を超えている（読みにくい）
• セクション間で見出しのサイズが一貫していない
• 字間を調整せずにすべて大文字にしたテキスト

3. 色とコントラスト

確認項目：

• テキストと背景のコントラスト（読みやすく見えるか）
• ブランドカラーが一貫して使われているか
• 色の意味が一貫しているか（リンクとエラーの両方に同じ青が使われていないか）
• ダークモードの問題（該当する場合）
• ホバー／アクティブ状態が視認できるか

よくある問題：

• 白い背景に薄いグレーのテキスト（コントラスト不足）
• プライマリーカラーが多くの異なる用途に使われている
• ほとんど見えない境界線
• ステータスカラーの意味が矛盾している（危険を緑、成功を赤で示している）

4. ビジュアル階層

確認項目：

• 視線の流れ — 最初にどこへ目が行くか。それは適切か
• CTA の目立ちやすさ — 主なアクションが最も目立つ要素になっているか
• 情報密度 — まばらすぎたり、詰め込みすぎたりしていないか
• グルーピング — 関連する項目が視覚的にまとめられているか
• 余白 — 意図的に使われているか、それとも単に余っただけか

よくある問題：

• 目立ち方が同じ 2 つの CTA が注意を奪い合っている
• 重要な情報が、重要度の低い要素の下に埋もれている
• セクション同士のつながりが感じられない
• 視覚的な区切りがない、テキストが密集した塊

5. コンポーネントの品質

確認項目：

• ボタンのサイズとパディングの一貫性
• 入力フィールドのスタイルの一貫性
• カードのスタイルの一貫性（シャドウ、枠線、角丸）
• アイコンのサイズとテキストとの位置合わせ
• 画像のアスペクト比とトリミング

よくある問題：

• パディングや高さに一貫性のないボタン
• 角丸の値が混在している（8px、12px、4px など）
• アイコンが隣接するテキストのベースラインとずれている
• 画像が引き伸ばされている、またはトリミングが適切でない

6. 仕上げと細部

確認項目：

• ホバー状態があり、視認できる
• キーボード操作時のフォーカス状態
• ローディング状態（スケルトン画面、スピナー）
• 空の状態（データがない場合に何が表示されるか）
• 状態間の遷移（急激か、滑らかか）
• ファビコンとOG画像（ページ全体をレビューする場合）

よくある問題：

• インタラクティブな要素にホバー状態がない
• フォーカスリングが削除され、代替表示もない
• データの読み込み時にコンテンツが急激にずれる
• 空の状態がなく、空白の領域だけが表示される

7. レスポンシブ表示の問題（複数のビューポートを利用できる場合）

確認項目：

• モバイルでコンテンツを読みやすい（小さすぎない）
• モバイルでタッチターゲットが44px以上
• 小さな画面でもナビゲーションにアクセスできる
• 画像がコンテナからはみ出していない
• 水平スクロール（ほとんどの場合、バグです）

---

出力形式

詳細レビュー

### Visual QA Review

**Overall impression:** [One sentence — first gut reaction]
**Quality score:** [1-10] / 10

#### 🔴 Critical Issues (fix before shipping)
1. **[Category]:** [Specific issue with exact details]
   → **Fix:** [Actionable recommendation]

#### 🟡 Improvements (should fix)
1. **[Category]:** [Specific issue]
   → **Fix:** [Recommendation]

#### 🟢 Minor Polish (nice to fix)
1. **[Category]:** [Specific issue]
   → **Fix:** [Recommendation]

#### ✅ What's Working Well
- [Specific praise — what's well-executed]
- [Another positive]

簡易レビュー

### Quick QA: [Page/Component Name]

Score: [X]/10

Top 3 fixes:
1. [Most impactful issue + fix]
2. [Second issue + fix]
3. [Third issue + fix]

Looks good: [What's working]

比較レビュー（実装とモックアップ）

### Design vs Implementation Review

**Fidelity score:** [1-10] / 10

#### Deviations Found
1. **[Element]:** Mockup shows [X], implementation has [Y]
   Impact: [High/Medium/Low]
   → **Fix:** [How to match the mockup]

#### Matching Well
- [Elements that accurately match the design]

---

ビジョンモデル向けレビュー用プロンプト

必要に応じて、以下のプロンプトをimageツールと組み合わせて使用してください。

一般的なレビュー

Review this UI screenshot for design quality. Check spacing consistency,
typography hierarchy, color contrast, visual hierarchy, and component
quality. Be specific about issues — reference exact elements and suggest
fixes. Prioritize by impact.

間隔とレイアウトに注目したレビュー

Analyze the spacing and layout of this UI. Check if elements follow a
consistent spacing grid, if padding within similar components matches,
if alignment is correct, and if the overall spacing rhythm feels right.
Note any elements that appear off-grid or inconsistently spaced.

比較レビュー

Compare these two images. The first is the design mockup, the second is
the implementation. Identify every deviation — differences in spacing,
color, typography, alignment, or missing elements. Rate the fidelity
on a 1-10 scale.

レスポンシブ表示の確認

Review this mobile screenshot for responsive design quality. Check that
text is readable, touch targets are large enough (≥44px), nothing
overflows the viewport, and the layout adapts well to the narrow width.

アクセシビリティに注目したレビュー

Review this UI screenshot for visual accessibility. Check text contrast
against backgrounds, focus indicator visibility, touch target sizes,
color-only information (anything that relies solely on color to convey
meaning), and text readability at the shown sizes.

---

ビルドワークフローとの統合

コンポーネントのビルド後

1. ブラウザーでコンポーネントをレンダリングする
2. スクリーンショットを撮る
3. ビジュアルQAレビューを実施する
4. 問題を修正する
5. 再度スクリーンショットを撮り、確認する

ページ全体のビルド後

1. デスクトップ（1440px）、タブレット（768px）、モバイル（375px）の各サイズでスクリーンショットを撮る
2. 3つすべてのサイズでレスポンシブレビューを実施する
3. デスクトップ版の詳細レビューを実施する
4. 重大な問題を優先して修正する

モックアップとの比較

1. モックアップ画像を用意する（Figmaのエクスポート、スクリーンショット、ユーザー提供の画像など）
2. 同じビューポートサイズで実装のスクリーンショットを撮る
3. 比較レビューを実施する
4. 優先度に従って差異を修正する

---

例

例 1：「このランディングページのスクリーンショットをレビューして」

image: [screenshot path]
prompt: "Review this landing page for design quality. Check spacing
consistency, typography hierarchy, visual hierarchy (where does the eye
go first?), CTA prominence, color contrast, and overall polish. Be
specific about issues and suggest fixes. Rate 1-10."

例 2：「自分の実装はこのFigmaデザインと一致していますか？」

image: [mockup.png, implementation.png]
prompt: "Compare these two images. First is the Figma mockup, second
is the implementation. Identify every deviation in spacing, color,
typography, alignment, and missing elements. Rate fidelity 1-10."

例 3：「このコンポーネントがモバイルで適切に表示されるか確認して」

image: [mobile-screenshot.png]
prompt: "Review this mobile UI. Is text readable? Are touch targets
large enough (≥44px)? Does anything overflow? Is the layout well-adapted
to mobile width? Check contrast and spacing."