docs: add description for individual theme mixins

Author: devversion

guides/duplicate-theming-styles.md

@@ -4,7 +4,9 @@ As explained in the [theming guide](./theming.md), a theme in Angular Material c
 configurations for the `color`, `density` and `typography` systems. As some of these individual
 systems have default configurations, some usage patterns may cause duplication in the CSS output.
 
-Below is an example of a pattern that generates duplicative theme styles:
+Below are examples of patterns that generate duplicative theme styles:
+
+**Example #1**
 
 ```scss
 $light-theme: mat-light-theme((color: ...));
@@ -36,7 +38,44 @@ selector. Replace the `angular-material-theme` mixin and include the dark theme
 }
 ```
 
-Typography can also be configured via Sass mixin; see `angular-material-typography`.  
+Typography can also be configured via Sass mixin; see `angular-material-typography`.
+
+**Example #2**
+
+Theme styles could also be duplicated if individual theme mixins are used. For example:
+
+```scss
+@include angular-material-theme($my-theme);
+
+.my-custom-dark-button {
+  // This will also generate the default density styles again.
+  @include mat-button-theme($my-theme);
+}
+```
+
+To avoid this duplication of styles, use the dedicated mixin for the color system and
+extract the configuration for the color system from the theme.
+
+```scss
+.my-custom-dark-button {
+  // This will only generate the color styles for `mat-button`.
+  @include mat-button-color(map_get($my-theme, color));
+}
+```
+
+Alternatively, a new theme object can be constructed that explicitly disables
+styles from other systems such as `density` or `typography`:
+
+```scss
+.my-custom-dark-button {
+  $only-color-theme: map_merge($my-theme, (
+    density: null,
+    typography: null
+  ));
+  // This will only generate the color styles for `mat-button`.
+  @include mat-button-theme($only-color-theme);
+}
+```
 
 #### Disabling duplication warnings
 

guides/theming.md

@@ -192,6 +192,8 @@ styles for all configured theming system parts. For example, typography styles w
 multiple times, even though the configuration did not change. Instead, use fine-grained mixins such
 as `angular-material-color` that only result in styles being generated for the [color system][2].
 
+Read more about duplicated theme styles in the [dedicated guide](./duplicate-theming-styles.md).
+
 ##### Multiple themes and overlay-based components
 Since certain components (e.g. menu, select, dialog, etc.) are inside of a global overlay container,
 an additional step is required for those components to be affected by the theme's css class selector
@@ -247,12 +249,20 @@ $candy-app-theme:   mat-light-theme((
 #### Changing styles at run-time
 
 ##### Toggling classes
-You can use the mixins described above to define styles to customize any part of your application
-with standard CSS selectors. For example, let's say you want to toggle alternate colors on a button.
+You can use the theming mixins to customize any part of your application with standard
+CSS selectors. For example, let's say you want to toggle alternate colors on a button.
 You would first define a CSS class with the alternate colors.
+
+Note that `mat-button-color` should be used instead of `mat-button-theme` as we only
+want to have alternate colors for the button. Using the theme mixin could result in
+duplicative theme styles if the `mat-button-theme` has been included before. Read more about
+this in the [dedicated guide](./duplicate-theming-styles.md).
+
 ```scss
 .alternate-button {
-  @include mat-button-theme($alternate-theme);
+  // Extract the color configuration from the theme and generate
+  // the color theme styles for `mat-button`.
+  @include mat-button-color(map_get($alternate-theme, color));
 }
 ```