fix(material/schematics): Create README and update docs theme example

guides/material-3.md

@@ -78,7 +78,7 @@ used with the `primary` and `tertiary` options:
 - `$m3-violet-palette`
 - `$m3-rose-palette`
 
-For more customization, you can run a schematic to generate a scss file with
+For more customization, you can run a [schematic](https://github.com/angular/components/blob/main/src/material/schematics/ng-generate/m3-theme/README.md) to generate a scss file with
 theme(s) that use custom colors. You can specify a color to represent the
 primary color palette and the rest of the color palettes (secondary, tertiary,
 neutral) are generated from Material. The generated color palettes are
@@ -93,16 +93,23 @@ Material has more detailed guidance for [accessible design](https://m3.material.
 ng generate @angular/material:m3-theme
 ```
 
-You can then import the generated theme scss file to use `$m3-light-theme` and/or
-`$m3-dark-theme` to where you apply your themes.
+You can then import the generated theme scss file to use `$light-theme` and/or
+`$dark-theme` to where you apply your themes.
 
 ```scss
-@import './path/to/m3-theme';
-
-html {
-  // Apply the base theme at the root, so it will be inherited by the whole app.
-  @include mat.all-component-themes($m3-light-theme);
-  @include mat.all-component-themes($m3-dark-theme);
+@use '@angular/material' as mat;
+@use './path/to/m3-theme' as m3;
+
+// Apply the light theme by default
+@include mat.core-theme(m3.$light-theme);
+@include mat.button-theme(m3.$light-theme);
+
+// Apply the dark theme only when the user prefers dark themes.
+@media (prefers-color-scheme: dark) {
+ // Use the `-color` mixins to only apply color styles without reapplying the same
+ // typography and density styles.
+ @include mat.core-color(m3.$dark-theme);
+ @include mat.button-color(m3.$dark-theme);
 }
 ```
 
@@ -296,6 +303,7 @@ provided by Angular Material to access properties of the theme.
 ```
 
 ### Reading tonal palette colors
+
 To read a
 [tonal palette color](https://m3.material.io/styles/color/system/how-the-system-works#3ce9da92-a118-4692-8b2c-c5c52a413fa6)
 from the theme, use the `get-theme-color` function with three arguments:
@@ -454,18 +462,14 @@ $theme: matx.define-theme();
 
 ## FAQ
 
-### Can I use colors other than the pre-defined Material 3 palettes?
-
-Currently, we only offer predefined palettes, but we plan to add support for using custom generated
-palettes as part of making the M3 APIs stable and available in `@angular/material`.
-
 ### Can I depend on the CSS custom property names being stable?
 
 We may make changes to the custom property names before moving the API out of experimental, but
 these changes would be accompanied by a schematic to find & replace the old name with the new name
 across your app.
 
 ### Are the Material 2 styles and APIs going away?
+
 Material 2 styles and their APIs will continue to be supported, and we do not have any immediate
 plans to deprecate them. We understand that it will take time for applications to switch to the
 latest Material 3 styles, and we want to provide enough time for migrations. When we do decide to

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

@@ -0,0 +1,21 @@
+# Material 3 Custom Theme schematic
+`ng generate` schematic that helps users to generate a file with a M3 theme
+object(s) that is created from predefined color(s) to represent the different M3
+color palettes: https://m3.material.io/styles/color/roles. The generated
+theme(s) will be called $light-theme and/or $dark-theme. The schematic can be
+run with `ng generate @angular/material:m3-theme` and it has the following
+options:
+
+* `primaryColor` - Color to use for app's primary color palette (Note: the other
+palettes described in the M3 spec will be automatically chosen based on your
+primary palette unless specified, to ensure a harmonious color combination).
+* `secondaryColor` - Color to use for app's secondary color palette. Defaults to
+secondary color generated from Material based on the primary.
+* `tertiaryColor` - Color to use for app's tertiary color palette. Defaults to
+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.
+* `directory` - Relative path to a directory within the project that the
+generated theme file should be created in. Defaults to the project root.
+* `themeTypes` - List of theme types (light and dark) to generate theme(s) for.
+Defaults to both light and dark.

src/material/schematics/ng-generate/m3-theme/index.spec.ts

@@ -288,14 +288,14 @@ $_rest: (
 $_primary: map.merge(map.get($_palettes, primary), $_rest);
 $_tertiary: map.merge(map.get($_palettes, tertiary), $_rest);
 
-$m3-light-theme: matx.define-theme((
+$light-theme: matx.define-theme((
   color: (
     theme-type: light,
     primary: $_primary,
     tertiary: $_tertiary,
   )
 ));
-$m3-dark-theme: matx.define-theme((
+$dark-theme: matx.define-theme((
   color: (
     theme-type: dark,
     primary: $_primary,
@@ -332,11 +332,11 @@ describe('material-m3-theme-schematic', () => {
         ${content}
 
         html {
-          @if variable-exists(m3-light-theme) {
-            @include mat.all-component-colors($m3-light-theme);
+          @if variable-exists(light-theme) {
+            @include mat.all-component-colors($light-theme);
           }
-          @if variable-exists(m3-dark-theme) {
-            @include mat.all-component-colors($m3-dark-theme);
+          @if variable-exists(dark-theme) {
+            @include mat.all-component-colors($dark-theme);
           }
         }
         `,

src/material/schematics/ng-generate/m3-theme/index.ts

@@ -132,7 +132,7 @@ export function generateSCSSTheme(
   // from the palettes is a private function
   for (const themeType of themeTypes) {
     scss = scss.concat([
-      '$m3-' + themeType + '-theme: matx.define-theme((',
+      '$' + themeType + '-theme: matx.define-theme((',
       '  color: (',
       '    theme-type: ' + themeType + ',',
       '    primary: $_primary,',