material-3

Material Design 3

本技能将指导你实现 Google 的 Material Design 3（MD3）——一套个性化、自适应且富有表现力的设计系统。MD3 使用动态颜色、色调表面、圆角形状和基于弹簧的动效，打造鲜活且个性化的 UI。

设计理念

MD3 建立在三项原则之上：

• 个性化：动态颜色会根据用户的壁纸或内容调整 UI。主题因人而异，而非千篇一律。
• 自适应：布局会在 5 种窗口尺寸类别间转换。组件会根据不同设备灵活调整大小、位置和形态。
• 表现力：形状变形、弹簧物理效果和强调式排版，能带来愉悦体验，同时不牺牲易用性。

最新更新：Google I/O 2026

Material 在 Google I/O 2026 上的更新进一步确立了 Compose 优先的 Android 路径，并拓展了表现力和自适应设计指南：

• Material Android 以 Compose 为先：对于新的 Android 开发，优先选择 Jetpack Compose Material3，以使用最新组件、表现力 API、自适应脚手架和 Styles API 集成。现有应用可能仍需使用 Android Views，但新 Material 3 实现不应默认采用这种路径。
• 表现力布局系统：使用表现力布局脚手架，使屏幕适配手机、桌面设备、折叠屏设备、手表、XR 及其他空间设备形态。应从自适应脚手架和窗口尺寸类别入手，而非采用固定的手机优先布局。
• 8dp 间距系统：使用间距令牌设置边距、内边距和间隔，让布局和组件能根据设备类型与屏幕密度进行程序化适配。
• 新增／更新的表现力组件：列表、菜单、搜索和搜索应用栏的表现力设计指南已更新，主要实现目标为 Jetpack Compose。
• 手表和 XR：手表设计着重于基于物理效果的动效、弧形文字和贴边容器。XR 设计着重于空间面板和基于深度的高度。

与 MD2 的主要区别：

• 色调表面取代高度阴影，成为主要的深度提示
• 动态颜色可根据单个种子颜色生成完整配色方案
• 默认采用全圆角，而非轻微圆角
• 组件使用基于弹簧的动效物理效果，取代固定缓动曲线
• 提供 3 个由用户控制的对比度级别（标准／中等／高）

与 frontend-design 技能的关系： 两项技能同时启用时，MD3 提供设计系统（令牌、组件、布局规则），frontend-design 则在这些约束内提供创意方向。组件结构和令牌用法应以 MD3 规则为准。注意：Roboto／Roboto Flex 确实是 MD3 的默认字体——实现 MD3 时，不适用 frontend-design 中避免使用 Roboto 的指南。

决策树

你要构建什么？

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（与规范中的语义角色相同）。在 Web 上，这些角色会映射到 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	对比元素（Snackbar）
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 另有 15 种通过 --md-sys-typescale-emphasized-* 提供的强调变体（字重更高）

完整详情：references/typography-and-shape.md

形状令牌（--md-sys-shape-corner-*）

令牌	值	组件示例
none	0dp	—
extra-small	4dp	标签、Snackbar
small	8dp	文本字段、菜单
medium	12dp	卡片
large	16dp	FAB、导航抽屉
large-increased	20dp	（Expressive）
extra-large	28dp	对话框、底部工作表
extra-large-increased	32dp	（Expressive）
extra-extra-large	48dp	（Expressive）
full	9999px	按钮、标签、徽章

高度级别

级别	DP	色调偏移	用途
0	0dp	无	平面表面、大多数静止状态的组件
1	1dp	+5% primary	浮起的卡片、模态工作表
2	3dp	+8% primary	菜单、导航栏、滚动后的应用栏
3	6dp	+11% primary	FAB、对话框、搜索、日期／时间选择器
4	8dp	+12% primary	（仅在悬停／聚焦时增加）
5	12dp	+14% primary	（仅在悬停／聚焦时增加）

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	线性、圆形；确定／不确定	通信
Snackbar	—	单行、双行、操作	通信
工具提示	—	简洁、富文本	通信
卡片	—	填充、描边、悬浮	容器
轮播	—	多项浏览、不受容器限制、主视觉	容器
对话框	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	单行、双行、三行	数据展示

**注意：**Web 元素标记为 — 的组件尚无 @material/web 实现。请将 CSS 自定义属性与标准 HTML 搭配使用。Compose 映射和示例位于 references/component-catalog.md。

完整组件详情及代码示例：references/component-catalog.md

Jetpack Compose（主要方式）

使用 androidx.compose.material3，搭配 MaterialTheme 和 Material 3 可组合项（Scaffold、Button、NavigationBar、顶部应用栏等）。

• 主题：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。
• 边缘到边缘显示与内边距：使用 WindowInsets / Scaffold 内边距布局内容，确保系统栏和 IME 行为正确——请参阅 references/layout-and-responsive.md。
• 实验性 API：部分 Material 3 API 需要 @OptIn(ExperimentalMaterial3Api::class) 或表达式相关的 opt-in；请确保与 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 处于维护模式，且 Web 尚未实现 M3 Expressive。在适当情况下，可使用 @material/web 构建基于令牌的 Web UI，但不要将其视为与当前 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-*) 令牌，绝不要使用原始的十六进制或 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 通常使用 Roboto 或 Roboto Flex，并搭配 MD3 令牌。仅在有意自定义字体比例时才替换字体。
• 假设兼容 SSR：@material/web 使用 Web Components（自定义元素），需要 JavaScript 才能渲染。如果没有额外的 hydration 策略，它们在 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 且启用了动态颜色时，使用 LocalContext.current 搭配 dynamicLightColorScheme / dynamicDarkColorScheme；否则，请提供静态的浅色/深色配色方案。

组件名称对照表

概念	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 更新在保持易用性的同时，增添了视觉丰富度。不同平台的可用功能有所差异——不要假设所有技术栈都实现了全部功能。

功能	Jetpack Compose	Flutter	Web（@material/web）
Expressive 布局框架／自适应布局	优先使用 Compose，通过 Material3 自适应 API 和窗口尺寸类别实现	使用 Flutter 自适应／布局基础组件	CSS／容器查询／手动布局；与 Material Web 不完全一致
8dp 间距系统	使用设计令牌／Dp 间距常量；让外边距、内边距和间隔保持自适应	使用主题间距常量	CSS 自定义属性／设计令牌
Expressive 列表、菜单、搜索、搜索应用栏	根据当前 Material 指南，这是主要目标；请检查 BOM 和 opt-in 要求	查阅当前 Flutter Material 文档	符合规范的自定义实现；@material/web 仅处于维护阶段
弹簧／动态效果物理	Material 3 支持（参见 MotionScheme，并根据 BOM 使用 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 / 表现力 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