feat: report warning if duplicate theme styles are generated

As of the new theming API refactorings, a theme by default includes
density styles for the zero density-scale. This means that the common
pattern of using the `angular-material-theme` for secondary themes in
a project could cause duplicated styles when the new API is explicitly used.

Generally, we want to detect if theme styles are duplicated. This will
be helpful for developers defining multiple themes as we can notify them
if similar theme styles end up multiple times in an application.

If the duplicate styles are intentional, the warning can be explicitly disabled.

docs: improvements to guide changes

docs: add description for individual theme mixins

refactor: add duplicated theme styles check to all individual theme mixins

Adds the duplicated theme styles check to all individual theme mixins.
Also, adds a lint rule that enforces that the theme styles check is
included in every theme mixin w/ autofix.

build: do not build test sass files in legacy output

Looks like the exclude glob does not work as expected. Hence
the new theming bundle test fails as there is no theming
bundle when the legacy gulp tasks process Sass files.

Address feedback as per team meeting

Address feedback (cleanup stylelint rule)

More obvious error if theme variables are named incorrectly

Also ran clang-format

refactor: all-theme file should transitively provide `mat-core` mixin.

Partially reverts commit 9c97cf3 so
that we don't need to perform a large migration in g3 to land the
density API changes.

refactor: convert new theme-mixin-api stylelint rule to typescript

We recently refactored all stylelint rules to TypeScript. Similarly
we should migrate the new rule that has been added in the density
feature branch.

build: include mdc-color and mdc-density entry-points in release (#19141)

The new `mdc-color` and `mdc-density` entry-points should be
included in the `@angular/material-experimental` package.

Author: devversion

.stylelintrc.json

@@ -6,13 +6,15 @@
     "./tools/stylelint/selector-no-deep.ts",
     "./tools/stylelint/no-nested-mixin.ts",
     "./tools/stylelint/no-concrete-rules.ts",
-    "./tools/stylelint/no-top-level-ampersand-in-mixin.ts"
+    "./tools/stylelint/no-top-level-ampersand-in-mixin.ts",
+    "./tools/stylelint/theme-mixin-api.ts"
   ],
   "rules": {
     "material/no-prefixes": [true, {
       "browsers": ["last 2 versions", "not ie <= 10", "not ie_mob <= 10"],
       "filePattern": "**/!(*-example.css)"
     }],
+    "material/theme-mixin-api": true,
     "material/selector-no-deep": true,
     "material/no-nested-mixin": true,
     "material/no-ampersand-beyond-selector-start": [true, {

guides/duplicate-theming-styles.md

@@ -0,0 +1,78 @@
+# Avoiding duplicated theming styles
+
+As explained in the [theming guide](./theming.md), a theme in Angular Material consists of
+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 are examples of patterns that generate duplicative theme styles:
+
+**Example #1**
+
+```scss
+$light-theme: mat-light-theme((color: ...));
+$dark-theme: mat-dark-theme((color: ...));
+
+// Generates styles for all systems configured in the theme. In this case, color styles
+// and default density styles are generated. Density is in themes by default.
+@include angular-material-theme($light-theme);
+
+.dark-theme {
+  // Generates styles for all systems configured in the theme. In this case, color styles
+  // and the default density styles are generated. **Note** that this is a problem because it
+  // means that density styles are generated *again*, even though only the color should change.
+  @include angular-material-theme($dark-theme);
+}
+```
+
+To fix this, you can use the dedicated mixin for color styles for the `.dark-theme`
+selector. Replace the `angular-material-theme` mixin and include the dark theme using the
+`angular-material-color` mixin. For example:
+
+```scss
+...
+@include angular-material-theme($light-theme);
+
+.dark-theme {
+  // This mixin only generates the color styles now.
+  @include angular-material-color($dark-theme);
+}
+```
+
+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($my-theme);
+}
+```
+
+#### Disabling duplication warnings
+
+If your application intentionally duplicates styles, a global Sass variable can be
+set to disable duplication warnings from Angular Material. For example:
+
+```scss
+$mat-theme-ignore-duplication-warnings: true;
+
+// Include themes as usual.
+@include angular-material-theme($light-theme);
+
+...
+```

guides/theming-your-components.md

@@ -11,7 +11,10 @@ For example, if building a custom carousel component:
 // Import library functions for theme creation.
 @import '~@angular/material/theming';
 
-@mixin candy-carousel-color($config) {
+@mixin candy-carousel-color($config-or-theme) {
+  // Extract the color configuration in case a theme has been passed.
+  // This allows consumers to either pass a theme object or a color configuration.
+  $config: mat-get-color-config($config-or-theme);
   // Extract the palettes you need from the theme definition.
   $primary: map-get($config, primary);
   $accent: map-get($config, accent);
@@ -29,7 +32,10 @@ Second, create another Sass mixin that accepts an Angular Material typography co
 and outputs typographic styles. For example:
 
 ```scss
-@mixin candy-carousel-typography($config) {
+@mixin candy-carousel-typography($config-or-theme) {
+  // Extract the typography configuration in case a theme has been passed.
+  $config: mat-get-typography-config($config-or-theme);
+
   .candy-carousel {
     font: {
       family: mat-font-family($config, body-1);

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($alternate-theme);
 }
 ```
 

src/dev-app/BUILD.bazel

@@ -96,6 +96,7 @@ sass_binary(
     ],
     deps = [
         "//src/material-experimental/column-resize:column_resize_scss_lib",
+        "//src/material-experimental/mdc-color:all_color",
         "//src/material-experimental/mdc-density:all_density",
         "//src/material-experimental/mdc-theming:all_themes",
         "//src/material-experimental/mdc-typography:all_typography",

src/dev-app/theme.scss

@@ -1,11 +1,11 @@
-@import '../material/core/core';
-@import '../material/core/theming/all-theme';
+@import '../material/core/color/all-color';
 @import '../material/core/density/all-density';
 @import '../material/core/focus-indicators/focus-indicators';
 @import '../material/core/theming/all-theme';
 @import '../material-experimental/column-resize/column-resize';
 @import '../material-experimental/mdc-helpers/mdc-helpers';
-@import '../material-experimental/mdc-helpers/focus-indicator';
+@import '../material-experimental/mdc-helpers/focus-indicators';
+@import '../material-experimental/mdc-color/all-color';
 @import '../material-experimental/mdc-theming/all-theme';
 @import '../material-experimental/mdc-typography/all-typography';
 @import '../material-experimental/mdc-density/all-density';
@@ -65,16 +65,16 @@ $dark-theme: mat-dark-theme((
 // `.demo-unicorn-dark-theme` will be affected by this alternate dark theme instead of the
 // default theme.
 .demo-unicorn-dark-theme {
-  @include angular-material-theme($dark-theme);
-  @include angular-material-mdc-theme($dark-theme);
-  @include mat-column-resize-theme($dark-theme);
-  @include mat-popover-edit-theme($dark-theme);
+  @include angular-material-color($dark-theme);
+  @include angular-material-mdc-color($dark-theme);
+  @include mat-column-resize-color($dark-theme);
+  @include mat-popover-edit-color($dark-theme);
 }
 
 // Include the dark theme for focus indicators.
 .demo-unicorn-dark-theme.demo-strong-focus {
-  @include mat-strong-focus-indicators-theme($dark-theme);
-  @include mat-mdc-strong-focus-indicators-theme($dark-theme);
+  @include mat-strong-focus-indicators-color($dark-theme);
+  @include mat-mdc-strong-focus-indicators-color($dark-theme);
 }
 
 // Create classes for all density scales which are supported by all MDC-based components.

src/e2e-app/theme.scss

@@ -1,4 +1,3 @@
-@import '../material/core/core';
 @import '../material/core/theming/all-theme';
 @import '../material-experimental/mdc-theming/all-theme';
 @import '../material-experimental/mdc-typography/all-typography';

src/material-experimental/BUILD.bazel

@@ -24,6 +24,8 @@ ng_package(
     name = "npm_package",
     srcs = ["package.json"],
     data = MATERIAL_EXPERIMENTAL_SCSS_LIBS + [
+        "//src/material-experimental/mdc-color",
+        "//src/material-experimental/mdc-density",
         "//src/material-experimental/mdc-helpers",
         "//src/material-experimental/mdc-theming",
         "//src/material-experimental/mdc-typography",

src/material-experimental/column-resize/_column-resize.scss

@@ -3,7 +3,8 @@
 @import '../../material/core/theming/palette';
 @import '../../material/core/theming/theming';
 
-@mixin mat-column-resize-color($config) {
+@mixin mat-column-resize-color($config-or-theme) {
+  $config: mat-get-color-config($config-or-theme);
   $primary: map-get($config, primary);
   $foreground: map-get($config, foreground);
 
@@ -95,11 +96,17 @@
   }
 }
 
-@mixin mat-column-resize-typography($config) {}
+@mixin mat-column-resize-typography($config-or-theme) {
+  $config: mat-get-typography-config($config-or-theme);
+}
 
-@mixin mat-column-resize-density($density-scale) {}
+@mixin mat-column-resize-density($config-or-theme) {
+  $density-scale: mat-get-density-config($config-or-theme);
+}
 
-@mixin mat-column-resize-theme($theme) {
+@mixin mat-column-resize-theme($theme-or-color-config) {
+  $theme: _mat-legacy-get-theme($theme-or-color-config);
+  @include _mat-check-duplicate-theme-styles($theme, 'mat-column-resize');
   $color: mat-get-color-config($theme);
   $density: mat-get-density-config($theme);
   $typography: mat-get-typography-config($theme);

src/material-experimental/mdc-autocomplete/_autocomplete-theme.scss

@@ -1,20 +1,26 @@
 @import '../mdc-helpers/mdc-helpers';
 
-@mixin mat-mdc-autocomplete-color($config) {
+@mixin mat-mdc-autocomplete-color($config-or-theme) {
+  $config: mat-get-color-config($config-or-theme);
   @include mat-using-mdc-theme($config) {
     // TODO: implement MDC-based autocomplete.
   }
 }
 
-@mixin mat-mdc-autocomplete-typography($config) {
+@mixin mat-mdc-autocomplete-typography($config-or-theme) {
+  $config: mat-get-typography-config($config-or-theme);
   @include mat-using-mdc-typography($config) {
     // TODO: implement MDC-based autocomplete.
   }
 }
 
-@mixin mat-mdc-autocomplete-density($density-scale) {}
+@mixin mat-mdc-autocomplete-density($config-or-theme) {
+  $density-scale: mat-get-density-config($config-or-theme);
+}
 
-@mixin mat-mdc-autocomplete-theme($theme) {
+@mixin mat-mdc-autocomplete-theme($theme-or-color-config) {
+  $theme: _mat-legacy-get-theme($theme-or-color-config);
+  @include _mat-check-duplicate-theme-styles($theme, 'mat-mdc-autocomplete');
   $color: mat-get-color-config($theme);
   $density: mat-get-density-config($theme);
   $typography: mat-get-typography-config($theme);

src/material-experimental/mdc-button/_button-theme.scss

@@ -49,7 +49,8 @@ $mat-button-state-target: '.mdc-button__ripple';
 }
 
 
-@mixin mat-mdc-button-color($config) {
+@mixin mat-mdc-button-color($config-or-theme) {
+  $config: mat-get-color-config($config-or-theme);
   @include mat-using-mdc-theme($config) {
     // Add state interactions for hover, focus, press, active. Colors are changed based on
     // the mixin mdc-states-base-color
@@ -164,13 +165,15 @@ $mat-button-state-target: '.mdc-button__ripple';
   }
 }
 
-@mixin mat-mdc-button-typography($config) {
+@mixin mat-mdc-button-typography($config-or-theme) {
+  $config: mat-get-typography-config($config-or-theme);
   @include mat-using-mdc-typography($config) {
     @include mdc-button-without-ripple($query: $mat-typography-styles-query);
   }
 }
 
-@mixin mat-mdc-button-density($density-scale) {
+@mixin mat-mdc-button-density($config-or-theme) {
+  $density-scale: mat-get-density-config($config-or-theme);
   .mat-mdc-button,
   .mat-mdc-raised-button,
   .mat-mdc-unelevated-button,
@@ -179,7 +182,9 @@ $mat-button-state-target: '.mdc-button__ripple';
   }
 }
 
-@mixin mat-mdc-button-theme($theme) {
+@mixin mat-mdc-button-theme($theme-or-color-config) {
+  $theme: _mat-legacy-get-theme($theme-or-color-config);
+  @include _mat-check-duplicate-theme-styles($theme, 'mat-mdc-button');
   $color: mat-get-color-config($theme);
   $density: mat-get-density-config($theme);
   $typography: mat-get-typography-config($theme);
@@ -195,7 +200,8 @@ $mat-button-state-target: '.mdc-button__ripple';
   }
 }
 
-@mixin mat-mdc-fab-color($config) {
+@mixin mat-mdc-fab-color($config-or-theme) {
+  $config: mat-get-color-config($config-or-theme);
   @include mat-using-mdc-theme($config) {
     .mat-mdc-fab, .mat-mdc-mini-fab {
       @include mdc-states(
@@ -244,15 +250,20 @@ $mat-button-state-target: '.mdc-button__ripple';
   }
 }
 
-@mixin mat-mdc-fab-typography($config) {
+@mixin mat-mdc-fab-typography($config-or-theme) {
+  $config: mat-get-typography-config($config-or-theme);
   @include mat-using-mdc-typography($config) {
     @include mdc-fab-without-ripple($query: $mat-typography-styles-query);
   }
 }
 
-@mixin mat-mdc-fab-density($density-scale) {}
+@mixin mat-mdc-fab-density($config-or-theme) {
+  $density-scale: mat-get-density-config($config-or-theme);
+}
 
-@mixin mat-mdc-fab-theme($theme) {
+@mixin mat-mdc-fab-theme($theme-or-color-config) {
+  $theme: _mat-legacy-get-theme($theme-or-color-config);
+  @include _mat-check-duplicate-theme-styles($theme, 'mat-mdc-fab');
   $color: mat-get-color-config($theme);
   $density: mat-get-density-config($theme);
   $typography: mat-get-typography-config($theme);
@@ -269,7 +280,8 @@ $mat-button-state-target: '.mdc-button__ripple';
 }
 
 
-@mixin mat-mdc-icon-button-color($config) {
+@mixin mat-mdc-icon-button-color($config-or-theme) {
+  $config: mat-get-color-config($config-or-theme);
   @include mat-using-mdc-theme($config) {
     .mat-mdc-icon-button {
       @include mdc-states(
@@ -312,19 +324,23 @@ $mat-button-state-target: '.mdc-button__ripple';
   }
 }
 
-@mixin mat-mdc-icon-button-typography($config) {
+@mixin mat-mdc-icon-button-typography($config-or-theme) {
+  $config: mat-get-typography-config($config-or-theme);
   @include mat-using-mdc-typography($config) {
     @include mdc-icon-button-without-ripple($query: $mat-typography-styles-query);
   }
 }
 
-@mixin mat-mdc-icon-button-density($density-scale) {
+@mixin mat-mdc-icon-button-density($config-or-theme) {
+  $density-scale: mat-get-density-config($config-or-theme);
   .mat-mdc-icon-button {
     @include mdc-icon-button-density($density-scale);
   }
 }
 
-@mixin mat-mdc-icon-button-theme($theme) {
+@mixin mat-mdc-icon-button-theme($theme-or-color-config) {
+  $theme: _mat-legacy-get-theme($theme-or-color-config);
+  @include _mat-check-duplicate-theme-styles($theme, 'mat-mdc-icon-button');
   $color: mat-get-color-config($theme);
   $density: mat-get-density-config($theme);
   $typography: mat-get-typography-config($theme);