feat(material/schematics): Switch custom theme schematic to use theme mixin instead of define-theme and add high contrast override mixins

Author: amysorto

package.json

@@ -98,7 +98,7 @@
     "@bazel/terser": "5.8.1",
     "@bazel/worker": "5.8.1",
     "@firebase/app-types": "^0.7.0",
-    "@material/material-color-utilities": "^0.2.7",
+    "@material/material-color-utilities": "^0.3.0",
     "@octokit/rest": "18.3.5",
     "@rollup/plugin-commonjs": "^21.0.0",
     "@rollup/plugin-node-resolve": "^13.1.3",

src/material/schematics/ng-generate/m3-theme/README.md

@@ -4,44 +4,76 @@
 ng generate @angular/material:m3-theme
 ```
 
-This schematic allows users to create new Material 3 theme configurations based
+This schematic allows users to create new Material 3 theme palettes based
 on custom colors by using [Material Color Utilities](https://github.com/material-foundation/material-color-utilities).
 
 The generated [color palettes](https://m3.material.io/styles/color/roles) are
 optimized to have enough contrast to be more accessible. See [Science of Color Design](https://material.io/blog/science-of-color-design) for more information about Material's color design.
 
-For more customization, custom palette colors can be also be provided for the
-secondary, tertiary, and neutral colors. It is recommended to choose colors that
+For more customization, custom colors can be also be provided for the
+secondary, tertiary, and neutral palette colors. It is recommended to choose colors that
 are contrastful, Material has more detailed guidance for [accessible design](https://m3.material.io/foundations/accessible-design/patterns).
 
 The output of the schematic will create a file named `m3-theme.scss` at the
-specified directory or the project root with the generated themes. The exported
-themes (`$light-theme` and/or `$dark-theme`) can be provided to component theme
-mixins.
-
-If you're using the system variables option, you should remember to either provide values for the
-system variables (all prefixed with `--sys-`), or to include the `system-level-colors` and
-`system-level-typography` mixins which will generate the values based on your theme.
-
-The default prefix for system variables is `--sys-`. This prefix can be customized. For
-example, to change the prefix to `--md-sys-`, use the following configuration at the color or typography level:
-`system-prefix: md-sys`.
+specified directory or the project root with the generated palettes. The exported
+palettes (`$primary-palette` and `$tertiary-palette`) can be provided to the `private-experimental-theme` mixin within your theme file to use the custom colors.
 
 ```scss
 @use '@angular/material' as mat;
-@use './path/to/my-theme';
+@use './path/to/my-theme'; // location of generated file
 
-@include mat.core();
+html {
+  @include mat.private-experimental-theme(
+    color: (
+      primary: my-theme.$primary-palette,
+      tertiary: my-theme.$tertiary-palette,
+    ),
+    typography: Roboto,
+    density: 0,
+  )
+}
+```
+
+High contrast override theme mixins are also generated in the file if specified
+(`high-contrast-light-theme-overrides` and `high-contrast-dark-theme-overrides`). These mixins
+override the system level variables with high contrast equivalent values from your theme. This is
+helpful for users who prefer more contrastful colors for either preference or accessibility reasons.
+
+```scss
+@use '@angular/material';
+@use './path/to/my-theme'; // location of generated file
 
 html {
   // Apply the light theme by default
-  @include mat.core-theme(my-theme.$light-theme);
-  @include mat.button-theme(my-theme.$light-theme);
-
-  // When using system variables, remember to provide values for them
-  // or uncomment the lines below to generate them from the theme.
-  // @include mat.system-level-colors(my-theme.$light-theme);
-  // @include mat.system-level-typography(my-theme.$light-theme);
+  @include material.private-experimental-theme((
+    color: (
+      primary: my-theme.$primary-palette,
+      tertiary: my-theme.$tertiary-palette,
+    ),
+    typography: Roboto,
+    density: 0,
+  ));
+
+  // Use high contrast light theme colors when users prefer contrast
+  @media (prefers-contrast: more) {
+    @include my-theme.high-contrast-light-theme-overrides();
+  }
+
+  // Apply dark theme when users prefer a dark color scheme
+  @media (prefers-color-scheme: dark) {
+    @include material.private-experimental-theme((
+      color: (
+        primary: my-theme.$primary-palette,
+        tertiary: my-theme.$tertiary-palette,
+        theme-type: dark,
+      ),
+    ));
+
+    // Use high contrast dark theme colors when users prefers a dark color scheme and contrast
+    @media (prefers-contrast: more) {
+      @include my-theme.high-contrast-dark-theme-overrides();
+    }
+  }
 }
 ```
 
@@ -61,8 +93,8 @@ secondary color generated from Material based on the primary.
 tertiary color generated from Material based on the primary.
 * `neutralColor` - Color to use for app's neutral color palette. Defaults to
 neutral color generated from Material based on the primary.
+* `includeHighContrast` - Whether to add high contrast override mixins to generated
+theme file. Developers can call the mixin when they want to show a high contrast version of their
+theme. Defaults to false.
 * `directory` - Relative path to a directory within the project that the
 generated theme file should be created in. Defaults to the project root.
-* `themeTypes` - Theme types ('light', 'dark', or 'both') to generate themes for. Defaults to both.
-* `useSystemVariables` - Whether to generate a theme that uses system-level variables for easier
-dynamic theming. Defaults to false.