what's use-system-variables in angular material

Question

when I try to generate a custom theme in @angular/material@18 using nx generate @angular/material:m3-theme it asks me for this question

√ Do you want to use system-level variables in the theme? System-level variables make dynamic theming easier through CSS custom properties, but increase the bundle size. (y/N) · true

when it's true it adds use-system-variables: true

 $light-theme: mat.define-theme((
   color: (
     theme-type: light,
     primary: $_primary,
     tertiary: $_tertiary,
+    use-system-variables: true,
   ),
+  typography: (
+    use-system-variables: true,
+  ),
 ));

my question, what exactly does use-system-variables do? I can't find any documentation about it

Answer 1

To add on to the other answer:

These have originated from Material Design Tokens.

There are three kinds of tokens in Material:

Reference tokens

All available tokens with associated values

System tokens

Decisions and roles that give the design system its character, from color and typography, to elevation and shape

Component tokens

The design attributes assigned to elements in a component, such as the color of a button icon

With three kinds of tokens, teams can update design decisions globally or apply a change to a single component.

---

System tokens

Subsystem tokens begin with md.sys.

These are the decisions that systematize the design language for a specific theme or context.

System tokens define the purpose that a reference token serves in the UI.

When applying theming, a system token can point to different reference tokens depending on the context, such as a light or dark theme. Whenever possible, system tokens should point to reference tokens rather than static values.

The code to implement the tokens will look like below:

@use 'sass:map';
@use '@angular/material' as mat;

$light-theme: mat.define-theme((
  color: (
    theme-type: light,
    primary: mat.$azure-palette,
    tertiary: mat.$blue-palette,
    use-system-variables: true,
  ),
  typography: (
    use-system-variables: true,
  ),
));


@include mat.core();
@include mat.color-variants-backwards-compatibility($light-theme);

:root {
  @include mat.all-component-themes($light-theme);
  @include mat.system-level-colors($light-theme);
  @include mat.system-level-typography($light-theme);
}

As for what it does, it looks like it a highest css variable definition with the prefix --sys, this is being used by all the other global material styles.

Output After Configuring:

--mdc-plain-tooltip-supporting-text-font: var(--sys-body-small-font);
...
--sys-body-small-font: Roboto, sans-serif;