From a4384c427e123969db2efff20533ad04b8e2305f Mon Sep 17 00:00:00 2001
From: Amy Sorto <8575252+amysorto@users.noreply.github.com>
Date: Tue, 16 Apr 2024 14:28:23 +0000
Subject: [PATCH] fix(material/schematics): Create README and update docs theme
 example

---
 guides/material-3.md                          | 20 ++++++++++++-------
 .../schematics/ng-generate/m3-theme/README.md | 20 +++++++++++++++++++
 2 files changed, 33 insertions(+), 7 deletions(-)
 create mode 100644 src/material/schematics/ng-generate/m3-theme/README.md

diff --git a/guides/material-3.md b/guides/material-3.md
index a3820b07dace..d1ed7c24a02a 100644
--- a/guides/material-3.md
+++ b/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
@@ -97,12 +97,18 @@ You can then import the generated theme scss file to use `$m3-light-theme` and/o
 `$m3-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';
+
+// 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);
 }
 ```
 
diff --git a/src/material/schematics/ng-generate/m3-theme/README.md b/src/material/schematics/ng-generate/m3-theme/README.md
new file mode 100644
index 000000000000..b4090a1577ee
--- /dev/null
+++ b/src/material/schematics/ng-generate/m3-theme/README.md
@@ -0,0 +1,20 @@
+# Material 3 Custom Theme schematic
+`ng generate` schematic that helps users to generate a file with a M3 theme
+object that is created from predefined color(s) to represent the different M3
+color palettes: https://m3.material.io/styles/color/roles, 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.