docs-bug(core): Missing documentation about elevation since v19.1

[PowerKiKi]

Documentation Feedback

In v18, we had https://v18.material.angular.io/guide/elevation that documented in depth what is, and how to use, elevations in Material.

Since 5753ce24a3e3bf743a9fc9f471eff46b85a7817b, and v19.1 that content is declared to have been moved to https://material.angular.io/guide/theming. However that new page does not even include the term "elevation" at all. So we cannot even know whether classes such as mat-elevation-z2 are still supported, and even less how to make them work (via @include mat.elevation-classes();).

If this is something that has been deprecated (which does not seems to be the case when reading code), then it should at least be mentioned as such. Otherwise the original documentation should be restored.

Would you accept a PR that restore previous documentation, but included on the new https://material.angular.io/guide/theming ?

Affected documentation page

https://v18.material.angular.io/guide/elevation

[PowerKiKi]

An alternative solution would be to change the redirection to point to https://material.angular.io/guide/system-variables#elevation, which contains some information, but still lacks information about class usages. Are they deprecated as suggested by https://github.com/angular/components/issues/30055#issuecomment-2491854795 ? Are they not-deprecated but not recommended either ? whatever the case, they still need to be documented in some way.

[bogui]

Here I'd like to mention, that while I was researching on how to make those mat-elevation-zX classes to appear, I found something strange:

Inside node_modules/@angular/material/core/_m3-app.scss, in the function @function get-tokens($theme: m3.$sys-theme) there is a bunch of

      app-elevation-shadow-level-0: elevation.get-box-shadow(0, map.get($system, shadow)),
      app-elevation-shadow-level-1: elevation.get-box-shadow(1, map.get($system, shadow)),
      app-elevation-shadow-level-2: elevation.get-box-shadow(2, map.get($system, shadow)),
      app-elevation-shadow-level-3: elevation.get-box-shadow(3, map.get($system, shadow)),
      app-elevation-shadow-level-4: elevation.get-box-shadow(4, map.get($system, shadow)),
      app-elevation-shadow-level-5: elevation.get-box-shadow(5, map.get($system, shadow)),
      app-elevation-shadow-level-6: elevation.get-box-shadow(6, map.get($system, shadow)),

The part, that I don't understand is - this map.get($system, shadow) returns --mat-sys-shadow and the @function get-box-shadow($zValue, $shadow-color: black, $opacity: null) needs a color (as the default suggests), not a system variable name.

When I wrap those map.get($system, shadow) inside a var() - everything works perfect.

I have to note - I am not quite familiar on how the saas compilation works, but code is code and the result in the browser speaks for itself:

.mat-elevation-z8, .mat-mdc-elevation-specific.mat-elevation-z8 {
  box-shadow: var(--mat-app-elevation-shadow-level-8, 0px 5px 5px -3px --mat-sys-shadow, 0px 8px 10px 1px --mat-sys-shadow, 0px 3px 14px 2px --mat-sys-shadow);
}

[bogui]

An alternative solution would be to change the redirection to point to https://material.angular.io/guide/system-variables#elevation, which contains some information, but still lacks information about class usages. Are they deprecated as suggested by #30055 (comment) ? Are they not-deprecated but not recommended either ? whatever the case, they still need to be documented in some way.

The workaround/new style shown in the documentation of the link does not provide the ability to customize the shadow color. The variable has the color hard coded

--mat-sys-level5: 0px 7px 8px -4px rgba(0, 0, 0, 0.2), 0px 12px 17px 2px rgba(0, 0, 0, 0.14), 0px 5px 22px 4px rgba(0, 0, 0, 0.12);

I use dark theme and to customize the shadow color is quite the work. I'd use the tailwindcss for this, but I prefer the angular/material - is more concistent