@angular/material 17.1.2 → 17.2.0-next.1

package/button-toggle/_button-toggle-theme.scss

@@ -1,4 +1,3 @@
-@use 'sass:map';
 @use '../core/theming/theming';
 @use '../core/theming/inspection';
 @use '../core/typography/typography';
@@ -7,6 +6,9 @@
 @use '../core/tokens/token-utils';
 @use '../core/style/sass-utils';
 
+/// Outputs base theme styles (styles not dependent on the color, typography, or density settings)
+/// for the mat-button-toggle.
+/// @param {Map} $theme The theme to generate base styles for.
 @mixin base($theme) {
   @if inspection.get-theme-version($theme) == 1 {
     @include _theme-from-tokens(inspection.get-theme-tokens($theme, base));
@@ -25,9 +27,14 @@
   }
 }
 
-@mixin color($theme) {
+/// Outputs color theme styles for the mat-button-toggle.
+/// @param {Map} $theme The theme to generate color styles for.
+/// @param {ArgList} Additional optional arguments (only supported for M3 themes):
+///   $color-variant: The color variant to use for the button toggle: primary, secondary, tertiary,
+///      or error (If not specified, default secondary color will be used).
+@mixin color($theme, $options...) {
   @if inspection.get-theme-version($theme) == 1 {
-    @include _theme-from-tokens(inspection.get-theme-tokens($theme, color));
+    @include _theme-from-tokens(inspection.get-theme-tokens($theme, color), $options...);
   }
   @else {
     @include sass-utils.current-selector-or-root() {
@@ -39,6 +46,8 @@
   }
 }
 
+/// Outputs typography theme styles for the mat-button-toggle.
+/// @param {Map} $theme The theme to generate typography styles for.
 @mixin typography($theme) {
   @if inspection.get-theme-version($theme) == 1 {
     @include _theme-from-tokens(inspection.get-theme-tokens($theme, typography));
@@ -53,6 +62,8 @@
   }
 }
 
+/// Outputs density theme styles for the mat-button-toggle.
+/// @param {Map} $theme The theme to generate density styles for.
 @mixin density($theme) {
   @if inspection.get-theme-version($theme) == 1 {
     @include _theme-from-tokens(inspection.get-theme-tokens($theme, density));
@@ -67,10 +78,15 @@
   }
 }
 
-@mixin theme($theme) {
+/// Outputs all (base, color, typography, and density) theme styles for the mat-button-toggle.
+/// @param {Map} $theme The theme to generate styles for.
+/// @param {ArgList} Additional optional arguments (only supported for M3 themes):
+///   $color-variant: The color variant to use for the button toggle: primary, secondary, tertiary,
+///      or error (If not specified, default secondary color will be used).
+@mixin theme($theme, $options...) {
   @include theming.private-check-duplicate-theme-styles($theme, 'mat-button-toggle') {
     @if inspection.get-theme-version($theme) == 1 {
-      @include _theme-from-tokens(inspection.get-theme-tokens($theme));
+      @include _theme-from-tokens(inspection.get-theme-tokens($theme), $options...);
     }
     @else {
       @include base($theme);
@@ -87,10 +103,9 @@
   }
 }
 
-@mixin _theme-from-tokens($tokens) {
-  @if ($tokens != ()) {
-    @include token-utils.create-token-values(
-        tokens-mat-standard-button-toggle.$prefix,
-        map.get($tokens, tokens-mat-standard-button-toggle.$prefix));
-  }
+@mixin _theme-from-tokens($tokens, $options...) {
+  $mat-standard-button-toggle-tokens:
+      token-utils.get-tokens-for($tokens, tokens-mat-standard-button-toggle.$prefix, $options...);
+  @include token-utils.create-token-values(
+      tokens-mat-standard-button-toggle.$prefix, $mat-standard-button-toggle-tokens);
 }

package/checkbox/_checkbox-theme.scss

@@ -1,14 +1,17 @@
-@use 'sass:map';
 @use '@material/checkbox/checkbox-theme' as mdc-checkbox-theme;
 @use '@material/form-field/form-field-theme' as mdc-form-field-theme;
 @use '../core/style/sass-utils';
 @use '../core/theming/theming';
 @use '../core/theming/inspection';
+@use '../core/tokens/token-utils';
 @use '../core/typography/typography';
-@use '../core/mdc-helpers/mdc-helpers';
 @use '../core/tokens/m2/mdc/checkbox' as tokens-mdc-checkbox;
 @use '../core/tokens/m2/mdc/form-field' as tokens-mdc-form-field;
+@use '../core/tokens/m2/mat/checkbox' as tokens-mat-checkbox;
 
+/// Outputs base theme styles (styles not dependent on the color, typography, or density settings)
+/// for the mat-checkbox.
+/// @param {Map} $theme The theme to generate base styles for.
 @mixin base($theme) {
   @if inspection.get-theme-version($theme) == 1 {
     @include _theme-from-tokens(inspection.get-theme-tokens($theme, base));
@@ -16,17 +19,26 @@
   @else {
     @include sass-utils.current-selector-or-root() {
       @include mdc-checkbox-theme.theme(tokens-mdc-checkbox.get-unthemable-tokens());
+      @include token-utils.create-token-values(
+        tokens-mat-checkbox.$prefix, tokens-mat-checkbox.get-unthemable-tokens());
     }
   }
 }
 
-@mixin color($theme) {
+/// Outputs color theme styles for the mat-checkbox.
+/// @param {Map} $theme The theme to generate color styles for.
+/// @param {ArgList} Additional optional arguments (only supported for M3 themes):
+///   $color-variant: The color variant to use for the checkbox: primary, secondary, tertiary, or
+///     error (If not specified, default primary color will be used).
+@mixin color($theme, $options...) {
   @if inspection.get-theme-version($theme) == 1 {
-    @include _theme-from-tokens(inspection.get-theme-tokens($theme, color));
+    @include _theme-from-tokens(inspection.get-theme-tokens($theme, color), $options...);
   }
   @else {
     @include sass-utils.current-selector-or-root() {
       @include mdc-checkbox-theme.theme(tokens-mdc-checkbox.get-color-tokens($theme));
+      @include token-utils.create-token-values(
+        tokens-mat-checkbox.$prefix, tokens-mat-checkbox.get-color-tokens($theme));
     }
 
     .mat-mdc-checkbox {
@@ -39,15 +51,12 @@
       &.mat-warn {
         @include mdc-checkbox-theme.theme(tokens-mdc-checkbox.get-color-tokens($theme, warn));
       }
-
-      &.mat-mdc-checkbox-disabled label {
-        // MDC should set the disabled color on the label, but doesn't, so we do it here instead.
-        color: inspection.get-theme-color($theme, foreground, disabled-text);
-      }
     }
   }
 }
 
+/// Outputs typography theme styles for the mat-checkbox.
+/// @param {Map} $theme The theme to generate typography styles for.
 @mixin typography($theme) {
   @if inspection.get-theme-version($theme) == 1 {
     @include _theme-from-tokens(inspection.get-theme-tokens($theme, typography));
@@ -55,6 +64,8 @@
   @else {
     @include sass-utils.current-selector-or-root() {
       @include mdc-checkbox-theme.theme(tokens-mdc-checkbox.get-typography-tokens($theme));
+      @include token-utils.create-token-values(
+        tokens-mat-checkbox.$prefix, tokens-mat-checkbox.get-typography-tokens($theme));
     }
 
     .mat-mdc-checkbox {
@@ -63,6 +74,8 @@
   }
 }
 
+/// Outputs density theme styles for the mat-checkbox.
+/// @param {Map} $theme The theme to generate density styles for.
 @mixin density($theme) {
   $density-scale: inspection.get-theme-density($theme);
 
@@ -72,20 +85,21 @@
   @else {
     @include sass-utils.current-selector-or-root() {
       @include mdc-checkbox-theme.theme(tokens-mdc-checkbox.get-density-tokens($theme));
-    }
-
-    @include mdc-helpers.if-touch-targets-unsupported($density-scale) {
-      .mat-mdc-checkbox-touch-target {
-        display: none;
-      }
+      @include token-utils.create-token-values(
+        tokens-mat-checkbox.$prefix, tokens-mat-checkbox.get-density-tokens($theme));
     }
   }
 }
 
-@mixin theme($theme) {
+/// Outputs all (base, color, typography, and density) theme styles for the mat-checkbox.
+/// @param {Map} $theme The theme to generate styles for.
+/// @param {ArgList} Additional optional arguments (only supported for M3 themes):
+///   $color-variant: The color variant to use for the checkbox: primary, secondary, tertiary, or
+///     error (If not specified, default primary color will be used).
+@mixin theme($theme, $options...) {
   @include theming.private-check-duplicate-theme-styles($theme, 'mat-checkbox') {
     @if inspection.get-theme-version($theme) == 1 {
-      @include _theme-from-tokens(inspection.get-theme-tokens($theme));
+      @include _theme-from-tokens(inspection.get-theme-tokens($theme), $options...);
     }
     @else {
       @include base($theme);
@@ -102,10 +116,14 @@
   }
 }
 
-@mixin _theme-from-tokens($tokens) {
-  @if ($tokens != ()) {
-    // TODO(mmalerba): Some of the theme styles above are not represented in terms of tokens,
-    //   so this mixin is currently incomplete.
-    @include mdc-checkbox-theme.theme(map.get($tokens, tokens-mdc-checkbox.$prefix));
-  }
+@mixin _theme-from-tokens($tokens, $options...) {
+  $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,
+  // only the mdc-checkbox does.
+  $mdc-form-field-tokens: token-utils.get-tokens-for($tokens, tokens-mdc-form-field.$prefix);
+  $mat-checkbox-tokens: token-utils.get-tokens-for($tokens, tokens-mat-checkbox.$prefix);
+  @include mdc-checkbox-theme.theme($mdc-checkbox-tokens);
+  @include mdc-form-field-theme.theme($mdc-form-field-tokens);
+  @include token-utils.create-token-values(tokens-mat-checkbox.$prefix, $mat-checkbox-tokens);
 }

package/chips/_chips-theme.scss

@@ -1,11 +1,15 @@
-@use 'sass:map';
 @use 'sass:color';
 @use '@material/chips/chip-theme' as mdc-chip-theme;
 @use '../core/tokens/m2/mdc/chip' as tokens-mdc-chip;
+@use '../core/tokens/m2/mat/chip' as tokens-mat-chip;
+@use '../core/tokens/token-utils';
 @use '../core/theming/theming';
 @use '../core/theming/inspection';
 @use '../core/typography/typography';
 
+/// Outputs base theme styles (styles not dependent on the color, typography, or density settings)
+/// for the mat-chips.
+/// @param {Map} $theme The theme to generate base styles for.
 @mixin base($theme) {
   @if inspection.get-theme-version($theme) == 1 {
     @include _theme-from-tokens(inspection.get-theme-tokens($theme, base));
@@ -13,18 +17,27 @@
   @else {
     .mat-mdc-standard-chip {
       @include mdc-chip-theme.theme(tokens-mdc-chip.get-unthemable-tokens());
+      @include token-utils.create-token-values(
+          tokens-mat-chip.$prefix, tokens-mat-chip.get-unthemable-tokens());
     }
   }
 }
 
-@mixin color($theme) {
+/// Outputs color theme styles for the mat-chips.
+/// @param {Map} $theme The theme to generate color styles for.
+/// @param {ArgList} Additional optional arguments (only supported for M3 themes):
+///   $color-variant: The color variant to use for the selected chip: primary, secondary, tertiary,
+///      or error (If not specified, default secondary color will be used).
+@mixin color($theme, $options...) {
   @if inspection.get-theme-version($theme) == 1 {
-    @include _theme-from-tokens(inspection.get-theme-tokens($theme, color));
+    @include _theme-from-tokens(inspection.get-theme-tokens($theme, color), $options...);
   }
   @else {
     .mat-mdc-standard-chip {
       $default-color-tokens: tokens-mdc-chip.get-color-tokens($theme);
       @include mdc-chip-theme.theme($default-color-tokens);
+      @include token-utils.create-token-values(
+          tokens-mat-chip.$prefix, tokens-mat-chip.get-color-tokens($theme));
 
       &.mat-mdc-chip-selected,
       &.mat-mdc-chip-highlighted {
@@ -47,6 +60,8 @@
   }
 }
 
+/// Outputs typography theme styles for the mat-chips.
+/// @param {Map} $theme The theme to generate typography styles for.
 @mixin typography($theme) {
   @if inspection.get-theme-version($theme) == 1 {
     @include _theme-from-tokens(inspection.get-theme-tokens($theme, typography));
@@ -56,10 +71,14 @@
 
     .mat-mdc-standard-chip {
       @include mdc-chip-theme.theme($typography-tokens);
+      @include token-utils.create-token-values(
+          tokens-mat-chip.$prefix, tokens-mat-chip.get-typography-tokens($theme));
     }
   }
 }
 
+/// Outputs density theme styles for the mat-chips.
+/// @param {Map} $theme The theme to generate density styles for.
 @mixin density($theme) {
   @if inspection.get-theme-version($theme) == 1 {
     @include _theme-from-tokens(inspection.get-theme-tokens($theme, density));
@@ -69,14 +88,21 @@
 
     .mat-mdc-chip.mat-mdc-standard-chip {
       @include mdc-chip-theme.theme($density-tokens);
+      @include token-utils.create-token-values(
+          tokens-mat-chip.$prefix, tokens-mat-chip.get-density-tokens($theme));
     }
   }
 }
 
-@mixin theme($theme) {
+/// Outputs all (base, color, typography, and density) theme styles for the mat-chips.
+/// @param {Map} $theme The theme to generate styles for.
+/// @param {ArgList} Additional optional arguments (only supported for M3 themes):
+///   $color-variant: The color variant to use for the selected chip: primary, secondary, tertiary,
+///      or error (If not specified, default secondary color will be used).
+@mixin theme($theme, $options...) {
   @include theming.private-check-duplicate-theme-styles($theme, 'mat-chips') {
     @if inspection.get-theme-version($theme) == 1 {
-      @include _theme-from-tokens(inspection.get-theme-tokens($theme));
+      @include _theme-from-tokens(inspection.get-theme-tokens($theme), $options...);
     }
     @else {
       @include base($theme);
@@ -93,8 +119,9 @@
   }
 }
 
-@mixin _theme-from-tokens($tokens) {
-  @if ($tokens != ()) {
-    @include mdc-chip-theme.theme(map.get($tokens, tokens-mdc-chip.$prefix));
-  }
+@mixin _theme-from-tokens($tokens, $options...) {
+  $mdc-chip-tokens: token-utils.get-tokens-for($tokens, tokens-mdc-chip.$prefix, $options...);
+  $mat-chip-tokens: token-utils.get-tokens-for($tokens, tokens-mat-chip.$prefix);
+  @include mdc-chip-theme.theme($mdc-chip-tokens);
+  @include token-utils.create-token-values(tokens-mat-chip.$prefix, $mat-chip-tokens);
 }

package/core/_core-theme.scss

@@ -10,37 +10,51 @@
 @use './typography/typography';
 @use './tokens/token-utils';
 @use './tokens/m2/mat/app' as tokens-mat-app;
+@use './tokens/m2/mat/ripple' as tokens-mat-ripple;
+@use './tokens/m2/mat/option' as tokens-mat-option;
+@use './tokens/m2/mat/full-pseudo-checkbox' as tokens-mat-full-pseudo-checkbox;
+@use './tokens/m2/mat/minimal-pseudo-checkbox' as tokens-mat-minimal-pseudo-checkbox;
 
 @mixin base($theme) {
-  @include ripple-theme.base($theme);
-  @include option-theme.base($theme);
-  @include optgroup-theme.base($theme);
-  @include pseudo-checkbox-theme.base($theme);
-  // TODO(mmalerba): Move additional core base tokens here
+  @if inspection.get-theme-version($theme) == 1 {
+    @include _theme-from-tokens(inspection.get-theme-tokens($theme, base));
+  }
+  @else {
+    @include ripple-theme.base($theme);
+    @include option-theme.base($theme);
+    @include optgroup-theme.base($theme);
+    @include pseudo-checkbox-theme.base($theme);
+  }
 }
 
 @mixin color($theme) {
-  @include ripple-theme.color($theme);
-  @include option-theme.color($theme);
-  @include optgroup-theme.color($theme);
-  @include pseudo-checkbox-theme.color($theme);
-  @include sass-utils.current-selector-or-root() {
-    @include token-utils.create-token-values(tokens-mat-app.$prefix,
-      tokens-mat-app.get-color-tokens($theme));
+  @if inspection.get-theme-version($theme) == 1 {
+    @include _theme-from-tokens(inspection.get-theme-tokens($theme, color));
   }
+  @else {
+    @include ripple-theme.color($theme);
+    @include option-theme.color($theme);
+    @include optgroup-theme.color($theme);
+    @include pseudo-checkbox-theme.color($theme);
+    @include sass-utils.current-selector-or-root() {
+      @include token-utils.create-token-values(tokens-mat-app.$prefix,
+        tokens-mat-app.get-color-tokens($theme));
+    }
 
-  // Provides external CSS classes for each elevation value. Each CSS class is formatted as
-  // `mat-elevation-z$zValue` where `$zValue` corresponds to the z-space to which the element is
-  // elevated.
-  @for $zValue from 0 through 24 {
-    $selector: elevation.$prefix + $zValue;
-    // We need the `mat-mdc-elevation-specific`, because some MDC mixins
-    // come with elevation baked in and we don't have a way of removing it.
-    .#{$selector}, .mat-mdc-elevation-specific.#{$selector} {
-      @include private.private-theme-elevation($zValue, $theme);
+    // Provides external CSS classes for each elevation value. Each CSS class is formatted as
+    // `mat-elevation-z$zValue` where `$zValue` corresponds to the z-space to which the element is
+    // elevated.
+    @for $zValue from 0 through 24 {
+      $selector: elevation.$prefix + $zValue;
+      // We need the `mat-mdc-elevation-specific`, because some MDC mixins
+      // come with elevation baked in and we don't have a way of removing it.
+      .#{$selector}, .mat-mdc-elevation-specific.#{$selector} {
+        @include private.private-theme-elevation($zValue, $theme);
+      }
     }
   }
 
+  // TODO(crisbeto): move this into the base.
   // Marker that is used to determine whether the user has added a theme to their page.
   @at-root {
     .mat-theme-loaded-marker {
@@ -50,34 +64,67 @@
 }
 
 @mixin typography($theme) {
-  @include option-theme.typography($theme);
-  @include optgroup-theme.typography($theme);
-  @include pseudo-checkbox-theme.typography($theme);
-  @include ripple-theme.typography($theme);
+  @if inspection.get-theme-version($theme) == 1 {
+    @include _theme-from-tokens(inspection.get-theme-tokens($theme, typography));
+  }
+  @else {
+    @include option-theme.typography($theme);
+    @include optgroup-theme.typography($theme);
+    @include pseudo-checkbox-theme.typography($theme);
+    @include ripple-theme.typography($theme);
+  }
 }
 
 @mixin density($theme) {
-  @include option-theme.density($theme);
-  @include optgroup-theme.density($theme);
-  @include pseudo-checkbox-theme.density($theme);
-  @include ripple-theme.density($theme);
+  @if inspection.get-theme-version($theme) == 1 {
+    @include _theme-from-tokens(inspection.get-theme-tokens($theme, density));
+  }
+  @else {
+    @include option-theme.density($theme);
+    @include optgroup-theme.density($theme);
+    @include pseudo-checkbox-theme.density($theme);
+    @include ripple-theme.density($theme);
+  }
 }
 
 // Mixin that renders all of the core styles that depend on the theme.
-@mixin theme($theme) {
+@mixin theme($theme, $options...) {
   // Wrap the sub-theme includes in the duplicate theme styles mixin. This ensures that
   // there won't be multiple warnings. e.g. if `mat-core-theme` reports a warning, then
   // the imported themes (such as `mat-ripple-theme`) should not report again.
   @include theming.private-check-duplicate-theme-styles($theme, 'mat-core') {
-    @include base($theme);
-    @if inspection.theme-has($theme, color) {
-      @include color($theme);
-    }
-    @if inspection.theme-has($theme, density) {
-      @include density($theme);
+    @if inspection.get-theme-version($theme) == 1 {
+      @include _theme-from-tokens(inspection.get-theme-tokens($theme), $options...);
     }
-    @if inspection.theme-has($theme, typography) {
-      @include typography($theme);
+    @else {
+      @include base($theme);
+      @if inspection.theme-has($theme, color) {
+        @include color($theme);
+      }
+      @if inspection.theme-has($theme, density) {
+        @include density($theme);
+      }
+      @if inspection.theme-has($theme, typography) {
+        @include typography($theme);
+      }
     }
   }
 }
+
+@mixin _theme-from-tokens($tokens, $options...) {
+  $mat-app-tokens: token-utils.get-tokens-for($tokens, tokens-mat-app.$prefix, $options...);
+  $mat-ripple-tokens: token-utils.get-tokens-for($tokens, tokens-mat-ripple.$prefix, $options...);
+  $mat-option-tokens: token-utils.get-tokens-for($tokens, tokens-mat-option.$prefix, $options...);
+  $mat-full-pseudo-checkbox-tokens: token-utils.get-tokens-for($tokens,
+    tokens-mat-full-pseudo-checkbox.$prefix, $options...);
+  $mat-minimal-pseudo-checkbox-tokens: token-utils.get-tokens-for($tokens,
+    tokens-mat-minimal-pseudo-checkbox.$prefix, $options...);
+
+  @include token-utils.create-token-values(tokens-mat-app.$prefix, $mat-app-tokens);
+  @include token-utils.create-token-values(tokens-mat-ripple.$prefix, $mat-ripple-tokens);
+  @include token-utils.create-token-values(tokens-mat-option.$prefix, $mat-option-tokens);
+  @include token-utils.create-token-values(tokens-mat-full-pseudo-checkbox.$prefix,
+    $mat-full-pseudo-checkbox-tokens);
+  @include token-utils.create-token-values(tokens-mat-minimal-pseudo-checkbox.$prefix,
+    $mat-minimal-pseudo-checkbox-tokens);
+}

package/core/mdc-helpers/_mdc-helpers.scss

@@ -5,7 +5,6 @@
 @use '@material/typography' as mdc-typography;
 @use '@material/theme/theme-color' as mdc-theme-color;
 @use '@material/theme/css' as mdc-theme-css;
-@use 'sass:meta';
 
 // A set of standard queries to use with MDC's queryable mixins.
 $mdc-base-styles-query: mdc-feature-targeting.without(mdc-feature-targeting.any(color, typography));
@@ -59,10 +58,3 @@ $mdc-typography-styles-query: typography;
   @content;
   mdc-theme-css.$enable-fallback-declarations: $previous-value;
 }
-
-// Excludes the passed-in CSS content if the layout is too dense to supports touch targets.
-@mixin if-touch-targets-unsupported($scale) {
-  @if ($scale == 'minimum' or (meta.type-of($scale) == 'number' and $scale < -1)) {
-    @content;
-  }
-}

package/core/option/_option-theme.scss

@@ -1,4 +1,3 @@
-@use 'sass:map';
 @use '../tokens/m2/mat/option' as tokens-mat-option;
 @use '../tokens/token-utils';
 @use '../style/sass-utils';
@@ -6,6 +5,9 @@
 @use '../theming/inspection';
 @use '../typography/typography';
 
+/// Outputs base theme styles (styles not dependent on the color, typography, or density settings)
+/// for the mat-option.
+/// @param {Map} $theme The theme to generate base styles for.
 @mixin base($theme) {
   @if inspection.get-theme-version($theme) == 1 {
     @include _theme-from-tokens(inspection.get-theme-tokens($theme, base));
@@ -13,9 +15,14 @@
   @else {}
 }
 
-@mixin color($theme) {
+/// Outputs color theme styles for the mat-option.
+/// @param {Map} $theme The theme to generate color styles for.
+/// @param {ArgList} Additional optional arguments (only supported for M3 themes):
+///   $color-variant: The color variant to use for the selected option: primary, secondary,
+///      tertiary, or error (If not specified, default secondary color will be used).
+@mixin color($theme, $options...) {
   @if inspection.get-theme-version($theme) == 1 {
-    @include _theme-from-tokens(inspection.get-theme-tokens($theme, color));
+    @include _theme-from-tokens(inspection.get-theme-tokens($theme, color), $options...);
   }
   @else {
     @include sass-utils.current-selector-or-root() {
@@ -35,6 +42,8 @@
   }
 }
 
+/// Outputs typography theme styles for the mat-option.
+/// @param {Map} $theme The theme to generate typography styles for.
 @mixin typography($theme) {
   @if inspection.get-theme-version($theme) == 1 {
     @include _theme-from-tokens(inspection.get-theme-tokens($theme, typography));
@@ -47,6 +56,8 @@
   }
 }
 
+/// Outputs density theme styles for the mat-option.
+/// @param {Map} $theme The theme to generate density styles for.
 @mixin density($theme) {
   @if inspection.get-theme-version($theme) == 1 {
     @include _theme-from-tokens(inspection.get-theme-tokens($theme, density));
@@ -54,10 +65,15 @@
   @else {}
 }
 
-@mixin theme($theme) {
+/// Outputs all (base, color, typography, and density) theme styles for the mat-option.
+/// @param {Map} $theme The theme to generate styles for.
+/// @param {ArgList} Additional optional arguments (only supported for M3 themes):
+///   $color-variant: The color variant to use for the selected option: primary, secondary,
+///      tertiary, or error (If not specified, default secondary color will be used).
+@mixin theme($theme, $options...) {
   @include theming.private-check-duplicate-theme-styles($theme, 'mat-option') {
     @if inspection.get-theme-version($theme) == 1 {
-      @include _theme-from-tokens(inspection.get-theme-tokens($theme));
+      @include _theme-from-tokens(inspection.get-theme-tokens($theme), $options...);
     }
     @else {
       @include base($theme);
@@ -74,9 +90,7 @@
   }
 }
 
-@mixin _theme-from-tokens($tokens) {
-  @if ($tokens != ()) {
-    @include token-utils.create-token-values(
-        tokens-mat-option.$prefix, map.get($tokens, tokens-mat-option.$prefix));
-  }
+@mixin _theme-from-tokens($tokens, $options...) {
+  $mat-option-tokens: token-utils.get-tokens-for($tokens, tokens-mat-option.$prefix, $options...);
+  @include token-utils.create-token-values(tokens-mat-option.$prefix, $mat-option-tokens);
 }