docs(material/badge): minor doc fixes (#29233)

(cherry picked from commit d15df24)

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

@@ -3,14 +3,14 @@
 <!-- #enddocregion mat-badge-overlap -->
 
 <!-- #docregion mat-badge-size -->
+  <div matBadge="1" matBadgeSize="small" class="demo-section">Text with small badge</div>
   <div matBadge="1" matBadgeSize="large" class="demo-section">Text with large badge</div>
 <!-- #enddocregion mat-badge-size -->
 
 <div class="demo-section">
   Button with a badge on the left
 <!-- #docregion mat-badge-position -->
-  <button mat-raised-button color="primary"
-      matBadge="8" matBadgePosition="before" matBadgeColor="accent">
+  <button mat-raised-button matBadge="8" matBadgePosition="before">
     Action
   </button>
 <!-- #enddocregion mat-badge-position -->
@@ -28,7 +28,7 @@
 <div class="demo-section">
   Icon with a badge
 <!-- #docregion mat-badge-color -->
-  <mat-icon matBadge="15" matBadgeColor="warn">home</mat-icon>
+  <mat-icon matBadge="15">home</mat-icon>
 <!-- #enddocregion mat-badge-color -->
     <!-- Include text description of the icon's meaning for screen-readers -->
     <span class="cdk-visually-hidden">

src/material/badge/badge.md

@@ -1,4 +1,4 @@
-Badges are small status descriptors for UI elements. A badge consists of a small circle, 
+Badges are small status descriptors for UI elements. A badge consists of a small circle,
 typically containing a number or other short set of characters, that appears in proximity to
 another object.
 
@@ -13,40 +13,35 @@ By default, the badge will be placed `above after`. The direction can be changed
 the attribute `matBadgePosition` follow by `above|below` and `before|after`.
 
 <!-- example({"example":"badge-overview",
-              "file":"badge-overview-example.html", 
+              "file":"badge-overview-example.html",
               "region":"mat-badge-position"}) -->
 
 The overlap of the badge in relation to its inner contents can also be defined
 using the `matBadgeOverlap` tag. Typically, you want the badge to overlap an icon and not
 a text phrase. By default it will overlap.
 
 <!-- example({"example":"badge-overview",
-              "file":"badge-overview-example.html", 
+              "file":"badge-overview-example.html",
               "region":"mat-badge-overlap"}) -->
 
 ### Badge sizing
 The badge has 3 sizes: `small`, `medium` and `large`. By default, the badge is set to `medium`.
+
+Badges that are `small` do not show the label text. This can be useful in contexts such as showing there are unread notifications but not needing to show the exact amount.
+
 You can change the size by adding `matBadgeSize` to the host element.
 
 <!-- example({"example":"badge-overview",
-              "file":"badge-overview-example.html", 
+              "file":"badge-overview-example.html",
               "region":"mat-badge-size"}) -->
 
 ### Badge visibility
 The badge visibility can be toggled programmatically by defining `matBadgeHidden`.
 
 <!-- example({"example":"badge-overview",
-              "file":"badge-overview-example.html", 
+              "file":"badge-overview-example.html",
               "region":"mat-badge-hide"}) -->
 
-### Theming
-Badges can be colored in terms of the current theme using the `matBadgeColor` property to set the
-background color to `primary`, `accent`, or `warn`.
-
-<!-- example({"example":"badge-overview",
-              "file":"badge-overview-example.html", 
-              "region":"mat-badge-color"}) -->
-
 ### Accessibility
 You must provide a meaningful description via `matBadgeDescription`. When attached to an interactive
 element, `MatBadge` applies this description to its host via `aria-describedby`. When attached to

src/material/badge/badge.ts

@@ -83,7 +83,10 @@ export class _MatBadgeStyleLoader {}
   standalone: true,
 })
 export class MatBadge implements OnInit, OnDestroy {
-  /** The color of the badge. Can be `primary`, `accent`, or `warn`. */
+  /**
+   * The color of the badge. Can be `primary`, `accent`, or `warn`.
+   * Not recommended in M3, for more information see https://material.angular.io/guide/material-2-theming#optional-add-backwards-compatibility-styles-for-color-variants.
+   */
   @Input('matBadgeColor')
   get color(): ThemePalette {
     return this._color;