docs: Add better documentation and errors regarding including theme mixins at root (#28593)

Author: mmalerba

guides/material-3.md

@@ -339,6 +339,9 @@ well.
 ### Update usages of APIs that are not supported for Material 3 themes
 Because Material 3 is implemented as an alternate theme for the same components used for Material 2,
 the APIs for both are largely the same. However, there are a few differences to be aware of:
+- M3 expects that any `@include` of the `-theme`, `-color`, `-typography`, `-density`, or `-base`
+  mixins should be wrapped in a selector. If your app includes such an `@include` at the root level,
+  we recommend wrapping it in `html { ... }`
 - M3 has a different API for setting the color variant of a component (see
   [using component color variants](#using-component-color-variants) for more).
 - The `backgroundColor` property of `<mat-tab-group>` is not supported, and should not be used with

src/material/autocomplete/_autocomplete-theme.scss

@@ -1,6 +1,7 @@
 @use 'sass:map';
 @use '../core/theming/theming';
 @use '../core/theming/inspection';
+@use '../core/theming/validation';
 @use '../core/typography/typography';
 @use '../core/style/sass-utils';
 @use '../core/tokens/token-utils';
@@ -75,6 +76,8 @@
 }
 
 @mixin _theme-from-tokens($tokens) {
+  @include validation.selector-defined(
+      'Calls to Angular Material theme mixins with an M3 theme must be wrapped in a selector');
   @if ($tokens != ()) {
     @include token-utils.create-token-values(
         tokens-mat-autocomplete.$prefix, map.get($tokens, tokens-mat-autocomplete.$prefix));

src/material/badge/_badge-theme.scss

@@ -1,6 +1,7 @@
 @use 'sass:color';
 @use '../core/theming/theming';
 @use '../core/theming/inspection';
+@use '../core/theming/validation';
 @use '../core/typography/typography';
 @use '../core/tokens/m2/mat/badge' as tokens-mat-badge;
 @use '../core/tokens/token-utils';
@@ -97,6 +98,8 @@
 }
 
 @mixin _theme-from-tokens($tokens, $options...) {
+  @include validation.selector-defined(
+      'Calls to Angular Material theme mixins with an M3 theme must be wrapped in a selector');
   $mat-badge-tokens: token-utils.get-tokens-for($tokens, tokens-mat-badge.$prefix, $options...);
   @include token-utils.create-token-values(tokens-mat-badge.$prefix, $mat-badge-tokens);
 }

src/material/bottom-sheet/_bottom-sheet-theme.scss

@@ -2,6 +2,7 @@
 @use '../core/typography/typography';
 @use '../core/theming/theming';
 @use '../core/theming/inspection';
+@use '../core/theming/validation';
 @use '../core/style/sass-utils';
 @use '../core/tokens/token-utils';
 @use '../core/tokens/m2/mat/bottom-sheet' as tokens-mat-bottom-sheet;
@@ -70,6 +71,8 @@
 }
 
 @mixin _theme-from-tokens($tokens) {
+  @include validation.selector-defined(
+      'Calls to Angular Material theme mixins with an M3 theme must be wrapped in a selector');
   @if ($tokens != ()) {
     @include token-utils.create-token-values(
         tokens-mat-bottom-sheet.$prefix, map.get($tokens, tokens-mat-bottom-sheet.$prefix));

src/material/button-toggle/_button-toggle-theme.scss

@@ -1,5 +1,6 @@
 @use '../core/theming/theming';
 @use '../core/theming/inspection';
+@use '../core/theming/validation';
 @use '../core/typography/typography';
 @use '../core/tokens/m2/mat/legacy-button-toggle' as tokens-mat-legacy-button-toggle;
 @use '../core/tokens/m2/mat/standard-button-toggle' as tokens-mat-standard-button-toggle;
@@ -104,6 +105,8 @@
 }
 
 @mixin _theme-from-tokens($tokens, $options...) {
+  @include validation.selector-defined(
+      'Calls to Angular Material theme mixins with an M3 theme must be wrapped in a selector');
   $mat-standard-button-toggle-tokens:
       token-utils.get-tokens-for($tokens, tokens-mat-standard-button-toggle.$prefix, $options...);
   @include token-utils.create-token-values(

src/material/button/_button-theme.scss

@@ -5,6 +5,7 @@
 
 @use '../core/theming/theming';
 @use '../core/theming/inspection';
+@use '../core/theming/validation';
 @use '../core/tokens/token-utils';
 @use '../core/typography/typography';
 @use '../core/tokens/m2/mdc/filled-button' as tokens-mdc-filled-button;
@@ -78,6 +79,8 @@
 }
 
 @mixin _theme-from-tokens($tokens, $options...) {
+  @include validation.selector-defined(
+      'Calls to Angular Material theme mixins with an M3 theme must be wrapped in a selector');
   $mdc-text-button-tokens:
       token-utils.get-tokens-for($tokens, tokens-mdc-text-button.$prefix, $options...);
   $mdc-protected-button-tokens:

src/material/button/_fab-theme.scss

@@ -4,6 +4,7 @@
 @use '../core/style/sass-utils';
 @use '../core/theming/theming';
 @use '../core/theming/inspection';
+@use '../core/theming/validation';
 @use '../core/tokens/m2/mdc/fab' as tokens-mdc-fab;
 @use '../core/tokens/m2/mdc/fab-small' as tokens-mdc-fab-small;
 @use '../core/tokens/m2/mdc/extended-fab' as tokens-mdc-extended-fab;
@@ -166,6 +167,8 @@
 }
 
 @mixin _theme-from-tokens($tokens, $options...) {
+  @include validation.selector-defined(
+      'Calls to Angular Material theme mixins with an M3 theme must be wrapped in a selector');
   $mdc-extended-fab-tokens: token-utils.get-tokens-for(
       $tokens, tokens-mdc-extended-fab.$prefix, $options...);
   $mdc-fab-tokens: token-utils.get-tokens-for($tokens, tokens-mdc-fab.$prefix, $options...);

src/material/button/_icon-button-theme.scss

@@ -8,6 +8,7 @@
 @use '../core/tokens/token-utils';
 @use '../core/theming/theming';
 @use '../core/theming/inspection';
+@use '../core/theming/validation';
 
 
 @mixin base($theme) {
@@ -141,6 +142,8 @@
 }
 
 @mixin _theme-from-tokens($tokens) {
+  @include validation.selector-defined(
+      'Calls to Angular Material theme mixins with an M3 theme must be wrapped in a selector');
   @if ($tokens != ()) {
     @include mdc-icon-button-theme.theme(map.get($tokens, tokens-mdc-icon-button.$prefix));
     @include token-utils.create-token-values(

src/material/card/_card-theme.scss

@@ -2,6 +2,7 @@
 @use '../core/style/sass-utils';
 @use '../core/theming/theming';
 @use '../core/theming/inspection';
+@use '../core/theming/validation';
 @use '../core/typography/typography';
 @use '../core/tokens/token-utils';
 @use '../core/tokens/m2/mat/card' as tokens-mat-card;
@@ -108,6 +109,8 @@
 }
 
 @mixin _theme-from-tokens($tokens) {
+  @include validation.selector-defined(
+      'Calls to Angular Material theme mixins with an M3 theme must be wrapped in a selector');
   @if ($tokens != ()) {
     $elevated-card-tokens: map.get($tokens, tokens-mdc-elevated-card.$prefix);
     // Work around a bug in MDC where the elevation is not resolved to an actual shadow value.

src/material/checkbox/_checkbox-theme.scss

@@ -3,6 +3,7 @@
 @use '../core/style/sass-utils';
 @use '../core/theming/theming';
 @use '../core/theming/inspection';
+@use '../core/theming/validation';
 @use '../core/tokens/token-utils';
 @use '../core/typography/typography';
 @use '../core/tokens/m2/mdc/checkbox' as tokens-mdc-checkbox;
@@ -117,6 +118,8 @@
 }
 
 @mixin _theme-from-tokens($tokens, $options...) {
+  @include validation.selector-defined(
+      'Calls to Angular Material theme mixins with an M3 theme must be wrapped in a selector');
   $mdc-checkbox-tokens: token-utils.get-tokens-for(
       $tokens, tokens-mdc-checkbox.$prefix, $options...);
   // Don't pass $options here, since the mdc-form-field doesn't support color options,