fix(material/core): rename utility-classes to system-classes (#31745)

andrewseguin · Andrew Seguin · web-flow · commit 605e2c9f6557 · 2025-08-21T09:34:45.000-06:00
* fix(material/core): rename utility-classes to system-classes

* fix(material/core): update more prefixes

---------

Co-authored-by: Andrew Seguin &lt;andrewseguin@google.com&gt;
diff --git a/src/dev-app/BUILD.bazel b/src/dev-app/BUILD.bazel
@@ -85,6 +85,7 @@ ng_project(
         "//src/dev-app/snack-bar",
         "//src/dev-app/stepper",
         "//src/dev-app/system",
+        "//src/dev-app/system-classes-demo",
         "//src/dev-app/table",
         "//src/dev-app/table-scroll-container",
         "//src/dev-app/tabs",
@@ -94,7 +95,6 @@ ng_project(
         "//src/dev-app/tooltip",
         "//src/dev-app/tree",
         "//src/dev-app/typography",
-        "//src/dev-app/utility-classes-demo",
         "//src/dev-app/virtual-scroll",
         "//src/dev-app/youtube-player",
         "//src/material/core",
diff --git a/src/dev-app/dev-app/dev-app-layout.ts b/src/dev-app/dev-app/dev-app-layout.ts
@@ -116,6 +116,7 @@ export class DevAppLayout {
     {name: 'Snack Bar', route: '/snack-bar'},
     {name: 'Stepper', route: '/stepper'},
     {name: 'System', route: '/system'},
+    {name: 'System classes', route: '/system-classes'},
     {name: 'Table Scroll Container', route: '/table-scroll-container'},
     {name: 'Table', route: '/table'},
     {name: 'Tabs', route: '/tabs'},
@@ -125,7 +126,6 @@ export class DevAppLayout {
     {name: 'Tooltip', route: '/tooltip'},
     {name: 'Tree', route: '/tree'},
     {name: 'Typography', route: '/typography'},
-    {name: 'Utility', route: '/utility'},
     {name: 'Virtual Scrolling', route: '/virtual-scroll'},
     {name: 'YouTube Player', route: '/youtube-player'},
   ];
diff --git a/src/dev-app/routes.ts b/src/dev-app/routes.ts
@@ -302,15 +302,15 @@ export const DEV_APP_ROUTES: Routes = [
     loadComponent: () =>
       import('./youtube-player/youtube-player-demo').then(m => m.YouTubePlayerDemo),
   },
-  {
-    path: 'utility',
-    loadComponent: () =>
-      import('./utility-classes-demo/utility-classes-demo').then(m => m.UtilityClassesDemo),
-  },
   {
     path: 'selection',
     loadComponent: () => import('./selection/selection-demo').then(m => m.SelectionDemo),
   },
+  {
+    path: 'system-classes',
+    loadComponent: () =>
+      import('./system-classes-demo/system-classes-demo').then(m => m.SystemClassesDemo),
+  },
   {
     path: 'examples',
     loadComponent: () => import('./examples-page/examples-page').then(m => m.ExamplesPage),
diff --git a/src/dev-app/system-classes-demo/BUILD.bazel b/src/dev-app/system-classes-demo/BUILD.bazel
@@ -3,18 +3,18 @@ load("//tools:defaults.bzl", "ng_project", "sass_binary")
 package(default_visibility = ["//visibility:public"])
 
 ng_project(
-    name = "utility-classes-demo",
+    name = "system-classes-demo",
     srcs = glob(["**/*.ts"]),
     assets = [
-        "utility-classes-demo.html",
-        ":utility_classes_demo_scss",
+        "system-classes-demo.html",
+        ":system_classes_demo_scss",
     ],
     deps = [
         "//:node_modules/@angular/core",
     ],
 )
 
 sass_binary(
-    name = "utility_classes_demo_scss",
-    src = "utility-classes-demo.scss",
+    name = "system_classes_demo_scss",
+    src = "system-classes-demo.scss",
 )
diff --git a/src/dev-app/system-classes-demo/system-classes-demo.html b/src/dev-app/system-classes-demo/system-classes-demo.html
@@ -34,32 +34,32 @@ <h2>Text Color</h2>
 <section>
   <h2>Typography</h2>
   <div class="demo-typography">
-    <div class="mat-font-display-large">Display Large</div>
-    <div class="mat-font-display-medium">Display Medium</div>
-    <div class="mat-font-display-small">Display Small</div>
-    <div class="mat-font-headline-large">Headline Large</div>
-    <div class="mat-font-headline-medium">Headline Medium</div>
-    <div class="mat-font-headline-small">Headline Small</div>
-    <div class="mat-font-title-large">Title Large</div>
-    <div class="mat-font-title-medium">Title Medium</div>
-    <div class="mat-font-title-small">Title Small</div>
-    <div class="mat-font-body-large">Body Large</div>
-    <div class="mat-font-body-medium">Body Medium</div>
-    <div class="mat-font-body-small">Body Small</div>
+    <div class="mat-font-display-lg">mat-font-display-lg (Display Large)</div>
+    <div class="mat-font-display-md">mat-font-display-md (Display Medium)</div>
+    <div class="mat-font-display-sm">mat-font-display-sm (Display Small)</div>
+    <div class="mat-font-headline-lg">mat-font-headline-lg (Headline Large)</div>
+    <div class="mat-font-headline-md">mat-font-headline-md (Headline Medium)</div>
+    <div class="mat-font-headline-sm">mat-font-headline-sm (Headline Small)</div>
+    <div class="mat-font-title-lg">mat-font-title-lg (Title Large)</div>
+    <div class="mat-font-title-md">mat-font-title-md (Title Medium)</div>
+    <div class="mat-font-title-sm">mat-font-title-sm (Title Small)</div>
+    <div class="mat-font-body-lg">mat-font-body-lg (Body Large)</div>
+    <div class="mat-font-body-md">mat-font-body-md (Body Medium)</div>
+    <div class="mat-font-body-sm">mat-font-body-sm (Body Small)</div>
   </div>
 </section>
 
 <section>
   <h2>Shape</h2>
   <div class="demo-grid">
-    <div class="mat-corner-extra-small demo-box mat-bg-primary-container">
-      mat-corner-extra-small
+    <div class="mat-corner-extra-sm demo-box mat-bg-primary-container">
+      mat-corner-extra-sm
     </div>
-    <div class="mat-corner-small demo-box mat-bg-primary-container">mat-corner-small</div>
-    <div class="mat-corner-medium demo-box mat-bg-primary-container">mat-corner-medium</div>
-    <div class="mat-corner-large demo-box mat-bg-primary-container">mat-corner-large</div>
-    <div class="mat-corner-extra-large demo-box mat-bg-primary-container">
-      mat-corner-extra-large
+    <div class="mat-corner-sm demo-box mat-bg-primary-container">mat-corner-sm</div>
+    <div class="mat-corner-md demo-box mat-bg-primary-container">mat-corner-md</div>
+    <div class="mat-corner-lg demo-box mat-bg-primary-container">mat-corner-lg</div>
+    <div class="mat-corner-xl demo-box mat-bg-primary-container">
+      mat-corner-xl
     </div>
     <div class="mat-corner-full demo-box mat-bg-primary-container">mat-corner-full</div>
   </div>
diff --git a/src/dev-app/system-classes-demo/system-classes-demo.scss b/src/dev-app/system-classes-demo/system-classes-demo.scss
diff --git a/src/dev-app/system-classes-demo/system-classes-demo.ts b/src/dev-app/system-classes-demo/system-classes-demo.ts
@@ -0,0 +1,9 @@
+import {ChangeDetectionStrategy, Component} from '@angular/core';
+
+@Component({
+  selector: 'app-system-classes-demo',
+  templateUrl: './system-classes-demo.html',
+  styleUrls: ['./system-classes-demo.scss'],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class SystemClassesDemo {}
diff --git a/src/dev-app/theme-m3.scss b/src/dev-app/theme-m3.scss
@@ -53,7 +53,7 @@ html {
     ));
   }
 
-  @include mat.utility-classes();
+  @include mat.system-classes();
 }
 
 @include mat.typography-hierarchy($light-theme);
diff --git a/src/dev-app/theme.scss b/src/dev-app/theme.scss
@@ -24,7 +24,7 @@ $candy-app-theme: mat.m2-define-light-theme((
 @include mat.app-background();
 @include mat.elevation-classes();
 @include mat.m2-theme($candy-app-theme);
-@include mat.utility-classes();
+@include mat.system-classes();
 
 // Include the default theme styles.
 @include mat.all-component-themes($candy-app-theme);
diff --git a/src/dev-app/utility-classes-demo/utility-classes-demo.ts b/src/dev-app/utility-classes-demo/utility-classes-demo.ts
diff --git a/src/material/_index.scss b/src/material/_index.scss
@@ -20,7 +20,7 @@
 @forward 'core/tokens/system' show system-level-colors,
     system-level-typography, system-level-elevation, system-level-shape,
     system-level-motion, system-level-state, theme, theme-overrides, m2-theme;
-@forward 'core/tokens/classes' show utility-classes;
+@forward 'core/tokens/classes' show system-classes;
 
 // Private/Internal
 @forward './core/density/private/all-density' show all-component-densities;
diff --git a/src/material/core/tokens/_classes.scss b/src/material/core/tokens/_classes.scss
@@ -1,8 +1,6 @@
-// Utility classes that can be used to style elements with the most commonly used tokens in
+// Utility classes that can be used to style elements with the most commonly used system tokens in
 // Material Design. Includes color, typography, elevation, and shape.
-// This API is experimental and may not release. Implemented for prototyping and testing.
-// Use caution depending on this.
-@mixin utility-classes() {
+@mixin system-classes() {
 
   // ***********************************************************************************************
   // Background
@@ -171,86 +169,86 @@
 
   // Sets the font to the body small typeface. Use for small body text, such as captions. In Angular
   // Material, this is used for the subscript text in a form field and the text in a paginator.
-  .mat-font-body-small {
+  .mat-font-body-sm {
     font: var(--mat-sys-body-small);
     letter-spacing: var(--mat-sys-body-small-tracking);
   }
 
   // Sets the font to the body medium typeface. Use for medium body text, this is the default
   // body font. In Angular Material, this is used for the text in a table row and the supporting
   // text in a dialog.
-  .mat-font-body-medium {
+  .mat-font-body-md {
     font: var(--mat-sys-body-medium);
     letter-spacing: var(--mat-sys-body-medium-tracking);
   }
 
   // Sets the font to the body large typeface. Use for large body text, such as an introductory
   // paragraph. In Angular Material, this is used for the text in a list item and the text in a
   // select trigger.
-  .mat-font-body-large {
+  .mat-font-body-lg {
     font: var(--mat-sys-body-large);
     letter-spacing: var(--mat-sys-body-large-tracking);
   }
 
   // Sets the font to the display small typeface. Use for small display text, such as a date.
-  .mat-font-display-small {
+  .mat-font-display-sm {
     font: var(--mat-sys-display-small);
     letter-spacing: var(--mat-sys-display-small-tracking);
   }
 
   // Sets the font to the display medium typeface. Use for medium display text, such as a hero
   // title.
-  .mat-font-display-medium {
+  .mat-font-display-md {
     font: var(--mat-sys-display-medium);
     letter-spacing: var(--mat-sys-display-medium-tracking);
   }
 
   // Sets the font to the display large typeface. Use for large display text, such as a hero title.
-  .mat-font-display-large {
+  .mat-font-display-lg {
     font: var(--mat-sys-display-large);
     letter-spacing: var(--mat-sys-display-large-tracking);
   }
 
   // Sets the font to the headline small typeface. Use for small headlines, such as a page title. In
   // Angular Material, this is used for the headline in a dialog.
-  .mat-font-headline-small {
+  .mat-font-headline-sm {
     font: var(--mat-sys-headline-small);
     letter-spacing: var(--mat-sys-headline-small-tracking);
   }
 
   // Sets the font to the headline medium typeface. Use for medium headlines, such as a section
   // title.
-  .mat-font-headline-medium {
+  .mat-font-headline-md {
     font: var(--mat-sys-headline-medium);
     letter-spacing: var(--mat-sys-headline-medium-tracking);
   }
 
   // Sets the font to the headline large typeface. Use for large headlines, such as a page title on
   // a large screen.
-  .mat-font-headline-large {
+  .mat-font-headline-lg {
     font: var(--mat-sys-headline-large);
     letter-spacing: var(--mat-sys-headline-large-tracking);
   }
 
   // Sets the font to the title small typeface. Use for small titles, such as a card title. In
   // Angular Material, this is used for the header of a table and the label of an option group.
-  .mat-font-title-small {
+  .mat-font-title-sm {
     font: var(--mat-sys-title-small);
     letter-spacing: var(--mat-sys-title-small-tracking);
   }
 
   // Sets the font to the title medium typeface. Use for medium titles, such as a dialog title
   // or the primary text in a list item. In Angular Material, this is used for the subtitle
   // of a card and the header of an expansion panel.
-  .mat-font-title-medium {
+  .mat-font-title-md {
     font: var(--mat-sys-title-medium);
     letter-spacing: var(--mat-sys-title-medium-tracking);
   }
 
   // Sets the font to the title large typeface. Use for large titles, such as a page title on a
   // small screen. In Angular Material, this is used for the title of a card and the title of a
   // toolbar.
-  .mat-font-title-large {
+  .mat-font-title-lg {
     font: var(--mat-sys-title-large);
     letter-spacing: var(--mat-sys-title-large-tracking);
   }
@@ -262,39 +260,39 @@
 
   // Sets the border radius to extra small. Use for components that need a small amount of rounding,
   // such as a chip. In Angular Material, this is used for the shape of a snackbar and a tooltip.
-  .mat-corner-extra-small {
+  .mat-rounded-extra-sm {
     border-radius: var(--mat-sys-corner-extra-small);
   }
 
   // Sets the border radius to small. Use for components that need a small amount of rounding, such
   // as a text field.
-  .mat-corner-small {
+  .mat-rounded-sm {
     border-radius: var(--mat-sys-corner-small);
   }
 
   // Sets the border radius to medium. Use for components that need a medium amount of rounding,
   // such as a button. In Angular Material, this is used for the shape of a card.
-  .mat-corner-medium {
+  .mat-rounded-md {
     border-radius: var(--mat-sys-corner-medium);
   }
 
   // Sets the border radius to large. Use for components that need a large amount of rounding, such
   // as a card. In Angular Material, this is used for the shape of a floating action button and a
   // datepicker.
-  .mat-corner-large {
+  .mat-rounded-lg {
     border-radius: var(--mat-sys-corner-large);
   }
 
   // Sets the border radius to extra large. Use for components that need a large amount of
   // rounding. In Angular Material, this is used for the shape of a button toggle and the shape of
   // a dialog.
-  .mat-corner-extra-large {
+  .mat-rounded-xl {
     border-radius: var(--mat-sys-corner-extra-large);
   }
 
   // Sets the border radius to full. Use for components that are circular, such as a user avatar.
   // In Angular Material, this is used for the shape of a badge and the shape of a button.
-  .mat-corner-full {
+  .mat-rounded-full {
     border-radius: var(--mat-sys-corner-full);
   }
 
@@ -305,14 +303,14 @@
 
   // Adds an outline to an element. Use for components that need a visible boundary. In Angular
   // Material, this is used for the outline of an outlined button.
-  .mat-outline {
+  .mat-border {
     border: 1px solid var(--mat-sys-outline);
   }
 
   // Adds a less prominent outline to an element. Use for components that need a less obvious
   // boundary. In Angular Material, this is used for the outline of an outlined card and the color
   // of the divider
-  .mat-outline-variant {
+  .mat-border-subtle {
     border: 1px solid var(--mat-sys-outline-variant);
   }
 
@@ -384,32 +382,32 @@
 
   // Use to slightly raise the appearance of a surface. In Angular Material, this is used for the
   // elevation of an elevated card and the handle of a slider.
-  .mat-shadow-level-1 {
+  .mat-shadow-1 {
     box-shadow: var(--mat-sys-level1);
   }
 
   // Use to raise the appearance of a surface. In Angular Material, this is used for the
   // elevation of a menu and a select panel.
-  .mat-shadow-level-2 {
+  .mat-shadow-2 {
     box-shadow: var(--mat-sys-level2);
   }
 
   // Used to raise the appearance of a surface. In Angular Material, this is used for the elevation
   // of a floating action button.
-  .mat-shadow-level-3 {
+  .mat-shadow-3 {
     box-shadow: var(--mat-sys-level3);
   }
 
   // Used to raise the appearance of a surface. This is generally reserved for elevation changes
   // due to interaction like focus and hover. In Angular Material, this is used for the elevation
   // of a hovered floating action button.
-  .mat-shadow-level-4 {
+  .mat-shadow-4 {
     box-shadow: var(--mat-sys-level4);
   }
 
   // Used to greatly raise the appearance of a surface. This is generally reserved for elevation
   // changes due to interaction like focus and hover.
-  .mat-shadow-level-5 {
+  .mat-shadow-5 {
     box-shadow: var(--mat-sys-level5);
   }
 }

Original file line number	Diff line number	Diff line change
`@@ -53,7 +53,7 @@ html {`
`53`	`53`	`));`
`54`	`54`	`}`
`55`	`55`
`56`		`- @include mat.utility-classes();`
	`56`	`+ @include mat.system-classes();`
`57`	`57`	`}`
`58`	`58`
`59`	`59`	`@include mat.typography-hierarchy($light-theme);`