reviewing-wireframes

reviewing-wireframes — SKILL.md

バリアント： standard · 使用する場面： 完成済み（または修正済み）のワイヤーフレーム文書を受け入れゲートとして評価するとき — 上流のフローと照らし合わせて、実装可能性、網羅性、構成の適切さを確認し、実行可能な指摘事項を添えて VERDICT: approve|revise を出力します。

概要

このスキルは、ワイヤーフレームを作成する側と評価する側のペアのうち、レビューを担います。完成済みのワイヤーフレーム文書を手元に持つレビュアーがこのスキルを読み込み、次の一点を基準に文書を評価します。後続の hi-fi 工程と UI エンジニアリングで、すべてのフローに記載された画面と状態を網羅し、各画面を適切に構成したうえで、画面構造を構築できるか？ 固定の実装可能性＋網羅性＋構成チェックリストを適用します。これは authoring-wireframes が成果物を作成する際の基準と同じもので、作成基準とレビュー基準がずれないよう、情報源を一元化しています。その後、機械で解析可能な判定と、作成者が一度の修正で対応できる指摘事項を出力します。これは受け入れゲートであり、作成、修正、描き直しは行いません。評価して指摘事項を返します。

ここでいうワイヤーフレームは、テキストで表現された低〜中程度の忠実度を持つ構造的な成果物です。具体的には、構造化されたレイアウト説明＋ASCII／Markdownのボックススケッチ＋要素ごとの注釈で構成されます。ピクセル単位のモックアップでも、バイナリ形式のデザインファイルでもありません。この手法は媒体に依存しません。現在の成果物は Markdown ですが、将来デザインツールのバックエンドを導入しても、変わるのは媒体だけであり、以下のチェックリストは変わりません。

レビュアーにはワイヤーフレーム文書が渡され、利用可能な場合は、相互確認用の入力として上流の user-flows（画面の網羅性を検証するため）とdesign-system（コンポーネントが実在し、一貫していること、および文書でコンポーネントごとの a11y 契約を再評価していないことを検証するため）も渡されます。相互確認用の入力がない場合は、文書内の画面一覧とコンポーネント参照に基づいて評価し、比較対象を勝手に作らず、入力が不足していることを記録します。

有効にするタイミング

• 後続の hi-fi 工程／UI エンジニアリングが始まる前に、完成済みのワイヤーフレーム文書について承認／修正の判定が必要な場合。
• 作成者が作成したばかりのワイヤーフレーム文書を、独立したレビュアー／ゲートキーパーとして評価する場合。
• 以前の revise を受けて修正版のワイヤーフレーム文書を再評価する場合、または修正済みの文書を範囲を限定して差分レビューする場合（条件13を参照）。

次の場合は有効にしないでください：

• ワイヤーフレーム文書の作成または修復 → authoring-wireframes を使用してください。このスキルでは、作成も描き直しも行いません。
• 画面間のナビゲーショングラフ／経路の評価 → これは上流のuser-flowsの対象です（reviewing-user-flows）。このスキルでは、画面ごとのレイアウトと網羅性を評価します。
• ビジュアルトークンの体系／コンポーネントカタログ、またはコンポーネントごとの a11y 契約（コントラスト、フォーカス表示、コンポーネント固有のターゲットサイズ／キーボード操作）の評価 → これはdesign-systemの対象です。このスキルでは、ワイヤーフレーム内のコンポーネントが DS を一貫して参照していること、および文書で画面構成に関する a11y の配慮が確保されていることを確認します。DS 自体の妥当性は評価しません。
• 高忠実度のビジュアルデザイン、最終的なピクセル、色、書体、モーションの評価 → これは後続のhi-fi工程の対象であり、構造的なワイヤーフレームの範囲外です。
• テンプレート／セクションへの準拠の確認 → これはテンプレートの対象です。このスキルでは、すべての見出しが存在するかではなく、基準に照らした品質を評価します。
• その他の種類の文書のレビュー。

ワークフロー

ステップ1：新たな独立した視点でワイヤーフレーム文書全体を読む

作成者の説明に引きずられず、最初から最後まで読みます。あなたは次の工程（hi-fi＋UI エンジニアリングによる実装）に向けたゲートキーパーです。指摘事項に意味があるのは、記述どおりには画面構造を構築できない、フローに記載された画面／状態が欠けている、または構成が客観的な基準を満たしていないことを示す場合に限られます。上流の user-flows および／または design-system が提供されている場合は、この時点でざっと目を通し、ステップ2で網羅性とコンポーネントの一貫性を相互確認できるようにします。

ステップ2：チェックリストを実施する — 各条件を評価する

以下の各条件について、合格かギャップかを判定してください。条件が不合格となるのは、実在する明確な欠陥がある場合に限ります。「自分なら別のレイアウトにした」はギャップではありません（基準は客観的です）。ギャップごとに正確な場所（画面／状態）を記録してください（ステップ 4 で指摘事項に変換します）。各条件は画面の類型に応じたものです。シンプルな静的画面では、不要な条件が正当に省かれることがあります。簡潔さを理由にギャップをでっち上げないでください。

以下の機能境界チェック項目が適用されるのは、capability_record が作成時の呼び出しに含まれ、レビューのコンテキストとして利用できる場合に限ります。含まれていない場合は該当なしとして扱い、境界が定義されていない文書に機能境界マーカーがないことを理由に減点しないでください。

1. 画面全体の網羅性。 フローで名前が挙がっているすべての画面と、暗黙的な状態遷移ごとにワイヤーフレームがあること。存在しない場合はギャップとします（ユーザーフローと照合し、なければドキュメント独自の一覧を確認し、不足している入力に言及してください）。省略しないことを基準とします。
2. 画面ごとに該当するすべての状態と品質。 空・読み込み中・データ表示中・エラーに加え、状態変更が発生する場合は成功状態も含めます（該当する場合は部分状態も含めます）。存在するだけではなく、品質も評価します。読み込み中は、既知のレイアウトを反映したスケルトンを使用します（単なるスピナーは不可）。空状態には理由と次の行動への案内を含めます。エラーには平易な言葉で原因と復旧方法を示します。該当する状態が欠けている場合、または存在する状態が中身のない殻の場合はギャップとします。省略可能： 静的な画面ではデータ表示中のみとします。
3. レイアウトと構成が明確であること。 領域とコンテンツの優先順位が、推測なしで実装できるほど明確であり、グリッドに沿い、共通のアプリシェルを1つだけ使用していること（画面ごとに再発明しない）。2人のエンジニアが異なる構成を作る可能性がある場合、または画面がシェルを再発明・省略している場合はギャップとします。省略可能： 要素が1つだけの画面では、グリッドについての説明は不要です。
4. レイアウトの品質（客観的評価）。 主なアクションが視線の流れに沿って配置され、関連する要素がグループ化され、不必要な領域や要素がなく、兄弟画面との一貫性があること。客観的な問題がある場合に限りギャップとします（主なアクションが埋もれている、無関係な項目が一緒に詰め込まれている、冗長な領域がある、兄弟画面間でレイアウトに一貫性がない）。「もっと見栄えのよいレイアウトがある」といった主観的な好みは、ギャップではありません。省略可能： ごくシンプルな画面は、そのシンプルさに見合った構成で問題ありません。
5. コンポーネントの特定、一貫性、実在性。 注目すべき要素には、該当するデザインシステム（DS）コンポーネントが存在する場合、その名前を明記します。再利用するコンポーネントは一貫させ、新たなものを発明せず、アナトミーに沿って使用します。未特定の要素の塊、命名の不一致、または決定済みとして提示された架空のコンポーネント／トークンがあればギャップとします。省略しないこと（新たに発明しないこと）を基準とします。
6. アフォーダンスとデータ表示への注釈。 すべてのインタラクティブ要素について、動作、遷移先、例外ケースに注釈を付けます。データ密度の高い画面では、テーブル／リスト／カードの選択、その操作項目（並べ替え／絞り込み／ページネーション／表示密度／展開）、および段階的な情報開示を明記します。フォームでは構造化入力を使い、シリアライズされた文字列のフィールドは使用しません。コントロールの動作を推測しなければならない場合、またはデータテーブルが「ここにテーブルを配置」といった未構造の記述だけの場合はギャップとします。省略可能： 静的な画面にはデータもフォームもありません。
7. コンテンツとマイクロコピーの意図。 意味のあるテキスト項目には意図を明記します。ラベルに生のデータモデル識別子を使いません（人向けのラベルと説明を使用します）。ラベルは常時表示し（プレースホルダーをラベルの代わりにしない）、画面間で用語を統一し、ローカライズする場合は i18n による文字列の拡張に対応します。ラベルへのデータモデル識別子の漏出、プレースホルダーをラベルとして使用すること、用語の揺れがあればギャップとします。基準： データモデル識別子をラベルに漏出させないルールと用語の一貫性は、省略しない基準です。単一ロケールである理由が明記されている場合、i18n は省略可能です。
8. レスポンシブ対応の考慮。 フォームファクターが重要な画面では、リフローの仕組み（縦積み／折りたたみ／非表示／並べ替え）、モバイルでのコンテンツ優先順位、アダプティブナビゲーション、タッチターゲット用の余白を明記します。明らかにリフローする画面で、その方法が何も示されていない場合はギャップとします。省略可能： 理由を明記した単一フォームファクターの画面、または意味のあるリフローがない画面。
9. 画面構成のアクセシビリティ。 ランドマーク、h1 を1つにする見出し順序、読み上げ順序／フォーカス順序、アクセシブルネーム（アイコンのみの要素を含む）、キーボード操作、24px 以上のターゲットサイズを確保する余白、フォーカスが隠れないこと（固定要素がある場合）、色だけに依存しない意図を考慮します。ピクセル単位のコントラスト、フォーカス表示、コンポーネントごとのターゲットサイズ／キーボード操作は、ここでは評価しません。これらはデザインシステムの契約であり、この範囲外です。 インタラクティブなコントロールがある画面で構成上のアクセシビリティに関する注釈がない場合、アイコンのみのコントロールにアクセシブルネームがない場合、または必須の操作がマウスでしか実行できない場合はギャップとします。基準： ランドマーク、h1 を1つにすること、アクセシブルネーム、キーボード操作はあらゆるサイズで適用します。それ以外は該当する場合に適用します。
10. 注釈、引き継ぎ、スケッチとの同期。 記法の凡例を定義し、意味のある要素すべてに注釈を付けます（単に描くだけでなく、動作も説明します）。要素をデザインシステムのコンポーネントに対応付け、デザインからコードへの引き継ぎを可能にします。スケッチと注釈を同期させます（対応するスケッチのない注釈も、注釈のない要素も残しません）。注釈のない静的なスケッチ、またはスケッチと注釈の不一致があればギャップとします。基準： スケッチと注釈の同期、および実装可能な引き継ぎは省略しません。
11. ギャップを明示し、発明しないこと。 未定義の画面／コンテンツ、不足している DS コンポーネント、後回しにしたコンポーネント契約のアクセシビリティ（DS／高忠実度デザインなし）は、暗黙に補完・削除せず、前提または未解決の質問として明示します。未定義の画面／コンポーネントを、決定済みとして発明し、ドキュメントで取り繕っている場合はギャップとします。前提であることを正直に明記していれば、ギャップではありません。
12. 構造に重点を置き、高忠実度にしないこと。 低〜中忠実度とし、レイアウトと注釈を示します。最終的なピクセル、色、書体は指定しません。高忠実度デザインの領域に踏み込み、デザインシステムの対象範囲を侵すほど詳細な場合はギャップとします。省略しないことを基準とします。
13. 差分に限定したレビュー（改訂されたドキュメントのみ）。 改訂をレビューする場合は、ドキュメント全体ではなく差分をレビューします。対象範囲を限定します（未変更の画面はそのまま）。変更の波及漏れがないこと（共有領域の変更がそれを再利用するすべての画面に反映されている、一覧の行に対応漏れがない、新たに未対応となったフロー上の画面がない、コンポーネント名の揺れがない、スケッチと注釈が引き続き同期している、参照先の DS コンポーネントが引き続き実在し非推奨ではない）。変更の種類に応じたドキュメント自身のバージョン更新、破壊的な削除に伴う非推奨化、差分との整合性が取れた変更履歴も必要です。これらのいずれかに問題があればギャップとします。ゼロからの初回作成では該当なしです。
14. 機能境界（capability_record がない場合は該当なし）： すべての entry_points にアクセスできる初期画面の到着コンテキストを用意します。すべての exit_points を、機能間の遷移マーカーとして表示します。グローバルナビゲーションやシェルの再設計は行いません（対象外として明記します。これは system-wireframes に属します）。
15. システムの網羅性（capability records がない場合は該当なし）： has_ui=true のすべての機能にナビ項目が少なくとも1つあります。すべての exit_points に、対応する entry_point への遷移画面があります。共通テンプレート（読み込み／エラー／空の状態）も用意されています。

ステップ 3：判定を決める

• approve — 適用対象となる条件をすべて満たしています。記述どおりに構築でき、フローで名前が挙がった画面と状態をすべて網羅し、構成も目標基準を満たしています。レイアウトを改善できそうに思えても承認します。基準は構築可能性、網羅性、目標に沿った構成であり、完璧さではありません。
• revise — 1つ以上の条件に、具体的に指摘できる不足があります（状態の欠落／未記入、コンポーネントの独自追加、曖昧なレイアウト、主要アクションが埋もれている、データモデルの実装を露呈するラベル、構成のアクセシビリティが考慮されていない、ハイファイの範囲を逸脱している、フローで名前が挙がった画面が未網羅、変更差分に問題がある）。

作業量を示すため、あるいは「あればよい」要望を出すために revise と判定してはいけません。また、主観的なレイアウトの好み（条件 4）や、デザインシステムの管轄であるピクセル単位のコントラスト（条件 9）を理由に revise と判定してはいけません。条件は満たしているか、満たしていないかのどちらかです。

ステップ 4：判定と実行可能な指摘を出力する

判定は、単独行に文字列 VERDICT: approve または VERDICT: revise をそのまま記載して出力します。前後にフェンス、引用符、その他の語句を付けてはいけません（ここに示すフェンスは説明用です）。

VERDICT: approve

続いて、指摘を列挙します。revise の場合、各指摘はすべて実行可能な内容にします。つまり、満たせなかった条件、正確な箇所（画面／状態）、および修正方法を示し、作成者が1回の修正で解決できるようにします。approve の場合、指摘は任意の参考情報であり、承認を妨げるものではありません。

よい指摘は、不足箇所と修正方法を明確に示します。

revise — 画面ごとの状態（条件 2）：Dashboard 画面にはデータが表示された状態のみが記載されており、空、読み込み、エラーの状態がありません。修正：空の状態（ゼロ件メッセージ＋作成 CTA）、読み込み状態（表示済みレイアウトを反映したスケルトン）、エラー状態（メッセージの配置＋再試行。インラインかブロックか）を追加してください。

悪い指摘は曖昧です。「Dashboard にもっと状態を追加してください。」

ルール

厳守するルール（決して違反しないこと）：

• 判定行は必ず1行だけ出力してください。VERDICT: approve または VERDICT: revise — この文字列を、それだけの行として出力してください。後続のツールがこれを解析します。
• 判断するだけで、作成しないでください。 指摘事項を返してください。書き換え、描き直し、補完はしないでください。修正は作成者が行います。
• 単一の基準を適用してください。 ステップ 2 の条件に照らして判断してください。作成者が従うものと同じ基準です。独自の厳しい基準を設けたり、条件を追加したりしないでください。
• 誤って revise にしないでください。 適用されるすべての条件を満たすドキュメントは、画面が相応に簡略化されていて薄い内容であっても approve としてください。実際の、具体的に特定できる不足がある場合に限り revise とします。主観的なレイアウトの好み（条件 4）は、決して不足事項にはなりません。
• 誤って approve にしないでください。 状態の欠落、コンポーネントの創作、フロー名が示す画面の未カバー、データモデルが漏れたラベル、またはハイファイの範囲超過があれば revise としてください。
• カバレッジはフローを基準に判断してください。 フロー名が付いた画面／状態にワイヤーフレームがない場合は revise としてください。フローが提供されていない場合は、ドキュメント内の一覧を基準に判断し、照合ができない旨を指摘してください。
• 創作されたコンポーネント／トークンはブロッキングです。 デザインシステムで定義されていないコンポーネント／トークンが、未確定であるとの明示なしに、決定事項として提示されている場合は revise としてください。
• アクセシビリティの範囲を守ってください。 判断対象は（条件 9）の画面構成におけるアクセシビリティです。ピクセル単位のコントラスト、フォーカスの見え方、コンポーネントごとのターゲットサイズ／キーボード操作を評価しないでください。これらはデザインシステムが定める範囲です。これらを評価するのは厳密な判断ではなく、範囲逸脱です。
• ドキュメントに提供された上流資料に照らして判断してください。 作成されていない上流資料を revise の理由にしてはいけません。作成済みだが無視されている上流資料（ワイヤーフレームが画面をカバーしていないフロー、定義を超えるコンポーネントをワイヤーフレームに創作しているデザインシステム）は、正当な指摘事項です。
• 修正は差分レビューとして扱ってください。 修正時は変更差分とその波及影響（条件 13）を確認し、ドキュメント全体を再レビューしないでください。変更されていない画面を蒸し返さないでください。
• revise の指摘はすべて実行可能な内容にしてください。 未達条件、該当箇所、具体的な修正方法を示してください。

優先事項（必要に応じて変更可能）：

• 指摘は重大度の高い順に並べてください。まずブロッキングとなる不足（画面／状態の欠落、コンポーネントの創作、曖昧なレイアウト、埋もれた主要アクション）、次に軽微なもの（簡潔なマイクロコピーの注記）を示してください。
• 各指摘で、条件番号または条件名に言及してください。
• approve の注記は少数にとどめ、ブロッキングではないことを明確にしてください。
• 照合に必要な入力（ユーザーフローまたはデザインシステム）がない場合は、暗黙に推測せず、その旨を一度だけ伝えてください。

注意点

• 構築可能性ではなく、網羅性だけで承認する。 すべてのセクションが揃っていても、ドキュメントが構築不能な場合があります（曖昧な領域、注釈のないアフォーダンス、フローで名前が挙がっているのに描かれていない画面など）。テンプレートが埋まっているかではなく、構造を構築できるか、またフローで名前が挙がっているすべての画面が網羅されているかを判断してください。
• ハッピーパスだけの抜けを見逃す。 内容が入力された状態しかなく、空・読み込み中・エラー・成功の各状態がひそかに欠けている画面は、最もよくある不備です。
• フロー網羅性の抜けを見逃す。 フローで名前が挙がっている画面のワイヤーフレームがありません。フローから画面までたどってください。これが表面化するのはインベントリ表です（条件 1）。
• 独自のコンポーネントを見逃す。 デザインシステムで定義されていないコンポーネント名を自信たっぷりに使っている場合は、逸脱として指摘してください（条件 5）。
• ピクセル単位のコントラストを採点する。 コントラスト比が記載されていないことを理由に修正を求めるのは、対象範囲外です。それはデザインシステムの契約に属します。ピクセル値ではなく、色に依存しない意図の確保と構成を判断してください（条件 9）。
• レイアウトの好みで修正を求める。 「自分ならカードを使った」というのは主観的です。条件 4 で客観的に判断するのは、視線の流れ・グループ化・不要な要素がないこと・一貫性だけです。好みの違いを不備として作り出すのは、誤った修正要求です。
• 画面の比重が相対的に小さいことを理由に誤って修正を求める。 静的な情報画面には、読み込み中・エラー状態がなく、グリッドについての説明もリフローも必要ない場合があります。画面の類型に応じて判断してください。
• ハイファイレビューに逸脱する。 色・書体・ピクセル単位の間隔を採点すると、構造の範囲を超えます（条件 12）。
• 修正時にドキュメント全体を再レビューする。 差分とその波及を確認してください（条件 13）。変更のない画面を再び議論するのはノイズです。
• 判定トークンが揺れている。 「承認済み」、「LGTM」、「要修正」や段落の途中に埋め込まれた判定は解析できません。単独の行に、文字どおり VERDICT: approve|revise と出力してください。

アンチパターン

• おざなりな承認。 ざっと見て承認すること。ゲートは構築不能または不完全なワイヤーフレームを見つけるためにあります。画面のエラー状態が欠けたまま通すと、後続の構築を損ないます。
• 些細な点での修正要求。 レイアウトの好み、スケッチの見た目、ピクセル単位のコントラスト、または不備を装ったあると望ましい要件を理由にブロックすること。修正を求めるのは、構築可能性・網羅性・構成に関わる実際の阻害要因に限ります。
• 黙って描き直す。 「スケッチを直すほうが簡単」という考え方です。レビュー中に作成まで行うと、制作と評価の分離が崩れます。
• 条件を勝手に追加する。 「最終的な色も決めるべき」「完全なコンポーネント仕様も必要」「コントラスト比も必要」などとすること。基準がハイファイ領域とデザインシステムの管轄に逸脱します。
• 別の成果物を採点する。 画面ごとのワイヤーフレームではなく、ナビゲーショングラフ（user-flows）やトークンカタログ／コンポーネントのアクセシビリティ契約（design-system）を評価すること。担当範囲を守ってください。
• 曖昧な判定。 「おおむね承認ですが……」や判定を2行に分けること。決定は1つ、トークンも1つだけにしてください。

出力

1つのワイヤーフレーム文書に対するレビュー結果を1つ出力します。

• 判定行を1行 — 単独の行に、文字どおり VERDICT: approve または VERDICT: revise と記載します。
• 指摘事項 — revise の場合、ブロック要因となる不備ごとに、実行可能な指摘を1件ずつ記載します（満たしていない条件＋該当箇所＋具体的な修正方法）。approve の場合、ブロック要因とならない注記は任意です。

抽象的なコンシューマーとは、制作→レビューのループを調整するものを指します。approve は次のフェーズ（後続のハイファイ作業と UI エンジニアリング）に進むためワイヤーフレーム文書を承認し、revise は範囲を限定した修正のために指摘事項を制作者へ返します。

関連項目

• authoring-wireframes — 制作側を担い、このスキルが評価するのと同じ実装可能性＋網羅性＋構成の基準で作成します。組み合わせることで基準を一元化し、制作とレビューの間にずれが生じないようにします。
• reviewing-user-flows — 上流のナビゲーショングラフを対象とする、兄弟関係のゲートです。ユーザーフローはここでは（画面の網羅性を確認するための）相互チェック用の入力であり、このスキルの評価対象ではありません。
• reviewing-design-system — ビジュアルトークンシステム＋コンポーネントカタログ＋コンポーネントごとの a11y 契約（コントラスト、フォーカス表示）を対象とする、兄弟関係のゲートです。デザインシステムはここでは（コンポーネントの一貫性を確認するための）相互チェック用の入力であり、このスキルの評価対象ではありません。
• 下流のハイファイレビュー — 最終的なビジュアルやピクセルを評価します。このスキルは構造までを対象とします。
• ワイヤーフレームテンプレート／コンテンツテンプレートツール — セクションの構造を担います。このスキルは構造への準拠ではなく、基準に照らした品質を評価します。

プログレッシブディスクロージャー

• references/buildability-bar.md — 条件ごとの合格／不足の指標と、具体的な評価結果（a11y の境界、レイアウト品質の目的サブセット、差分レビューを含む）を加えて、チェックリストの条件を詳述しています。判断が分かれる条件について、より明確な判断基準が必要な場合に読み込みます。
• references/sources.md — この手法および単一の情報源に基づく基準（兄弟スキルの authoring-wireframes と共有）の調査上の出典です。

本文の目安

• description は 1,024 文字以下（agentskills.io の上限）。一覧では description と when_to_use の合計が 1,536 文字で切り捨てられます。
• 本文は約 500 行／5,000 トークン（目安。品質を優先し、700 行／7,000 トークンを継続的に超える場合は警告してください）とし、毎ターンのコンテキストに含めます。
• 参照ファイルごとに、10k トークン超で警告、25k トークン超でエラーとします。参照ファイルの合計は、25k トークン超で警告、50k トークン超でエラーとします。