docs-bug(M2 theming): M2 theming guide references defunct background and foreground palettes

[benelliott]

Documentation Feedback

Since the release of 20.1.0, Material 2 components no longer use the background and foreground palettes for neutral colours (such as default-colour button backgrounds). However, these are still referenced in the Material 2 Theming guide - both in terms of the palette tokens being listed out, and in terms of being able to read the palette values via mat.get-theme-color.

In my opinion the fact that these are documented strengthens the argument that the move to _mat-system is a breaking change that should have been pushed to the next major release. Regardless, there is now a bug with the documentation because it references these outdated tokens that no longer do what the documentation claims.

(More discussion in #31630)

Affected documentation page

https://material.angular.dev/guide/material-2-theming#reading-values-from-a-theme

[andrewseguin]

As mentioned in the other issue, many of those palette colors were already outdated and inconsistently used in Angular Material. It would have been better if we had kept aligned and correct, but we decided at this point it would be far more disruptive to change these colors since users depend on them being what they are.

The change to use _mat-system under the hood meant that the components are aligning closer to the M2 spec. Doing these minor hue changes to adjust to the latest spec has never been considered a breaking change since the Material spec can update anytime regardless of our schedule.

I do see how it can be disruptive if you tried to match the same colors as the palette and now the components have changed. Can you enumerate which palette colors you tried to consume and how different it is now? That could help us understand the extent of changes you are seeing here. In my experience with this change, we basically have sightly different shades of grey being used in the components, that might differ from the palette.