diff --git a/content/components/button.mdx b/content/components/button.mdx
index c5173d845..faca33de1 100644
--- a/content/components/button.mdx
+++ b/content/components/button.mdx
@@ -290,6 +290,31 @@ There are two recommended ways an inactive button should respond to user input:
+### Loading
+
+
+
+
+
+
+
+You may use a button loading state if we need to wait for a button's action to be completed. Refer to the accessibility section's [button loading state](#button-loading-state) guidance for more information.
+
+
+
+
+
## Best practices
### Primary and outline button usage
@@ -417,6 +442,35 @@ Labeling buttons properly lets users know what will happen when they activate th
Read more about [descriptive buttons](/guides/accessibility/descriptive-buttons).
+### Button loading state
+
+
+
+
+
+
+
+When implementing a "loading" button state, don't remove the button from the DOM or pass the `disabled` attribute. Doing so would make it impossible to tab to the button. If the button was just focused and activated, it would reset focus. Resetting focus would disrupt the keyboard navigation flow, and creates a confusing experience for assistive technologies such as screen readers.
+
+Once the button is activated (and is in a loading state), it get the attribute `aria-disabled="true"`.
+
+A separate, visually hidden element should be rendered outside of the `
+
+
+
+
+
+This message should be in an ARIA live region, using `aria-live="polite"`. The live region must be present on page load, but the message inside the live region should only be rendered while the button is in a loading state.
+
+If an error prevents process from being completed, focus should be brought to an `
` (or next relevant heading) of the error banner.
+
+
### Known accessibility issues (GitHub staff only)
diff --git a/content/ui-patterns/loading.mdx b/content/ui-patterns/loading.mdx
index f41d06f2c..6814c9bf5 100644
--- a/content/ui-patterns/loading.mdx
+++ b/content/ui-patterns/loading.mdx
@@ -369,7 +369,7 @@ If the process loads new content, move focus to first focusable element in the n
You may disable form controls after the user submits the form to avoid confusion over whether changes that were made during the submission process will be saved.
-However, the button that initiates the a loading process may not be semantically disabled.
+However, the button that initiates the a loading process may not be semantically disabled using `aria-disabled`. For more information about button loading states, see the [loading section](/components/button#loading) of the button component guidelines.
@@ -377,48 +377,17 @@ However, the button that initiates the a loading process may not be semantically
width="456"
loop
autoplay
- src="https://github.com/primer/design/assets/2313998/cc592284-08d9-4330-8f36-548f27615706"
+ src="https://github.com/primer/design/assets/2313998/b138567f-3ba8-49ab-9fa1-80a4fe30b034"
/>
-### Button loading state
-
-<>
-{/**/}
->
-
-
-
-
-
-
-
-When implementing a "loading" button state, don't remove the button from the DOM or pass the `disabled` attribute. Doing so would make it impossible to tab to the button. If the button was just focused and activated, it would reset focus. Resetting focus would disrupt the keyboard navigation flow, and creates a confusing experience for assistive technologies such as screen readers.
-
-Once the button is activated (and is in a loading state), it get the attribute `aria-disabled="true"`.
-
-A separate, visually hidden element should be rendered outside of the `
-
-
-
-
-This message should be in an ARIA live region, using `aria-live="polite"`. The live region must be present on page load, but the message inside the live region should only be rendered while the button is in a loading state.
-
-If an error prevents process from being completed, focus should be brought to an `
` (or next relevant heading) of the error banner.
-
### Motion considerations
Animated loading indicators help reassure the user that the system isn't frozen, and should not be disabled when for users that prefer reduced motion. However, the animation in loading indicators should be kept as subtle as possible. Large, flashy animations would be harmful to users with sensitivity to motion.
## Related links
-- [Graceful degradation](ui-patterns/degraded-experiences)
+- [Graceful degradation](/ui-patterns/degraded-experiences)
- [Patterns for saving](/ui-patterns/saving)
- [Spinner](/components/spinner)
- [ProgressBar](/components/progress-bar)