Web开发中如何正确使用Material 3设计令牌？

1. 关于--md-sys-color-primary等系统令牌的定义问题 #

• 这类高层系统令牌无需手动定义，Angular Material M3会在正确初始化主题后自动生成并注入全局CSS变量。报错“var(--md-sys-color-primary) is not a color”，大概率是主题初始化步骤缺失：
  • 确保已安装支持M3的最新版@angular/material
  • 在styles.scss中正确配置M3主题（示例代码如下）：

    @use '@angular/material' as mat;
    
    // 定义主题色板
    $primary-palette: mat.define-palette(mat.$indigo-palette);
    $accent-palette: mat.define-palette(mat.$pink-palette);
    $warn-palette: mat.define-palette(mat.$red-palette);
    
    // 创建浅色主题
    $m3-theme: mat.define-light-theme((
      color: (
        primary: $primary-palette,
        accent: $accent-palette,
        warn: $warn-palette,
      ),
    ));
    
    // 初始化核心样式+所有组件主题
    @include mat.core();
    @include mat.all-component-themes($m3-theme);
    

  配置完成后，刷新页面即可正常调用var(--md-sys-color-primary)。

2. 如何获取全量M3设计令牌概览 #

• 两种可靠方式：
  • 查看@angular/material/styles目录下的源码文件（如_color.scss、_typography.scss），里面列出了所有--md-sys-*系统令牌和--mat-*组件衍生令牌的定义
  • 通过浏览器开发者工具检查根元素（<html>或<body>）的CSS变量，编译后的主题会把所有可用令牌挂载到根节点上

3. 令牌使用的最佳实践 #

• 优先使用--md-sys-*系列系统基准令牌，这是M3设计系统的核心规范，能保证主题调整时颜色、排版等样式自动同步，符合设计一致性要求。
• 你当前使用的--mat-app-text-color等属于组件级衍生令牌，是Angular Material为组件内部样式封装的变量，虽然能正常使用，但灵活性和规范性不如系统级令牌。建议替换为对应的系统令牌：
  • 比如--mat-app-background-color对应--md-sys-color-background
  • --mat-app-text-color对应--md-sys-color-on-background

内容的提问来源于stack exchange，提问作者Sarah