material-3

Material Design 3

このスキルでは、Google の Material Design 3（MD3）の実装方法を説明します。MD3 は、個人に合わせて適応し、表現力豊かなデザインシステムです。動的カラー、トーンを重ねたサーフェス、角丸の形状、スプリングベースのモーションにより、生き生きとした個性のある UI を実現します。

哲学

MD3 は、次の 3 つの原則に基づいています。

• パーソナル：動的カラーが、ユーザーの壁紙やコンテンツに合わせて UI を調整します。テーマは画一的ではなく、個々に合わせたものです。
• アダプティブ：レイアウトは 5 つのウィンドウサイズクラスに応じて変化します。コンポーネントは、画面サイズに応じてサイズや配置、フォームファクターを変えます。
• 表現力豊か：形状のモーフィング、スプリング物理、強調されたタイポグラフィにより、使いやすさを損なうことなく、心躍る瞬間を生み出します。

最新情報：Google I/O 2026

Material のGoogle I/O 2026 アップデートでは、Compose を最優先する Android の方針を強化し、表現力と適応性に関するガイダンスを拡充しています。

• Material Android は Compose を最優先します：新しい Android 開発では、最新のコンポーネント、表現力豊かな API、アダプティブなスキャフォールド、Styles API との統合を利用できる Jetpack Compose Material3 を優先してください。既存のアプリでは Android Views が引き続き必要な場合もありますが、新しい Material 3 実装の標準的な方法として扱うべきではありません。
• 表現力豊かなレイアウトシステム：表現力豊かなレイアウトスキャフォールドを使い、モバイル、デスクトップ、折りたたみ式デバイス、時計、XR などの空間的なフォームファクターに応じて画面を調整します。固定されたスマートフォン優先のレイアウトではなく、アダプティブスキャフォールドやウィンドウサイズクラスから始めてください。
• 8dp のスペーシングシステム：マージン、パディング、間隔にスペーシングトークンを適用し、デバイスの種類や密度に応じてレイアウトやコンポーネントをプログラムで調整できるようにします。
• 新規・更新された表現力豊かなコンポーネント：リスト、メニュー、検索、検索アプリバーの表現力豊かなガイダンスが更新されており、Jetpack Compose が主な実装対象です。
• 時計と XR：時計では、物理ベースのモーション、円弧状のテキスト、画面の端に沿うコンテナーを重視します。XR では、空間パネルと奥行きに基づく高度を重視します。

MD2 との主な違い：

• 深さを示す主な手がかりとして、エレベーションシャドウの代わりにトーン付きサーフェスを使用します
• 動的カラーにより、1 つのシードカラーから完全なカラースキームを生成します
• デフォルトの角は完全な丸みを帯びています（わずかな角丸ではありません）
• コンポーネントでは、固定されたイージングカーブの代わりにスプリングベースのモーション物理を使用します
• ユーザーが調整できるコントラストレベルは 3 段階です（標準／中／高）

frontend-design スキルとの関係： 両方のスキルが有効な場合、MD3 はデザインシステム（トークン、コンポーネント、レイアウト規則）を提供し、frontend-design はその制約の範囲内でクリエイティブな方向性を示します。コンポーネントの構造とトークンの使用については、MD3 の規則が優先されます。注：Roboto／Roboto Flex は MD3 における正しいデフォルト書体です。Roboto を避けるという frontend-design のガイダンスは、MD3 の実装には適用されません。

決定ツリー

何を作成しますか？

Full app scaffold        → See "Common Patterns: App Shell" + references/layout-and-responsive.md
Single component         → See "Component Quick Reference" table → references/component-catalog.md
Custom theme             → See references/theming-and-dynamic-color.md
Form / input layout      → See references/component-catalog.md § Input Components
Navigation structure     → See references/navigation-patterns.md
Data display             → See references/component-catalog.md § Data Display

どのプラットフォームですか？

Jetpack Compose          → Primary: androidx.compose.material3, MaterialTheme, references/*
Flutter                  → useMaterial3: true in ThemeData, ColorScheme.fromSeed()
Web (vanilla JS)         → @material/web (limited; maintenance mode) + CSS custom properties
Web (React/Vue/Svelte)   → CSS custom properties + wrapper components (no official React lib)
Web (CSS-only)           → MD3 token values as CSS custom properties (no <md-*> elements)

デザイントークンシステム

すべての MD3 トークンは md.sys 名前空間を使用します。Jetpack Compose では、ロールを MaterialTheme.colorScheme、MaterialTheme.typography、MaterialTheme.shapes に割り当てます（仕様と同じ意味的なロールです）。ウェブでは、これらを CSS カスタムプロパティ（--md-sys-*）に割り当てます。

カラートークン（--md-sys-color-*）

トークン	用途
primary	サーフェス上で強い強調を示す塗りつぶし、テキスト、アイコン
on-primary	primary 上のテキスト／アイコン
primary-container	主要なコンポーネント（FAB など）用の目立つ塗りつぶし
on-primary-container	primary-container 上のテキスト／アイコン
secondary / on-secondary	控えめなアクセント
secondary-container / on-secondary-container	控えめなコンポーネント（トーナルボタン）
tertiary / on-tertiary	コントラストのあるアクセント
tertiary-container / on-tertiary-container	補完的なコンテナー
error / on-error	エラー状態（固定。ダイナミックカラーによって変化しません）
error-container / on-error-container	エラーコンテナーの塗りつぶし
surface	デフォルトの背景
on-surface	あらゆるサーフェス上のテキスト／アイコン
on-surface-variant	サーフェス上の、強調度を抑えたテキスト／アイコン
surface-container-lowest	最も強調度の低いコンテナー
surface-container-low	強調度の低いコンテナー
surface-container	デフォルトのコンテナー（ナビゲーション領域）
surface-container-high	強調度の高いコンテナー
surface-container-highest	最も強調度の高いコンテナー
surface-dim / surface-bright	ライト／ダークモード間で相対的な明るさを維持
inverse-surface / inverse-on-surface / inverse-primary	コントラストをつける要素（スナックバー）
outline	重要な境界線（テキストフィールドの枠線）
outline-variant	装飾要素（区切り線）

詳細：references/color-system.md

タイポグラフィトークン（--md-sys-typescale-*）

スケール	サイズ	用途
Display	L / M / S	ヒーローテキスト、大きな数字
Headline	L / M / S	セクション見出し
Title	L / M / S	小さな見出し、カードタイトル
Body	L / M / S	段落テキスト、説明
Label	L / M / S	ボタン、チップ、キャプション

各スタイルには次のトークンがあります：-font、-weight、-size、-line-height、-tracking さらに、--md-sys-typescale-emphasized-* による、ウェイトを高めた強調バリアントが15種類あります。

詳細：references/typography-and-shape.md

シェイプトークン（--md-sys-shape-corner-*）

トークン	値	コンポーネントの例
none	0dp	—
extra-small	4dp	チップ、スナックバー
small	8dp	テキストフィールド、メニュー
medium	12dp	カード
large	16dp	FAB、ナビゲーションドロワー
large-increased	20dp	（エクスプレッシブ）
extra-large	28dp	ダイアログ、ボトムシート
extra-large-increased	32dp	（エクスプレッシブ）
extra-extra-large	48dp	（エクスプレッシブ）
full	9999px	ボタン、チップ、バッジ

エレベーションレベル

レベル	DP	トーナルオフセット	用途
0	0dp	なし	フラットなサーフェス、静止状態のほとんどのコンポーネント
1	1dp	primary を +5%	エレベーテッドカード、モーダルシート
2	3dp	primary を +8%	メニュー、ナビゲーションバー、スクロール時のアプリバー
3	6dp	primary を +11%	FAB、ダイアログ、検索、日付／時刻ピッカー
4	8dp	primary を +12%	（ホバー／フォーカス時のみ増加）
5	12dp	primary を +14%	（ホバー／フォーカス時のみ増加）

MD3 では、エレベーションは影ではなくトーナルサーフェスカラーによって表現されます。影は、複雑な背景に対する追加の視認性確保が必要な場合にのみ使用します。

モーション

MD3 Expressive（2025年5月）では、コンポーネントにスプリングベースのモーション物理が導入されました。従来のイージング／継続時間システムは、引き続きトランジション（入場／退場／共有軸）に使用されます。

イージング	継続時間	トランジションの種類
強調	500ms	画面上で開始および終了
強調・減速	400ms	画面に入る
強調・加速	200ms	画面から出る
標準	300ms	画面上で開始および終了（ユーティリティ）
標準・減速	250ms	画面に入る（ユーティリティ）
標準・加速	200ms	画面から出る（ユーティリティ）

CSS イージング値：

• 強調：cubic-bezier(0.2, 0, 0, 1)
• 強調・減速：cubic-bezier(0.05, 0.7, 0.1, 1)
• 強調・加速：cubic-bezier(0.3, 0, 0.8, 0.15)
• 標準：cubic-bezier(0.2, 0, 0, 1)
• 標準・減速：cubic-bezier(0, 0, 0, 1)
• 標準・加速：cubic-bezier(0.3, 0, 1, 1)

コンポーネント早見表

コンポーネント	Web 要素	主なバリエーション	カテゴリ
ボタン	md-filled-button, md-outlined-button, md-text-button, md-elevated-button, md-filled-tonal-button	塗りつぶし、アウトライン、テキスト、浮き上がり、トーナル；5 サイズ（XS–XL）；トグル	アクション
ボタングループ	md-button-group	標準、連結	アクション
拡張 FAB	md-extended-fab	サーフェス、プライマリ、セカンダリ、ターシャリ	アクション
FAB	md-fab	スモール、ミディアム、ラージ	アクション
FAB メニュー	—	—	アクション
アイコンボタン	md-icon-button, md-filled-icon-button, md-filled-tonal-icon-button, md-outlined-icon-button	標準、塗りつぶし、トーナル塗りつぶし、アウトライン	アクション
セグメントボタン	—	単一選択、複数選択	アクション
分割ボタン	—	—	アクション
バッジ	—	スモール（ドット）、ラージ（カウント）	コミュニケーション
ローディングインジケーター	—	線形、円形	コミュニケーション
プログレスインジケーター	md-linear-progress, md-circular-progress	線形、円形；確定／不確定	コミュニケーション
スナックバー	—	1 行、2 行、アクション	コミュニケーション
ツールチップ	—	プレーン、リッチ	コミュニケーション
カード	—	塗りつぶし、アウトライン、浮き上がり	コンテナ
カルーセル	—	複数表示、コンテナなし、ヒーロー	コンテナ
ダイアログ	md-dialog	基本、全画面	コンテナ
ボトムシート	—	標準、モーダル	シート
サイドシート	—	標準、モーダル	シート
区切り線	md-divider	全幅、インセット	コンテナ
チェックボックス	md-checkbox	—	入力
チップ	md-chip-set, md-assist-chip, md-filter-chip, md-input-chip, md-suggestion-chip	アシスト、フィルター、入力、候補	入力
日付ピッカー	—	ドッキング、モーダル、範囲	入力
メニュー	md-menu, md-menu-item	—	入力
ラジオボタン	md-radio	—	入力
スライダー	md-slider	連続、離散、範囲	入力
スイッチ	md-switch	アイコンあり／なし	入力
テキストフィールド	md-filled-text-field, md-outlined-text-field	塗りつぶし、アウトライン	入力
時刻ピッカー	—	ドッキング、モーダル	入力
アプリバー（上部）	—	中央揃え、スモール、ミディアム、ラージ	ナビゲーション
ナビゲーションバー	md-navigation-bar	—	ナビゲーション
ナビゲーションドロワー	md-navigation-drawer	標準、モーダル	ナビゲーション
ナビゲーションレール	—	—	ナビゲーション
検索	—	検索バー、検索ビュー	ナビゲーション
タブ	md-tabs, md-primary-tab, md-secondary-tab	プライマリ、セカンダリ	ナビゲーション
ツールバー	—	—	ナビゲーション
リスト	md-list, md-list-item	1 行、2 行、3 行	データ表示

注： Web 要素が — と記載されているコンポーネントには、まだ @material/web の実装がありません。これらには、標準 HTML と CSS カスタムプロパティを使用してください。Compose の対応表と例は references/component-catalog.md にあります。

コード例を含むコンポーネントの詳細：references/component-catalog.md

Jetpack Compose（主要）

MaterialTheme と Material 3 のコンポーザブル（Scaffold、Button、NavigationBar、トップアプリバーなど）で androidx.compose.material3 を使用します。

• テーマ設定：MaterialTheme(colorScheme = …, typography = …, shapes = …) を使用します。動的カラーを使う場合は、Android 12+（API 31+） では dynamicLightColorScheme／dynamicDarkColorScheme を優先します。それ以外の場合は lightColorScheme／darkColorScheme、または Material Theme Builder で生成したテーマコードを使用します。
• アダプティブ UI：ウィンドウサイズクラス、リスト・詳細画面と補助ペインのレイアウト、折りたたみ式デバイスについては、references/layout-and-responsive.md と references/navigation-patterns.md を参照してください。
• エッジツーエッジとインセット：バーと IME が正しく動作するよう、WindowInsets／Scaffold のパディングを使ってコンテンツを配置します。references/layout-and-responsive.md を参照してください。
• 実験的 API：一部の Material 3 API では @OptIn(ExperimentalMaterial3Api::class) または Expressive のオプトインが必要です。BOM とコンパイラーに合わせてください。

MaterialTheme(
    colorScheme = colorScheme, // from dynamicLightColorScheme / lightColorScheme / etc.
    typography = Typography(),
    shapes = Shapes(),
) {
    // M3 content — prefer references for Scaffold, navigation, text fields
}

Web（限定的）：@material/web

重要： Material Design 3 for Web によると、Material Web Components はメンテナンスモードであり、 M3 Expressive は Web に実装されていません。 トークンに基づく Web UI で適切な場合は @material/web を使用できますが、現在の Expressive 機能において Compose と同等のものとして扱わないでください。

セットアップ

npm install @material/web

コンポーネントを個別にインポートする

バンドルの肥大化を防ぐため、使用するコンポーネントだけをインポートしてください。

// Good — individual imports
import '@material/web/button/filled-button.js';
import '@material/web/button/outlined-button.js';
import '@material/web/textfield/outlined-text-field.js';
import '@material/web/icon/icon.js';

// Bad — never do this
import '@material/web'; // imports everything

基本的な使い方

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <link href="https://fonts.googleapis.com/css2?family=Roboto+Flex:wght@400;500;700&display=swap" rel="stylesheet">
  <link href="https://fonts.googleapis.com/icon?family=Material+Symbols+Outlined" rel="stylesheet">
</head>
<body>
  <md-filled-button>Get started</md-filled-button>
  <md-outlined-text-field label="Email" type="email"></md-outlined-text-field>

  <script type="module">
    import '@material/web/button/filled-button.js';
    import '@material/web/textfield/outlined-text-field.js';
  </script>
</body>
</html>

CSS カスタムプロパティを使ったテーマ設定

:root または任意の祖先要素に CSS カスタムプロパティを設定して、カスタムテーマを適用します。

:root {
  /* Color scheme (generate with @material/material-color-utilities) */
  --md-sys-color-primary: #6750A4;
  --md-sys-color-on-primary: #FFFFFF;
  --md-sys-color-primary-container: #EADDFF;
  --md-sys-color-on-primary-container: #21005D;
  --md-sys-color-secondary: #625B71;
  --md-sys-color-on-secondary: #FFFFFF;
  --md-sys-color-secondary-container: #E8DEF8;
  --md-sys-color-on-secondary-container: #1D192B;
  --md-sys-color-surface: #FEF7FF;
  --md-sys-color-on-surface: #1D1B20;
  --md-sys-color-surface-container: #F3EDF7;
  --md-sys-color-outline: #79747E;
  --md-sys-color-outline-variant: #CAC4D0;

  /* Typography */
  --md-sys-typescale-body-large-font: 'Roboto Flex', sans-serif;
  --md-sys-typescale-body-large-size: 1rem;
  --md-sys-typescale-body-large-weight: 400;
  --md-sys-typescale-body-large-line-height: 1.5rem;

  /* Shape */
  --md-sys-shape-corner-full: 9999px;
  --md-sys-shape-corner-medium: 12px;
}

コンポーネント単位のオーバーライド

個別のコンポーネントトークンをオーバーライドして、特定のカスタマイズを行います。

md-filled-button {
  --md-filled-button-container-color: var(--md-sys-color-primary);
  --md-filled-button-label-text-color: var(--md-sys-color-on-primary);
  --md-filled-button-container-shape: var(--md-sys-shape-corner-full);
  --md-filled-button-container-height: 40px;
}

md-outlined-text-field {
  --md-outlined-text-field-container-shape: var(--md-sys-shape-corner-small);
  --md-outlined-text-field-focus-outline-color: var(--md-sys-color-primary);
}

ダークテーマ

クラスまたはメディアクエリーでカラーのトークンをオーバーライドして、ダークテーマを適用します。

@media (prefers-color-scheme: dark) {
  :root {
    --md-sys-color-primary: #D0BCFF;
    --md-sys-color-on-primary: #381E72;
    --md-sys-color-primary-container: #4F378B;
    --md-sys-color-on-primary-container: #EADDFF;
    --md-sys-color-surface: #141218;
    --md-sys-color-on-surface: #E6E0E9;
    --md-sys-color-surface-container: #211F26;
    --md-sys-color-outline: #938F99;
    --md-sys-color-outline-variant: #49454F;
  }
}

テーマ設定の詳細ガイド：references/theming-and-dynamic-color.md

よく使われるパターン

アプリシェル

レスポンシブなナビゲーション、トップアプリバー、コンテンツ領域を備えた標準的な MD3 アプリです。

<div class="md3-app">
  <nav class="md3-nav-rail" aria-label="Main navigation">
    
    <md-fab size="small" aria-label="Compose">
      <md-icon slot="icon">edit</md-icon>
    </md-fab>
    <md-navigation-bar>
      <md-navigation-tab label="Home">
        <md-icon slot="active-icon">home</md-icon>
        <md-icon slot="inactive-icon">home</md-icon>
      </md-navigation-tab>
      <md-navigation-tab label="Search">
        <md-icon slot="active-icon">search</md-icon>
        <md-icon slot="inactive-icon">search</md-icon>
      </md-navigation-tab>
    </md-navigation-bar>
  </nav>
  <main class="md3-content">
    <header class="md3-top-app-bar">
      <h1 class="md3-top-app-bar__title" style="font: var(--md-sys-typescale-title-large)">
        Page Title
      </h1>
    </header>
    <div class="md3-body">
      
    </div>
  </main>
</div>

.md3-app {
  display: flex;
  min-height: 100vh;
  background: var(--md-sys-color-surface);
  color: var(--md-sys-color-on-surface);
}

.md3-nav-rail {
  width: 80px;
  background: var(--md-sys-color-surface);
  border-right: 1px solid var(--md-sys-color-outline-variant);
  display: flex;
  flex-direction: column;
  align-items: center;
  padding-top: 12px;
  gap: 12px;
}

.md3-content {
  flex: 1;
  display: flex;
  flex-direction: column;
}

.md3-top-app-bar {
  height: 64px;
  padding: 0 16px;
  display: flex;
  align-items: center;
  background: var(--md-sys-color-surface);
}

.md3-body {
  padding: 24px;
  flex: 1;
}

/* Responsive: switch to bottom nav on compact */
@media (max-width: 599px) {
  .md3-app { flex-direction: column; }
  .md3-nav-rail {
    order: 1;
    width: 100%;
    flex-direction: row;
    justify-content: center;
    border-right: none;
    border-top: 1px solid var(--md-sys-color-outline-variant);
    padding: 0;
  }
}

カードグリッド

<div class="md3-card-grid">
  <div class="md3-card md3-card--outlined">
    <img src="image.jpg" alt="Description" class="md3-card__media">
    <div class="md3-card__content">
      <h3 style="font: var(--md-sys-typescale-title-medium)">Card Title</h3>
      <p style="font: var(--md-sys-typescale-body-medium); color: var(--md-sys-color-on-surface-variant)">
        Supporting text for this card.
      </p>
    </div>
    <div class="md3-card__actions">
      <md-text-button>Learn more</md-text-button>
      <md-filled-tonal-button>Action</md-filled-tonal-button>
    </div>
  </div>
</div>

.md3-card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
  gap: 16px;
}

.md3-card--outlined {
  border: 1px solid var(--md-sys-color-outline-variant);
  border-radius: var(--md-sys-shape-corner-medium, 12px);
  background: var(--md-sys-color-surface);
  overflow: hidden;
}

.md3-card__content { padding: 16px; }
.md3-card__actions { padding: 8px 16px 16px; display: flex; gap: 8px; justify-content: flex-end; }
.md3-card__media { width: 100%; aspect-ratio: 16/9; object-fit: cover; }

フォームのレイアウト

<form class="md3-form">
  <md-outlined-text-field label="Full name" required></md-outlined-text-field>
  <md-outlined-text-field label="Email" type="email" required></md-outlined-text-field>
  <md-outlined-text-field label="Message" type="textarea" rows="4"></md-outlined-text-field>
  <div class="md3-form__actions">
    <md-text-button type="reset">Cancel</md-text-button>
    <md-filled-button type="submit">Submit</md-filled-button>
  </div>
</form>

.md3-form {
  display: flex;
  flex-direction: column;
  gap: 16px;
  max-width: 560px;
}

.md3-form__actions {
  display: flex;
  gap: 8px;
  justify-content: flex-end;
  margin-top: 8px;
}

その他のパターン：references/navigation-patterns.md、references/layout-and-responsive.md

アンチパターン

MD3 を実装する際に、次のことは決して行わないでください。

• MD2 と MD3 のライブラリを混在させる：@material/mdc-*（MD2）と @material/web（MD3）を併用しないでください。これらは互換性のない API とスタイルを使用しています。
• 色をハードコードする：常に var(--md-sys-color-*) トークンを使用し、生の 16 進数や RGB 値は使用しないでください。色をハードコードすると、動的なテーマ設定、ダークモード、コントラスト調整が機能しなくなります。
• トーンの組み合わせを無視する：意図された組み合わせ（例：primary + on-primary、surface-container + on-surface）のみを使用してください。任意の組み合わせでは、動的カラーやハイコントラストモードでコントラストが損なわれます。
• 区切り線に outline を使用する：区切り線には outline-variant を使用してください。outline は、テキストフィールドの枠線など、重要な境界に使用します。
• @material/web をすべてインポートする：コンポーネントのモジュールを個別にインポートしてください。バレルインポートではすべてのコンポーネントが含まれ、バンドルサイズが大幅に増加します。
• border-radius を直接使用する：シェイプトークン（var(--md-sys-shape-corner-medium)）を使用し、テーマ設定にかかわらずシェイプの一貫性を保ってください。
• デフォルトで影を使ってエレベーションを表現する：MD3 では、影ではなくトーンの異なるサーフェスカラーでエレベーションを表現します。煩雑な背景から要素を際立たせる必要がある場合にのみ、影を追加してください。
• frontend-design の「Roboto を避ける」ルールを適用する：Android では Roboto がデフォルトの Material 書体です。Web でも、MD3 トークンとともに Roboto または Roboto Flex がよく使われます。文字スケールを意図的にカスタマイズする場合にのみ、書体を変更してください。
• SSR との互換性を前提にする：@material/web は Web Components（カスタム要素）を使用するため、レンダリングには JavaScript が必要です。追加のハイドレーション戦略がなければ、SSR では意味のある HTML が生成されません。
• 折りたたみ式端末や大画面を無視する：MD3 はあらゆる画面サイズを想定して設計されています。スマートフォン専用のレイアウトはリリースせず、標準レイアウトを使用し、600dp 以上ではマルチペインにし、折りたたみ式端末やタブレットのエミュレーターでテストしてください。折り目やヒンジをまたいでインタラクティブなコンテンツを配置しないでください。
• 広い画面いっぱいにコンテンツを引き伸ばす：Large（1200dp 以上）および Extra-large（1600dp 以上）のウィンドウでは、コンテンツの最大幅を制限してください（840～1040dp）。横幅いっぱいに続くテキスト行は読みにくくなります。

プラットフォームに関する注意事項

Flutter

MaterialApp(
  theme: ThemeData(
    useMaterial3: true,
    colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
  ),
);

Jetpack Compose

上記の**Jetpack Compose（主要）**を参照してください。Build.VERSION.SDK_INT >= Build.VERSION_CODES.S かつ動的カラーが有効な場合にのみ、dynamicLightColorScheme／dynamicDarkColorScheme とともに LocalContext.current を使用してください。それ以外の場合は、静的なライト／ダークのスキームを指定してください。

コンポーネント名の対応表

概念	Web	Flutter	Compose
塗りつぶしボタン	md-filled-button	FilledButton	Button
枠線付きテキストフィールド	md-outlined-text-field	OutlinedTextField	OutlinedTextField
FAB	md-fab	FloatingActionButton	FloatingActionButton
ナビゲーションバー	md-navigation-bar	NavigationBar	NavigationBar
スイッチ	md-switch	Switch	Switch

M3 Expressive（2025年5月）

Expressive アップデートでは、使いやすさを維持しながら、ビジュアルの豊かさを高めます。利用可否はプラットフォームによって異なります。1 つのスタックですべてが実装されていると想定しないでください。

機能	Jetpack Compose	Flutter	Web（@material/web）
Expressive レイアウトのスキャフォールド／アダプティブレイアウト	Material3 のアダプティブ API とウィンドウサイズクラスを使った Compose 優先の実装	Flutter のアダプティブ／レイアウトプリミティブを使用	CSS／コンテナークエリ／手動レイアウト。Material Web と同等の機能はありません
8dp 間隔システム	デザイントークン／Dp 間隔定数を使用し、マージン、パディング、間隔をアダプティブに保ちます	テーマの間隔定数を使用	CSS カスタムプロパティ／デザイントークン
Expressive リスト、メニュー、検索、検索用アプリバー	現行の Material ガイダンスでの主な対象です。BOM とオプトインを確認してください	現行の Flutter Material ドキュメントを確認してください	仕様に準拠したカスタム実装です。@material/web はメンテナンスモードのみです
スプリング／モーション物理	Material 3 でサポートされています（BOM に応じて MotionScheme、Expressive API を参照してください）	Flutter Material のバージョンによって異なります	Material Web ではサポートされていません。イージング／時間、またはカスタムモーションを使用してください
強調されたタイポグラフィ	テーマ／文字スケールを通じて設定します	テーマを通じて設定します	トークン／CSS のみです。Expressive コンポーネントセットはありません
シェイプの変形	Google の Expressive 展開では Compose が優先されます	現行の Flutter ドキュメントを確認してください	@material/web ではサポートされていません
新しいボタンサイズ（XS–XL）、トグル	Compose Material3 コンポーネントに準拠します	Flutter MD3 に準拠します	高さ／CSS による近似のみです
追加のコーナートークン（例：large-increased）	MaterialTheme.shapes／トークン	テーマのシェイプ	CSS --md-sys-shape-*
3 段階のコントラスト	スキームビルダー／システム	プラグイン／手動	JS ユーティリティの SchemeContent コントラストパラメーター
ウォッチ／XR フォームファクター	利用可能な場合は Compose／Wear／XR 固有のガイダンスを使用します	プラットフォーム固有	Web／空間 UI のカスタム実装

Web： Material Web はメンテナンスモードのみです。M3 Expressive は Web では利用できません。モーションの代替手段として、スプリングと同等の動きではなく、CSS のイージング／時間トークンを使用してください。

従来のイージング／時間は、仕様で引き続き参照されているトランジション（入場／退場／共有軸）では有効です。以下のモーション表を参照してください。

MD3 準拠性監査

引数に audit を指定して呼び出された場合（例：/material-3 audit）、または MD3 準拠性の監査／レビューを依頼された場合は、対象のアプリまたはページを分析し、準拠性レポートを作成します。

監査手順

1. 対象を特定する：ユーザーが URL（ブラウザーツールで確認）、ファイルパス（ソースを読む）、または実行中のアプリを提供します。
2. 以下のカテゴリを調査し、それぞれ 0～10 で採点します。

カテゴリ	確認項目
カラー トークン	Web： --md-sys-color-*／生成された CSS。Compose： MaterialTheme.colorScheme のロール（理由なくサーフェスに任意の Color(...) を使用しない）。適切なトーンの組み合わせ（X 上に onX）。ダークテーマ。Flutter： ColorScheme のロール。
タイポグラフィ	MD3 のタイプスケール：Compose MaterialTheme.typography、Web タイプスケールのトークン。適切なロール（Display、Headline、Title、Body、Label）。
シェイプ	Compose MaterialTheme.shapes／コンポーネントの Shape、Web var(--md-sys-shape-*)。ボタン：完全な形、カード：中程度の角丸。マジックナンバーは避けます。
エレベーション	適切に Surface のトーンエレベーション／シャドウを使用します。Web： 関連する場合はホバー／フォーカス時の状態。
コンポーネント	Compose： Material3 のコンポーザブル（Button、Scaffold など）。Web： @material/web または仕様に沿った HTML／CSS。適切なバリアント。
レイアウト	標準的なレイアウト。Compose： ウィンドウサイズクラス／アダプティブ API。大きな画面幅で読みやすい最大幅。折りたたみ式デバイスのヒンジを避けます。
ナビゲーション	サイズクラスに応じたバー／レール／ドロワー／ドロワー＋Compose NavHost のパターン。該当する場合は予測型「戻る」操作。
モーション	Compose： 使用している場合は MotionScheme／Expressive API。トランジションでは引き続きイージング／継続時間を使用できます。Web： CSS モーショントークンへのフォールバック。
アクセシビリティ	MD3 のロールは役立ちますが、コントラストを確認します。UI コンポーネントでは、大きなテキスト／境界線に 3:1、通常のテキストに 4.5:1 が必要な場合があります（WCAG 2.x）。TalkBack／セマンティクス（Compose）、フォーカス順序、タッチターゲット（約 48dp）。Web： ARIA、キーボード操作。
テーマ設定	Compose： 設計に応じて MaterialTheme とライト／ダーク／ダイナミックカラーを使用します。Web： :root またはサブツリー上の CSS カスタムプロパティ。Flutter： ThemeData と ColorScheme。

3. レポートを生成する：

# MD3 Compliance Audit Report

Target: [URL or file path]
Date: [date]
Overall Score: [X/100]

## Scores by Category
| Category       | Score | Status |
|----------------|-------|--------|
| Color tokens   | X/10  | [pass/warn/fail] |
| Typography     | X/10  | [pass/warn/fail] |
| Shape          | X/10  | [pass/warn/fail] |
| Elevation      | X/10  | [pass/warn/fail] |
| Components     | X/10  | [pass/warn/fail] |
| Layout         | X/10  | [pass/warn/fail] |
| Navigation     | X/10  | [pass/warn/fail] |
| Motion         | X/10  | [pass/warn/fail] |
| Accessibility  | X/10  | [pass/warn/fail] |
| Theming        | X/10  | [pass/warn/fail] |

## Critical Issues
[List items scoring 0-3 with specific file:line references and fixes]

## Warnings
[List items scoring 4-6 with recommendations]

## Passing
[List items scoring 7-10 with notes on what's done well]

## Recommended Fixes (Priority Order)
1. [Most impactful fix first]
2. ...

監査方法

ライブ URL の場合（ブラウザーまたは開発者ツール）：

• 計算済みスタイルと CSS 変数（--md-sys-*）を調査します
• ビューポートのサイズを変更するか、レスポンシブモードでブレークポイントを確認します
• 役立つ場合は、主要な画面幅でスクリーンショットを撮影します

ソースコードの場合（ファイルパスが提供された場合）：

• Compose／Kotlin： .kt ファイル — MaterialTheme、コンポーザブル、Color(0x…) の不適切な使用、ハードコードされた Dp、必要な箇所での Modifier.semantics の不足
• Flutter： .dart — ThemeData、ColorScheme
• Web： HTML／JSX／Vue／Svelte、トークン用の CSS／SCSS
• Web のインポートを確認し、@material/web と @material/mdc-*（MD2）のどちらを使っているか調べます

クイックチェック（使用する技術スタックに合わせてパスを調整してください）：

# Web: hardcoded colors
grep -rn '#[0-9a-fA-F]\{3,8\}' --include='*.css' --include='*.scss'

# Compose: raw Color(...) audits (sample — tune for your codebase)
grep -rn 'Color(0x' --include='*.kt'

# MD2 on web
grep -rn '@material/mdc-' --include='*.js' --include='*.ts'

ブラウザー自動化（環境で MCP ブラウザーツールが利用可能な場合）：ページを開き、DOM／CSS 変数のスナップショットを取得し、ブレークポイントを確認するためにサイズを変更します。任意であり、必須ではありません。

採点ガイド

• 9-10：MD3 に完全準拠し、適切なトークンとパターンを使用
• 7-8：おおむね準拠。軽微な問題（例：一部の値がハードコードされている）
• 4-6：部分的に準拠。MD3 のパターンを一部使用しているものの、重大な不足がある
• 1-3：重大な違反があり、MD3 以外または MD2 のパターンが大半を占める
• 0：該当しない、または完全に欠如

ステータスのしきい値：合格（7 以上）、警告（4～6）、不合格（0～3）

参考ドキュメント

• references/color-system.md — カラーロール、トーンパレット、ダイナミックカラー、Compose と CSS の対応付け
• references/typography-and-shape.md — タイプスケール、シェイプの角、エレベーション、モーション、Expressive に関する注記
• references/component-catalog.md — コンポーネント：Compose と該当する場合の @material/web
• references/navigation-patterns.md — ナビゲーションの選択、Compose を優先したアダプティブパターン
• references/layout-and-responsive.md — ブレークポイント、標準的なレイアウト、インセット、折りたたみ式デバイス
• references/theming-and-dynamic-color.md — テーマ設定：Compose を優先し、次に Flutter と Web