From efe092861fb8f93b8ac432968f5453a1cf423576 Mon Sep 17 00:00:00 2001
From: Adam Dierkens <adierkens@github.com>
Date: Mon, 6 Jul 2026 12:59:30 -0400
Subject: [PATCH 1/2] docs(Button): document built-in loading announcement

Document that Button and IconButton automatically render a visually
hidden polite live-region announcement (default "Loading") when the
`loading` prop is set, that the text is customizable via
`loadingAnnouncement`, and that consumers should not add their own
aria-live loading message to avoid duplicate announcements.

Closes #7881

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
---
 packages/react/src/Button/Button.docs.json       |  5 +++--
 .../react/src/Button/Button.features.stories.tsx | 16 ++++++++++++++++
 packages/react/src/Button/IconButton.docs.json   | 11 +++++++++++
 .../src/Button/IconButton.features.stories.tsx   |  8 ++++++++
 packages/react/src/Button/types.ts               |  9 +++++++--
 5 files changed, 45 insertions(+), 4 deletions(-)

diff --git a/packages/react/src/Button/Button.docs.json b/packages/react/src/Button/Button.docs.json
index 91707c4c7bd..91bd01ae378 100644
--- a/packages/react/src/Button/Button.docs.json
+++ b/packages/react/src/Button/Button.docs.json
@@ -135,12 +135,13 @@
     {
       "name": "loading",
       "type": "boolean",
-      "description": "When true, the button is in a loading state."
+      "description": "When true, the button is in a loading state. A spinner replaces the button's content and the button automatically announces its loading state to screen readers through a built-in, visually hidden live region. Do not add your own separate `aria-live` loading message for the button, as that would cause a duplicate announcement."
     },
     {
       "name": "loadingAnnouncement",
       "type": "string",
-      "description": "The content to announce to screen readers when loading. This requires `loading` prop to be true"
+      "defaultValue": "'Loading'",
+      "description": "The text announced to screen readers through the built-in, visually hidden live region when the button enters its loading state. Requires the `loading` prop to be true."
     },
     {
       "name": "ref",
diff --git a/packages/react/src/Button/Button.features.stories.tsx b/packages/react/src/Button/Button.features.stories.tsx
index 0b7d3da149b..cac3d8d733c 100644
--- a/packages/react/src/Button/Button.features.stories.tsx
+++ b/packages/react/src/Button/Button.features.stories.tsx
@@ -154,12 +154,28 @@ export const Medium = () => <Button size="medium">Default</Button>
 export const Large = () => <Button size="large">Default</Button>
 
 export const Loading = () => <Button loading>Default</Button>
+Loading.parameters = {
+  docs: {
+    description: {
+      story:
+        'When `loading` is set, the button automatically renders a visually hidden live region that announces "Loading" to screen readers. Because this announcement is built in, do not add your own separate `aria-live` loading message for the button — doing so would cause a duplicate announcement.',
+    },
+  },
+}
 
 export const LoadingCustomAnnouncement = () => (
   <Button loading loadingAnnouncement="This is a custom loading announcement">
     Default
   </Button>
 )
+LoadingCustomAnnouncement.parameters = {
+  docs: {
+    description: {
+      story:
+        'Use the `loadingAnnouncement` prop to customize the text announced to screen readers when the button enters its loading state. This replaces the default "Loading" announcement.',
+    },
+  },
+}
 
 export const LoadingWithLeadingVisual = () => (
   <Button loading leadingVisual={DownloadIcon}>
diff --git a/packages/react/src/Button/IconButton.docs.json b/packages/react/src/Button/IconButton.docs.json
index 4af4062608e..42994b65889 100644
--- a/packages/react/src/Button/IconButton.docs.json
+++ b/packages/react/src/Button/IconButton.docs.json
@@ -81,6 +81,17 @@
       "defaultValue": "",
       "description": "Changes the size of the icon button component"
     },
+    {
+      "name": "loading",
+      "type": "boolean",
+      "description": "When true, the button is in a loading state. A spinner replaces the icon and the button automatically announces its loading state to screen readers through a built-in, visually hidden live region. Do not add your own separate `aria-live` loading message for the button, as that would cause a duplicate announcement."
+    },
+    {
+      "name": "loadingAnnouncement",
+      "type": "string",
+      "defaultValue": "'Loading'",
+      "description": "The text announced to screen readers through the built-in, visually hidden live region when the button enters its loading state. Requires the `loading` prop to be true."
+    },
     {
       "name": "inactive",
       "type": "boolean",
diff --git a/packages/react/src/Button/IconButton.features.stories.tsx b/packages/react/src/Button/IconButton.features.stories.tsx
index 27147337b90..cdcf3199ccd 100644
--- a/packages/react/src/Button/IconButton.features.stories.tsx
+++ b/packages/react/src/Button/IconButton.features.stories.tsx
@@ -64,6 +64,14 @@ export const AsAMenuAnchor = () => (
 )
 
 export const Loading = () => <IconButton loading icon={HeartIcon} variant="primary" aria-label="Primary" />
+Loading.parameters = {
+  docs: {
+    description: {
+      story:
+        'When `loading` is set, the button automatically renders a visually hidden live region that announces "Loading" to screen readers. Customize this text with the `loadingAnnouncement` prop. Because the announcement is built in, do not add your own separate `aria-live` loading message for the button — doing so would cause a duplicate announcement.',
+    },
+  },
+}
 
 export const LoadingTrigger = () => {
   const [isLoading, setIsLoading] = useState(false)
diff --git a/packages/react/src/Button/types.ts b/packages/react/src/Button/types.ts
index acdd7190527..24da50bface 100644
--- a/packages/react/src/Button/types.ts
+++ b/packages/react/src/Button/types.ts
@@ -31,11 +31,16 @@ export type ButtonBaseProps = {
    */
   block?: boolean
   /**
-   * Specify whether the button is in a loading state
+   * Specify whether the button is in a loading state. While loading, a spinner replaces the
+   * button's content and the button automatically announces its loading state to screen readers
+   * through a visually hidden live region. Do not add a separate `aria-live` loading message for
+   * the button, as that would cause a duplicate announcement.
    */
   loading?: boolean
   /**
-   * The content to announce to screen readers when loading
+   * The text announced to screen readers through the built-in visually hidden live region when the
+   * button enters its loading state. Requires `loading` to be true.
+   * @default 'Loading'
    */
   loadingAnnouncement?: string
   /*

From e505760f93c7de13d6ecac0f70d7877edbc75f22 Mon Sep 17 00:00:00 2001
From: Adam Dierkens <adierkens@github.com>
Date: Mon, 6 Jul 2026 13:07:38 -0400
Subject: [PATCH 2/2] docs(Button): surface loading result-announcement
 examples

Address review feedback from the earlier attempt (#7882): the React
examples section, not just the props table, should reflect the loading
behavior. Reference the existing LoadingStatusAnnouncementSuccessful and
LoadingStatusAnnouncementError example stories from Button.docs.json and
add narrative describing how they complement the built-in loading
announcement (the button announces "Loading"; consumers announce the
result).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
---
 packages/react/src/Button/Button.docs.json       |  6 ++++++
 .../react/src/Button/Button.examples.stories.tsx | 16 ++++++++++++++++
 2 files changed, 22 insertions(+)

diff --git a/packages/react/src/Button/Button.docs.json b/packages/react/src/Button/Button.docs.json
index 91bd01ae378..907548e9f51 100644
--- a/packages/react/src/Button/Button.docs.json
+++ b/packages/react/src/Button/Button.docs.json
@@ -73,6 +73,12 @@
     {
       "id": "components-button-features--loading-trigger"
     },
+    {
+      "id": "components-button-examples--loading-status-announcement-successful"
+    },
+    {
+      "id": "components-button-examples--loading-status-announcement-error"
+    },
     {
       "id": "components-button-features--label-wrap"
     },
diff --git a/packages/react/src/Button/Button.examples.stories.tsx b/packages/react/src/Button/Button.examples.stories.tsx
index b3401ef6577..27506ef52ee 100644
--- a/packages/react/src/Button/Button.examples.stories.tsx
+++ b/packages/react/src/Button/Button.examples.stories.tsx
@@ -43,6 +43,14 @@ export const LoadingStatusAnnouncementSuccessful = () => {
     </>
   )
 }
+LoadingStatusAnnouncementSuccessful.parameters = {
+  docs: {
+    description: {
+      story:
+        'While `loading` is set, the button announces its loading state for you through its built-in live region, so you should not add a separate loading announcement. Announcing the *result* of the action is still your responsibility — here, a polite `AriaStatus` live region announces "Export completed" once the action resolves successfully.',
+    },
+  },
+}
 
 export const LoadingStatusAnnouncementError = () => {
   const [loading, setLoading] = React.useState(false)
@@ -81,3 +89,11 @@ export const LoadingStatusAnnouncementError = () => {
     </>
   )
 }
+LoadingStatusAnnouncementError.parameters = {
+  docs: {
+    description: {
+      story:
+        'The button handles the loading announcement for you, so you only need to announce the outcome. Here, an assertive `AriaAlert` surfaces an error `Banner` when the action fails.',
+    },
+  },
+}