マテリアルデザイン3 レビュー
ユーザーインターフェースをマテリアルデザイン3(M3)に照らしてレビューし、プロジェクト独自のガイドラインを尊重した上で、ユーザーが項目ごとに決定できる番号付きレポートを作成します。その後、決定事項を記録し、承認された変更を出力します。
使用する場合 / 使用しない場合
以下の場合に使用します:
- 「この画面・ページ・コンポーネントをMaterial 3に照らしてレビューして」「これはM3準拠ですか?」「M3監査」「デザインレビュー」とユーザーが依頼した場合
- 既存UIのタッチターゲット、コントラスト、タイプスケール、カラーロール、シェイプ、スペーシング、コンポーネントをチェックする場合
- リリース前にスクリーンショットや実行中のページをMaterialガイドラインと比較する場合
- どのMaterialからの逸脱を維持し、どれを修正するかを決定する場合
以下の場合は使用しません:
- ユーザーが新しいUIの生成、テーマの構築、またはコードの新規作成を希望する場合(「M3のログインページを作って」など)。本スキルはレビューを行い、生成は行いません。
- 対象のデザインシステムが明示的にMaterialでない場合(Apple HIG、Fluent、M3ベースでないカスタムシステム)。ただし、ユーザーが最低限のフロアチェックのみを希望する場合は除きます。
- 質問が単一の事実確認(「FABの高さは?」)の場合。その場合はリファレンスファイルから直接回答します。
レビュー中にコードを変更しないでください。ユーザーが決定後に依頼した場合にのみコードを変更します。
レイヤーと優先順位
以下の順序でルールを適用します。上位のレイヤーが下位のレイヤーよりも優先されます。
- フロアルール、階層F:アクセシビリティとユーザビリティの最低要件(ターゲット、コントラスト、フォーカス、ラベル、テキストスケーリング、モーション削減)。交渉不可。プロジェクトガイドラインもこれを放棄できません。
- プロジェクトガイドラインと記録された決定。アダプタープロトコル(
references/adapter-protocol.md)を通じて見つけます。 - M3コア、階層C:ロール、トークン、タイプスケール、シェイプスケール、コンポーネント仕様。逸脱には明示的な決定が必要です。
- M3表現的・オプション項目、階層E。欠落を欠陥として報告しないでください。
プロジェクトガイドラインや記録された決定が階層CまたはEのルールと競合する場合、違反を報告しないでください。競合を「決定候補」に一度だけリストアップします(それがまだ台帳に記録されていない場合のみ)。階層Fのルールと競合する場合、Fの指摘を報告し、その証拠に競合するガイドラインを記載します。
トレランス
2つのモード。デフォルトは inspired。
strict:階層Cの不一致はすべて問題。階層Eの項目は提案。inspired:階層Cの不一致は、ユーザビリティを損なわない限り提案(損なう場合は問題)。階層Eの項目は、明確な価値を追加する場合のみ提案。- 両モードにおいて、階層Fの指摘はすべて問題。
ユーザーが指定したモードを使用します。プロジェクトガイドラインが指定している場合はそれを使用します。それ以外の場合は inspired を使用し、レポートヘッダーにその旨を記載します。
証拠ラベル
すべての指摘と注記に、以下のいずれかのラベルを正確に1つ付けます:
measured-rendered:レンダリングされたページ(DOM、計算済みスタイル、ヒットテスト)から読み取ったもの。セレクタと値を明記。measured-code:ソースコードや宣言されたCSSから読み取ったもの。レンダリングされたページで確認していない。measured-simulation:シミュレーション下でレンダリングされたページ上で測定したもの(狭いビューポートでのテキストズーム、ダークモードなどのエミュレート設定、モーション削減、強制色)。実際のデバイスでの確認を推奨。estimated:画像から推測したもの。
v0.1のラベル measured は measured-rendered として扱います。複数の情報源を組み合わせた指摘の場合は、最も弱いラベルを使用します。スケール(CSS px単位のビューポート幅と devicePixelRatio、または既知の参照要素)が不明な場合、スクリーンショットから正確なdp値やpx値を記載しないでください。スケールを一度尋ねるか、範囲を指定して estimated ラベルを付けます。圧縮画像から正確なコントラスト比を決して与えず、おおよその比率を与えて estimated ラベルを付けます。
ワークフロー
ステップ0. 対象の特定
提供された資料から、または一度質問することによって、以下を特定します:
- レビュー対象:スクリーンショット、ソースファイル、URLまたはローカルページ、デザインツールのエクスポート
- プラットフォーム:Web、Android(ComposeまたはViews)、Flutter、iOS、クロスプラットフォーム
- フォームファクターとウィンドウサイズクラス:コンパクト(< 600)、ミディアム(600-839)、エクスパンデッド(840-1199)、ラージまたはエクストララージ
- ライト、ダーク、またはその両方。ハイコントラスト、モーション削減、またはアプリ内テキストサイズ設定の有無
対象に個人データ(氏名、金額、住所、メッセージ、健康情報、アカウントデータ)が含まれている場合、その旨を回答の先頭に記載し、編集済みまたはデモ状態でのレビューを提案します。スクリーンショットやページデータをファイル、メモリ、または台帳に保存しないでください。要素を特定するために最低限必要なテキストのみを引用します。
ステップ1. アダプターの読み込み
references/adapter-protocol.md に従います:プロジェクトデザインガイドライン、決定台帳、規則リスト、変更リスト形式、およびレビュー設定(テストする幅とテキストサイズ設定)を探します。見つからない場合、一度だけ簡単な質問をします。ユーザーが答えない、または存在しないと言った場合、M3のみとデフォルト設定で続行します。
デザインブリーフ:ブリーフが提供された、または見つかった場合(m3-design-brief、または受け入れ基準 AC-nn を持つブリーフから)、それをプロジェクトガイドラインとして扱います。その決定(B-nn)は、その範囲内では記録された決定としてカウントされます(決定候補ではありません)。そのトレランス、幅、テーマがレビュー設定です。階層Fは依然として優先されます。すべてのACを確認し、レポートの「ブリーフ受け入れ基準」セクションに記入します(合格、不合格、未チェック、証拠付き)。
ステップ2. トレランスの選択
strict または inspired(トレランスを参照)。ユーザーまたはガイドラインが既に決定している場合は質問しないでください。
ステップ3. 測定
推定よりも測定を優先します。以下の順序で行います:
- レンダリングされたページが利用可能(Playwright、ブラウザ自動化ツール、DevTools):ページ内で
scripts/measure.jsを評価し、そのJSONを使用します(references/measurement.md、「実行方法」および「出力フィールドとそれらが供給するルール」を参照)。各幅とテーマを個別に測定します:アダプターからの幅とテキストサイズ設定。それ以外の場合は、コンパクト幅(例:390 px)とエクスパンデッド幅(例:1280 px)、ライトとダークで測定します。 - ソースコードのみ利用可能:CSS/HTML/JSまたはコンポーネントコードを読み取り、サイズ、色、半径を計算し、結果に
measured-codeラベルを付けます。 - 画像のみ利用可能:推定し、
estimatedラベルを付け、正確な数値が重要な場合はスケールを尋ねます。
結果を読む前のセットアップチェック(measurement.md、「セットアップチェック」):
- テストする意図したCSS幅を
expectWidthに渡します。 warningsにviewport-meta-missingまたはviewport-width-mismatchが含まれている場合、停止します。ページは意図した幅(多くの場合980 px)でレイアウトされていないため、すべてのサイズが間違っています。セットアップを修正し(ビューポートを設定するか、本番環境で提供されるものと同じビューポートメタタグを注入する)、再実行してから続行します。そのような実行からのサイズを決して報告しないでください。本番環境自体にタグがない場合は、一度だけ報告します。
有効ヒット領域(measurement.md、「有効ヒット領域」):hitScan がオン(デフォルト)の場合、視覚的なボックスではなく hitWidth x hitHeight でターゲットサイズを判断します。hitAreaVia は領域がどのように見つかったかを示します(box、label、pseudo、probe)。probe はヒットテストが確認したかどうかを示します(ok)またはそうでないか(covered、offscreen、limited:ジオメトリのみ、正確なサイズを報告する前に確認してください)。
::before/::after によって拡大された pseudo 領域はカウントされます。そのボックスが境界線で縮小されていないか、overflow: hidden の祖先によってクリップされていないかを確認し、疑わしい場合はコードで確認します。
テキストスケーリングについては measurement.md、「レシピ:200%でのテキスト」に従います(結果は measured-simulation)。メニュー、ダイアログ、シート、タブ、ラジオグループ、ビューチェンジについては measurement.md、「レシピ:フォーカスフロー」に従います。
スクリプト出力(truncated、nonTextContrast、labelInName、ariaConflicts を含む)を判定ではなく候補として扱い、報告前にそれぞれをルールに対して確認します。ステートスタイルとモーションは測定されません。重要である場合、コードまたはインタラクションで確認します。
スクリプトがコントラストを解決できない場合(グラデーション、画像、または半透明の背景)、手動で最悪のケースを計算し(テキストの下の最も暗いストップと最も明るいストップ、または実際の背景と合成されたアルファ色)、使用したストップと共に estimated として報告します。color-mix() またはアルファテキスト色の場合は、最終的な合成色を使用します。ページにダークバリアントがない場合、要素ごとではなく一度だけ報告します(references/color.md のテーマパリティルール)。
ステップ4. 関連するリファレンスのみを読み込む
段階的開示:すべてのリファレンスファイルを決して読み込まないでください。画面に表示されているものに基づいて選択します。
| 表面に含まれるもの | 読み込むもの |
|---|---|
| 任意の表面(常に) | 最初に references/layout-interaction-a11y.md、「アクセシビリティフロア」と「コンポーネント間ルール」のセクション |
| 色、テーマ、ダークモード、トークン、コントラスト | references/color.md |
| タイポグラフィ、コーナー、エレベーション、スペーシング、モーション、アイコン | references/styles.md |
| アプリバー、バッジ、ボトムシート、ボタングループ、ボタン、カード、カルーセル、チェックボックス、チップ、日付ピッカー、ダイアログ、仕切り | references/components-1.md |
| 拡張FAB、FABメニュー、FAB、アイコンボタン、リスト、ローディングインジケーター、メニュー、ナビゲーションバー/ドロワー/レール、プログレスインジケーター、ラジオボタン | references/components-2.md |
| 検索、セグメントボタン、サイドシート、スライダー、スナックバー、スプリットボタン、スイッチ、タブ、テキストフィールド、タイムピッカー、ツールバー、ツールチップ | references/components-3.md |
| 表現的特徴、スプリングモーション、シェイプモーフ、またはユーザーがExpressiveについて質問した場合 | references/expressive.md |
| レポート作成 | references/report-template.md |
| 決定の記録、規則、変更リスト | references/adapter-protocol.md |
大きなファイル内では、画面にあるコンポーネントのセクションのみを読み取ります。最初に見出しをリストアップし(grep -n '^## ' references/components-1.md)、次にそれらの行範囲のみを読み取ります(sed -n 'START,ENDp' file)。リファレンスファイルがない場合は、その旨を伝えて他のファイルで続行します。ギャップを埋めるためにルールを発明しないでください。
ステップ5. チェック、分類、グループ化
各候補について:
- まず機能(CMP-01)でコントロールを分類し、次にルールを見つけます。そのIDと
Sourceをリファレンスファイルに正確に引用します。複数のルールが重複する場合(同じターゲットサイズに対するコンポーネントルールとフロアルール)、最も具体的なルールを引用し、その後に他のルールをリストアップします(「A11-01も参照」)。 - ルールIDでサポートされていない場合、M3の指摘として報告しないでください。プロジェクトガイドライン、またはリファレンスでカバーされていないWCAG 2.2達成基準に違反する場合、「プロジェクトおよびWCAG注記」(
N-01…)に、ガイドラインセクションまたはWCAG 2.2 SC x.y.zをソースとして入れます(典型的なケース:lang属性の欠落、ズームを無効にするビューポートメタタグ)。それ以外の場合は除外します。 - 台帳を確認します:記録された逸脱は再度報告しません(抑制された項目の数を1行で言及します)。
- プロジェクトガイドラインを確認します:階層CまたはEとの競合は「決定候補」に行き、指摘には行きません。プロジェクトの選択に逸脱するM3ルールがない場合、候補はルールID
none (project convention)を使用します。 - 分類:階層(F、C、E)と種類(問題または提案)をトレランスに従って行います。
inspiredモードでは、階層Cの不一致が「ユーザビリティを損なう」(したがって問題)のは、典型的なユーザーにとってコンテンツが読みにくい、操作しにくい、またはあいまいになる場合のみです:12px未満のテキスト、目的や状態が不明確なコントロール、サポートされている幅でレイアウトが壊れる場合。それ以外の場合は提案です。 - グループ化:根本原因ごとに1つの指摘。同じ問題が複数の場所に現れる場合、または1つの共有コンポーネント、クラス、トークンから発生する場合、カウントと各出現箇所(または2〜3つの例と合計:「14個のアイコンボタン、32 x 32 px、例:
.toolbar button、#close」)を付けて一度報告し、単一の決定でカバーできるようにします。修正が存在する領域に指摘を配置します。
影響度で並べ替え:最初に階層Fの問題、次にタスク完了に影響する問題、次に階層Cの問題、最後に提案。グループ内では、リーチ(影響を受ける要素または画面の数)で並べ替えます。レポートを約25の指摘に制限します。それ以上ある場合は、除外した数を伝え、2回目のパスを提供します。
問題がほとんどない、またはない場合は、その旨を簡潔に述べてください。お世辞の賞賛を追加しないでください。レポートを埋めるために問題を発明しないでください。
ステップ6. 提示
references/report-template.md を正確に使用します。各指摘には以下が含まれます:実行ID(階層ではなく F-01)、領域、階層と種類、証拠(セレクタまたは画像領域、値、証拠ラベル、出現回数)、ルールIDとそのソース、なぜ重要か(1行、ユーザー影響を最初に)、具体的な提案変更(min-height: 48px、color: var(--md-sys-color-on-surface-variant)、「コーナーエクストララージ、28dp」。「コントラストを改善」は不可)、労力(S:1つのプロパティまたはトークン、M:1つのコンポーネントまたは複数のファイル、L:構造的または画面横断)、および決定ボックス。
レポートヘッダーには以下が記載されます:レビュー対象と幅、トレランス、リファレンスのスナップショット日付(読み込まれたリファレンスファイルのヘッダーの中で最も古い「スナップショット日付」)、プロジェクトガイドラインと台帳が見つかったかどうか、証拠の混合(4つのラベルそれぞれのカウント)。ブリーフがある場合、ルールに違反する失敗したACは指摘(または注記)でもあります。そのAC行は証拠を繰り返す代わりに、その F-nn/N-nn を指します。
鮮度:スナップショット日付を今日の日付と比較します。6ヶ月以上前の場合、またはユーザーが新しいMaterialリリースについて言及した場合、ヘッダーにその旨を記載し、階層Cの変更を実装する前にリファレンス(リポジトリの maintenance/UPDATING.md)を更新することを推奨し、影響を受けるルールを https://m3.material.io/ に対して最初に検証することを提案します。階層Fの指摘はスナップショットの経過時間に関係なく有効です。
ステップ7. 決定の適用
ユーザーが回答した場合(例:「F-01からF-05を受け入れる、F-07の逸脱:ブランドピルボタン、残りは却下」):
- 階層CまたはEのルールに対する各
deviationについて:決定台帳に1つのエントリを追加します(日付、ルールID、範囲、1行の根拠、指摘ID)。形式はreferences/adapter-protocol.mdに従います。階層Fの指摘は逸脱できません。accepted riskとして記録し、サマリー行で報告し続けます。台帳が存在しない場合、そのパスを提案し、ユーザーが同意した後にのみ作成します。 - ルールIDが
noneの各決定候補について...