docs: add more about m2 support

Author: andrewseguin

guides/theming-your-components.md

@@ -11,7 +11,7 @@ theme:
 
 - **CSS variables** included by `mat.theme()`. These are prefixed with `--mat-sys` and can be used
   in your component stylesheets to match the theme and design for your application.
-- **CSS classes** included by `mat.system-classes()`. These utility classes wrap the CSS variables
+- **Utility classes** included by `mat.system-classes()`. These utility classes wrap the CSS variables
   and allow you to apply theme styles directly from your component templates.
 
 Both approaches are valid ways to ensure your application is consistently designed alongside Angular
@@ -733,3 +733,55 @@ html {
   @include mat.system-classes();
 }
 ```
+
+By using CSS variables and utility classes, you can avoid creating component-specific theme files 
+and mixins that extract values from the `$theme` Sass map. For example, consider the following
+example of how styles used to be applied in custom components:
+
+```scss
+@use '@angular/material' as mat;
+@use 'sass:map';
+
+@mixin my-component-theme($theme) {
+  $foreground: map.get(mat.m2-get-color-config($theme), foreground);
+  $background: map.get(mat.m2-get-color-config($theme), background);
+  $primary: map.get(mat.m2-get-color-config($theme), primary);
+  $typography: mat.m2-get-typography-config($config-or-theme);
+
+  .widget-a {
+    background-color: mat.m2-get-color-from-palette($background, card);
+    color: mat.m2-get-color-from-palette($foreground, text);
+    @include mat.m2-typography-level($config, body-1);  
+  }
+
+  .widget-b {
+    background-color: mat.m2-get-color-from-palette($primary, default);
+    color: mat.m2-get-color-from-palette($primary, default-contrast);
+  }
+}
+```
+
+By using the CSS variables, you can define these theme styles in your component's
+stylesheet and avoid creating a separate theme file or mixin:
+
+```scss
+.widget-a  {
+  background-color: var(--mat-sys-surface);
+  color: var(--mat-sys-on-surface);    
+  font: var(--mat-sys-body-medium);
+}
+
+.widget-b {
+  background-color: var(--mat-sys-primary);
+  color: var(--mat-sys-on-primary);
+}
+```
+
+Taking it one step further, you can alternatively use the utility classes to achieve the same styles
+in the component template:
+
+```html
+<widget-a class="mat-bg-surface mat-font-body-medium"/>
+
+<widget-b class="mat-bg-primary"/>
+```