Communityコーディング&開発github.com

ビジュアルQA

重要なUI変更に対して必須のスクリーンショット駆動型ビジュアルQAループ — Playwrightでサイトを実行し、すべてのブレークポイントをキャプチャ、各スクリーンショットを評価、修正、繰り返す。ページやセクションの構築・再スタイリング後、UI作業完了報告前に行う。デザイン判断にはpremium-frontendを、コンバージョン監査にはconversion-optimizationを使用する。

ビジュアルQA とは?

この「ビジュアルQA」は、UIの変更が完了したと見なす前に、実際のスクリーンショットを用いて徹底的にビジュアル品質をチェックするためのスキルです。開発者は通常、コードの動作確認には注意を払いますが、レイアウトの崩れ、階層の弱さ、ホワイトスペースの不均一、フォントサイズの問題、CTAの目立ち具合など、視覚的な細部を見落としがちです。本スキルは、あらゆるUI変更(新規ページ構築、リスタイリング後)に対して、あらかじめ定義されたブレークポイント(375px、390px、768px、1440px、1920pxなど)でスクリーンショットを自動キャプチャし、それらを人間の目(または設計思想に基づく判断)でレビューする反復プロセスを強制します。Playwrightを使用した自動スクリプトにより、各ルート・ブレークポイントごとにフルページスクリーンショットを生成し、水平オーバーフローやコンソールエラーも自動検出します。特にモバイルファーストの観点から、InstagramやGoogle Maps経由のユーザーを想定した確認項目(タップターゲット、スティッキーCTA、縦長画像のトリミングなど)も含まれています。このスキルはClaude Code, Cursor, CodexなどのAIエージェントと連携し、開発者が「見た目も完成」と言えるまで厳格なループを繰り返すためのガイドラインを提供します。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/artem2167/website-factory/tree/HEAD/.claude/skills/visual-qa

Installed? Explore more コーディング&開発 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

visual-qa(ビジュアルQA)

妥当なJSXは優れたデザインの証拠にはなりません。UI作業が完了したと報告する前に、必ず実際にそのUIを見て確認してください。

コア

ローカルでサイトを実行する。

以下のブレークポイントで検査:
375px
390px
768px
1440px
1920px

スクリーンショットをキャプチャする。

各スクリーンショットを以下の観点でレビュー:

- レイアウトの崩れ
- 情報階層の弱さ
- 過剰な余白
- 不足している余白
- 醜い行の折り返し
- 画像のトリミング不良
- 一貫性のないマージン
- 大きすぎるタイポグラフィ
- 小さすぎるタイポグラフィ
- 弱いCTAの視認性
- 配置の問題
- 一般的なAIデザインパターン

検出された問題を修正する。

大きな視覚的問題がなくなるまで繰り返す。

実行方法

開発サーバーを起動した後、以下を実行:

QA_ROUTES=/,/services,/doctors,/contact node scripts/qa-screenshots.mjs

出力は qa/<route>/<width>.png に、フルページ、ブレークポイントごとに1ファイルずつ保存されます。 このスクリプトは各ブレークポイントで水平オーバーフローとコンソールエラーも報告します — 両方とも自動的に不合格となります。

キャプチャされるブレークポイント:375×812、390×844、430×932、768×1024、1440×900、1920×1080。

初回セットアップ:

npm i -D playwright && npx playwright install chromium

全体的なスイープではなく、インタラクティブに試したい場合は、エディタ内のブラウザツールの方が高速です:ページを開き、リサイズし、アクセシビリティツリーを読み、コンソールを確認します。

スクリーンショットの読み方

ブレークポイントごとに進めます。各ブレークポイントで以下の質問に答えてください:

  1. 水平方向にオーバーフローしているものはありますか?
  2. 一目でわかる焦点(フォーカルポイント)はありますか?それとも視線がさまよいますか?
  3. 見出しが醜いオーファン(孤立した1語行)や1語だけで折り返されていますか?
  4. セクション間のマージンは、一貫性が求められる場所で一貫しており、意図的に異なるべき場所で異なっていますか?
  5. 画像が顔、皿、ベッドなどを通してトリミングされていませんか?
  6. プライマリCTAは、その画面内で最も目立つ要素ですか?
  7. モバイルでは:スティッキーCTAが表示され、親指で届きやすく、コンテンツを覆い隠していませんか?
  8. デフォルトのAIページのように見えるものはありませんか — グラデーション、アイコンカードグリッド、ピルバッジ、ぼかしブロブなど?

モバイル固有のチェック

ローカルビジネスの訪問者はInstagram、Google Maps、TikTok、広告、メッセンジャーリンクから来ます。モバイルは主要な画面であり、後付けではありません。

  • 375pxで水平スクロールがないこと;
  • ヒーローテキストが大きすぎないこと — 最初の画面全体を占めてはいけません;
  • タップターゲットが十分な大きさで、小さなものがないこと;
  • ナビゲーションが到達可能で閉じられること;
  • 画像がポートレート用にトリミングされており、ランドスケープデスクトップクロップから圧縮されていないこと;
  • スティッキーCTAが表示され、洗練されていること。

ループの規律

  • 問題を修正したら、再キャプチャする。目隠しで修正しないこと。
  • 完全なスイープで大きな問題が発生しなくなった時点で停止する。リストが退屈になったからではない。
  • 修正後も同じ問題が再発する場合、問題はページではなくブロックにある — ブロックライブラリで修正すること。
  • 正直に報告する:あるブレークポイントに未解決の問題が残っている場合は、その旨を明記すること。

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

関連スキル