design-review

デザインレビュー スキル

役割と対象範囲

ADS の判断責任者であり、2 つ目の実行ループではありません。大規模なビジュアル作業と、依頼された批評をレビューします。小規模な変更では、影響を受ける結果と周辺の動作だけを確認します。コピーのみの編集に、調査、複数案、完全な状態マトリクス、独立した評価者は必要ありません。ADS で定められたタスクの予算と承認範囲を守ってください。

ビジュアル基盤の契約

大規模な作業では、ADS が固定した Foundation プロファイル ../agentic-design-system/contracts/visual-foundation.v2.json を使用してください。 確認済みの never ルールに反する場合、未解決の所見を正直に引き継ぐことは妨げられませんが、準備完了とは判断できません。

• 角丸の長方形の一辺だけに境界線を付けないでください。全周を囲む境界線は問題ありません。
• ぼかしなし、または内側のシャドウで、一辺だけの境界線を再現しないでください。
• 強制的に大文字表記にしないでください。作成するインターフェースのコピーには、文頭のみ大文字にする表記かタイトルケースを使います。ただし、変更すると不正確になる文字どおりの外部識別子は例外です。
• インターフェースのコピーに em ダッシュを使わないでください。
• 静的またはアニメーションするステータスドットを使わないでください。ステータスは色がなくても読み取れるようにし、スキャンや理解を実質的に助ける場合に限りアイコンを追加してください。
• 現在の「装飾的なドットを使わない」という方針は、円形のステータス要素だけでなく、作成するテキストの区切り記号やリストマーカーにも適用してください。文字どおりのデータや数学表記はそのまま維持してください。
• コントロールに相当するアイコンがある場合は、実際のアイコンを使ってください。プロジェクト内の一貫したアイコンファミリーを維持してください。そうでない場合は、ライセンスされた Nucleo または単一のオープンなファミリーを使い、混在させないでください。
• ユーティリティ用途の作業では、製品のフォント、システムサンセリフ、または一般的な別のフォントファミリーを使い始めてください。表現力のあるタイポグラフィを使うには、対象サーフェスが条件を満たすか、明示的な成果が求められます。
• 独自の字間や行間は、装飾目的の即興ではなく、定義された文字スタイルに基づいて設定してください。
• 通常の言い回しで済む場合、インターフェースのコピーにコロンを使わないでください。文字どおりの時刻、リンク、コード、プロトコル、構造化データ、外部データのそのままの引用には引き続き使えます。
• 仕切りを追加する前に、余白とグループ化を活用してください。仕切りの密度は、硬直的な自動判定ではなく、独立したレビュー上の判断とします。

レビュー対象を特定する

依頼、ソース、既存の DESIGN.md またはガイドラインから、現在の要件、対象サーフェス、維持する要素の一覧を把握してください。実際のベースライン、コンポーネント、トークンを確認してください。バックエンド、フレームワーク、エクスポート形式が指定されているだけでは、それがユーザーの望んだインターフェースだとは判断できません。不足している参照資料やパターンの選択が重要な場合に限り調査し、以前の回答や承認済みの例を再利用してください。方向性が決まっている場合や小さな修正では、新たな参照資料を必須にしないでください。

判断の順序

1. 製品とタスクの適合性： 意図された製品やサーフェスになっているか、ユーザーが依頼された作業を完了できるかを確認します。維持すべきベースラインの強みを挙げてください。
2. 情報設計： 実装に関する説明がなくても、読み手が重要な対象、比較、期間、次のアクションを把握できるかを確認します。根拠や詳細を開くときは、読解時の文脈を保ったまま戻れることを、直接アクセス時の動作も含めて確認してください。
3. 参照資料とビジュアルの方向性： 要件で実際に取り入れるプロパティを、意図された忠実度で比較します。参照資料に偶然含まれる装飾要素が、必ずしも依頼の一部とは限りません。
4. 仕上がり： 最終サイズで、構成、階層、タイポグラフィ、余白、一貫性を確認します。
5. 動作と納品： 該当する状態、実際の操作、対象ブラウザーを確認し、依頼された成果物がユーザーのレビュー環境で利用できることを確かめます。

後の段階で機械的な確認を重ねても、前の段階での失敗を埋め合わせることはできません。重み付けした自己採点ではなく、実際の成果物に基づいて所見を報告してください。実際に確認した不具合、好みの判断、根拠の不足を区別してください。独立した批評者を使うのは、承認を得ていて利用可能な場合に限り、未解決の製品方針や好みについては人間の判断を維持してください。

基本原則

• 抑制こそがデザインです。
• 余白が最も重要な指標です。
• 情報設計では、色よりタイポグラフィの階層を優先します。
• 独自のアイデアを加える前に、合意済みの参考資料の特性と忠実度に合わせます。
• 新しいパターンより、既存のパターンを優先します。
• インタラクティブな要素は、反応しないように感じさせず、洗練されたものにします。
• 基盤が間違っていれば、どれだけ磨き込んでも解決しません。
• 優れたデザインは求心的であり、遠心的ではありません。

参考ファイル

必要なものだけを読みます。この SKILL は簡潔に保ち、詳細は必要に応じて読み込みます。

• references/typography.md — 階層、スケール、組み合わせ、行長
• references/color.md — 抑制されたパレット、色味を加えたニュートラルカラー、コントラスト、OKLCH
• references/spacing.md — 余白システム、リズム、グルーピング、レイアウト密度
• references/motion.md — タイミング、イージング、動きを抑える設定、インタラクティブな感触、名前付きのモーション用語
• references/mobile.md — モバイルレビューのプロファイル：デザイン判断とプラットフォーム上の不具合の確認、判断の分岐、重大度の段階
• references/anti-patterns.md — 却下すべき、エージェントによく見られるパターン
• references/ux-writing.md — インターフェース文言、用語の一貫性、ラベル、エラー、空の状態

サブエージェント向け

• 作成内容に応じて、関連する参考ファイルを読みます。
• 新しいレイアウトやダッシュボードの場合は、spacing と anti-patterns を読みます。
• タイポグラフィが中心の画面の場合は、typography と spacing を読みます。
• 色やテーマに関する作業の場合は、color と anti-patterns を読みます。
• インタラクションの仕上げの場合は、motion と anti-patterns を読みます。
• モバイル、レスポンシブ、アプリ、PWA のレビューの場合は、mobile と responsive を読みます。
• インターフェース文言や、同じ概念に対する名称が競合している場合は、ux-writing を読みます。
• 関連するデザイン上の判断や、確認された不具合の解決に必要な参考資料だけを読み込みます。

依頼範囲内での検証

判断を終えた後、該当する以下のチェックを行います。小さな編集を全面的なレビューに広げないでください。必須のチェックを実行できない場合は、黙って省略せず、未検証のままにします。

Step 1: ビジュアル検証

• レンダリング結果のスクリーンショットを撮ります。
• 参考資料がある場合は、並べて比較します。
• 任意の DevTools 幅ではなく、対象のビューポートで確認します。
• スクリーンショットと状態固有のインタラクション記録を使って、状態の違いを検証します。テキストとマークアップの署名が同一であれば、比較対象としてフラグを立てますが、状態が欠落していることを意味するわけではありません。フォーカスやホバーによって、マークアップが変わらなくてもピクセルは変化することがあります。状態ゲートの判定が食い違う場合は、レンダリング結果の証拠に基づいて解決します。署名が同一か異なるかだけでは、意図した状態がレンダリングされたかどうかは判断できません。挿入した診断用スタイルは主要なキャプチャと分け、明示的に記録します。
• レンダリング後のアクセシビリティチェックを実行する前に、ネストされた開示要素と、インライン表示版と詳細表示版が併存できる場合はその両方を展開します。スマートフォンのビューポートで開示要素のタップ対象を測定し、ランドマーク名の重複を確認します。ランドマークにする必要のない反復項目には、ラベル付きグループを使います。修正後に、展開した状態を再度確認します。
• 操作可能なモーダルの画面を実際に操作して確認します。初期フォーカス、Tab と Shift+Tab でモーダル内にフォーカスが留まること、Escape による閉じ方、フォーカスの復帰、背景コンテンツが操作不能になっていることを検証します。サイト固有の手順なしではキャプチャからモーダルを開けない場合は、合格とせず not verified と記録します。
• ダイアログ内のヘルプ開示要素については、コンポーネントテストだけでなく、デスクトップ Chromium とモバイル WebKit でクリック／タップ後に Escape を押して確認します。必要に応じて、ヘルプの展開中に Escape でダイアログを閉じず、展開したヘルプだけを閉じられるよう、操作時にヘルプのトリガーへフォーカスを移します。ヘルプを閉じた後は、Escape がダイアログに届くようにします。フォーカスがトリガー上に残ること、繰り返し表示されるヘルプコントロールがそれぞれ独立していることを検証します。

ステップ 2：デザイン監査

• 余白の確認 — グルーピングと密度がタスクに適しており、選択したプロダクトの言葉遣いを保っています。
• 色の確認 — 不必要な色を追加していませんか？
• タイポグラフィの確認 — 色に頼らず、階層が明確になっていますか？
• パターンの確認 — プロジェクト既存のコンポーネントを使用していますか？
• インタラクションの確認 — ホバー、フォーカス、アクティブ状態があり、意図的に設計されていますか？
• 用語の確認 — ユーザー向けの各概念に主要な名称が一つあり、別名は一度だけ導入され、 主要な用語と競合していませんか？
• 完全性の確認 — プレースホルダー、機能しない状態、壊れたアセット、データ処理の欠落はありませんか？
• 表記の確認 — 影響を受けるレンダリング済みの文言、マーカー、生成 CSS の内容を確認します。 準備完了と判断する前に、該当する検出結果を実際のコンテキストに照らして解決してください。文字どおりの 表記は装飾ではありません。ソースのスキャンや候補数がゼロであることだけでは、準拠を確認できません。

ステップ 3：誠実さの確認

• 本当に完了していますか？
• 近接する別の依頼ではなく、依頼内容を満たしていますか？
• 予備知識のない人によるレビューにも耐えられますか？

ステップ 4：ソースの事前チェック用スクリプトを実行する

スクリプトが利用可能な場合は、影響を受けるコードと主張に関連するチェックを実行します。<skills-root> は、インストール済みのスキルフォルダーを含むディレクトリに置き換えてください。

# check for common agent anti-patterns
python3 <skills-root>/design-review/scripts/anti-pattern-check.py <your-file.tsx>

# verify loading, empty, and error states exist
python3 <skills-root>/design-review/scripts/state-check.py <your-file.tsx>

# check semantic HTML, aria labels, alt text, heading hierarchy
python3 <skills-root>/design-review/scripts/accessibility-check.py <your-file.tsx>

警告を提示する前に調査してください。これらのチェックはソースを grep する、意図的に簡易で回避可能なものです。「loading, empty, error」を含むコメントだけでも、状態チェックを通過できますが、どの状態もレンダリングされません。これらは参考情報であり、作業の完了を証明するものではありません。

視覚的に意味のある変更では、実際のルートをキャプチャしてください。タスクで必要な状態を選択します。 以下の default,loading,empty,error は一例であり、必須の共通マトリックスではありません。

node <skills-root>/agentic-design-system/scripts/run-capture.mjs "<running-route-url>" \
  --states default,loading,empty,error --out evidence/<slug>

キャプチャを確認し、必要なインタラクションを実際に試してください。自動キャプチャでは、サイト固有のすべての状態に到達できない場合があります。 ゲートの仕組みは、好みではなく、確立されたレンダリング済みのフィールドに基づかせてください。エビデンス形式 2 では、丸みのある片側だけの境界線、片側だけのシャドウ候補、強制された大文字表記、タイポグラフィの外れ値、記号だけのコントロール、ステータスドット候補、ドット文字・リストマーカー候補、区切り線の数、コロン、em ダッシュも記録します。これらの新しい測定値は、フィクスチャーの精度が実証されるまでは、引き続き報告のみとします。

visualFoundation.dotGlyphCandidates は、テキスト、CSS で生成されたグリフ、表示されていると推定された標準の丸いリストマーカーを報告します。 各検出結果を確認してください。透明またはクリップされたグリフは誤検出の可能性があり、マークのない数式や原文の引用が正当な場合もあります。 コード／数式の要素は除外され、通常の句読点は変更されません。シャドウ DOM、キャンバス、画像の内容、カスタムの図形マーカーは、引き続き目視確認が必要です。この診断が文言を編集することはありません。

レンダリング済みのキャプチャでは、可視の aria-modal コントラクトの検査結果と、(hover: hover) and (pointer: fine) がない、モーションを伴う :hover ルールも報告されます。調整中、これらのインタラクション診断は報告のみです。モーダルが存在しない、または到達できない場合は、合格ではなく「未検証」です。

CI アダプターはソースリポジトリの保守用であり、出荷されるランタイム依存関係ではありません。統合を提案する前に、ソースチェックアウトと依頼された範囲を確認してください。日常的なデザイン作業のために CI を追加しないでください。

ステップ 5：エビデンスとともに提示する

タスクの結果、維持したベースライン、関連するエビデンス、既知の不足点を返します。リモートでのレビューが必要な場合は、利用可能な添付ファイル、またはすでに許可されているアクセス可能な URL を使用してください。ローカルでの準備、実際の納品、人による受け入れ、リリースを区別します。ビルド、スキャナーの合格、スクリーンショットの存在だけでは、その後の三つのいずれも個別に証明できません。

フィードバックの管理

ADS のフィードバック分類に従ってください。明示的な好みは現在の所有者のもとに保ち、プロダクト上の選択はプロジェクトのコンテキストに、繰り返し発生する測定可能な不具合はプリミティブ／テストに、単発の修正はタスクに紐づけます。フィードバックがあったという理由だけで、新しい一般ルールを追加しないでください。承認済みの例は、エージェントの自己評価ではなく、承認のエビデンスとともに維持してください。