@angular/material 20.0.0-rc.0 → 20.0.0-rc.1

package/core/tokens/_m3-system.scss

@@ -19,6 +19,7 @@
 @use '../style/sass-utils';
 @use '../theming/config-validation';
 @use '../theming/definition';
+@use '../theming/palettes';
 @use './m3';
 @use './m3-tokens';
 @use 'sass:list';
@@ -63,9 +64,40 @@
       $color: map.set($color, theme-type, color-scheme);
     }
 
-    $color-config: if($is-palette,
-            definition.define-colors((primary: $color, theme-type: color-scheme)),
-            definition.define-colors($color));
+    $color-config: $color;
+    @if ($is-palette) {
+      $color: map.set($color, tertiary, $color);
+      $color-config: (
+        definition.$internals: (
+          palettes: (
+            primary: map.remove($color, neutral, neutral-variant, secondary),
+            secondary: map.get($color, secondary),
+            tertiary: map.remove($color, neutral, neutral-variant, secondary, error),
+            neutral: map.get($color, neutral),
+            neutral-variant: map.get($color, neutral-variant),
+            error: map.get($color, error),
+          ),
+          theme-type: color-scheme,
+        )
+      );
+    } @else {
+      $primary: map.get($color, primary) or palettes.$violet-palette;
+      $tertiary: map.get($color, tertiary) or $primary;
+      $color-config: (
+        definition.$internals: (
+          palettes: (
+            primary: map.remove($primary, neutral, neutral-variant, secondary),
+            secondary: map.get($primary, secondary),
+            tertiary: map.remove($tertiary, neutral, neutral-variant, secondary, error),
+            neutral: map.get($primary, neutral),
+            neutral-variant: map.get($primary, neutral-variant),
+            error: map.get($primary, error),
+          ),
+          theme-type: map.get($color, theme-type),
+        )
+      );
+    }
+
     @include system-level-colors($color-config, $overrides, definition.$system-fallback-prefix);
     @include system-level-elevation($color-config, $overrides, definition.$system-fallback-prefix);
   }
@@ -73,9 +105,31 @@
   $typography: map.get($config, typography);
   $typography-config: null;
   @if ($typography) {
-    $typography-config: if(meta.type-of($typography) == 'map',
-      definition.define-typography($typography),
-      definition.define-typography((plain-family: $typography)));
+    $plain: (Roboto, sans-serif);
+    $brand: $plain;
+    $bold: 700;
+    $medium: 500;
+    $regular: 400;
+    @if (meta.type-of($typography) == map) {
+      $plain: map.get($typography, plain-family);
+      $brand: map.get($typography, brand-family) or $plain;
+      $bold: map.get($typography, bold-weight) or $bold;
+      $medium: map.get($typography, medium-weight) or $medium;
+      $regular: map.get($typography, regular-weight) or $regular;
+    } @else {
+      $plain: $typography;
+    }
+    $typography-config: (
+      definition.$internals: (
+        font-definition: (
+          plain: $plain,
+          brand: $brand,
+          bold: $bold,
+          medium: $medium,
+          regular: $regular,
+        )
+      )
+    );
     @include system-level-typography(
         $typography-config, $overrides, definition.$system-fallback-prefix);
   }
@@ -83,10 +137,12 @@
   $density: map.get($config, density);
   $density-config: null;
   @if ($density) {
-    $density-config: if(meta.type-of($density) == 'map',
-      definition.define-density($density),
-      definition.define-density((scale: $density)));
-    $scale: map.get($density-config, _mat-theming-internals-do-not-access, density-scale);
+    $scale: 0;
+    @if (meta.type-of($density) == map) {
+      $scale: map.get($density, scale);
+    } @else {
+      $scale: $density;
+    }
     @if ($scale != 0) {
       // Emit component-level density tokens if the scale is lower than 0. The density tokens
       // do not fallback to any system-level values and must be defined if the scale is different.
@@ -130,8 +186,14 @@
 /// change the primary color to red, use `mat.theme-overrides((primary: red));`
 @mixin theme-overrides($overrides, $prefix: definition.$system-fallback-prefix) {
   $sys-names: map-merge-all(
-      m3.md-sys-color-values-light(),
-      m3.md-sys-typescale-values(),
+      m3.md-sys-color-values-light(palettes.$blue-palette),
+      m3.md-sys-typescale-values((
+        brand: (Roboto),
+        plain: (Roboto),
+        bold: 700,
+        medium: 500,
+        regular: 400
+      )),
       m3.md-sys-elevation-values(),
       m3.md-sys-shape-values(),
       m3.md-sys-state-values());
@@ -146,36 +208,21 @@
 }
 
 @mixin system-level-colors($theme, $overrides: (), $prefix: null) {
-  $palettes: map.get($theme, _mat-theming-internals-do-not-access, palettes);
-  $base-palettes: (
-    neutral: map.get($palettes, neutral),
-    neutral-variant: map.get($palettes, neutral-variant),
-    secondary: map.get($palettes, secondary),
-    error: map.get($palettes, error),
-  );
-
-  $type: map.get($theme, _mat-theming-internals-do-not-access, theme-type);
-  $primary: map.merge(map.get($palettes, primary), $base-palettes);
-  $tertiary: map.merge(map.get($palettes, tertiary), $base-palettes);
-  $error: map.get($palettes, error);
+  $palettes: map.get($theme, definition.$internals, palettes);
+  $type: map.get($theme, definition.$internals, theme-type);
 
   @if (not $prefix) {
-    $prefix: map.get($theme, _mat-theming-internals-do-not-access,
+    $prefix: map.get($theme, definition.$internals,
         color-system-variables-prefix) or definition.$system-level-prefix;
   }
 
-  $ref: (
-    md-ref-palette: m3-tokens.generate-ref-palette-tokens($primary, $tertiary, $error)
-  );
 
-  $sys-colors: _generate-sys-colors($ref, $type);
+  $sys-colors: _generate-sys-colors($palettes, $type);
 
   // Manually insert a subset of palette values that are used directly by components
   // instead of system variables.
-  $sys-colors: map.set($sys-colors,
-    'neutral-variant20', map.get($ref, md-ref-palette, neutral-variant20));
-  $sys-colors: map.set($sys-colors,
-    'neutral10', map.get($ref, md-ref-palette, neutral10));
+  $sys-colors: map.set($sys-colors, neutral-variant20, map.get($palettes, neutral-variant, 20));
+  $sys-colors: map.set($sys-colors, neutral10, map.get($palettes, neutral, 10));
 
   & {
     @each $name, $value in $sys-colors {
@@ -184,13 +231,13 @@
   }
 }
 
-@function _generate-sys-colors($ref, $type) {
-  $light-sys-colors: m3.md-sys-color-values-light($ref);
+@function _generate-sys-colors($palettes, $type) {
+  $light-sys-colors: m3.md-sys-color-values-light($palettes);
   @if ($type == light) {
     @return $light-sys-colors;
   }
 
-  $dark-sys-colors: m3.md-sys-color-values-dark($ref);
+  $dark-sys-colors: m3.md-sys-color-values-dark($palettes);
   @if ($type == dark) {
     @return $dark-sys-colors;
   }
@@ -209,23 +256,15 @@
 }
 
 @mixin system-level-typography($theme, $overrides: (), $prefix: null) {
-  $font-definition: map.get($theme, _mat-theming-internals-do-not-access, font-definition);
-  $brand: map.get($font-definition, brand);
-  $plain: map.get($font-definition, plain);
-  $bold: map.get($font-definition, bold);
-  $medium: map.get($font-definition, medium);
-  $regular: map.get($font-definition, regular);
-  $ref: (md-ref-typeface:
-      m3-tokens.generate-ref-typeface-tokens($brand, $plain, $bold, $medium, $regular)
-  );
+  $font-definition: map.get($theme, definition.$internals, font-definition);
 
   @if (not $prefix) {
-    $prefix: map.get($theme, _mat-theming-internals-do-not-access,
+    $prefix: map.get($theme, definition.$internals,
         typography-system-variables-prefix) or definition.$system-level-prefix;
   }
 
   & {
-    @each $name, $value in m3.md-sys-typescale-values($ref) {
+    @each $name, $value in m3.md-sys-typescale-values($font-definition) {
       --#{$prefix}-#{$name}: #{map.get($overrides, $name) or $value};
     }
   }
@@ -233,7 +272,7 @@
 
 @mixin system-level-elevation($theme, $overrides: (), $prefix: definition.$system-level-prefix) {
   $shadow-color: map.get(
-      $theme, _mat-theming-internals-do-not-access, color-tokens, (mat, theme), shadow);
+      $theme, definition.$internals, palettes, neutral, 0);
 
   @each $name, $value in m3.md-sys-elevation-values() {
     $level: map.get($overrides, $name) or $value;
@@ -275,27 +314,6 @@
 // system fallback variables referencing Material's system keys.
 // Includes density token fallbacks where density is 0.
 @function create-system-fallbacks() {
-  $app-vars: (
-    'md-sys-color':
-        _create-system-app-vars-map(m3.md-sys-color-values-light()),
-    'md-sys-typescale':
-        _create-system-app-vars-map(m3.md-sys-typescale-values()),
-    'md-sys-elevation':
-        _create-system-app-vars-map(m3.md-sys-elevation-values()),
-    'md-sys-state':
-        _create-system-app-vars-map(m3.md-sys-state-values()),
-    'md-sys-shape':
-        _create-system-app-vars-map(m3.md-sys-shape-values()),
-    // Add a subset of palette-specific colors used by components instead of system values
-    'md-ref-palette':
-        _create-system-app-vars-map(
-          (
-            neutral10: '', // Form field native select option text color
-            neutral-variant20: '', // Sidenav scrim (container background shadow when opened),
-          )
-        ),
-  );
-
   @return sass-utils.deep-merge-all(
       m3-tokens.generate-tokens($app-vars, true, true),
       get-density-tokens(0),
@@ -310,3 +328,28 @@
   }
   @return $result;
 }
+
+$placeholder-palettes: m3.md-sys-color-values-light(palettes.$blue-palette);
+$placeholder-palettes: map.set($placeholder-palettes, primary, palettes.$blue-palette);
+$app-vars: (
+  'md-sys-color': _create-system-app-vars-map(m3.md-sys-color-values-light($placeholder-palettes)),
+  'md-sys-typescale': _create-system-app-vars-map(m3.md-sys-typescale-values((
+    brand: (Roboto),
+    plain: (Roboto),
+    bold: 700,
+    medium: 500,
+    regular: 400
+  ))),
+  'md-sys-elevation': _create-system-app-vars-map(m3.md-sys-elevation-values()),
+  'md-sys-state': _create-system-app-vars-map(m3.md-sys-state-values()),
+  'md-sys-shape': _create-system-app-vars-map(m3.md-sys-shape-values()),
+  // Add a subset of palette-specific colors used by components instead of system values
+  'md-ref-palette': _create-system-app-vars-map(
+      (
+        neutral10: '', // Form field native select option text color
+        neutral-variant20: '', // Sidenav scrim (container background shadow when opened),
+      )
+  ),
+);
+
+$theme-with-system-vars: (definition.$internals: $app-vars);

package/core/tokens/_m3-tokens.scss

@@ -1,5 +1,4 @@
 @use '../../autocomplete/m3-autocomplete';
-@use '../../badge/m3-badge';
 @use '../../bottom-sheet/m3-bottom-sheet';
 @use '../../button-toggle/m3-button-toggle';
 @use '../../button/m3-button';
@@ -41,61 +40,10 @@
 @use '../ripple/m3-ripple';
 @use '../selection/pseudo-checkbox/m3-pseudo-checkbox';
 @use '../style/sass-utils';
-@use './format-tokens';
 @use './m2-tokens';
 @use './m3';
 @use 'sass:map';
 
-/// Generates tokens for the given palette with the given prefix.
-/// @param {Map} $palette The palette to generate tokens for
-/// @param {String} $prefix The key prefix used to name the tokens
-/// @return {Map} A set of tokens for the given palette
-@function _generate-palette-tokens($palette, $prefix) {
-  $palette: map.remove($palette, neutral, neutral-variant);
-  $result: ();
-  @each $hue, $value in $palette {
-    $result: map.set($result, '#{$prefix}#{$hue}', $value);
-  }
-  @return $result;
-}
-
-/// Creates a set of `md-ref-palette` tokens from the given palettes. (See
-/// ./m3/definitions/_md-ref-palette.scss)
-/// @param {Map} $primary The primary palette
-/// @param {Map} $secondary The secondary palette
-/// @param {Map} $tertiary The tertiary palette
-/// @param {Map} $error The error palette
-/// @return {Map} A set of `md-ref-palette` tokens
-@function generate-ref-palette-tokens($primary, $tertiary, $error) {
-  @return sass-utils.merge-all(
-      (black: #000, white: #fff),
-      _generate-palette-tokens($primary, primary),
-      _generate-palette-tokens(map.get($primary, secondary), secondary),
-      _generate-palette-tokens($tertiary, tertiary),
-      _generate-palette-tokens(map.get($primary, neutral), neutral),
-      _generate-palette-tokens(map.get($primary, neutral-variant), neutral-variant),
-      _generate-palette-tokens($error, error),
-  );
-}
-
-/// Creates a set of `md-ref-typeface` tokens from the given palettes. (See
-/// ./m3/definitions/_md-ref-typeface.scss)
-/// @param {List|String} $brand The font-family to use for brand text
-/// @param {List|String} $plain The font-family to use for plain text
-/// @param {String} $bold The font-weight to use for bold text
-/// @param {String} $medium The font-weight to use for medium text
-/// @param {String} $regular The font-weight to use for regular text
-/// @return {Map} A set of `md-ref-typeface` tokens
-@function generate-ref-typeface-tokens($brand, $plain, $bold, $medium, $regular) {
-  @return (
-    brand: $brand,
-    plain: $plain,
-    weight-bold: $bold,
-    weight-medium: $medium,
-    weight-regular: $regular,
-  );
-}
-
 $_cached-token-slots: null;
 
 /// Determines the token slots for all components.
@@ -138,9 +86,6 @@ $_cached-token-slots: null;
   ), $systems);
   $exclude-hardcoded: not $include-non-systemized;
 
-  // DO NOT REMOVE
-  // This function is used internally.
-  $systems: format-tokens.private-format-tokens($systems);
   $token-slots: _get-token-slots();
 
   // TODO(mmalerba): Fill in remaining tokens.
@@ -164,170 +109,34 @@ $_cached-token-slots: null;
   @return $result;
 }
 
-@function _get-sys-color($type, $ref, $prefix) {
-  $mdc-sys-color: if($type == dark,
-    m3.md-sys-color-values-dark($ref),
-    m3.md-sys-color-values-light($ref));
+@function get-sys-color($type, $palettes, $prefix) {
+  $sys-color: if($type == dark,
+    m3.md-sys-color-values-dark($palettes),
+    m3.md-sys-color-values-light($palettes));
 
   @if (sass-utils.$use-system-color-variables) {
-    $keys: (
-            'background',
-            'error',
-            'error-container',
-            'inverse-on-surface',
-            'inverse-primary',
-            'inverse-surface',
-            'on-background',
-            'on-error',
-            'on-error-container',
-            'on-primary',
-            'on-primary-container',
-            'on-primary-fixed',
-            'on-primary-fixed-variant',
-            'on-secondary',
-            'on-secondary-container',
-            'on-secondary-fixed',
-            'on-secondary-fixed-variant',
-            'on-surface',
-            'on-surface-variant',
-            'on-tertiary',
-            'on-tertiary-container',
-            'on-tertiary-fixed',
-            'on-tertiary-fixed-variant',
-            'outline',
-            'outline-variant',
-            'primary',
-            'primary-container',
-            'primary-fixed',
-            'primary-fixed-dim',
-            'scrim',
-            'secondary',
-            'secondary-container',
-            'secondary-fixed',
-            'secondary-fixed-dim',
-            'surface',
-            'surface-bright',
-            'surface-container',
-            'surface-container-high',
-            'surface-container-highest',
-            'surface-container-low',
-            'surface-container-lowest',
-            'surface-dim',
-            'surface-tint',
-            'surface-variant',
-            'tertiary',
-            'tertiary-container',
-            'tertiary-fixed',
-            'tertiary-fixed-dim'
-    );
-    @return map.merge(create-map($keys, $prefix), (
-      shadow: map.get($mdc-sys-color, shadow)
-    ));
+    $var-values: ();
+    @each $key in map.keys($sys-color) {
+      $var-values: map.set($var-values, $key, var(--#{$prefix}-#{$key}));
+    }
+    $var-values: map.set($var-values, shadow, map.get($sys-color, shadow));
+    @return $var-values;
   }
 
-  @return $mdc-sys-color;
+  @return $sys-color;
 }
 
-@function _get-sys-typeface($ref, $prefix) {
+@function get-sys-typeface($typography, $prefix) {
+  $sys-typography: m3.md-sys-typescale-values($typography);
   @if (sass-utils.$use-system-typography-variables) {
-    $keys: (
-            'body-large',
-            'body-large-font',
-            'body-large-line-height',
-            'body-large-size',
-            'body-large-tracking',
-            'body-large-weight',
-            'body-medium',
-            'body-medium-font',
-            'body-medium-line-height',
-            'body-medium-size',
-            'body-medium-tracking',
-            'body-medium-weight',
-            'body-small',
-            'body-small-font',
-            'body-small-line-height',
-            'body-small-size',
-            'body-small-tracking',
-            'body-small-weight',
-            'display-large',
-            'display-large-font',
-            'display-large-line-height',
-            'display-large-size',
-            'display-large-tracking',
-            'display-large-weight',
-            'display-medium',
-            'display-medium-font',
-            'display-medium-line-height',
-            'display-medium-size',
-            'display-medium-tracking',
-            'display-medium-weight',
-            'display-small',
-            'display-small-font',
-            'display-small-line-height',
-            'display-small-size',
-            'display-small-tracking',
-            'display-small-weight',
-            'headline-large',
-            'headline-large-font',
-            'headline-large-line-height',
-            'headline-large-size',
-            'headline-large-tracking',
-            'headline-large-weight',
-            'headline-medium',
-            'headline-medium-font',
-            'headline-medium-line-height',
-            'headline-medium-size',
-            'headline-medium-tracking',
-            'headline-medium-weight',
-            'headline-small',
-            'headline-small-font',
-            'headline-small-line-height',
-            'headline-small-size',
-            'headline-small-tracking',
-            'headline-small-weight',
-            'label-large',
-            'label-large-font',
-            'label-large-line-height',
-            'label-large-size',
-            'label-large-tracking',
-            'label-large-weight',
-            'label-large-weight-prominent',
-            'label-medium',
-            'label-medium-font',
-            'label-medium-line-height',
-            'label-medium-size',
-            'label-medium-tracking',
-            'label-medium-weight',
-            'label-medium-weight-prominent',
-            'label-small',
-            'label-small-font',
-            'label-small-line-height',
-            'label-small-size',
-            'label-small-tracking',
-            'label-small-weight',
-            'title-large',
-            'title-large-font',
-            'title-large-line-height',
-            'title-large-size',
-            'title-large-tracking',
-            'title-large-weight',
-            'title-medium',
-            'title-medium-font',
-            'title-medium-line-height',
-            'title-medium-size',
-            'title-medium-tracking',
-            'title-medium-weight',
-            'title-small',
-            'title-small-font',
-            'title-small-line-height',
-            'title-small-size',
-            'title-small-tracking',
-            'title-small-weight'
-    );
-
-    @return create-map($keys, $prefix);
+    $var-values: ();
+    @each $key in map.keys($sys-typography) {
+      $var-values: map.set($var-values, $key, var(--#{$prefix}-#{$key}));
+    }
+    @return $var-values;
   }
-  @return m3.md-sys-typescale-values($ref);
+
+  @return $sys-typography;
 }
 
 /// Generates a set of namespaced color tokens for all components.
@@ -337,15 +146,15 @@ $_cached-token-slots: null;
 /// @param {Map} $error The error palette
 /// @param {String} $system-variables-prefix The prefix of system tokens
 /// @return {Map} A map of namespaced color tokens
-@function generate-color-tokens($type, $primary, $tertiary, $error, $system-variables-prefix) {
-  $ref: (
-    md-ref-palette: generate-ref-palette-tokens($primary, $tertiary, $error)
-  );
+@function generate-color-tokens($type, $palettes, $system-variables-prefix) {
+  $sys-color: get-sys-color($type, $palettes, $system-variables-prefix);
 
-  $sys-color: _get-sys-color($type, $ref, $system-variables-prefix);
-
-  @return generate-tokens(map.merge($ref, (
+  @return generate-tokens((
     md-sys-color: $sys-color,
+    md-ref-palette: (
+      neutral-10: map.get($palettes, neutral, 10),
+      neutral-variant20: map.get($palettes, neutral-variant, 20),
+    ),
     // Because the elevation values are always combined with color values to create the box shadow,
     // elevation needs to be part of the color dimension.
     md-sys-elevation: m3.md-sys-elevation-values(),
@@ -354,7 +163,7 @@ $_cached-token-slots: null;
     // TODO(mmalerba): If at some point we remove the need for these combined values, we can move
     //  state to the base dimension.
     md-sys-state: m3.md-sys-state-values(),
-  )));
+  ));
 }
 
 /// Generates a set of namespaced color tokens for all components.
@@ -365,12 +174,8 @@ $_cached-token-slots: null;
 /// @param {String|Number} $regular The regular font-weight
 /// @param {String} $system-variables-prefix The prefix of system tokens
 /// @return {Map} A map of namespaced typography tokens
-@function generate-typography-tokens($brand, $plain, $bold, $medium, $regular,
-$system-variables-prefix) {
-  $ref: (
-    md-ref-typeface: generate-ref-typeface-tokens($brand, $plain, $bold, $medium, $regular)
-  );
-  $sys-typeface: _get-sys-typeface($ref, $system-variables-prefix);
+@function generate-typography-tokens($typography, $system-variables-prefix) {
+  $sys-typeface: get-sys-typeface($typography, $system-variables-prefix);
   @return generate-tokens((
     md-sys-typescale: $sys-typeface
   ));
@@ -396,7 +201,6 @@ $system-variables-prefix) {
   $tokens-list: (
     m3-app.get-tokens($systems, $exclude-hardcoded, $token-slots),
     m3-autocomplete.get-tokens($systems, $exclude-hardcoded, $token-slots),
-    m3-badge.get-tokens($systems, $exclude-hardcoded, $token-slots),
     m3-bottom-sheet.get-tokens($systems, $exclude-hardcoded, $token-slots),
     m3-button-toggle.get-tokens($systems, $exclude-hardcoded, $token-slots),
     m3-button.get-tokens($systems, $exclude-hardcoded, $token-slots),

package/core/tokens/_m3-utils.scss

@@ -1,6 +1,7 @@
 @use 'sass:map';
 @use 'sass:list';
 @use 'sass:meta';
+@use 'sass:string';
 
 /// Gets the MDC tokens for the given prefix, M3 token values, and supported token slots.
 /// @param {List} $prefix The token prefix for the given tokens.
@@ -83,3 +84,37 @@
   }
   @return $result;
 }
+
+// Replaces color tokens in the map with those defined as the variant color.
+@function replace-colors-with-variant($system, $color, $variant) {
+  $system: map.set($system, on-#{$color}, map.get($system, on-#{$variant}));
+  $system: map.set($system, on-#{$color}-container, map.get($system, on-#{$variant}-container));
+  $system: map.set($system, #{$color}, map.get($system, #{$variant}));
+  $system: map.set($system, #{$color}-container, map.get($system, #{$variant}-container));
+  @return $system;
+}
+
+// Gets the theme's system values as a flat map.
+@function get-system($theme) {
+  $system: ();
+  $system: map.merge($system,
+      map.get($theme, _mat-theming-internals-do-not-access, md-sys-color));
+  $system: map.merge($system,
+      map.get($theme, _mat-theming-internals-do-not-access, md-sys-elevation));
+  $system: map.merge($system,
+      map.get($theme, _mat-theming-internals-do-not-access, md-sys-shape));
+  $system: map.merge($system,
+      map.get($theme, _mat-theming-internals-do-not-access, md-sys-state));
+  $system: map.merge($system,
+      map.get($theme, _mat-theming-internals-do-not-access, md-sys-typescale));
+  @return $system;
+}
+
+// Returns the color with an opacity value using color-mix. If the color is a variable name, it
+// will wrap it with `var()`.
+@function color-with-opacity($color, $opacity) {
+  @if (meta.type-of($color) == string and string.index($color, '--') == 1) {
+    $color: var($color);
+  }
+  @return color-mix(in srgb, #{$color} #{$opacity}, transparent);
+}

package/core/tokens/_token-utils.scss

@@ -9,16 +9,29 @@
 $_tokens: null;
 $_component-prefix: null;
 $_system-fallbacks: m3-system.create-system-fallbacks();
+$_direct-system-fallbacks: ();
 
 // Sets the token prefix and map to use when creating token slots.
-@mixin use-tokens($prefix, $tokens) {
+@mixin use-tokens($prefix, $tokens, $direct-system-fallbacks: null) {
   $_component-prefix: $prefix !global;
   $_tokens: $tokens !global;
 
+  // Direct system fallbacks are a map of base, color, typography, and density tokens. To simplify
+  // lookup, flatten these token groups into a single map.
+  @if $direct-system-fallbacks {
+    $_direct-system-fallbacks: () !global;
+    @each $tokens in map.values($direct-system-fallbacks) {
+      @each $token, $value in $tokens {
+        $_direct-system-fallbacks: map.set($_direct-system-fallbacks, $token, $value) !global;
+      }
+    }
+  }
+
   @content;
 
   $_component-prefix: null !global;
   $_tokens: null !global;
+  $_direct-system-fallbacks: () !global;
 }
 
 // Combines a prefix and a string to generate a CSS variable name for a token.
@@ -90,6 +103,14 @@ $_system-fallbacks: m3-system.create-system-fallbacks();
     $fallback: map.get($_tokens, $token);
   }
 
+  $direct-sys-fallback: map.get($_direct-system-fallbacks, $token);
+  @if ($direct-sys-fallback) {
+    @if (sass-utils.is-css-var-name($direct-sys-fallback)) {
+      @return _create-var($direct-sys-fallback, $fallback);
+    }
+    @return $direct-sys-fallback;
+  }
+
   // Check whether there's a system-level fallback. If not, return the optional
   // provided fallback (otherwise null).
   $sys-fallback: map.get($_system-fallbacks, $_component-prefix, $token);