material-design-3

Material Design 3（Material You）技能

🎯 用途

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

📦 什么是 Material Design 3？

Material Design 3 是 Google 最新的设计语言，带来了以下特性：

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

🎨 何时使用此技能

在以下情况下使用 Material Design 3 指南：

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

🛠️ 核心概念

1. 颜色系统

Material Design 3 引入了复杂的颜色系统：

颜色角色：

• Primary：用于醒目操作的主要品牌色
• Secondary：用于不太醒目操作的辅助色
• Tertiary：用于突出显示和对比的强调色
• Error：用于错误状态的颜色
• Surface：组件的背景色
• On-colors：用于对比的文本／图标颜色（on-primary、on-secondary 等）

颜色变体：

• 容器颜色（例如，primary-container）
• 容器上的颜色（例如，on-primary-container）
• Surface 变体（surface-dim、surface-bright、surface-container）

2. 动态颜色

Material Design 3 的标志性特性：

• 根据源颜色生成配色方案
• 支持浅色和深色主题
• 自动调整对比度
• 提取系统级颜色（在支持的平台上从壁纸提取）

3. 排版

五种排版字号层级：

• 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. 海拔

三种海拔策略：

• 阴影：使用阴影的传统海拔效果
• 叠加层：色调表面叠加层
• 组合：阴影 + 叠加层，增强深度感

5. 形状

包含四种级别的圆角系统：

• 无：0dp（直角）
• 特小：4dp
• 小：8dp
• 中：12dp
• 大：16dp
• 特大：28dp

📚 在 Angular 中实现

设置 Material Design 3 主题

// 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);
}

使用颜色令牌

// 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);
}

排版用法

// 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);
}

海拔和阴影

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

🎯 最佳实践

1. 主题一致性

• 使用设计令牌，而不是硬编码值
• 在各组件中保持颜色使用一致
• 遵循 Material Design 3 的颜色角色指南

2. 无障碍性

• 确保文本的对比度至少为 4.5:1
• 使用语义化颜色角色（primary、secondary、error）
• 同时支持浅色和深色主题
• 提供足够大的触控目标（至少 48x48dp）

3. 响应式设计

• 使用 Material Design 3 断点
• 针对不同屏幕尺寸调整布局
• 在手机、平板电脑和桌面视口上进行测试

4. 动态主题

// 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);
  }
}

🔧 常见模式

使用 M3 令牌的自定义组件

@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';
}

🐛 故障排查

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

📖 参考资料

• Material Design 3 官方指南
• Angular Material 主题指南
• Material Design 色彩系统
• Material Design 字体排版
• 无障碍指南

💡 从 Material Design 2 迁移

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

1. 将调色板替换为主题类型方案
2. 更新组件样式以使用设计令牌
3. 使用新的主题 API 迁移自定义主题
4. 将字体排版从 mat-typography-level 更新为 M3 令牌
5. 使用 CSS 自定义属性替换 elevation mixin
6. 根据新的对比度要求测试无障碍功能

---

📂 推荐放置位置

项目级技能：

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

个人全局技能：

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

提及 Material Design 3 相关主题时，Copilot 会自动加载此技能。