material-design-3

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Material Design 3 (Material You) Skill

Material Design 3（Material You）技能指南

🎯 Purpose

🎯 核心用途

This skill provides comprehensive guidance on Material Design 3 (also known as Material You), Google's latest design system that emphasizes personalization, accessibility, and modern UI patterns for Angular applications.

本技能提供关于Material Design 3（又称Material You）的全面指导，这是谷歌最新的设计系统，强调Angular应用中的个性化、无障碍性和现代UI模式。

📦 What is Material Design 3?

📦 什么是Material Design 3？

Material Design 3 is Google's latest design language that introduces:

Dynamic Color: Adaptive color palettes based on user preferences
Enhanced Accessibility: WCAG 2.1 AA compliance by default
Flexible Theming: Token-based theming system
Modern Components: Updated component designs with better customization
Personalization: User-centric design that adapts to preferences

Material Design 3是谷歌最新的设计语言，引入了以下特性：

动态色彩：基于用户偏好的自适应调色板
增强的无障碍性：默认符合WCAG 2.1 AA标准
灵活的主题系统：基于令牌的主题设计体系
现代组件：经过更新、可定制性更强的组件设计
个性化：以用户为中心、可适配偏好的设计

🎨 When to Use This Skill

🎨 何时使用本技能

Use Material Design 3 guidance when:

Implementing a new Angular application with Material Design
Migrating from Material Design 2 to Material Design 3
Creating custom themes using Material Design 3 tokens
Implementing dynamic color theming
Building accessible, modern UI components
Following Material You design principles
Working with Material Design 3 typography and spacing systems

在以下场景中使用Material Design 3相关指导：

基于Material Design实现全新Angular应用
从Material Design 2迁移至Material Design 3
使用Material Design 3令牌创建自定义主题
实现动态色彩主题
构建无障碍的现代UI组件
遵循Material You设计原则
使用Material Design 3的排版和间距系统

🛠️ Core Concepts

🛠️ 核心概念

1. Color System

1. 色彩系统

Material Design 3 introduces a sophisticated color system:

Color Roles:

Primary: Main brand color for prominent actions
Secondary: Supporting color for less prominent actions
Tertiary: Accent color for highlights and contrasts
Error: Color for error states
Surface: Background colors for components
On-colors: Contrasting text/icon colors (on-primary, on-secondary, etc.)

Color Variants:

Container colors (e.g.,
```
primary-container
```
)
On-container colors (e.g.,
```
on-primary-container
```
)
Surface variants (surface-dim, surface-bright, surface-container)

Material Design 3引入了一套完善的色彩系统：

色彩角色：

Primary（主色）：用于突出操作的品牌主色调
Secondary（辅助色）：用于次要操作의支持色调
Tertiary（强调色）：用于高亮和对比的强调色调
Error（错误色）：用于错误状态的颜色
Surface（表面色）：组件背景色
On-colors（对应文本/图标色）：与底色对比的文本或图标颜色（如on-primary、on-secondary等）

色彩变体：

容器色（例如
```
primary-container
```
）
容器对应文本色（例如
```
on-primary-container
```
）
表面变体（surface-dim、surface-bright丶surface-container）

2. Dynamic Color

2. 动态色彩

Material Design 3's signature feature:

Generate color schemes from source colors
Support both light and dark themes
Automatic contrast adjustments
System-level color extraction (from wallpaper on supported platforms)

Material Design 3的标志性特性：

从源色生成配色方案
支持亮色和暗色主题
自动对比度调整
系统级色彩提取（在支持的平台上从壁纸提取）

3. Typography

3. 排版

Five typography scales:

Display: Largest text (display-large, display-medium, display-small)
Headline: Section headers (headline-large to headline-small)
Title: Subsection titles (title-large to title-small)
Body: Main content (body-large, body-medium, body-small)
Label: UI labels (label-large to label-small)

五种排版层级：

Display（展示级）：最大号文本（display-large、display-medium、display-small）
Headline（标题级）：章节标题（headline-large至headline-small）
Title（子标题级）：小节标题（title-large至title-small）
Body（正文级）：主要内容文本（body-large、body-medium、body-small）
Label（标签级）：UI标签文本（label-large至label-small）

4. Elevation

4. 层级（Elevation）

Three elevation strategies:

Shadow: Traditional elevation with shadows
Overlay: Tonal surface overlays
Combined: Shadow + overlay for enhanced depth perception

三种层级实现策略：

Shadow（阴影）：传统的阴影层级
Overlay（覆盖层）：色调表面覆盖层
Combined（组合式）：阴影+覆盖层以增强深度感知

5. Shape

5. 形状

Rounded corner system with four scales:

None: 0dp (sharp corners)
Extra Small: 4dp
Small: 8dp
Medium: 12dp
Large: 16dp
Extra Large: 28dp

带圆角的形状系统，包含六种尺寸：

None（无圆角）：0dp（直角）
Extra Small（极小）：4dp
Small（小）：8dp
Medium（中）：12dp
Large（大）：16dp
Extra Large（极大）：28dp

📚 Implementation in Angular

📚 在Angular中的实现

Setting Up Material Design 3 Theme

设置Material Design 3主题

scss

// Define your theme using M3 tokens
@use '@angular/material' as mat;

// Include core Material Design 3 styles
@include mat.core();

// Define your color palette
$my-primary: mat.define-palette(mat.$azure-palette);
$my-accent: mat.define-palette(mat.$blue-palette);
$my-warn: mat.define-palette(mat.$red-palette);

// Create the theme
$my-theme: mat.define-theme((
  color: (
    theme-type: light,
    primary: $my-primary,
    tertiary: $my-accent,
  ),
  typography: (
    brand-family: 'Roboto',
    bold-weight: 700
  ),
  density: (
    scale: 0
  )
));

// Apply the theme
@include mat.all-component-themes($my-theme);

// Dark theme variant
$my-dark-theme: mat.define-theme((
  color: (
    theme-type: dark,
    primary: $my-primary,
    tertiary: $my-accent,
  )
));

// Apply dark theme when needed
.dark-theme {
  @include mat.all-component-colors($my-dark-theme);
}

scss

// Define your theme using M3 tokens
@use '@angular/material' as mat;

// Include core Material Design 3 styles
@include mat.core();

// Define your color palette
$my-primary: mat.define-palette(mat.$azure-palette);
$my-accent: mat.define-palette(mat.$blue-palette);
$my-warn: mat.define-palette(mat.$red-palette);

// Create the theme
$my-theme: mat.define-theme((
  color: (
    theme-type: light,
    primary: $my-primary,
    tertiary: $my-accent,
  ),
  typography: (
    brand-family: 'Roboto',
    bold-weight: 700
  ),
  density: (
    scale: 0
  )
));

// Apply the theme
@include mat.all-component-themes($my-theme);

// Dark theme variant
$my-dark-theme: mat.define-theme((
  color: (
    theme-type: dark,
    primary: $my-primary,
    tertiary: $my-accent,
  )
));

// Apply dark theme when needed
.dark-theme {
  @include mat.all-component-colors($my-dark-theme);
}

Using Color Tokens

使用色彩令牌

scss

// Access theme colors in your components
.my-component {
  background-color: var(--mat-sys-primary);
  color: var(--mat-sys-on-primary);
  
  &:hover {
    background-color: var(--mat-sys-primary-container);
    color: var(--mat-sys-on-primary-container);
  }
}

// Surface variants
.surface {
  background-color: var(--mat-sys-surface);
  color: var(--mat-sys-on-surface);
}

.surface-container {
  background-color: var(--mat-sys-surface-container);
}

scss

// Access theme colors in your components
.my-component {
  background-color: var(--mat-sys-primary);
  color: var(--mat-sys-on-primary);
  
  &:hover {
    background-color: var(--mat-sys-primary-container);
    color: var(--mat-sys-on-primary-container);
  }
}

// Surface variants
.surface {
  background-color: var(--mat-sys-surface);
  color: var(--mat-sys-on-surface);
}

.surface-container {
  background-color: var(--mat-sys-surface-container);
}

Typography Usage

排版使用

scss

// Using typography tokens
.heading {
  font: var(--mat-sys-headline-large);
}

.body-text {
  font: var(--mat-sys-body-medium);
}

.label {
  font: var(--mat-sys-label-small);
}

scss

// Using typography tokens
.heading {
  font: var(--mat-sys-headline-large);
}

.body-text {
  font: var(--mat-sys-body-medium);
}

.label {
  font: var(--mat-sys-label-small);
}

Elevation and Shadows

层级与阴影

scss

.elevated-card {
  // Level 1 elevation
  box-shadow: var(--mat-sys-level1);
  
  &:hover {
    // Level 2 elevation on hover
    box-shadow: var(--mat-sys-level2);
  }
}

scss

.elevated-card {
  // Level 1 elevation
  box-shadow: var(--mat-sys-level1);
  
  &:hover {
    // Level 2 elevation on hover
    box-shadow: var(--mat-sys-level2);
  }
}

🎯 Best Practices

🎯 最佳实践

1. Theme Consistency

1. 主题一致性

Use design tokens instead of hardcoded values
Maintain consistent color usage across components
Follow Material Design 3 color role guidelines

使用设计令牌而非硬编码值
保持组件间色彩使用的一致性
遵循Material Design 3의色彩角色指南

2. Accessibility

2. 无障碍性

Ensure minimum 4.5:1 contrast ratio for text
Use semantic color roles (primary, secondary, error)
Support both light and dark themes
Provide sufficient touch target sizes (48x48dp minimum)

确保文本的最小对比度为4.5:1
使用语义化色彩角色（primary、secondary、error）
支持亮色和暗色主题
提供足够의触摸目标尺寸（最小48x48dp）

3. Responsive Design

3. 响应式设计

Use Material Design 3 breakpoints
Adapt layouts for different screen sizes
Test on mobile, tablet, and desktop viewports

使用Material Design 3의断点
针对不同屏幕尺寸适配布局
在移动设备、平板和桌面视口上进行测试

4. Dynamic Theming

4. 动态主题切换

typescript

// Example: Dynamic theme switching in Angular
export class ThemeService {
  private isDark = signal(false);
  
  toggleTheme() {
    this.isDark.update(dark => !dark);
    document.body.classList.toggle('dark-theme', this.isDark());
  }
  
  applyCustomColors(sourceColor: string) {
    // Generate M3 palette from source color
    const palette = this.generateM3Palette(sourceColor);
    this.applyCSSVariables(palette);
  }
}

typescript

// Example: Dynamic theme switching in Angular
export class ThemeService {
  private isDark = signal(false);
  
  toggleTheme() {
    this.isDark.update(dark => !dark);
    document.body.classList.toggle('dark-theme', this.isDark());
  }
  
  applyCustomColors(sourceColor: string) {
    // Generate M3 palette from source color
    const palette = this.generateM3Palette(sourceColor);
    this.applyCSSVariables(palette);
  }
}

🔧 Common Patterns

🔧 常见模式

Custom Component with M3 Tokens

基于M3令牌的自定义组件

typescript

@Component({
  selector: 'app-custom-button',
  template: `
    <button class="m3-button" [class.filled]="variant === 'filled'">
      <ng-content></ng-content>
    </button>
  `,
  styles: [`
    .m3-button {
      padding: 10px 24px;
      border-radius: var(--mat-sys-corner-full);
      font: var(--mat-sys-label-large);
      border: none;
      cursor: pointer;
      
      &.filled {
        background-color: var(--mat-sys-primary);
        color: var(--mat-sys-on-primary);
        
        &:hover {
          background-color: var(--mat-sys-primary-container);
          color: var(--mat-sys-on-primary-container);
        }
      }
      
      &.outlined {
        background-color: transparent;
        border: 1px solid var(--mat-sys-outline);
        color: var(--mat-sys-primary);
      }
    }
  `]
})
export class CustomButtonComponent {
  @Input() variant: 'filled' | 'outlined' = 'filled';
}

typescript

@Component({
  selector: 'app-custom-button',
  template: `
    <button class="m3-button" [class.filled]="variant === 'filled'">
      <ng-content></ng-content>
    </button>
  `,
  styles: [`
    .m3-button {
      padding: 10px 24px;
      border-radius: var(--mat-sys-corner-full);
      font: var(--mat-sys-label-large);
      border: none;
      cursor: pointer;
      
      &.filled {
        background-color: var(--mat-sys-primary);
        color: var(--mat-sys-on-primary);
        
        &:hover {
          background-color: var(--mat-sys-primary-container);
          color: var(--mat-sys-on-primary-container);
        }
      }
      
      &.outlined {
        background-color: transparent;
        border: 1px solid var(--mat-sys-outline);
        color: var(--mat-sys-primary);
      }
    }
  `]
})
export class CustomButtonComponent {
  @Input() variant: 'filled' | 'outlined' = 'filled';
}

🐛 Troubleshooting

🐛 故障排除

Issue	Solution
Colors not applying	Ensure `@include mat.core()` is called first
Theme tokens undefined	Check Angular Material version (requires v15+)
Dark theme not working	Verify `.dark-theme` class is applied to parent element
Custom colors not working	Use `define-palette()` with proper Material color palette
Typography not loading	Include Material Design fonts (Roboto) in index.html
Accessibility contrast issues	Use Material's built-in color roles instead of custom colors

问题	解决方案
颜色未生效	确保首先调用 `@include mat.core()`
主题令牌未定义	检查Angular Material版本（需要v15+）
暗色主题不生效	验证 `.dark-theme` 类已应用到父元素
自定义颜色不生效	使用 `define-palette()` 并传入正确的Material调色板
排版未加载	在index.html中引入Material Design字体（Roboto）
无障碍对比度问题	使用Material内置的色彩角色而非自定义颜色

📖 References

📖 参考资料

💡 Migration from Material Design 2

💡 从Material Design 2迁移

Key changes when migrating from M2 to M3:

Replace color palette with theme-type approach
Update component styles to use design tokens
Migrate custom themes to new theming API
Update typography from mat-typography-level to M3 tokens
Replace elevation mixins with CSS custom properties
Test accessibility with new contrast requirements

从M2迁移到M3的主要变化：

用主题类型（theme-type）方案替换原有的调色板方式
更新组件样式以使用设计令牌
将自定义主题迁移到新的主题API
将排版从mat-typography-level更新为M3令牌
用CSS自定义属性替换层级混合宏
针对新의对比度要求测试无障碍性

📂 Recommended Placement

📂 推荐存放位置

Project-level skill:

/.github/skills/material-design-3/SKILL.md

Personal global skill:

~/.github/skills/material-design-3/SKILL.md

Copilot will automatically load this skill when Material Design 3 topics are mentioned.

项目级技能：

/.github/skills/material-design-3/SKILL.md

个人全局技能:

~/.github/skills/material-design-3/SKILL.md

当提及Material Design 3相关主题时Copilot会自动加载本技能.