mcpField
M
material-design-3-guide

material-design-3-guide

github.com/shelbeely设计与 UI588 次安装36 周前更新
代码仓库

关于 material-design-3-guide

面向设计与编码 Agent 的 Material Design 3 实施总指南，涵盖 Material You 基础与 M3 Expressive，并指引按设计领域查阅专项技能。

主要功能

  1. 01介绍 Material You 与 M3 Expressive
  2. 02覆盖七个设计支柱
  3. 03指引查阅专项设计技能
  4. 04提供项目搭建顺序与组件场景

适用场景

  1. 01规划新的 Material Design 3 项目
  2. 02为 UI 组件选择设计指引
  3. 03为现有设计采用 M3 Expressive 扩展

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/shelbeely/shelbeely-agent-skills --skill material-design-3-guide

安装后在 Claude Code 中输入/material-design-3-guide确认已加载。

详细介绍

Material Design 3 指南

概述

这是实现 Material Design 3（M3）的主指南，涵盖从 Material You 基础到 M3 Expressive 增强功能的完整规范。本文将介绍整个系统，并引导你前往各个方面的专项技能。

关键词：Material Design 3、M3、Material Design、设计系统、Google 设计、Material You、表现力设计、UI 设计、M3 Expressive、React、MUI、Angular Material、Vue、Vuetify、Svelte、SMUI、Tailwind CSS、Next.js、Flutter、Jetpack Compose、Web 组件、Beer CSS、Ink、CLI、终端 UI

什么是 Material Design 3？

Material Design 3 是 Google 的开源设计系统，用于创建数字产品。它经历了两个主要阶段：

Material You（M3 基础版）

M3 基础系统引入了：

  • 动态颜色：根据用户壁纸和偏好生成的自适应主题
  • 色调调色板：五种关键调色板，采用系统化色调生成方式
  • 字体比例：涵盖五种角色的 15 种基准字体样式
  • 形状系统：从无到全的语义化圆角比例
  • 高度系统：五个层级，通过色调叠加体现深度
  • 组件库：完整的无障碍主题化组件集
  • Token 系统：用于保持主题一致性的 CSS 自定义属性
M3 Expressive（最新演进）

在 Material You 的基础上，M3 Expressive 新增了：

  • 30 种样式的字体比例：在 15 种基准样式之外，增加 15 种强调样式
  • 35 种表现力形状：支持平滑变形的装饰性形状库
  • 基于物理规律的动效：用弹簧参数（刚度、阻尼、速度）取代传统缓动
  • 固定强调色：在浅色和深色主题中保持不变的颜色
  • 对比度级别：标准化的标准、中等和高对比度模式
  • 新组件：拆分按钮、按钮组、浮动工具栏、FAB 菜单
  • 背景模糊：用于叠加层和导航的深度效果
  • 触觉集成：将振动与弹簧动画协调起来

Material Design 3 的七大支柱

Material Design 3 建立在七个相互关联的设计支柱之上：

1. 颜色与动态主题

内容：鲜明、自适应的颜色系统，包含 26 种以上角色，并具备适当的对比度和无障碍支持 在以下情况使用 material-design-3-color 技能：

  • 设置颜色调色板或主题
  • 实现动态颜色（Material You）
  • 使用主要、次要和第三颜色角色
  • 确保颜色的无障碍性和对比度
  • 创建浅色和深色主题
  • 定义颜色 Token 和变量
  • 应用状态层（悬停、聚焦、按下）
  • 实现高度色调叠加
  • 为品牌设置固定强调色（M3 Expressive）
  • 配置对比度级别（标准、中等、高）（M3 Expressive）
  • 定义表面容器层级

关键概念：色调调色板、颜色角色、动态颜色、无障碍、主题、固定强调色、对比度级别、表面容器

2. 动效与动画

内容：基于物理规律、自然流畅的动画，用于引导注意力并提供反馈 在以下情况使用 material-design-3-motion 技能：

  • 添加屏幕或状态间的过渡效果
  • 实现微交互（悬停、聚焦、按下）
  • 创建页面或视图过渡效果
  • 为组件状态添加动画
  • 构建加载状态或进度指示器
  • 实现涟漪效果
  • 为列表创建交错动画
  • 对容器或形状进行变形
  • 在表现力动效和标准动效之间进行选择（M3 Expressive）
  • 将触觉反馈与动画集成（M3 Expressive）

关键概念：弹簧物理、刚度／阻尼／速度、缓动曲线、时长、过渡、触觉反馈

3. 字体排印

内容：通过可变字体和明确定义的比例，构建清晰易读的字体层级 在以下情况下使用 material-design-3-typography 技能：

  • 设置文本样式和层级
  • 定义字体系列和字重
  • 实现字体比例（display、headline、title、body、label）
  • 使用可变字体
  • 确保文本易读且无障碍
  • 设置行高和字间距
  • 创建响应式字体排印
  • 在关键时刻使用强调字体样式（M3 Expressive）

关键概念：字体比例（15 种基础样式 + 15 种强调样式）、可变字体、层级、易读性、中等对比度

4. 形状与容器

内容：圆角、形状变换和富有表现力的装饰形状 在以下情况下使用 material-design-3-shape 技能：

  • 定义组件的边框半径
  • 为卡片、按钮和对话框设置圆角
  • 实现形状令牌（更新后：Large 为 20dp、XL 为 32dp、XXL 为 48dp）
  • 在不同状态间变换形状
  • 使用容器和容纳关系
  • 设置按钮、FAB、芯片或输入字段的样式
  • 使用 35 种富有表现力的形状库（M3 Expressive）
  • 实现富有表现力的形状变换（M3 Expressive）

关键概念：边框半径、形状比例、形状变换、容纳关系、35 种富有表现力的形状、圆角

5. 布局与尺寸层级

内容：策略性地运用间距、尺寸、容纳关系和深度，营造视觉流动感 在以下情况下使用 material-design-3-layout 技能：

  • 设置页面布局和网格
  • 定义间距系统
  • 创建响应式布局
  • 实现基于尺寸的层级
  • 使用断点
  • 定位组件
  • 通过尺寸营造视觉重点
  • 实现海拔和深度
  • 为叠加层使用背景模糊（M3 Expressive）
  • 定义显式与隐式容纳关系
  • 实现交互状态（悬停、焦点、按下、禁用）

关键概念：间距比例、网格系统、响应式设计、视觉层级、背景模糊、容纳关系、状态层

6. 组件

内容：完整的无障碍主题 UI 组件库 在以下情况下使用 material-design-3-components 技能：

  • 构建按钮、卡片、对话框、导航或任何 UI 组件
  • 查阅组件规格（尺寸、间距、颜色）
  • 实现新的 M3 Expressive 组件（分体式按钮、按钮组、工具栏）
  • 了解组件的交互状态
  • 为具体用例选择合适的组件
  • 实现 FAB、芯片、文本字段、标签页或菜单

关键概念：操作、容纳、沟通、导航、选择、文本输入组件

7. 图标

内容：Material Symbols 可变字体图标系统，包含 2,500 多个图标 在以下情况下使用 material-design-3-icons 技能：

  • 为界面添加图标
  • 配置 Material Symbols（填充、字重、等级、光学尺寸）
  • 实现图标无障碍功能
  • 使用图标填充过渡表示选中状态
  • 为不同组件选择正确的图标尺寸
  • 选择图标样式（轮廓、圆角、锐角）

关键概念：Material Symbols、可变字体轴（FILL、wght、GRAD、opsz）、图标无障碍功能

何时使用哪种技能

启动新的 Material Design 3 项目

步骤 1：色彩基础

  • 首先使用 material-design-3-color
  • 设置色彩调色板和主题
  • 定义所有颜色令牌（主色、次色、第三色、表面色、固定强调色）
  • 实现浅色和深色主题
  • 配置对比度级别

步骤 2：排版系统

  • 使用 material-design-3-typography
  • 定义字体比例和字体系列（基准 + 强调）
  • 设置排版令牌
  • 选择 Roboto 或自定义品牌字体

步骤 3：形状系统

  • 使用 material-design-3-shape
  • 为所有圆角定义形状令牌（更新后的值）
  • 设置组件专属形状

步骤 4：图标

  • 使用 material-design-3-icons
  • 加载 Material Symbols（选择一种样式）
  • 配置默认可变字体轴

步骤 5：布局基础

  • 使用 material-design-3-layout
  • 设置间距比例和网格系统
  • 定义响应式设计的断点
  • 设置容器模式和交互状态

步骤 6：构建组件

  • 使用 material-design-3-components
  • 使用已建立的令牌构建所有 UI 组件
  • 遵循组件专属规范

步骤 7：添加动效

  • 使用 material-design-3-motion
  • 实现过渡和动画（选择富表现力或标准样式）
  • 为交互元素添加微交互
  • 在适当情况下集成触觉反馈
开发特定组件

按钮：

  • 组件：material-design-3-components（规范、变体、按钮组）
  • 形状：material-design-3-shape（完整圆角、药丸形）
  • 颜色：material-design-3-color（主色/次色/第三色）
  • 排版：material-design-3-typography（label-large）
  • 动效：material-design-3-motion（悬停、聚焦、按压状态）
  • 布局：material-design-3-layout（间距、尺寸）
  • 图标：material-design-3-icons（按钮图标）

卡片：

  • 组件：material-design-3-components（抬高、填充、描边）
  • 形状：material-design-3-shape（中等圆角，12dp）
  • 颜色：material-design-3-color（表面容器变体）
  • 排版：material-design-3-typography（标题 + 正文）
  • 动效：material-design-3-motion（悬停时改变海拔高度）
  • 布局：material-design-3-layout（内边距、内容流）

对话框/模态框：

  • 组件：material-design-3-components（对话框规范）
  • 形状：material-design-3-shape（超大圆角，32dp）
  • 颜色：material-design-3-color（surface-container-high）
  • 排版：material-design-3-typography（标题 + 正文）
  • 动效：material-design-3-motion（进入/退出动画）
  • 布局：material-design-3-layout（居中、最大宽度、背景模糊）

导航：

  • 组件：material-design-3-components（栏、轨道、抽屉、标签页）
  • 颜色：material-design-3-color（表面变体、活动状态）
  • 排版：material-design-3-typography（label-large）
  • 形状：material-design-3-shape（指示器、药丸形）
  • 动效：material-design-3-motion（过渡动画）
  • 布局：material-design-3-layout（导航结构）
  • 图标：material-design-3-icons（带填充切换的导航图标）

表单/输入项：

  • 组件：material-design-3-components（文本字段、选择器）
  • 形状：material-design-3-shape（超小圆角，4dp）
  • 颜色：material-design-3-color（表面变体、轮廓）
  • 排版：material-design-3-typography（正文、标签）
  • 动效：material-design-3-motion（聚焦动画）
  • 布局：material-design-3-layout（字段间距、对齐）
常见场景

“让它看起来像 Material Design 3”：

  1. 从 material-design-3-color 开始——设置颜色系统
  2. 应用 material-design-3-shape——添加圆角
  3. 使用 material-design-3-typography——实现字体比例
  4. 加载 material-design-3-icons——设置 Material Symbols
  5. 使用 material-design-3-components 构建——采用 M3 组件规范
  6. 添加 material-design-3-motion——实现弹簧动画
  7. 应用 material-design-3-layout——确保间距恰当

“让它变得更具 M3 表现力”：

  1. 按照上面的标准 M3 设置进行配置
  2. 从 material-design-3-typography 添加强调字体样式
  3. 使用 material-design-3-shape 中富有表现力的形状，打造装饰效果
  4. 切换到 material-design-3-motion 中的表现力动效模式
  5. 使用 material-design-3-components 实现新组件（分割按钮、按钮组、工具栏）
  6. 从 material-design-3-color 添加固定强调色和对比度级别
  7. 使用 material-design-3-layout 实现背景模糊

“添加 Material Design 动画”：

  • 主要使用 material-design-3-motion
  • 可能需要 material-design-3-color 来设置状态层
  • 可能需要 material-design-3-shape 来实现形状变换

“修复 Material Design 颜色”：

  • 仅使用 material-design-3-color
  • 重点关注颜色角色、对比度和主题设置

“设置这个按钮／卡片／对话框的样式”：

  • 从 material-design-3-components 开始，了解规范
  • 然后根据需要应用形状、颜色和排版

“让它适配不同屏幕”：

  • 主要使用 material-design-3-layout
  • 可能需要 material-design-3-typography 来设置响应式文本
  • 可能需要 material-design-3-shape 来设置响应式圆角

“实现深色模式”：

  • 使用 material-design-3-color 切换主题
  • 确保为两种主题定义所有颜色令牌
  • 通过 material-design-3-icons 调整适用于深色模式的图标字重

“添加图标”：

  • 使用 material-design-3-icons 设置 Material Symbols
  • 使用 material-design-3-color 设置图标颜色令牌

集成原则

所有技能协同工作

Material Design 3 是一个整体系统——这些技能旨在协同使用：

  • 颜色定义调色板
  • 排版定义文本
  • 形状定义形式
  • 动效定义行为
  • 布局定义结构
  • 组件定义构建模块
  • 图标定义视觉语言
一致性是关键

使用多项技能时：

  • 使用各项技能中定义的令牌／变量
  • 不要硬编码值
  • 确保所有设计方面保持一致
  • 测试组合后的结果，而不只是单个部分
示例：完整的按钮实现
/* Uses all seven pillars */
.md3-button {
  /* Shape */
  border-radius: var(--md-sys-shape-corner-full);
  
  /* Color */
  background-color: var(--md-sys-color-primary);
  color: var(--md-sys-color-on-primary);
  
  /* Typography */
  font-family: var(--md-sys-typescale-label-large-font);
  font-size: var(--md-sys-typescale-label-large-size);
  font-weight: var(--md-sys-typescale-label-large-weight);
  letter-spacing: var(--md-sys-typescale-label-large-tracking);
  
  /* Layout */
  padding: var(--md-sys-spacing-2) var(--md-sys-spacing-6);
  min-height: 40px;
  display: inline-flex;
  align-items: center;
  gap: var(--md-sys-spacing-2);
  
  /* Motion */
  transition: 
    background-color var(--md-sys-motion-duration-short2) var(--md-sys-motion-easing-standard),
    box-shadow var(--md-sys-motion-duration-short2) var(--md-sys-motion-easing-standard),
    transform var(--md-sys-motion-duration-short2) var(--md-sys-motion-easing-standard);
}

.md3-button:hover {
  /* Color - state layer */
  background-color: var(--md-sys-color-primary);
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
  
  /* Motion */
  transform: translateY(-1px);
}

/* Icons in button */
.md3-button .material-symbols-outlined {
  font-size: 18px;
  font-variation-settings: 'opsz' 20;
}

快速参考

不同属性该使用哪项技能？
属性技能
color, background-colormaterial-design-3-color
font-size, font-family, line-height, font-weight, letter-spacingmaterial-design-3-typography
border-radius, clip-pathmaterial-design-3-shape
transition, animation, @keyframesmaterial-design-3-motion
margin, padding, gap, width, height, display, gridmaterial-design-3-layout
box-shadow（高度）material-design-3-layout（过渡效果使用 motion）
backdrop-filter（模糊）material-design-3-layout
font-variation-settings（图标）material-design-3-icons
特定于组件的规范material-design-3-components
哪些组件对应哪些 Skill？
组件主要 Skill辅助 Skill
按钮componentscolor、shape、typography、motion
卡片componentscolor、shape、layout
对话框componentscolor、shape、layout、motion
导航componentscolor、icons、layout、motion
文本字段componentscolor、shape、typography
FABcomponentscolor、shape、icons、motion
芯片componentscolor、shape、typography
标签页componentscolor、typography、icons、motion
列表componentscolor、typography、layout
菜单componentscolor、shape、layout
文件组织

实现 M3 时，请按以下方式组织代码：

styles/
├── tokens/
│   ├── color.css          # From material-design-3-color
│   ├── typography.css     # From material-design-3-typography
│   ├── shape.css          # From material-design-3-shape
│   ├── motion.css         # From material-design-3-motion
│   ├── layout.css         # From material-design-3-layout
│   └── icons.css          # From material-design-3-icons
├── components/
│   ├── button.css         # Uses all skills
│   ├── card.css           # Uses all skills
│   ├── dialog.css         # Uses all skills
│   ├── navigation.css     # Uses all skills
│   └── text-field.css     # Uses all skills
└── main.css               # Imports all tokens

最佳实践

应该做的事
  1. ✅ 使用全部七大支柱 - 完整实现所有方面时，M3 的效果最佳
  2. ✅ 从设计令牌开始 - 构建组件之前先定义所有设计令牌
  3. ✅ 遵循各项 Skill - 每项 Skill 都提供经过测试、以研究为依据的指南
  4. ✅ 测试无障碍功能 - 所有 Skill 都包含无障碍要求
  5. ✅ 支持两种主题 - 始终实现浅色和深色模式
  6. ✅ 使用语义化名称 - 使用令牌名称，而非硬编码值
  7. ✅ 保持一致 - 在所有组件中应用相同的模式
  8. ✅ 涵盖完整规范 - 包含 Material You 基线和 M3 Expressive 扩展内容
不应该做的事
  1. ❌ 不要挑着用 - 只使用颜色而不使用形状或动效，并不是真正的 M3
  2. ❌ 不要硬编码 - 始终使用已定义的令牌和变量
  3. ❌ 不要跳过无障碍功能 - 对比度、尺寸和动效偏好都很重要
  4. ❌ 不要忽略深色模式 - 它是 M3 的核心组成部分
  5. ❌ 不要自行臆定取值 - 使用各项 Skill 提供的比例尺
  6. ❌ 不要混用设计系统 - 不要将 M3 与其他设计语言结合
  7. ❌ 不要忘记动效 - 静态的 M3 会缺少“表现力”这一部分
  8. ❌ 不要跳过图标 - Material Symbols 是 M3 视觉语言不可或缺的一部分

适用于不同 Web 技术栈的 Material Design 3

M3 可在多种 Web 技术栈中实现。每种框架都有专用的库级 Skill，提供完整的设置、主题配置和组件示例。请使用下方概览表，为你的项目找到合适的 Skill。

Web 技术栈概览
技术栈主要库M3 支持Skill
Vanilla CSSCSS custom properties完整（手动）m3-web-vanilla
Web Components@material/web (Lit)完整 M3m3-web-webcomponents
React / Next.jsMUI (@mui/material)M3 主题配置m3-web-react
Angular@angular/material完整 M3（官方）m3-web-angular
VueVuetify 3完整 M3m3-web-vue
SvelteSMUI / @material/web部分 M3m3-web-svelte
Tailwind CSStailwind-material-3 插件基于令牌的 M3m3-web-tailwind
Ink (React CLI)ink + @inkjs/ui基于令牌的 M3m3-web-ink
Fluttermaterial / m3e_design完整 M3m3-web-flutter
AndroidJetpack Compose Material 3完整 M3 + Expressivem3-web-android
选择合适的技术栈
如果你的项目使用……推荐的技能原因
不使用框架（原生）m3-web-vanilla完全掌控，零依赖
React 或 Next.jsm3-web-react生态系统最庞大，支持 SSR
Angularm3-web-angular官方支持，M3 集成效果最佳
Vuem3-web-vue适用于企业，文档出色
Svelte / SvelteKitm3-web-svelteSvelte 可用的最佳选择
Tailwind CSSm3-web-tailwind基于工具类，搭配 M3 令牌
任意框架m3-web-webcomponents官方支持，与框架无关
CLI / 终端m3-web-ink基于 React，可自定义主题
Flutterm3-web-flutter官方支持，跨平台
Androidm3-web-android官方支持，M3 实现最完整

选择建议：

  1. Angular 项目：使用 m3-web-angular——它在所有 Web 框架中提供最佳的官方 M3 支持
  2. React 项目：使用 m3-web-react 搭配 MUI，或使用 m3-web-webcomponents 搭配 Google 官方组件
  3. Vue 项目：使用 m3-web-vue——Vuetify 3 已成熟，文档完善
  4. 与框架无关：使用 m3-web-webcomponents 或 m3-web-vanilla
  5. 快速构建原型：使用 m3-web-vanilla（Beer CSS），或通过 CDN 使用 m3-web-webcomponents
  6. 需要 Tailwind：使用 m3-web-tailwind 将 M3 令牌映射到 Tailwind 配置
  7. 移动端 + Web：使用 m3-web-flutter 实现跨平台 M3
  8. CLI / 终端：使用 m3-web-ink，将 M3 颜色令牌映射到终端颜色

资源

Material Design 3 核心技能
  • material-design-3-color - 调色板、主题、无障碍性、固定强调色、对比度级别
  • material-design-3-motion - 动画、过渡、微交互、弹簧物理效果、触觉反馈
  • material-design-3-typography - 字体比例（30 种样式）、字体、层级、强调变体
  • material-design-3-shape - 边框圆角、容器、形变、35 种富有表现力的形状
  • material-design-3-layout - 间距、网格、响应式设计、背景模糊、交互状态
  • material-design-3-components - 完整的组件目录，包含规格和实现
  • material-design-3-icons - Material Symbols、可变字体轴、图标无障碍性
特定库的技能
  • m3-web-vanilla - 原生 CSS 自定义属性、Beer CSS、零依赖 M3
  • m3-web-webcomponents - Google 官方基于 Lit 的 @material/web 组件
  • m3-web-react - React / MUI / Next.js M3 主题和 SSR 集成
  • m3-web-angular - Angular Material M3 主题、SCSS 混入、原理图
  • m3-web-vue - Vuetify 3 M3 主题、组件、深色模式
  • m3-web-svelte - 在 Svelte/SvelteKit 中使用 SMUI 和原生 @material/web
  • m3-web-tailwind - Tailwind CSS 的 M3 令牌映射和插件配置
  • m3-web-ink - 使用 @inkjs/ui 实现 M3 主题的 Ink React CLI
  • m3-web-flutter - Flutter M3 主题、动态颜色、M3 Expressive 软件包
  • m3-web-android - Jetpack Compose Material 3、动态颜色、M3 Expressive
外部资源

Material Design 3 项目检查清单

要启动新的 M3 项目？请按照此检查清单操作：

基础
  • 阅读本指南，了解七大支柱
  • 使用 material-design-3-color 设置颜色系统
  • 使用 material-design-3-typography 定义排版
  • 使用 material-design-3-shape 创建形状令牌
  • 使用 material-design-3-icons 加载 Material Symbols
  • 使用 material-design-3-layout 建立间距／布局系统
实现
  • 根据 material-design-3-components 规范构建组件
  • 实现浅色和深色主题
  • 使用 material-design-3-motion 添加动效和过渡
  • 在多种屏幕尺寸下测试（响应式）
  • 验证无障碍性（对比度、尺寸、动效偏好）
M3 表现力增强（可选）
  • 为重要时刻添加强调型文字样式
  • 使用富有表现力的形状增添装饰趣味
  • 在主视觉交互中切换到表现力动效模式
  • 为品牌实现固定强调色
  • 添加对比度级别支持
  • 使用新组件（分割按钮、按钮组、工具栏）
  • 为叠加层和导航添加背景模糊
质量保证
  • 所有颜色均使用语义令牌（不硬编码十六进制值）
  • 所有文本均使用字号比例（基准或强调）
  • 所有形状均使用形状比例
  • 所有动画均使用弹簧物理效果
  • 所有间距均使用间距比例
  • 所有图标均使用带正确轴值的 Material Symbols
  • 深色模式运行正常
  • 遵循减少动效偏好
  • 触控目标最小尺寸为 48×48dp
  • 文本对比度符合 WCAG AA（4.5:1）
  • 所有组件均具备正确的交互状态
  • 固定强调色在不同主题下保持一致

总结

Material Design 3 是一套完整的设计系统，涵盖从 Material You 基础到 M3 表现力增强的完整规范。它建立在七个相互关联的支柱之上，每个支柱都有对应的技能：

  1. 颜色 - 调色板、主题和无障碍性
  2. 动效 - 行为、物理效果和触觉反馈
  3. 排版 - 语气、层级和强调
  4. 形状 - 个性、形式和表现力
  5. 布局 - 结构、深度和容纳
  6. 组件 - 构建模块和交互
  7. 图标 - 视觉语言和符号

使用本指南了解哪些技能适用于你的具体需求，并记住：只有七大支柱和谐协作，M3 才能发挥最佳效果。

评论

支持 Markdown