Back to Details

material-3

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Material Design 3

Material Design 3

This skill guides implementation of Google's Material Design 3 (MD3) — a personal, adaptive, expressive design system. MD3 uses dynamic color, tonal surfaces, rounded shapes, and spring-based motion to create UIs that feel alive and personal.
本技能指导如何实现谷歌的Material Design 3（MD3）——一套个性化、自适应、富有表现力的设计系统。MD3采用动态色彩、色调化表面、圆角造型以及基于弹簧物理的动效，打造出鲜活且极具个性的UI界面。

Philosophy

设计理念

MD3 is built on three principles:
  • Personal: Dynamic color adapts UI to the user's wallpaper or content. Theming is individual, not one-size-fits-all.
  • Adaptive: Layouts transform across 5 window size classes. Components resize, reposition, and change form factor responsively.
  • Expressive: Shape morphing, spring physics, and emphasized typography create moments of delight without sacrificing usability.
MD3基于三大原则构建：
  • 个性化：动态色彩可根据用户壁纸或内容适配UI。主题配置因人而异，而非千篇一律。
  • 自适应：布局可在5种窗口尺寸类别间转换。组件会响应式地调整大小、位置及形态。
  • 表现力：形状变形、弹簧物理动效及强调式排版，在不牺牲可用性的前提下打造愉悦的交互体验。

Current Updates: Google I/O 2026

最新更新：Google I/O 2026

Material's Google I/O 2026 update reinforces a Compose-first Android path and expands expressive/adaptive guidance:
  • Material Android is Compose-first: For new Android work, prefer Jetpack Compose Material3 for the latest components, expressive APIs, adaptive scaffolds, and Styles API integration. Android Views may remain necessary in existing apps, but they should not be treated as the default path for new Material 3 implementations.
  • Expressive layout system: Use an expressive layout scaffold to adapt screens across mobile, desktop, foldables, watches, XR, and other spatial form factors. Start from adaptive scaffolds/window size classes instead of fixed phone-first layouts.
  • 8dp spacing system: Apply spacing tokens for margins, padding, and gaps so layouts and components can adapt programmatically to device type and density.
  • New/updated expressive components: Lists, menus, search, and search app bars have refreshed expressive guidance, with Jetpack Compose as the primary implementation target.
  • Watches and XR: Watches emphasize physics-based motion, arc text, and edge-hugging containers. XR emphasizes spatial panels and depth-based elevation.
Key differences from MD2:
  • Tonal surfaces replace elevation shadows as the primary depth cue
  • Dynamic color generates full schemes from a single seed color
  • Fully rounded corners by default (not slightly rounded)
  • Spring-based motion physics replace fixed easing curves for components
  • 3 levels of user-controlled contrast (standard/medium/high)
Relationship with frontend-design skill: When both skills are active, MD3 provides the design system (tokens, components, layout rules) and frontend-design provides creative direction within those constraints. MD3 rules take precedence for component structure and token usage. Note: Roboto/Roboto Flex IS the correct default typeface in MD3 — the frontend-design guidance to avoid Roboto does not apply when implementing MD3.
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种用户可控的对比度级别（标准/中等/高）
与前端设计技能的关系： 当两项技能同时启用时，MD3提供设计系统（令牌、组件、布局规则），前端设计则在这些约束内提供创意方向。组件结构和令牌使用以MD3规则为准。注意：Roboto/Roboto Flex是MD3的正确默认字体——前端设计中“避免使用Roboto”的指导不适用于MD3实现场景。

Decision Tree

决策树

What are you building?
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
What platform?
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)
你要构建什么？
完整应用脚手架        → 查看「通用模式：应用框架」+ references/layout-and-responsive.md
单个组件         → 查看「组件速查表」→ references/component-catalog.md
自定义主题             → 查看 references/theming-and-dynamic-color.md
表单/输入布局      → 查看 references/component-catalog.md § 输入组件
导航结构     → 查看 references/navigation-patterns.md
数据展示             → 查看 references/component-catalog.md § 数据展示
面向什么平台？
Jetpack Compose          → 核心依赖：androidx.compose.material3、MaterialTheme、references/*
Flutter                  → 在ThemeData中设置useMaterial3: true，使用ColorScheme.fromSeed()
Web（原生JS）         → @material/web（受限；维护模式） + CSS自定义属性
Web（React/Vue/Svelte）   → CSS自定义属性 + 封装组件（无官方React库）
Web（纯CSS）           → 将MD3令牌值作为CSS自定义属性使用（无需<md-*>元素）

Design Token System

设计令牌系统

All MD3 tokens use the 
md.sys
namespace. Jetpack Compose maps roles to 
MaterialTheme.colorScheme
, 
MaterialTheme.typography
, and 
MaterialTheme.shapes
(same semantic roles as the spec). On the web, these map to CSS custom properties (
--md-sys-*
):
所有MD3令牌使用
md.sys
命名空间。Jetpack Compose将角色映射到
MaterialTheme.colorScheme
、
MaterialTheme.typography
和
MaterialTheme.shapes
（与规范中的语义角色一致）。Web端则映射到CSS自定义属性（
--md-sys-*
）：

Color Tokens (
--md-sys-color-*
)

色彩令牌（
--md-sys-color-*
）

TokenPurpose
primary
High-emphasis fills, text, icons against surface
on-primary
Text/icons on primary
primary-container
Standout fill for key components (FAB, etc.)
on-primary-container
Text/icons on primary-container
secondary
/ 
on-secondary
Less prominent accents
secondary-container
/ 
on-secondary-container
Recessive components (tonal buttons)
tertiary
/ 
on-tertiary
Contrasting accents
tertiary-container
/ 
on-tertiary-container
Complementary containers
error
/ 
on-error
Error states (static — doesn't change with dynamic color)
error-container
/ 
on-error-container
Error container fills
surface
Default background
on-surface
Text/icons on any surface
on-surface-variant
Lower-emphasis text/icons on surface
surface-container-lowest
Lowest-emphasis container
surface-container-low
Low-emphasis container
surface-container
Default container (nav areas)
surface-container-high
High-emphasis container
surface-container-highest
Highest-emphasis container
surface-dim
/ 
surface-bright
Maintain relative brightness across light/dark
inverse-surface
/ 
inverse-on-surface
/ 
inverse-primary
Contrasting elements (snackbars)
outline
Important boundaries (text field borders)
outline-variant
Decorative elements (dividers)
Full details: 
references/color-system.md
令牌用途
primary
高强调填充色、文本、图标（用于表面之上）
on-primary
主色之上的文本/图标色
primary-container
关键组件（如FAB）的突出填充色
on-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

Typography Tokens (
--md-sys-typescale-*
)

排版令牌（
--md-sys-typescale-*
）

ScaleSizesUse
DisplayL / M / SHero text, large numbers
HeadlineL / M / SSection headers
TitleL / M / SSmaller headers, card titles
BodyL / M / SParagraph text, descriptions
LabelL / M / SButtons, chips, captions
Each style has tokens for: 
-font
, 
-weight
, 
-size
, 
-line-height
, 
-tracking
Plus 15 emphasized variants (higher weight) via 
--md-sys-typescale-emphasized-*
Full details: 
references/typography-and-shape.md
层级尺寸用途
DisplayL / M / S英雄文本、大数字
HeadlineL / M / S章节标题
TitleL / M / S小标题、卡片标题
BodyL / M / S段落文本、描述内容
LabelL / M / S按钮、芯片、说明文字
每种样式包含以下令牌：
-font
、
-weight
、
-size
、
-line-height
、
-tracking
另外还有15种强调变体（更粗字重），通过
--md-sys-typescale-emphasized-*
调用
详细内容：
references/typography-and-shape.md

Shape Tokens (
--md-sys-shape-corner-*
)

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

TokenValueExample components
none
0dp—
extra-small
4dpChips, snackbars
small
8dpText fields, menus
medium
12dpCards
large
16dpFABs, navigation drawer
large-increased
20dp(Expressive)
extra-large
28dpDialogs, bottom sheets
extra-large-increased
32dp(Expressive)
extra-extra-large
48dp(Expressive)
full
9999pxButtons, chips, badges
令牌值示例组件
none
0dp—
extra-small
4dp芯片、Snackbar
small
8dp文本框、菜单
medium
12dp卡片
large
16dpFAB、导航抽屉
large-increased
20dp（表现力场景）
extra-large
28dp对话框、底部弹窗
extra-large-increased
32dp（表现力场景）
extra-extra-large
48dp（表现力场景）
full
9999px按钮、芯片、徽章

Elevation Levels

层级级别

LevelDPTonal offsetUse
00dpNoneFlat surfaces, most components at rest
11dp+5% primaryElevated cards, modal sheets
23dp+8% primaryMenus, nav bar, scrolled app bar
36dp+11% primaryFAB, dialogs, search, date/time pickers
48dp+12% primary(hover/focus increase only)
512dp+14% primary(hover/focus increase only)
Elevation in MD3 is communicated through tonal surface color, not shadows. Shadows are only used when needed for additional protection against busy backgrounds.
级别DP色调偏移用途
00dp无平面、静止状态下的大多数组件
11dp+5% 主色悬浮卡片、模态弹窗
23dp+8% 主色菜单、导航栏、滚动应用栏
36dp+11% 主色FAB、对话框、搜索、日期/时间选择器
48dp+12% 主色（仅用于 hover/focus 状态提升）
512dp+14% 主色（仅用于 hover/focus 状态提升）
MD3通过色调化表面颜色传达层级，而非阴影。仅当元素需要与复杂背景额外区分时才使用阴影。

Motion

动效

MD3 Expressive (May 2025) introduced spring-based motion physics for components. The legacy easing/duration system is still used for transitions (enter/exit/shared-axis):
EasingDurationTransition type
Emphasized500msBegin and end on screen
Emphasized decelerate400msEnter the screen
Emphasized accelerate200msExit the screen
Standard300msBegin and end on screen (utility)
Standard decelerate250msEnter screen (utility)
Standard accelerate200msExit screen (utility)
CSS easing values:
  • Emphasized: 
    cubic-bezier(0.2, 0, 0, 1)
  • Emphasized decelerate: 
    cubic-bezier(0.05, 0.7, 0.1, 1)
  • Emphasized accelerate: 
    cubic-bezier(0.3, 0, 0.8, 0.15)
  • Standard: 
    cubic-bezier(0.2, 0, 0, 1)
  • Standard decelerate: 
    cubic-bezier(0, 0, 0, 1)
  • Standard accelerate: 
    cubic-bezier(0.3, 0, 1, 1)
MD3 Expressive（2025年5月）为组件引入了基于弹簧的物理动效。传统的缓动/时长系统仍用于过渡动画（进入/退出/共享轴）：
缓动类型时长过渡类型
Emphasized500ms元素在屏幕内开始和结束
Emphasized decelerate400ms元素进入屏幕
Emphasized accelerate200ms元素退出屏幕
Standard300ms屏幕内实用型过渡
Standard decelerate250ms实用型进入过渡
Standard accelerate200ms实用型退出过渡
CSS缓动值：
  • Emphasized: 
    cubic-bezier(0.2, 0, 0, 1)
  • Emphasized decelerate: 
    cubic-bezier(0.05, 0.7, 0.1, 1)
  • Emphasized accelerate: 
    cubic-bezier(0.3, 0, 0.8, 0.15)
  • Standard: 
    cubic-bezier(0.2, 0, 0, 1)
  • Standard decelerate: 
    cubic-bezier(0, 0, 0, 1)
  • Standard accelerate: 
    cubic-bezier(0.3, 0, 1, 1)

Component Quick Reference

组件速查表

ComponentWeb ElementKey VariantsCategory
Button
md-filled-button
, 
md-outlined-button
, 
md-text-button
, 
md-elevated-button
, 
md-filled-tonal-button
Filled, Outlined, Text, Elevated, Tonal; 5 sizes (XS–XL); toggleActions
Button group
md-button-group
Standard, connectedActions
Extended FAB
md-extended-fab
Surface, Primary, Secondary, TertiaryActions
FAB
md-fab
Small, Medium, LargeActions
FAB menu——Actions
Icon button
md-icon-button
, 
md-filled-icon-button
, 
md-filled-tonal-icon-button
, 
md-outlined-icon-button
Standard, Filled, Filled Tonal, OutlinedActions
Segmented button—Single-select, Multi-selectActions
Split button——Actions
Badge—Small (dot), Large (count)Communication
Loading indicator—Linear, CircularCommunication
Progress indicator
md-linear-progress
, 
md-circular-progress
Linear, Circular; determinate/indeterminateCommunication
Snackbar—Single-line, Two-line, ActionCommunication
Tooltip—Plain, RichCommunication
Card—Filled, Outlined, ElevatedContainment
Carousel—Multi-browse, Uncontained, HeroContainment
Dialog
md-dialog
Basic, Full-screenContainment
Bottom sheet—Standard, ModalSheets
Side sheet—Standard, ModalSheets
Divider
md-divider
Full-width, InsetContainment
Checkbox
md-checkbox
—Input
Chips
md-chip-set
, 
md-assist-chip
, 
md-filter-chip
, 
md-input-chip
, 
md-suggestion-chip
Assist, Filter, Input, SuggestionInput
Date picker—Docked, Modal, RangeInput
Menu
md-menu
, 
md-menu-item
—Input
Radio button
md-radio
—Input
Slider
md-slider
Continuous, Discrete, RangeInput
Switch
md-switch
With/without iconInput
Text field
md-filled-text-field
, 
md-outlined-text-field
Filled, OutlinedInput
Time picker—Docked, ModalInput
App bar (top)—Center-aligned, Small, Medium, LargeNavigation
Navigation bar
md-navigation-bar
—Navigation
Navigation drawer
md-navigation-drawer
Standard, ModalNavigation
Navigation rail——Navigation
Search—Search bar, Search viewNavigation
Tabs
md-tabs
, 
md-primary-tab
, 
md-secondary-tab
Primary, SecondaryNavigation
Toolbar——Navigation
List
md-list
, 
md-list-item
One-line, Two-line, Three-lineData Display
Note: Components marked with 
—
for web element don't have @material/web implementations yet. Use CSS custom properties with standard HTML for these. Compose mappings and examples live in 
references/component-catalog.md
.
Full component details with code examples: 
references/component-catalog.md
组件Web元素核心变体分类
Button
md-filled-button
, 
md-outlined-button
, 
md-text-button
, 
md-elevated-button
, 
md-filled-tonal-button
填充型、轮廓型、文本型、悬浮型、色调填充型；5种尺寸（XS–XL）；切换式操作类
Button group
md-button-group
标准型、连接型操作类
Extended FAB
md-extended-fab
表面色、主色、次色、第三色操作类
FAB
md-fab
小、中、大尺寸操作类
FAB menu——操作类
Icon button
md-icon-button
, 
md-filled-icon-button
, 
md-filled-tonal-icon-button
, 
md-outlined-icon-button
标准型、填充型、色调填充型、轮廓型操作类
Segmented button—单选、多选操作类
Split button——操作类
Badge—小型（圆点）、大型（计数）通讯类
Loading indicator—线性、圆形通讯类
Progress indicator
md-linear-progress
, 
md-circular-progress
线性、圆形；确定/不确定状态通讯类
Snackbar—单行、两行、带操作按钮通讯类
Tooltip—普通型、富文本型通讯类
Card—填充型、轮廓型、悬浮型容器类
Carousel—多浏览型、无容器型、英雄型容器类
Dialog
md-dialog
基础型、全屏型容器类
Bottom sheet—标准型、模态型弹窗类
Side sheet—标准型、模态型弹窗类
Divider
md-divider
全宽型、缩进型容器类
Checkbox
md-checkbox
—输入类
Chips
md-chip-set
, 
md-assist-chip
, 
md-filter-chip
, 
md-input-chip
, 
md-suggestion-chip
辅助型、筛选型、输入型、建议型输入类
Date picker—停靠型、模态型、范围选择型输入类
Menu
md-menu
, 
md-menu-item
—输入类
Radio button
md-radio
—输入类
Slider
md-slider
连续型、离散型、范围型输入类
Switch
md-switch
带/不带图标输入类
Text field
md-filled-text-field
, 
md-outlined-text-field
填充型、轮廓型输入类
Time picker—停靠型、模态型输入类
App bar (top)—居中对齐、小、中、大尺寸导航类
Navigation bar
md-navigation-bar
—导航类
Navigation drawer
md-navigation-drawer
标准型、模态型导航类
Navigation rail——导航类
Search—搜索栏、搜索视图导航类
Tabs
md-tabs
, 
md-primary-tab
, 
md-secondary-tab
主选项卡、次选项卡导航类
Toolbar——导航类
List
md-list
, 
md-list-item
一行、两行、三行数据展示类
注意： Web元素列为
—
的组件尚无@material/web实现。可使用CSS自定义属性结合标准HTML实现这些组件。Compose的映射及示例见
references/component-catalog.md
。
包含代码示例的完整组件详情：
references/component-catalog.md

Jetpack Compose (primary)

Jetpack Compose（核心方案）

Use 
androidx.compose.material3
 with 
MaterialTheme
and Material 3 composables (
Scaffold
, 
Button
, 
NavigationBar
, top app bars, etc.).
  • Theming: 
    MaterialTheme(colorScheme = …, typography = …, shapes = …)
    . Prefer 
    dynamicLightColorScheme
    / 
    dynamicDarkColorScheme
    on Android 12+ (API 31+) when dynamic color is desired; otherwise 
    lightColorScheme
    / 
    darkColorScheme
    or generated theme code from Material Theme Builder.
  • Adaptive UI: Window size classes, list-detail and supporting-pane layouts, foldables — see 
    references/layout-and-responsive.md
    and 
    references/navigation-patterns.md
    .
  • Edge-to-edge & insets: Lay out content with 
    WindowInsets
    / scaffold padding so bars and IME behave correctly — see 
    references/layout-and-responsive.md
    .
  • Experimental APIs: Some Material 3 APIs require 
    @OptIn(ExperimentalMaterial3Api::class)
    or expressive opt-ins; match your BOM and compiler.
kotlin
MaterialTheme(
    colorScheme = colorScheme, // from dynamicLightColorScheme / lightColorScheme / etc.
    typography = Typography(),
    shapes = Shapes(),
) {
    // M3 content — prefer references for Scaffold, navigation, text fields
}
使用**
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
    / 脚手架内边距布局内容，确保状态栏、导航栏及输入法行为正确——详见
    references/layout-and-responsive.md
    。
  • 实验性API：部分Material 3 API需要添加
    @OptIn(ExperimentalMaterial3Api::class)
    或表现力相关注解；请匹配对应的BOM和编译器版本。
kotlin
MaterialTheme(
    colorScheme = colorScheme, // 来自dynamicLightColorScheme / lightColorScheme 等
    typography = Typography(),
    shapes = Shapes(),
) {
    // M3 内容——脚手架、导航、文本框等优先参考官方文档
}

Web (limited): @material/web

Web端（受限）：@material/web

Important: Per Material Design 3 for Web, Material Web Components are in maintenance mode and M3 Expressive is not implemented on Web. Use 
@material/web
for token-backed web UIs when appropriate, but do not treat it as equivalent to Compose for current Expressive features.
重要提示： 根据Material Design 3 for Web文档，Material Web Components处于维护模式，且M3 Expressive未在Web端实现。在合适场景下可使用
@material/web
构建基于令牌的Web UI，但请勿将其视为与Compose等效的当前表现力特性实现方案。

Setup

安装

bash
npm install @material/web
bash
npm install @material/web

Import Components Individually

单独导入组件

Always import only the components you use — importing the entire package bloats the bundle:
javascript
// 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
始终仅导入所需组件——导入整个包会导致包体积膨胀：
javascript
// 推荐——单独导入
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';

// 不推荐——绝对不要这样做
import '@material/web'; // 导入所有组件

Basic Usage

基础用法

html
<!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>
html
<!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>

Theming with CSS Custom Properties

使用CSS自定义属性配置主题

Apply a custom theme by setting CSS custom properties on 
:root
or any ancestor:
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;
}
通过在
:root
或任意父元素上设置CSS自定义属性来应用自定义主题：
css
:root {
  /* 配色方案（使用@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;

  /* 排版 */
  --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;

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

Component-Level Overrides

组件级覆盖

Override individual component tokens for specific customization:
css
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);
}
针对特定组件覆盖令牌以实现自定义：
css
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);
}

Dark Theme

暗色主题

Apply dark theme by overriding color tokens on a class or media query:
css
@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;
  }
}
Full theming guide: 
references/theming-and-dynamic-color.md
通过类选择器或媒体查询覆盖色彩令牌来应用暗色主题：
css
@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

Common Patterns

通用模式

App Shell

应用框架

Standard MD3 app with responsive navigation + top app bar + content area:
html
<div class="md3-app">
  <nav class="md3-nav-rail" aria-label="Main navigation">
    <!-- Navigation rail for medium+ screens -->
    <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">
      <!-- Content here -->
    </div>
  </main>
</div>
css
.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;
  }
}
带响应式导航+顶部应用栏+内容区域的标准MD3应用：
html
<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>
css
.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;
}

/* 响应式：紧凑屏幕切换为底部导航 */
@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;
  }
}

Card Grid

卡片网格

html
<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>
css
.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; }
html
<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>
css
.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 Layout

表单布局

html
<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>
css
.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;
}
More patterns: 
references/navigation-patterns.md
, 
references/layout-and-responsive.md
html
<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>
css
.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

Anti-Patterns

反模式

Never do these when implementing MD3:
  • Mix MD2 and MD3 libraries: Don't use 
    @material/mdc-*
    (MD2) alongside 
    @material/web
    (MD3). They have incompatible APIs and styling.
  • Hardcode colors: Always use 
    var(--md-sys-color-*)
    tokens, never raw hex/rgb values. Hardcoded colors break dynamic theming, dark mode, and contrast adjustment.
  • Ignore tonal pairing: Only combine colors in their intended pairs (e.g., 
    primary
    + 
    on-primary
    , 
    surface-container
    + 
    on-surface
    ). Arbitrary pairings break contrast in dynamic color and high contrast modes.
  • Use 
    outline
    for dividers    : Use 
    outline-variant
    for dividers. 
    outline
    is for important boundaries like text field borders.
  • Import all of @material/web: Always import individual component modules. Barrel imports include every component and destroy bundle size.
  • Use 
    border-radius
    directly    : Use shape tokens (
    var(--md-sys-shape-corner-medium)
    ) so shapes stay consistent with theming.
  • Use shadows for elevation by default: MD3 communicates elevation through tonal surface color, not shadows. Only add shadows when elements need extra separation from busy backgrounds.
  • Apply frontend-design "avoid Roboto" rule: On Android, Roboto is the default Material typeface; web often uses Roboto or Roboto Flex with MD3 tokens. Replace only when intentionally customizing the type scale.
  • Assume SSR compatibility: 
    @material/web
    uses Web Components (custom elements) which require JavaScript to render. They won't produce meaningful HTML in SSR without additional hydration strategies.
  • Ignore foldables and large screens: MD3 is designed for all screen sizes. Don't ship phone-only layouts — use canonical layouts, multi-pane at 600dp+, and test on foldable/tablet emulators. Place no interactive content across the fold/hinge.
  • Stretch content to fill wide screens: On Large (1200dp+) and Extra-large (1600dp+) windows, constrain content to a max width (840–1040dp). Endless-width text lines are unreadable.
实现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通过色调化表面颜色传达层级，而非阴影。仅当元素需要与复杂背景额外区分时才添加阴影。
  • 遵循前端设计的“避免使用Roboto”规则：在Android上，Roboto是Material的默认字体；Web端通常在MD3令牌中使用Roboto或Roboto Flex。仅在有意自定义排版层级时才替换字体。
  • 假设支持SSR：
    @material/web
    使用Web Components（自定义元素），需要JavaScript才能渲染。若无额外的水合策略，它们在SSR中无法生成有意义的HTML。
  • 忽略折叠屏和大屏幕：MD3专为所有屏幕尺寸设计。不要只发布手机端布局——使用标准布局，在600dp+尺寸下使用多面板布局，并在折叠屏/平板模拟器上测试。不要在折叠铰链区域放置可交互内容。
  • 拉伸内容以填充宽屏：在大尺寸（1200dp+）和超大尺寸（1600dp+）窗口中，将内容限制在最大宽度（840–1040dp）。无限宽度的文本行难以阅读。

Platform Notes

平台注意事项

Flutter

Flutter

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

Jetpack Compose

Jetpack Compose

See Jetpack Compose (primary) above. Use 
LocalContext.current
with 
dynamicLightColorScheme
/ 
dynamicDarkColorScheme
only when 
Build.VERSION.SDK_INT >= Build.VERSION_CODES.S
and dynamic color is enabled; otherwise supply static light/dark schemes.
详见上方**Jetpack Compose（核心方案）**。仅当
Build.VERSION.SDK_INT >= Build.VERSION_CODES.S
且启用动态色彩时，才使用
LocalContext.current
结合
dynamicLightColorScheme
/ 
dynamicDarkColorScheme
；否则提供静态亮色/暗色配色方案。

Component Name Mapping

组件名称映射

ConceptWebFlutterCompose
Filled button
md-filled-button
FilledButton
Button
Outlined text field
md-outlined-text-field
OutlinedTextField
OutlinedTextField
FAB
md-fab
FloatingActionButton
FloatingActionButton
Navigation bar
md-navigation-bar
NavigationBar
NavigationBar
Switch
md-switch
Switch
Switch
概念Web端FlutterJetpack 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 (May 2025)

M3 Expressive（2025年5月更新）

The Expressive update adds visual richness while maintaining usability. Availability differs by platform — do not assume one stack implements everything.
CapabilityJetpack ComposeFlutterWeb (
@material/web
)
Expressive layout scaffold / adaptive layoutCompose-first via Material3 adaptive APIs and window size classesUse Flutter adaptive/layout primitivesCSS/container queries/manual layout; no Material Web parity
8dp spacing systemUse design tokens / 
Dp
spacing constants; keep margins, padding, and gaps adaptive		Use theme spacing constantsCSS custom properties / design tokens
Expressive lists, menus, search, search app barPrimary target per current Material guidance; check BOM and opt-insCheck current Flutter Material docsSpec-aligned custom implementation; 
@material/web
is maintenance-only
Spring / motion physicsSupported in Material 3 (see 
MotionScheme
, expressive APIs per BOM)		Varies by Flutter Material versionNot in Material Web; use easing/duration or custom motion
Emphasized typographyVia theme / type scaleVia themeToken/CSS only; no full Expressive component set
Shape morphingCompose-first in Google’s expressive rolloutCheck current Flutter docsNot in 
@material/web
New button sizes (XS–XL), toggleFollow Compose Material3 componentsFollow Flutter MD3Height/CSS approximations only
Extra corner tokens (e.g. large-increased)
MaterialTheme.shapes
/ tokens		Theme shapesCSS 
--md-sys-shape-*
3 contrast levelsScheme builders / systemPlugins / manual
SchemeContent
contrast parameter in JS utilities
Watches / XR form factorsUse Compose/Wear/XR-specific guidance where availablePlatform-specificWeb/spatial UI custom implementation
Web: Material Web is maintenance-only; M3 Expressive is not on Web. Use CSS easing/duration tokens as fallback for motion, not spring parity.
Legacy easing/duration remains valid for transitions (enter/exit/shared-axis) where the spec still references them; see the Motion table below.
Expressive更新在保持可用性的同时增加了视觉丰富度。各平台支持情况不同——不要假设所有技术栈都实现了所有功能。
功能特性Jetpack ComposeFlutterWeb（
@material/web
）
表现力布局脚手架/自适应布局通过Material3自适应API和窗口尺寸类别优先支持使用Flutter自适应/布局原语CSS/容器查询/手动布局；无Material Web对等实现
8dp间距系统使用设计令牌/
Dp
间距常量；保持边距、内边距和间隙自适应		使用主题间距常量CSS自定义属性/设计令牌
表现力列表、菜单、搜索、搜索应用栏是当前Material指导的主要目标；请检查BOM和注解查看当前Flutter Material文档符合规范的自定义实现；
@material/web
处于维护模式
弹簧/物理动效Material 3支持（见
MotionScheme
，需匹配BOM的表现力API）		取决于Flutter Material版本未在Material Web中实现；使用缓动/时长或自定义动效
强调式排版通过主题/排版层级实现通过主题实现仅支持令牌/CSS；无完整表现力组件集
形状变形Google表现力更新中优先支持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缓动/时长令牌作为动效 fallback，不要追求弹簧动效的一致性。
传统缓动/时长在规范仍引用的过渡动画（进入/退出/共享轴）中依然有效；详见下方动效表格。

MD3 Compliance Audit

MD3合规性审计

When invoked with 
audit
as the argument (e.g., 
/material-3 audit
), or when asked to audit/review MD3 compliance, analyze the target app or page and produce a compliance report.
当以
audit
为参数调用时（例如
/material-3 audit
），或被要求审计/审查MD3合规性时，分析目标应用或页面并生成合规性报告。

Audit Procedure

审计流程

  1. Identify the target: The user provides a URL (use browser tools to inspect), file paths (read source), or a running app.
  2. Inspect the following categories and score each 0–10:
CategoryWhat to check
Color tokensWeb: 
--md-sys-color-*
/ generated CSS. Compose: 
MaterialTheme.colorScheme
roles (no arbitrary 
Color(...)
for surfaces without reason). Proper tonal pairing (
onX
on 
X
). Dark theme. Flutter: 
ColorScheme
roles.
TypographyMD3 type scale: Compose 
MaterialTheme.typography
; web typescale tokens; correct roles (Display, Headline, Title, Body, Label).
ShapeCompose 
MaterialTheme.shapes
/ component 
Shape
; web 
var(--md-sys-shape-*)
. Buttons: full; cards: medium; avoid magic numbers.
ElevationTonal elevation (
Surface
tonal/shadow as appropriate). Web: hover/focus where relevant.
ComponentsCompose: Material3 composables (
Button
, 
Scaffold
, etc.). Web: 
@material/web
or spec-aligned HTML/CSS. Correct variants.
LayoutCanonical layouts; Compose window size class / adaptive APIs; readable max width on large widths; foldable hinge avoidance.
NavigationBar / rail / drawer / drawers+Compose 
NavHost
patterns per size class; predictive back where applicable.
MotionCompose 
MotionScheme
/ expressive APIs when used; transitions may still use easing/duration. Web: CSS motion tokens fallback.
AccessibilityMD3 roles help, but verify contrast: UI components often need 3:1 for large text/borders and 4.5:1 for normal text (WCAG 2.x). TalkBack/semantics (Compose), focus order, touch targets (~48dp). Web: ARIA, keyboard.
ThemingCompose: 
MaterialTheme
+ light/dark/dynamic as designed. Web: CSS custom properties on 
:root
or subtree. Flutter: 
ThemeData
+ 
ColorScheme
.
  1. Generate the report:
undefined
  1. 确定目标：用户提供URL（使用浏览器工具检查）、文件路径（读取源码）或运行中的应用。
  2. 检查以下类别，每项评分0–10：
类别检查内容
色彩令牌Web端： 
--md-sys-color-*
/ 生成的CSS。Compose： 
MaterialTheme.colorScheme
角色（无特殊原因时不要使用任意
Color(...)
设置表面色）。正确的色调配对（
onX
搭配
X
）。暗色主题。Flutter： 
ColorScheme
角色。
排版MD3排版层级：Compose 
MaterialTheme.typography
；Web端排版令牌；正确的角色（Display、Headline、Title、Body、Label）。
形状Compose 
MaterialTheme.shapes
/ 组件
Shape
；Web端 
var(--md-sys-shape-*)
。按钮：全圆角；卡片：中等圆角；避免魔法数字。
层级色调化层级（
Surface
色调/阴影按需使用）。Web端： 相关的hover/focus状态。
组件Compose： Material3可组合组件（
Button
、
Scaffold
等）。Web端： 
@material/web
或符合规范的HTML/CSS。正确的变体。
布局标准布局；Compose窗口尺寸类别/自适应API；大尺寸下的可读最大宽度；折叠屏铰链避让。
导航底部栏/侧边栏/抽屉/Compose 
NavHost
等符合尺寸类别的模式；适用时的预测返回。
动效Compose 使用
MotionScheme
/表现力API（若使用）；过渡动画仍可使用缓动/时长。Web端： CSS动效令牌 fallback。
无障碍适配MD3角色有帮助，但需验证对比度：UI组件通常需要大文本/边框达到3:1，普通文本达到4.5:1（WCAG 2.x）。TalkBack/语义化（Compose）、焦点顺序、触摸目标（约48dp）。Web端： ARIA、键盘导航。
主题配置Compose： 
MaterialTheme
+ 亮色/暗色/动态主题（按设计）。Web端： 在
:root
或子树设置CSS自定义属性。Flutter： 
ThemeData
+ 
ColorScheme
。
  1. 生成报告：
undefined

MD3 Compliance Audit Report

MD3合规性审计报告

Target: [URL or file path] Date: [date] Overall Score: [X/100]
目标: [URL或文件路径] 日期: [日期] 总分: [X/100]

Scores by Category

各类别评分

CategoryScoreStatus
Color tokensX/10[pass/warn/fail]
TypographyX/10[pass/warn/fail]
ShapeX/10[pass/warn/fail]
ElevationX/10[pass/warn/fail]
ComponentsX/10[pass/warn/fail]
LayoutX/10[pass/warn/fail]
NavigationX/10[pass/warn/fail]
MotionX/10[pass/warn/fail]
AccessibilityX/10[pass/warn/fail]
ThemingX/10[pass/warn/fail]
类别得分状态
色彩令牌X/10[通过/警告/失败]
排版X/10[通过/警告/失败]
形状X/10[通过/警告/失败]
层级X/10[通过/警告/失败]
组件X/10[通过/警告/失败]
布局X/10[通过/警告/失败]
导航X/10[通过/警告/失败]
动效X/10[通过/警告/失败]
无障碍适配X/10[通过/警告/失败]
主题配置X/10[通过/警告/失败]

Critical Issues

严重问题

[List items scoring 0-3 with specific file:line references and fixes]
[列出得分0-3的项，包含具体文件:行号参考及修复方案]

Warnings

警告

[List items scoring 4-6 with recommendations]
[列出得分4-6的项及建议]

Passing

通过项

[List items scoring 7-10 with notes on what's done well]
[列出得分7-10的项及做得好的地方说明]

Recommended Fixes (Priority Order)

推荐修复方案（优先级排序）

  1. [Most impactful fix first]
  2. ...
undefined
  1. [影响最大的修复方案优先]
  2. ...
undefined

Audit Methods

审计方法

For a live URL (browser or devtools):
  • Inspect computed styles and CSS variables (
    --md-sys-*
    )
  • Resize viewport or use responsive mode for breakpoints
  • Capture screenshots at key widths if helpful
For source code (file paths provided):
  • Compose/Kotlin: 
    .kt
    files — 
    MaterialTheme
    , composables, 
    Color(0x…)
    abuse, hard-coded 
    Dp
    , missing 
    Modifier.semantics
    where needed
  • Flutter: 
    .dart
    — 
    ThemeData
    , 
    ColorScheme
  • Web: HTML/JSX/Vue/Svelte; CSS/SCSS for tokens
  • Check web imports for 
    @material/web
    vs 
    @material/mdc-*
    (MD2)
Quick checks (adapt paths to your stack):
undefined
针对在线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）
快速检查（根据技术栈调整路径）：
undefined

Web: hardcoded colors

Web端：硬编码颜色

grep -rn '#[0-9a-fA-F]{3,8}' --include='.css' --include='.scss'
grep -rn '#[0-9a-fA-F]{3,8}' --include='.css' --include='.scss'

Compose: raw Color(...) audits (sample — tune for your codebase)

Compose：原始Color(...)审计（示例——根据代码库调整）

grep -rn 'Color(0x' --include='*.kt'
grep -rn 'Color(0x' --include='*.kt'

MD2 on web

Web端使用MD2

grep -rn '@material/mdc-' --include='.js' --include='.ts'

**Browser automation** (if your environment exposes MCP browser tools): navigate, snapshot DOM/CSS variables, resize for breakpoints — optional, not required.
grep -rn '@material/mdc-' --include='.js' --include='.ts'

**浏览器自动化**（若环境提供MCP浏览器工具）：导航、快照DOM/CSS变量、调整断点大小——可选，非必需。

Scoring Guide

评分指南

  • 9-10: Fully MD3 compliant, uses correct tokens and patterns
  • 7-8: Mostly compliant, minor issues (e.g., a few hardcoded values)
  • 4-6: Partially compliant, some MD3 patterns but significant gaps
  • 1-3: Major violations, mostly non-MD3 or MD2 patterns
  • 0: Not applicable or completely absent
Status thresholds: pass (7+), warn (4-6), fail (0-3)
  • 9-10：完全符合MD3规范，使用正确的令牌和模式
  • 7-8：基本符合，存在轻微问题（如少量硬编码值）
  • 4-6：部分符合，使用了一些MD3模式但存在显著差距
  • 1-3：严重违规，主要使用非MD3或MD2模式
  • 0：不适用或完全未使用MD3
状态阈值：通过（7+）、警告（4-6）、失败（0-3）

Reference Documents

参考文档

  • references/color-system.md
    — Color roles, tonal palettes, dynamic color, Compose + CSS mapping
  • references/typography-and-shape.md
    — Type scale, shape corners, elevation, motion, Expressive notes
  • references/component-catalog.md
    — Components: Compose + 
    @material/web
    where applicable
  • references/navigation-patterns.md
    — Navigation selection, Compose-first adaptive patterns
  • references/layout-and-responsive.md
    — Breakpoints, canonical layouts, insets, foldables
  • references/theming-and-dynamic-color.md
    — Theming: Compose first, then Flutter and web
  • 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端