From b903ee37c2b5d7fd7f56210fc656a04674818402 Mon Sep 17 00:00:00 2001
From: Amy Sorto <8575252+amysorto@users.noreply.github.com>
Date: Wed, 12 Jun 2024 08:45:45 -0700
Subject: [PATCH] docs(material/badge): minor doc fixes (#29233)

(cherry picked from commit d15df24d3554b5c3d8e5e130f4af72b5862b9dd6)
---
 .../badge-overview-example.html               |  6 +++---
 src/material/badge/badge.md                   | 21 +++++++------------
 src/material/badge/badge.ts                   |  5 ++++-
 3 files changed, 15 insertions(+), 17 deletions(-)

diff --git a/src/components-examples/material/badge/badge-overview/badge-overview-example.html b/src/components-examples/material/badge/badge-overview/badge-overview-example.html
index aeea433e5618..eab17a82714a 100644
--- a/src/components-examples/material/badge/badge-overview/badge-overview-example.html
+++ b/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">
diff --git a/src/material/badge/badge.md b/src/material/badge/badge.md
index 9a636d75d053..c3263b2e94df 100644
--- a/src/material/badge/badge.md
+++ b/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,7 +13,7 @@ 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
@@ -21,32 +21,27 @@ using the `matBadgeOverlap` tag. Typically, you want the badge to overlap an ico
 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
diff --git a/src/material/badge/badge.ts b/src/material/badge/badge.ts
index 14f8a9daf616..4b8676981409 100644
--- a/src/material/badge/badge.ts
+++ b/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;