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,22 @@ 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 './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);
 }
 ```
 

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,',