From 4d09e34caeda4f1152d72d3937ecd9e536bf0d3b Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 13 Aug 2026 17:28:48 +0000
Subject: [PATCH 1/2] Initial plan


From 77f15521383aa8cff8ed3d220ccc8e90430cf379 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 13 Aug 2026 17:32:44 +0000
Subject: [PATCH 2/2] docs(react-badge): clarify brand-background demo in
 ColorAndAppearance story

Co-authored-by: Hotell <1223799+Hotell@users.noreply.github.com>
---
 .../Badge/BadgeColorVsAppearance.stories.tsx  | 44 ++++++++++++++-----
 1 file changed, 33 insertions(+), 11 deletions(-)

diff --git a/packages/react-components/react-badge/stories/src/Badge/BadgeColorVsAppearance.stories.tsx b/packages/react-components/react-badge/stories/src/Badge/BadgeColorVsAppearance.stories.tsx
index 146a637b8ca8b9..f4a71de31e1912 100644
--- a/packages/react-components/react-badge/stories/src/Badge/BadgeColorVsAppearance.stories.tsx
+++ b/packages/react-components/react-badge/stories/src/Badge/BadgeColorVsAppearance.stories.tsx
@@ -12,12 +12,23 @@ const useStyles = makeStyles({
   },
   badge: {
     display: 'flex',
+    alignItems: 'center',
     gap: tokens.spacingHorizontalS,
   },
   brand: {
     display: 'flex',
+    alignItems: 'center',
+    gap: tokens.spacingHorizontalS,
     backgroundColor: tokens.colorBrandBackground,
-    padding: tokens.spacingHorizontalXXS,
+    padding: `${tokens.spacingVerticalS} ${tokens.spacingHorizontalM}`,
+    borderRadius: tokens.borderRadiusMedium,
+  },
+  brandLabel: {
+    color: tokens.colorNeutralForegroundOnBrand,
+    fontFamily: tokens.fontFamilyBase,
+    fontSize: tokens.fontSizeBase200,
+    lineHeight: tokens.lineHeightBase200,
+    fontWeight: tokens.fontWeightSemibold,
   },
 });
 
@@ -36,20 +47,29 @@ const Badges = (props: BadgeProps) => {
     'warning',
   ];
 
+  const isSubtleOnBrandOnly = appearance === 'ghost' || appearance === 'outline';
+
   return (
     <div className={styles.badge}>
       {colors.map(color => {
-        const BadgeWrapper =
-          color === 'subtle' && (appearance === 'ghost' || appearance === 'outline')
-            ? ({ children }: { children: React.ReactNode }) => <div className={styles.brand}>{children}</div>
-            : React.Fragment;
+        // `ghost-subtle` and `outline-subtle` are only meant to be used on a branded background,
+        // so they are rendered within an explicit "brand surface" demo container instead of the
+        // ambient story background.
+        if (color === 'subtle' && isSubtleOnBrandOnly) {
+          return (
+            <div key={`${appearance}-${color}`} className={styles.brand}>
+              <span className={styles.brandLabel}>On brand background:</span>
+              <Badge appearance={appearance} color={color} icon={<PasteIcon />}>
+                999+
+              </Badge>
+            </div>
+          );
+        }
 
         return (
-          <BadgeWrapper key={`${appearance}-${color}`}>
-            <Badge appearance={appearance} color={color} icon={<PasteIcon />}>
-              999+
-            </Badge>
-          </BadgeWrapper>
+          <Badge key={`${appearance}-${color}`} appearance={appearance} color={color} icon={<PasteIcon />}>
+            999+
+          </Badge>
         );
       })}
     </div>
@@ -76,7 +96,9 @@ export const ColorAndAppearance = (): JSXElement => {
 ColorAndAppearance.parameters = {
   docs: {
     description: {
-      story: 'Note: `ghost-subtle` and `outline-subtle` are intended only for use on brand background.',
+      story:
+        '`ghost-subtle` and `outline-subtle` are intended only for use on a branded background — ' +
+        'the boxed "On brand background:" examples above demonstrate the intended usage context.',
     },
   },
 };