Description
Documentation Feedback
I am trying to migrate an M2 app to M3 using the documentation on this page [A]:
However there are some incongruities when comparing to the guide to theming an M3 app from scratch here [B]:
https://material.angular.io/guide/theming#getting-started
Namely, page A implies that you must use the mat.define-theme mixin to create a new M3 theme, with no reference of mat.theme:
Create a new M3 theme object using define-theme and pass it everywhere you were previously passing your M2 theme. All Angular Material mixins that take an M2 theme are compatible with M3 themes as well.
While page B only mentions mat.define-theme in the context of legacy M2 themes:
If your application depends on a version before v19, or if your application's theme is applied using a theme config created with mat.define-theme, mat.define-light-theme, or mat.define-dark-theme, then you can refer to the theming guides at v18.material.angular.io/guides.
And then onwards only refers to mat.theme for defining an M3 theme.
The docs don't really explain how to use define-theme to generate an M3 theme, and it's unclear that the output of define-theme is not comparable to the config that can be passed to mat.theme. Similarly, it's not clear that a "valid" M3 theme config (as can be passed to mat.theme) is not sufficient to be passed to a mixin such as mat.color-variants-backwards-compatibility.
Some documentation that clarifies the difference between define-theme and theme would really help here I think. It might also be worth linking to https://v18.material.angular.io/guide/theming from the M2-M3 migration page (https://material.angular.io/guide/material-2-theming#pass-a-new-m3-theme-in-your-global-theme-styles) as there is otherwise no way to see how define-theme should be called (despite it being mandatory for the migration).
Affected documentation page
https://material.angular.io/guide/material-2-theming#pass-a-new-m3-theme-in-your-global-theme-styles