docs-bug(theming): mat.theme vs mat.define-theme difference is unclear

[benelliott]

Documentation Feedback

I am trying to migrate an M2 app to M3 using the documentation on this page [A]:

https://material.angular.io/guide/material-2-theming#how-to-migrate-an-app-from-material-2-to-material-3

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