design-qa

デザイン QA

引き渡し前に、プロトタイプの元デザインとレンダリングされた実装を比較するには、この内部ヘルパーを使用します。

幅広い UX レビュー、デザインレビュー、製品監査、フローのレビューには、このスキルを使用しないでください。これらのユーザー向けのリクエストには、audit を使用してください。

Product Design のビルドを引き渡す前に、必ずこのスキルを使用してください。

QA に合格するには、以下の両方が必要です。

• 元となる視覚的なターゲット：Figma ノード、画像、スクリーンショット、モックアップ、または元デザインのキャプチャ
• レンダリングされた実装：ローカル URL、デプロイ済み URL、アプリ画面、コンポーネント、またはスクリーンショット

いずれかのアーティファクトを開けない、キャプチャできない、または比較できない場合は、design-qa.md に final result: blocked と記載し、妨げとなっている要因を明記してください。ビルドスキルが完了として引き渡すことのないようにしてください。

重大な上書きルール

critical-overrides に従ってください。

ワークフロー

一般的な美的批評家ではなく、製品品質のレビュアーとして、意図されたデザインと実装を比較してください。出力には、両方のアーティファクトから得た根拠に基づく、優先順位付きの修正リストが必要です。

記憶、コード、またはファイルパスだけを基に QA レビューを書かないでください。まず元デザインと実装の両方を開くかキャプチャしてから、実際に表示されている内容を比較してください。

別々の画像ビューを並べたものを、左右に並べた比較だと見なさないでください。元画像と実装のスクリーンショットを同じ比較入力にまとめてから、視覚的な差異を判断してください。

デザイン QA は反復的なプロセスです。最初の比較で対応が必要な P0／P1／P2 の差異が見つからず、それに応じた視覚的な修正も行われなかった場合に限り、合格となることがあります。

比較で P0／P1／P2 の問題が見つかった場合：

• 指摘事項を記録し、現在の結果をブロック状態のままにします。
• 修正を適用します。
• 同じビューポートと状態で、修正版の実装をキャプチャします。
• 修正版のキャプチャと元デザインを再度比較します。

後の合格判定では、以前の指摘事項、実施した修正、修正後の視覚的な根拠を特定する必要があります。ビルド、依存関係、lint、デプロイ、プレビューのトラブルシューティングは、デザイン QA の反復には該当しません。

1. 比較対象を特定します。

   • 元デザインを特定します：Figma ノード、画像、デザインボード、スクリーンショット、仕様書、またはモックアップ。
   • 実装を特定します：ローカル URL、デプロイ済み URL、アプリ画面、コンポーネント、スクリーンショット、またはコードからレンダリングされた表示。
   • 判断する前に、同じビューポート、状態、テーマ、デバイス密度、ルート、コンテンツ、認証状態、インタラクション状態に揃えます。
   • アーティファクトが同じ状態を表していない場合は、まずその点を明示し、誤った精密さを避けてください。

2. 根拠をキャプチャします。

   • Figma では、利用可能な場合、デザインコンテキストとスクリーンショットのツールを使用します。
   • Web／アプリの実装では、index のブラウザー選択ルールに従います。ChatGPT Work Mode では、ローカル実装を開く前に、現在有効なビルドスキルの「ChatGPT Work Mode でのプロトタイプのプレビュー」セクションに従ってください。その後、意図されたビューポートでスクリーンショットをキャプチャします。
   • 必要に応じて、追加の状態もキャプチャします：モバイル／デスクトップ、ホバー／フォーカス／アクティブ、空／読み込み中／エラー、ダーク／ライト、主要なレスポンシブブレークポイント。
   • スクリーンショットのパスまたは URL を利用できる場合は保存し、指摘事項の根拠として引用できるようにします。
   • スクリーンショットをキャプチャするだけでは不十分です。判断の前に、元画像と実装のスクリーンショットを同じ比較入力にまとめてください。

3. 比較前に正規化します。

   • クロップ、ビューポートサイズ、スケール、デバイスフレームを揃えます。枠付きのモックアップと枠のないページを比較する場合は、その不一致を明記してください。
   • ブラウザーの全体的な UI や周囲のキャンバスより、コンテンツ領域の比較を優先してください。

4. 適切な詳細度で比較します。

   • 全体表示で比較し、全体的な構成、階層、レイアウト、密度、レスポンシブ構造を評価します。
   • 全体表示で重要な詳細を判断するには小さすぎる場合は、対象領域に絞って比較します。
   • 対象領域は、実際のソースと実装から選びます。タイポグラフィ、配置、画像、アセット、アイコン、ロゴ、コントロール、フォーム、ナビゲーション、テーブル、密度の高い UI、表示されるインタラクション状態の精度が重要な場合に使用します。
   • 対象領域を絞る必要がない場合は、その理由を design-qa.md に記載します。
   • 重要な詳細が明確に読み取れない場合、全体表示だけで QA を合格にしないでください。

5. 系統的にレビューします。

   • QA が簡単な視覚チェックを超える場合は、qa-rubric を読みます。
   • 情報アーキテクチャ、レイアウト、間隔、タイポグラフィ／フォント、色、画像／画質、アイコン、文言、アフォーダンス、インタラクション状態、レスポンシブ対応、アクセシビリティ、仕上がりを確認します。
   • 必須の忠実度確認対象である次の 5 項目を、必ず個別に確認します。ユーザーが明示していない場合も同様です。フォント／タイポグラフィ、間隔／レイアウトのリズム、色／トークン、画像の画質、文言／コンテンツ。
   • モックが確認中の問題（例：空の状態）に対応していない場合は、対処が必要なモックの欠点として別途指摘します。
   • もう 1 つの目標は、実装がモックと「同じくらいよく見える」かどうかを判断することです。スタイル上の問題があれば指摘します。ユーザーのプロンプトがアプリ自体で完結せず、実装に漏れ出している場合も指摘します。
   • デザインのずれと、意図的なプロダクト／コード上の制約を区別します。意図的な変更の可能性がある場合は、質問または仮定として表現します。

6. 修正につながる QA レポートを作成します。

   • 影響の大きさとユーザーへの影響に基づいて、重大度の高い順に指摘事項を記載します。
   • 各指摘事項には、重大度、場所、相違点、根拠、重要な理由、具体的な修正方法を含めます。
   • 実装のコンテキストがわかる場合は、具体的な CSS／コンポーネント／トークンの提案を含めます。
   • 客観的な不一致と、主観的な仕上げに関する提案は分けて記載します。
   • 必須の忠実度確認対象をすべて確認し、残る差異を許容可能、想定内、または未対応として明確に分類するまでは、デザインが一致している、完了している、これ以上改善できないなどと述べないでください。
   • 最後に、簡潔な実装チェックリストを記載します。

必須の忠実度確認対象

すべての QA レポートで、次の項目を明示的に評価してください。

• フォントとタイポグラフィ：書体、フォールバック、ウェイト、サイズ、行の高さ、字間、アンチエイリアス、階層、折り返し、切り捨て、ディスプレイテキストと小さな UI テキストに適切な視覚上のウェイトが使われているか。忠実度を確保するにはフォントを慎重に確認することが非常に重要です。類似書体を調べるか、画像分析を使ってフォントの違いを特定してください。
• 間隔とレイアウトのリズム：フレームサイズ、トリミング、配置、マージン、パディング、グリッドトラック、セクション間隔、コンポーネント間隔、角丸、影／エレベーション、垂直方向のリズム。
• 色とビジュアルトークン：サンプリングまたは推定したパレット、グラデーション、不透明度、コントラスト、セマンティックな状態色、前景色と背景色のバランス、CSS トークンが元のデザインに対応しているか。
• 画像の画質とアセットの忠実度：被写体の正確さ、トリミング、サイズ、鮮明さ、圧縮、透過部分の縁のにじみ、マスキング、背景処理、ラスター画像とベクター画像の適切さ、生成アセットが元のアートディレクションに合っているか。ビジュアルターゲットに含まれるロゴ、イラスト、装飾的なマーク、プロダクト画像、標準外のアイコン、その他の表示画像アセットが、カスタムのインライン SVG、手作業で作成した SVG、HTML 要素、div／span の図形、CSS 描画、グラデーション、絵文字、テキストグリフ、プレースホルダーの図形、またはコードでの近似表現に置き換えられている場合、QA は不合格としてください。
• アプリ固有のテキストの文言とコンテンツ

重大度

• P0：主要な使用を妨げる、深刻なアクセシビリティ上の問題、レイアウトの崩れ、またはタスクの実行が不可能な状態です。
• P1：ユーザーが気づく可能性が高い、重大なデザインの不一致またはユーザビリティの低下です。
• P2：中程度の視覚的なずれ、状態の不整合、レスポンシブ表示の問題、または修正可能な仕上げの不足です。
• P3：受け入れを妨げませんが、忠実度を高める軽微な調整です。

表示領域からのはみ出しによってアプリの常時表示コントロールが隠れる場合や、スクロールせずに見える範囲のコンテンツ、主要領域の比率、テキストの折り返し、インターフェースの密度が大きく変わる不一致は、P2 以上として扱ってください。

出力形式

ユーザーから別途指示がない限り、次の構成を使用してください。

**Findings**
- [P1] Short issue title
  Location: screen/component/selector/file if known.
  Evidence: design does X, implementation does Y.
  Impact: why this matters.
  Fix: concrete change.

**Open Questions**
- Any ambiguity about intentional deviations, unavailable states, or missing artifacts.

**Implementation Checklist**
- Ordered fixes that can be executed directly.

**Follow-up Polish**
- P3 refinements that can improve fidelity after handoff.

実質的な不一致がない場合は、その旨を明確に述べ、残っているテストの不足を列挙してください。

引き渡し前にこのスキルを使用する場合は、最新の QA レポートをプロジェクトのルートに design-qa.md として保存してください。

design-qa.md には、次の項目を含めてください。

• 元となるビジュアルの参照パス
• 実装のスクリーンショットのパス
• ビューポート
• 状態
• 全体表示の比較エビデンス
• 対象領域に絞った比較エビデンス、または不要とした理由
• 指摘事項
• P0／P1／P2 の各反復における比較履歴：以前の指摘事項、実施した修正、修正後の視覚的エビデンス
• 最終結果

ChatGPT Work Mode で構築した場合、design-qa.md には、ブラウザーでレンダリングした実装のスクリーンショット、ビューポート、テストした主なインタラクション、確認したコンソールエラー、最終結果を含めてください。ブラウザーでレンダリングしたエビデンスがない場合、final result は blocked です。

final result は、必ず passed または blocked にしてください。

対応が必要な P0／P1／P2 の指摘事項がない場合は passed とします。P3 の指摘事項は、後続の仕上げ項目として残してもかまいません。 対応が必要な P0／P1／P2 の指摘事項が残っている場合は blocked とし、阻害要因を明記してください。

QA レポートのファイルパスを返してください。