docs(material/button): update button documentation and examples for M3 (#29252)

Author: amysorto

src/components-examples/material/button/button-overview/button-overview-example.html

@@ -2,9 +2,6 @@
   <div class="example-label">Basic</div>
   <div class="example-button-row">
     <button mat-button>Basic</button>
-    <button mat-button color="primary">Primary</button>
-    <button mat-button color="accent">Accent</button>
-    <button mat-button color="warn">Warn</button>
     <button mat-button disabled>Disabled</button>
     <a mat-button href="https://www.google.com/" target="_blank">Link</a>
   </div>
@@ -14,9 +11,6 @@
   <div class="example-label">Raised</div>
   <div class="example-button-row">
     <button mat-raised-button>Basic</button>
-    <button mat-raised-button color="primary">Primary</button>
-    <button mat-raised-button color="accent">Accent</button>
-    <button mat-raised-button color="warn">Warn</button>
     <button mat-raised-button disabled>Disabled</button>
     <a mat-raised-button href="https://www.google.com/" target="_blank">Link</a>
   </div>
@@ -26,9 +20,6 @@
   <div class="example-label">Stroked</div>
   <div class="example-button-row">
     <button mat-stroked-button>Basic</button>
-    <button mat-stroked-button color="primary">Primary</button>
-    <button mat-stroked-button color="accent">Accent</button>
-    <button mat-stroked-button color="warn">Warn</button>
     <button mat-stroked-button disabled>Disabled</button>
     <a mat-stroked-button href="https://www.google.com/" target="_blank">Link</a>
   </div>
@@ -38,9 +29,6 @@
   <div class="example-label">Flat</div>
   <div class="example-button-row">
     <button mat-flat-button>Basic</button>
-    <button mat-flat-button color="primary">Primary</button>
-    <button mat-flat-button color="accent">Accent</button>
-    <button mat-flat-button color="warn">Warn</button>
     <button mat-flat-button disabled>Disabled</button>
     <a mat-flat-button href="https://www.google.com/" target="_blank">Link</a>
   </div>
@@ -53,15 +41,6 @@
       <button mat-icon-button aria-label="Example icon button with a vertical three dot icon">
         <mat-icon>more_vert</mat-icon>
       </button>
-      <button mat-icon-button color="primary" aria-label="Example icon button with a home icon">
-        <mat-icon>home</mat-icon>
-      </button>
-      <button mat-icon-button color="accent" aria-label="Example icon button with a menu icon">
-        <mat-icon>menu</mat-icon>
-      </button>
-      <button mat-icon-button color="warn" aria-label="Example icon button with a heart icon">
-        <mat-icon>favorite</mat-icon>
-      </button>
       <button mat-icon-button disabled aria-label="Example icon button with a open in new tab icon">
         <mat-icon>open_in_new</mat-icon>
       </button>
@@ -74,20 +53,10 @@
   <div class="example-button-row">
     <div class="example-flex-container">
       <div class="example-button-container">
-        <button mat-fab color="primary" aria-label="Example icon button with a delete icon">
+        <button mat-fab aria-label="Example icon button with a delete icon">
           <mat-icon>delete</mat-icon>
         </button>
       </div>
-      <div class="example-button-container">
-        <button mat-fab color="accent" aria-label="Example icon button with a bookmark icon">
-          <mat-icon>bookmark</mat-icon>
-        </button>
-      </div>
-      <div class="example-button-container">
-        <button mat-fab color="warn" aria-label="Example icon button with a home icon">
-          <mat-icon>home</mat-icon>
-        </button>
-      </div>
       <div class="example-button-container">
         <button mat-fab disabled aria-label="Example icon button with a heart icon">
           <mat-icon>favorite</mat-icon>
@@ -102,25 +71,40 @@
   <div class="example-button-row">
     <div class="example-flex-container">
       <div class="example-button-container">
-        <button mat-mini-fab color="primary" aria-label="Example icon button with a menu icon">
+        <button mat-mini-fab aria-label="Example icon button with a menu icon">
           <mat-icon>menu</mat-icon>
         </button>
       </div>
       <div class="example-button-container">
-        <button mat-mini-fab color="accent" aria-label="Example icon button with a plus one icon">
-          <mat-icon>plus_one</mat-icon>
+        <button mat-mini-fab disabled aria-label="Example icon button with a home icon">
+          <mat-icon>home</mat-icon>
         </button>
       </div>
+    </div>
+  </div>
+</section>
+<section>
+  <div class="example-label">Extended Fab</div>
+  <div class="example-button-row">
+    <div class="example-flex-container">
       <div class="example-button-container">
-        <button mat-mini-fab color="warn" aria-label="Example icon button with a filter list icon">
-          <mat-icon>filter_list</mat-icon>
+        <button mat-fab extended>
+          <mat-icon>favorite</mat-icon>
+          Basic
         </button>
       </div>
       <div class="example-button-container">
-        <button mat-mini-fab disabled aria-label="Example icon button with a home icon">
-          <mat-icon>home</mat-icon>
+        <button mat-fab extended disabled>
+          <mat-icon>favorite</mat-icon>
+          Disabled
         </button>
       </div>
+      <div class="example-button-container">
+        <a mat-fab extended routerLink=".">
+          <mat-icon>favorite</mat-icon>
+          Link
+        </a>
+      </div>
     </div>
   </div>
 </section>

src/components-examples/material/button/button-types/button-types-example.css

@@ -1,4 +1,3 @@
 export {ButtonOverviewExample} from './button-overview/button-overview-example';
-export {ButtonTypesExample} from './button-types/button-types-example';
 export {ButtonDisabledInteractiveExample} from './button-disabled-interactive/button-disabled-interactive-example';
 export {ButtonHarnessExample} from './button-harness/button-harness-example';

src/components-examples/material/button/button-types/button-types-example.html

@@ -107,7 +107,13 @@ export class MatButtonBase implements AfterViewInit, OnDestroy {
     this._rippleLoader?.attachRipple(this._elementRef.nativeElement, v);
   }
 
-  /** Theme color palette of the button */
+  /**
+   * Theme color palette of the button. This API is supported in M2 themes
+   * only, it has no effect in M3 themes.
+   *
+   * For information on applying color variants in M3, see
+   * https://material.angular.io/guide/theming#using-component-color-variants
+   */
   @Input() color?: string | null;
 
   /** Whether the ripple effect is disabled or not. */

src/components-examples/material/button/button-types/button-types-example.ts

@@ -12,26 +12,15 @@ There are several button variants, each applied as an attribute:
 
 | Attribute            | Description                                                              |
 |----------------------|--------------------------------------------------------------------------|
-| `mat-button`         | Rectangular text button w/ no elevation                                  |
-| `mat-raised-button`  | Rectangular contained button w/ elevation                                |
-| `mat-flat-button`    | Rectangular contained button w/ no elevation                             |
-| `mat-stroked-button` | Rectangular outlined button w/ no elevation                              |
+| `mat-button`         | Rectangular text button w/ no elevation and rounded corners                                 |
+| `mat-raised-button`  | Rectangular contained button w/ elevation and rounded corners                               |
+| `mat-flat-button`    | Rectangular contained button w/ no elevation and rounded corners                            |
+| `mat-stroked-button` | Rectangular outlined button w/ no elevation and rounded corners                             |
 | `mat-icon-button`    | Circular button with a transparent background, meant to contain an icon  |
-| `mat-fab`            | Circular button w/ elevation, defaults to theme's accent color           |
+| `mat-fab`            | Square button w/ elevation and rounded corners, meant to contain an icon. Can be [extended](https://material.angular.io/components/button/overview#extended-fab-buttons) to a rectangle to also fit a label           |
 | `mat-mini-fab`       | Same as `mat-fab` but smaller                                            |
 
 
-### Theming
-Buttons can be colored in terms of the current theme using the `color` property to set the
-background color to `primary`, `accent`, or `warn`.
-
-### Capitalization
-According to the Material design spec button text has to be capitalized, however we have opted not
-to capitalize buttons automatically via `text-transform: uppercase`, because it can cause issues in
-certain locales. It is also worth noting that using ALL CAPS in the text itself causes issues for
-screen-readers, which will read the text character-by-character. We leave the decision of how to
-approach this to the consuming app.
-
 ### Extended fab buttons
 Traditional fab buttons are circular and only have space for a single icon. However, you can add the
 `extended` attribute to allow the fab to expand into a rounded rectangle shape with space for a text
@@ -64,6 +53,11 @@ default. A `<button>` element should be used for any interaction that _performs
 current page_. An `<a>` element should be used for any interaction that _navigates to another
 URL_. All standard accessibility best practices for buttons and anchors apply to `MatButton`.
 
+#### Capitalization
+Using ALL CAPS in the button text itself causes issues for screen-readers, which
+will read the text character-by-character. It can also cause issues for localization.
+We recommend not changing the default capitalization for the button text.
+
 #### Disabling anchors
 `MatAnchor` supports disabling an anchor in addition to the features provided by the native
 `<a>` element. When you disable an anchor, the component sets `aria-disabled="true"` and