docs-bug(Theming Angular Material): theme overrides vs css variables

[whynotavailable]

Documentation Feedback

There exists seemingly two ways to implement MDC (or MAT) tokens in scss. The first way is by directly using the variables. Such as this.

mat-toolbar {
  --mat-toolbar-container-background-color: #{mat.get-theme-color($my-theme, primary-container)};
  --mat-toolbar-container-text-color: #{mat.get-theme-color($my-theme, on-primary-container)};
}

The second way is to use the override mixins to generate the appropriate tokens (especially neat when the component uses both MDC and MAT tokens) like this.

mat-toolbar {
  @include mat.toolbar-overrides((
    container-background-color: mat.get-theme-color($my-theme, primary-container),
    container-text-color: mat.get-theme-color($my-theme, on-primary-container)
  ))
}

I can find no places where these override mixins are used or documented. Is there a preference towards one or the other?

Affected documentation page

https://material.angular.io/guide/theming#granular-customizations-with-css-custom-properties

[hhaasbroek]

please assign this one to me