fix(material/core): rename some utility classes (#31795)

Author: andrewseguin

src/dev-app/system-classes-demo/system-classes-demo.html

@@ -68,26 +68,26 @@ <h2>Shape</h2>
 <section>
   <h2>Elevation</h2>
   <div class="demo-grid">
-    <div class="mat-shadow-level-1 demo-box mat-bg-surface">mat-shadow-level-1</div>
-    <div class="mat-shadow-level-2 demo-box mat-bg-surface">mat-shadow-level-2</div>
-    <div class="mat-shadow-level-3 demo-box mat-bg-surface">mat-shadow-level-3</div>
-    <div class="mat-shadow-level-4 demo-box mat-bg-surface">mat-shadow-level-4</div>
-    <div class="mat-shadow-level-5 demo-box mat-bg-surface">mat-shadow-level-5</div>
+    <div class="mat-shadow-1 demo-box mat-bg-surface">mat-shadow-1</div>
+    <div class="mat-shadow-2 demo-box mat-bg-surface">mat-shadow-2</div>
+    <div class="mat-shadow-3 demo-box mat-bg-surface">mat-shadow-3</div>
+    <div class="mat-shadow-4 demo-box mat-bg-surface">mat-shadow-4</div>
+    <div class="mat-shadow-5 demo-box mat-bg-surface">mat-shadow-5</div>
   </div>
 </section>
 
 <section>
   <h2>Outline</h2>
   <div class="demo-grid">
-    <div class="mat-outline demo-box">mat-outline</div>
-    <div class="mat-outline-variant demo-box">mat-outline-variant</div>
+    <div class="mat-border demo-box">mat-border</div>
+    <div class="mat-border-subtle demo-box">mat-border-subtle</div>
   </div>
 </section>
 
 <section>
   <h2>Stateful</h2>
   <div class="demo-grid">
-    <div class="mat-stateful demo-box">mat-stateful</div>
-    <div class="mat-stateful-primary demo-box">mat-stateful-primary</div>
+    <div class="mat-interactive demo-box">mat-interactive</div>
+    <div class="mat-interactive-primary demo-box">mat-interactive-primary</div>
   </div>
 </section>

src/material/core/tokens/_classes.scss

@@ -1,9 +1,10 @@
 // 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.
+// Material Design. Includes color, typography, elevation, state, and shape.
 @mixin system-classes() {
 
   // ***********************************************************************************************
-  // Background
+  // Background - Apply background color and a contrastful corresponding text color
+  // See https://m3.material.io/styles/color/roles for guidance.
   // ***********************************************************************************************
 
   // Styles an element with a primary color background and applies an accessible contrasting
@@ -135,7 +136,7 @@
 
 
   // ***********************************************************************************************
-  // Text
+  // Text - Apply colors to text
   // ***********************************************************************************************
 
   // Styles the text of an element with the primary color. Use for text that needs to stand out.
@@ -164,7 +165,8 @@
 
 
   // ***********************************************************************************************
-  // Font
+  // Font - Apply typography styles
+  // See https://m3.material.io/styles/typography/applying-type for guidance.
   // ***********************************************************************************************
 
   // Sets the font to the body small typeface. Use for small body text, such as captions. In Angular
@@ -255,50 +257,51 @@
 
 
   // ***********************************************************************************************
-  // Corner
+  // Corner - Apply varying amounts of a border radius
+  // See https://m3.material.io/styles/shape/corner-radius-scale for guidance.
   // ***********************************************************************************************
 
   // 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-rounded-extra-sm {
+  .mat-corner-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-rounded-sm {
+  .mat-corner-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-rounded-md {
+  .mat-corner-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-rounded-lg {
+  .mat-corner-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-rounded-xl {
+  .mat-corner-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-rounded-full {
+  .mat-corner-full {
     border-radius: var(--mat-sys-corner-full);
   }
 
 
   // ***********************************************************************************************
-  // Border
+  // Border - Applies a 1px solid border
   // ***********************************************************************************************
 
   // Adds an outline to an element. Use for components that need a visible boundary. In Angular
@@ -316,12 +319,12 @@
 
 
   // ***********************************************************************************************
-  // State
+  // Interactive - Adds interaction colors for hover, active, and focus
   // ***********************************************************************************************
 
   // Adds hover, focus, and active states to an element by applying varying shades of the surface
   // color. Use for interactive components that are not based on a primary color.
-  .mat-stateful {
+  .mat-interactive {
     &:hover {
       background: color-mix(
         in srgb,
@@ -349,7 +352,7 @@
 
   // Adds hover, focus, and active states to an element by applying varying shades of the primary
   // color. Use for interactive components that are not based on a primary color.
-  .mat-stateful-primary {
+  .mat-interactive-primary {
     &:hover {
       background: color-mix(
         in srgb,
@@ -377,7 +380,8 @@
 
 
   // ***********************************************************************************************
-  // Elevation
+  // Shadow - Applies elevation levels through box-shadow
+  // See https://m3.material.io/styles/elevation/applying-elevation for guidance.
   // ***********************************************************************************************
 
   // Use to slightly raise the appearance of a surface. In Angular Material, this is used for the