From bacd7472cf077c97f6745d07451340fbd378a4d7 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Fri, 5 Jan 2024 14:03:20 -0600
Subject: [PATCH 01/12] first pass on structure

---
 .../components/buttons/ContainedButtons.js    |  17 ---
 .../components/buttons/ContainedButtons.tsx   |  17 ---
 .../buttons/ContainedButtons.tsx.preview      |   7 -
 .../components/buttons/OutlinedButtons.js     |  17 ---
 .../components/buttons/OutlinedButtons.tsx    |  17 ---
 .../buttons/OutlinedButtons.tsx.preview       |   7 -
 .../components/buttons/TextButtons.js         |  13 --
 .../components/buttons/TextButtons.tsx        |  13 --
 .../buttons/TextButtons.tsx.preview           |   3 -
 .../material/components/buttons/buttons.md    | 141 +++++++-----------
 10 files changed, 55 insertions(+), 197 deletions(-)
 delete mode 100644 docs/data/material/components/buttons/ContainedButtons.js
 delete mode 100644 docs/data/material/components/buttons/ContainedButtons.tsx
 delete mode 100644 docs/data/material/components/buttons/ContainedButtons.tsx.preview
 delete mode 100644 docs/data/material/components/buttons/OutlinedButtons.js
 delete mode 100644 docs/data/material/components/buttons/OutlinedButtons.tsx
 delete mode 100644 docs/data/material/components/buttons/OutlinedButtons.tsx.preview
 delete mode 100644 docs/data/material/components/buttons/TextButtons.js
 delete mode 100644 docs/data/material/components/buttons/TextButtons.tsx
 delete mode 100644 docs/data/material/components/buttons/TextButtons.tsx.preview

diff --git a/docs/data/material/components/buttons/ContainedButtons.js b/docs/data/material/components/buttons/ContainedButtons.js
deleted file mode 100644
index f6ee5f5ed1d4fc..00000000000000
--- a/docs/data/material/components/buttons/ContainedButtons.js
+++ /dev/null
@@ -1,17 +0,0 @@
-import * as React from 'react';
-import Button from '@mui/material/Button';
-import Stack from '@mui/material/Stack';
-
-export default function ContainedButtons() {
-  return (
-    <Stack direction="row" spacing={2}>
-      <Button variant="contained">Contained</Button>
-      <Button variant="contained" disabled>
-        Disabled
-      </Button>
-      <Button variant="contained" href="#contained-buttons">
-        Link
-      </Button>
-    </Stack>
-  );
-}
diff --git a/docs/data/material/components/buttons/ContainedButtons.tsx b/docs/data/material/components/buttons/ContainedButtons.tsx
deleted file mode 100644
index f6ee5f5ed1d4fc..00000000000000
--- a/docs/data/material/components/buttons/ContainedButtons.tsx
+++ /dev/null
@@ -1,17 +0,0 @@
-import * as React from 'react';
-import Button from '@mui/material/Button';
-import Stack from '@mui/material/Stack';
-
-export default function ContainedButtons() {
-  return (
-    <Stack direction="row" spacing={2}>
-      <Button variant="contained">Contained</Button>
-      <Button variant="contained" disabled>
-        Disabled
-      </Button>
-      <Button variant="contained" href="#contained-buttons">
-        Link
-      </Button>
-    </Stack>
-  );
-}
diff --git a/docs/data/material/components/buttons/ContainedButtons.tsx.preview b/docs/data/material/components/buttons/ContainedButtons.tsx.preview
deleted file mode 100644
index f8903cf5ff7471..00000000000000
--- a/docs/data/material/components/buttons/ContainedButtons.tsx.preview
+++ /dev/null
@@ -1,7 +0,0 @@
-<Button variant="contained">Contained</Button>
-<Button variant="contained" disabled>
-  Disabled
-</Button>
-<Button variant="contained" href="#contained-buttons">
-  Link
-</Button>
\ No newline at end of file
diff --git a/docs/data/material/components/buttons/OutlinedButtons.js b/docs/data/material/components/buttons/OutlinedButtons.js
deleted file mode 100644
index 4c322ddf9b543d..00000000000000
--- a/docs/data/material/components/buttons/OutlinedButtons.js
+++ /dev/null
@@ -1,17 +0,0 @@
-import * as React from 'react';
-import Button from '@mui/material/Button';
-import Stack from '@mui/material/Stack';
-
-export default function OutlinedButtons() {
-  return (
-    <Stack direction="row" spacing={2}>
-      <Button variant="outlined">Primary</Button>
-      <Button variant="outlined" disabled>
-        Disabled
-      </Button>
-      <Button variant="outlined" href="#outlined-buttons">
-        Link
-      </Button>
-    </Stack>
-  );
-}
diff --git a/docs/data/material/components/buttons/OutlinedButtons.tsx b/docs/data/material/components/buttons/OutlinedButtons.tsx
deleted file mode 100644
index 4c322ddf9b543d..00000000000000
--- a/docs/data/material/components/buttons/OutlinedButtons.tsx
+++ /dev/null
@@ -1,17 +0,0 @@
-import * as React from 'react';
-import Button from '@mui/material/Button';
-import Stack from '@mui/material/Stack';
-
-export default function OutlinedButtons() {
-  return (
-    <Stack direction="row" spacing={2}>
-      <Button variant="outlined">Primary</Button>
-      <Button variant="outlined" disabled>
-        Disabled
-      </Button>
-      <Button variant="outlined" href="#outlined-buttons">
-        Link
-      </Button>
-    </Stack>
-  );
-}
diff --git a/docs/data/material/components/buttons/OutlinedButtons.tsx.preview b/docs/data/material/components/buttons/OutlinedButtons.tsx.preview
deleted file mode 100644
index fa5532b2840b06..00000000000000
--- a/docs/data/material/components/buttons/OutlinedButtons.tsx.preview
+++ /dev/null
@@ -1,7 +0,0 @@
-<Button variant="outlined">Primary</Button>
-<Button variant="outlined" disabled>
-  Disabled
-</Button>
-<Button variant="outlined" href="#outlined-buttons">
-  Link
-</Button>
\ No newline at end of file
diff --git a/docs/data/material/components/buttons/TextButtons.js b/docs/data/material/components/buttons/TextButtons.js
deleted file mode 100644
index a1b001cdd59c01..00000000000000
--- a/docs/data/material/components/buttons/TextButtons.js
+++ /dev/null
@@ -1,13 +0,0 @@
-import * as React from 'react';
-import Button from '@mui/material/Button';
-import Stack from '@mui/material/Stack';
-
-export default function TextButtons() {
-  return (
-    <Stack direction="row" spacing={2}>
-      <Button>Primary</Button>
-      <Button disabled>Disabled</Button>
-      <Button href="#text-buttons">Link</Button>
-    </Stack>
-  );
-}
diff --git a/docs/data/material/components/buttons/TextButtons.tsx b/docs/data/material/components/buttons/TextButtons.tsx
deleted file mode 100644
index a1b001cdd59c01..00000000000000
--- a/docs/data/material/components/buttons/TextButtons.tsx
+++ /dev/null
@@ -1,13 +0,0 @@
-import * as React from 'react';
-import Button from '@mui/material/Button';
-import Stack from '@mui/material/Stack';
-
-export default function TextButtons() {
-  return (
-    <Stack direction="row" spacing={2}>
-      <Button>Primary</Button>
-      <Button disabled>Disabled</Button>
-      <Button href="#text-buttons">Link</Button>
-    </Stack>
-  );
-}
diff --git a/docs/data/material/components/buttons/TextButtons.tsx.preview b/docs/data/material/components/buttons/TextButtons.tsx.preview
deleted file mode 100644
index b21873401ea164..00000000000000
--- a/docs/data/material/components/buttons/TextButtons.tsx.preview
+++ /dev/null
@@ -1,3 +0,0 @@
-<Button>Primary</Button>
-<Button disabled>Disabled</Button>
-<Button href="#text-buttons">Link</Button>
\ No newline at end of file
diff --git a/docs/data/material/components/buttons/buttons.md b/docs/data/material/components/buttons/buttons.md
index a002edeca8563b..f19ba18af28d8d 100644
--- a/docs/data/material/components/buttons/buttons.md
+++ b/docs/data/material/components/buttons/buttons.md
@@ -10,56 +10,65 @@ unstyled: /base-ui/react-button/
 
 # Button
 
-<p class="description">Buttons allow users to take actions, and make choices, with a single tap.</p>
+<p class="description">Buttons enable users to take actions and make choices.</p>
 
-Buttons communicate actions that users can take. They are typically placed throughout your UI, in places like:
-
-- Modal windows
-- Forms
-- Cards
-- Toolbars
+Buttons communicate actions that users can take.
+The Material UI Button component replaces the native HTML `<button>` element and offers expanded options for styling and accessibility.
 
 {{"component": "modules/components/ComponentLinkHeader.js"}}
 
-## Basic button
+## Basics
+
+```jsx
+import Button from '@mui/material/Button';
+```
+
+### Variants
 
-The `Button` comes with three variants: text (default), contained, and outlined.
+The Button component supports three values for the `variant` prop: `text` (default), `contained`, and `outlined`.
 
 {{"demo": "BasicButtons.js"}}
 
-### Text button
+### Colors
 
-[Text buttons](https://m2.material.io/components/buttons#text-button)
-are typically used for less-pronounced actions, including those located: in dialogs, in cards.
-In cards, text buttons help maintain an emphasis on card content.
+{{"demo": "ColorButtons.js"}}
 
-{{"demo": "TextButtons.js"}}
+In addition to using the default button colors, you can add custom ones, or disable any you don't need. See the [Adding new colors](/material-ui/customization/palette/#custom-colors) examples for more info.
 
-### Contained button
+### Sizes
+
+The Button component comes in three sizes: `small`, `medium` (default), and `large`.
 
-[Contained buttons](https://m2.material.io/components/buttons#contained-button)
-are high-emphasis, distinguished by their use of elevation and fill.
-They contain actions that are primary to your app.
+{{"demo": "ButtonSizes.js"}}
 
-{{"demo": "ContainedButtons.js"}}
+### Elevation
 
 You can remove the elevation with the `disableElevation` prop.
 
 {{"demo": "DisableElevation.js"}}
 
-### Outlined button
+### Start and end icons
 
-[Outlined buttons](https://m2.material.io/components/buttons#outlined-button) are medium-emphasis buttons.
-They contain actions that are important but aren't the primary action in an app.
+Use the `startIcon` or `endIcon` prop to affix an icon to the beginning or end of a Button's contents.
 
-Outlined buttons are also a lower emphasis alternative to contained buttons,
-or a higher emphasis alternative to text buttons.
+{{"demo": "IconLabelButtons.js"}}
 
-{{"demo": "OutlinedButtons.js"}}
+### Icon Buttons
 
-## Handling clicks
+```jsx
+import IconButton from '@mui/material/IconButton';
+```
 
-All components accept an `onClick` handler that is applied to the root DOM element.
+Icon buttons are commonly found in app bars and toolbars.
+They're also useful for toggle buttons that give the user a single choice to be selected or deselected, such as adding or removing a star to an item.
+
+The Material UI Icon Button component accepts the same props and values as the Button for [sizes](#sizes) and [colors](#colors).
+
+{{"demo": "IconButtons.js"}}
+
+### Handling clicks
+
+Material UI Buttons accept an `onClick` handler that's applied to the root DOM element.
 
 ```jsx
 <Button
@@ -71,80 +80,36 @@ All components accept an `onClick` handler that is applied to the root DOM eleme
 </Button>
 ```
 
-Note that the documentation [avoids](/material-ui/guides/api/#native-properties) mentioning native props (there are a lot) in the API section of the components.
-
-## Color
-
-{{"demo": "ColorButtons.js"}}
-
-In addition to using the default button colors, you can add custom ones, or disable any you don't need. See the [Adding new colors](/material-ui/customization/palette/#custom-colors) examples for more info.
-
-## Sizes
-
-For larger or smaller buttons, use the `size` prop.
-
-{{"demo": "ButtonSizes.js"}}
-
-## Buttons with icons and label
-
-Sometimes you might want to have icons for certain buttons to enhance the UX of the application as we recognize logos more easily than plain text. For example, if you have a delete button you can label it with a dustbin icon.
-
-{{"demo": "IconLabelButtons.js"}}
-
-## Icon button
-
-Icon buttons are commonly found in app bars and toolbars.
-
-Icons are also appropriate for toggle buttons that allow a single choice to be selected or
-deselected, such as adding or removing a star to an item.
-
-{{"demo": "IconButtons.js"}}
-
-### Sizes
-
-For larger or smaller icon buttons, use the `size` prop.
-
-{{"demo": "IconButtonSizes.js"}}
-
-### Colors
-
-Use `color` prop to apply theme color palette to component.
-
-{{"demo": "IconButtonColors.js"}}
+## Customization
 
-## File upload
+### File upload button
 
-To create a file upload button, turn the button into a label using `component="label"` and then create a visually-hidden input with type `file`.
+To create a file upload button, turn the Button into a label using `component="label"` and then create a visually-hidden input with type `file`.
 
 {{"demo": "InputFileUpload.js"}}
 
-## Customization
-
-Here are some examples of customizing the component.
-You can learn more about this in the [overrides documentation page](/material-ui/customization/how-to-customize/).
+### Button Base
 
-{{"demo": "CustomizedButtons.js", "defaultCodeOpen": false}}
-
-🎨 If you are looking for inspiration, you can check [MUI Treasury's customization examples](https://mui-treasury.com/styles/button/).
-
-## Complex button
+```jsx
+import ButtonBase from '@mui/material/ButtonBase';
+```
 
-The Text Buttons, Contained Buttons, Floating Action Buttons and Icon Buttons are built on top of the same component: the `ButtonBase`.
-You can take advantage of this lower-level component to build custom interactions.
+Material UI's Buttons are all built on top of the Button Base component.
+You can take advantage of this lower-level component to create custom interactions, as shown in the demo below.
 
 {{"demo": "ButtonBaseDemo.js"}}
 
-## Third-party routing library
+#### Routing
 
 One frequent use case is to perform navigation on the client only, without an HTTP round-trip to the server.
-The `ButtonBase` component provides the `component` prop to handle this use case.
+The Button Base component provides the `component` prop to handle this use case.
 Here is a [more detailed guide](/material-ui/guides/routing/#button).
 
-## Limitations
+#### Limitations
 
-### Cursor not-allowed
+##### Cursor not-allowed
 
-The ButtonBase component sets `pointer-events: none;` on disabled buttons, which prevents the appearance of a disabled cursor.
+The Button Base component sets `pointer-events: none;` on disabled buttons, which prevents the appearance of a disabled cursor.
 
 If you wish to use `not-allowed`, you have two options:
 
@@ -178,7 +143,11 @@ This has the advantage of supporting any element, for instance, a link `<a>` ele
 
 ### Loading button
 
-[`@mui/lab`](/material-ui/about-the-lab/) offers loading buttons that can show loading state and disable interactions.
+```jsx
+import LoadingButton from '@mui/lab/LoadingButton';
+```
+
+The [`@mui/lab`](/material-ui/about-the-lab/) package offers a Loading Button component, which displays a loading state and disables interactions.
 
 {{"demo": "LoadingButtons.js"}}
 

From a6e24c0551154c004f86af10bd0db27b79e22bd0 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Fri, 5 Jan 2024 14:49:17 -0600
Subject: [PATCH 02/12] docs:build

---
 .../material/components/buttons/buttons.md    | 24 ++++++++++++++-----
 1 file changed, 18 insertions(+), 6 deletions(-)

diff --git a/docs/data/material/components/buttons/buttons.md b/docs/data/material/components/buttons/buttons.md
index f19ba18af28d8d..d820613645ef2a 100644
--- a/docs/data/material/components/buttons/buttons.md
+++ b/docs/data/material/components/buttons/buttons.md
@@ -82,12 +82,6 @@ Material UI Buttons accept an `onClick` handler that's applied to the root DOM e
 
 ## Customization
 
-### File upload button
-
-To create a file upload button, turn the Button into a label using `component="label"` and then create a visually-hidden input with type `file`.
-
-{{"demo": "InputFileUpload.js"}}
-
 ### Button Base
 
 ```jsx
@@ -139,6 +133,14 @@ However:
 
 This has the advantage of supporting any element, for instance, a link `<a>` element.
 
+## Common examples
+
+### File upload button
+
+To create a file upload button, turn the Button into a label using `component="label"` and then create a visually-hidden input with type `file`.
+
+{{"demo": "InputFileUpload.js"}}
+
 ## Experimental APIs
 
 ### Loading button
@@ -180,3 +182,13 @@ import Button from '@mui/material-next/Button';
 {{"demo": "ButtonMaterialYouPlayground.js", "hideToolbar": true, "bg": "playground"}}
 
 For more instructions on how to use it, visit the [detailed guide](/material-ui/guides/material-3-components/).
+
+## Anatomy
+
+The Material UI Button is composed of a single root `<button>` element:
+
+```html
+<button class="MuiButton-root">
+  <!-- Button content here -->
+</button>
+```
\ No newline at end of file

From 5315fd4dc1da020916e6797d81d638d13d1f3085 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Fri, 5 Jan 2024 14:52:38 -0600
Subject: [PATCH 03/12] prettier

---
 docs/data/material/components/buttons/buttons.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/data/material/components/buttons/buttons.md b/docs/data/material/components/buttons/buttons.md
index d820613645ef2a..afbaff36f34a16 100644
--- a/docs/data/material/components/buttons/buttons.md
+++ b/docs/data/material/components/buttons/buttons.md
@@ -191,4 +191,4 @@ The Material UI Button is composed of a single root `<button>` element:
 <button class="MuiButton-root">
   <!-- Button content here -->
 </button>
-```
\ No newline at end of file
+```

From cf61e8855fa23406a9f3ee2de32ff2b6576a67c0 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Wed, 10 Jan 2024 12:12:48 -0600
Subject: [PATCH 04/12] second pass

---
 .../components/buttons/DisableElevation.js    |  2 +-
 .../components/buttons/DisableElevation.tsx   |  2 +-
 .../buttons/DisableElevation.tsx.preview      |  2 +-
 .../components/buttons/IntroButtons.js        | 18 ++++++++
 .../components/buttons/IntroButtons.tsx       | 18 ++++++++
 .../buttons/IntroButtons.tsx.preview          |  6 +++
 .../material/components/buttons/buttons.md    | 41 +++++++++++--------
 7 files changed, 70 insertions(+), 19 deletions(-)
 create mode 100644 docs/data/material/components/buttons/IntroButtons.js
 create mode 100644 docs/data/material/components/buttons/IntroButtons.tsx
 create mode 100644 docs/data/material/components/buttons/IntroButtons.tsx.preview

diff --git a/docs/data/material/components/buttons/DisableElevation.js b/docs/data/material/components/buttons/DisableElevation.js
index ba2f63127dab8d..e8326709da3ac5 100644
--- a/docs/data/material/components/buttons/DisableElevation.js
+++ b/docs/data/material/components/buttons/DisableElevation.js
@@ -4,7 +4,7 @@ import Button from '@mui/material/Button';
 export default function DisableElevation() {
   return (
     <Button variant="contained" disableElevation>
-      Disable elevation
+      Elevation disabled
     </Button>
   );
 }
diff --git a/docs/data/material/components/buttons/DisableElevation.tsx b/docs/data/material/components/buttons/DisableElevation.tsx
index ba2f63127dab8d..e8326709da3ac5 100644
--- a/docs/data/material/components/buttons/DisableElevation.tsx
+++ b/docs/data/material/components/buttons/DisableElevation.tsx
@@ -4,7 +4,7 @@ import Button from '@mui/material/Button';
 export default function DisableElevation() {
   return (
     <Button variant="contained" disableElevation>
-      Disable elevation
+      Elevation disabled
     </Button>
   );
 }
diff --git a/docs/data/material/components/buttons/DisableElevation.tsx.preview b/docs/data/material/components/buttons/DisableElevation.tsx.preview
index 4f12bf06dc4b44..5def93ce8cc808 100644
--- a/docs/data/material/components/buttons/DisableElevation.tsx.preview
+++ b/docs/data/material/components/buttons/DisableElevation.tsx.preview
@@ -1,3 +1,3 @@
 <Button variant="contained" disableElevation>
-  Disable elevation
+  Elevation disabled
 </Button>
\ No newline at end of file
diff --git a/docs/data/material/components/buttons/IntroButtons.js b/docs/data/material/components/buttons/IntroButtons.js
new file mode 100644
index 00000000000000..95629a0277b57c
--- /dev/null
+++ b/docs/data/material/components/buttons/IntroButtons.js
@@ -0,0 +1,18 @@
+import * as React from 'react';
+import Button from '@mui/material/Button';
+import DeleteIcon from '@mui/icons-material/Delete';
+import CheckIcon from '@mui/icons-material/Check';
+import Stack from '@mui/material/Stack';
+
+export default function IntroButtons() {
+  return (
+    <Stack direction="row" spacing={2}>
+      <Button variant="outlined" startIcon={<DeleteIcon />} color="error">
+        Cancel
+      </Button>
+      <Button variant="contained" startIcon={<CheckIcon />} color="success">
+        Confirm
+      </Button>
+    </Stack>
+  );
+}
diff --git a/docs/data/material/components/buttons/IntroButtons.tsx b/docs/data/material/components/buttons/IntroButtons.tsx
new file mode 100644
index 00000000000000..95629a0277b57c
--- /dev/null
+++ b/docs/data/material/components/buttons/IntroButtons.tsx
@@ -0,0 +1,18 @@
+import * as React from 'react';
+import Button from '@mui/material/Button';
+import DeleteIcon from '@mui/icons-material/Delete';
+import CheckIcon from '@mui/icons-material/Check';
+import Stack from '@mui/material/Stack';
+
+export default function IntroButtons() {
+  return (
+    <Stack direction="row" spacing={2}>
+      <Button variant="outlined" startIcon={<DeleteIcon />} color="error">
+        Cancel
+      </Button>
+      <Button variant="contained" startIcon={<CheckIcon />} color="success">
+        Confirm
+      </Button>
+    </Stack>
+  );
+}
diff --git a/docs/data/material/components/buttons/IntroButtons.tsx.preview b/docs/data/material/components/buttons/IntroButtons.tsx.preview
new file mode 100644
index 00000000000000..40f25da2ed6715
--- /dev/null
+++ b/docs/data/material/components/buttons/IntroButtons.tsx.preview
@@ -0,0 +1,6 @@
+<Button variant="outlined" startIcon={<DeleteIcon />} color="error">
+  Cancel
+</Button>
+<Button variant="contained" startIcon={<CheckIcon />} color="success">
+  Confirm
+</Button>
\ No newline at end of file
diff --git a/docs/data/material/components/buttons/buttons.md b/docs/data/material/components/buttons/buttons.md
index afbaff36f34a16..c813cf856b9825 100644
--- a/docs/data/material/components/buttons/buttons.md
+++ b/docs/data/material/components/buttons/buttons.md
@@ -12,10 +12,14 @@ unstyled: /base-ui/react-button/
 
 <p class="description">Buttons enable users to take actions and make choices.</p>
 
+{{"component": "modules/components/ComponentLinkHeader.js"}}
+
+## Introduction
+
 Buttons communicate actions that users can take.
 The Material UI Button component replaces the native HTML `<button>` element and offers expanded options for styling and accessibility.
 
-{{"component": "modules/components/ComponentLinkHeader.js"}}
+{{"demo": "IntroButtons.js"}}
 
 ## Basics
 
@@ -29,11 +33,22 @@ The Button component supports three values for the `variant` prop: `text` (defau
 
 {{"demo": "BasicButtons.js"}}
 
+#### Elevation
+
+Apply the `disableElevation` prop to remove the default drop shadow from the `contained` variant.
+
+{{"demo": "DisableElevation.js"}}
+
 ### Colors
 
+Every palette included in the theme is available via the `color` prop.
+
 {{"demo": "ColorButtons.js"}}
 
-In addition to using the default button colors, you can add custom ones, or disable any you don't need. See the [Adding new colors](/material-ui/customization/palette/#custom-colors) examples for more info.
+:::success
+If the default colors aren't sufficient, you can add custom colors and remove defaults that you don't need.
+See the [Palette—Custom colors](/material-ui/customization/palette/#custom-colors) doc for more info.
+:::
 
 ### Sizes
 
@@ -41,15 +56,9 @@ The Button component comes in three sizes: `small`, `medium` (default), and `lar
 
 {{"demo": "ButtonSizes.js"}}
 
-### Elevation
-
-You can remove the elevation with the `disableElevation` prop.
-
-{{"demo": "DisableElevation.js"}}
-
 ### Start and end icons
 
-Use the `startIcon` or `endIcon` prop to affix an icon to the beginning or end of a Button's contents.
+Use the `startIcon` or `endIcon` prop to append an icon to the beginning or end of a Button's contents.
 
 {{"demo": "IconLabelButtons.js"}}
 
@@ -97,7 +106,7 @@ You can take advantage of this lower-level component to create custom interactio
 
 One frequent use case is to perform navigation on the client only, without an HTTP round-trip to the server.
 The Button Base component provides the `component` prop to handle this use case.
-Here is a [more detailed guide](/material-ui/guides/routing/#button).
+For more information, see the [Routing—Button](/material-ui/guides/routing/#button) doc.
 
 #### Limitations
 
@@ -119,9 +128,9 @@ If you wish to use `not-allowed`, you have two options:
 However:
 
 - You should add `pointer-events: none;` back when you need to display [tooltips on disabled elements](/material-ui/react-tooltip/#disabled-elements).
-- The cursor won't change if you render something other than a button element, for instance, a link `<a>` element.
+- The cursor won't change if you render something other than a button element—for instance, a link `<a>` element.
 
-2. **DOM change**. You can wrap the button:
+2. **DOM change**. You can wrap the Button:
 
 ```jsx
 <span style={{ cursor: 'not-allowed' }}>
@@ -131,19 +140,19 @@ However:
 </span>
 ```
 
-This has the advantage of supporting any element, for instance, a link `<a>` element.
+This has the advantage of supporting any element—for instance, a link `<a>` element.
 
 ## Common examples
 
 ### File upload button
 
-To create a file upload button, turn the Button into a label using `component="label"` and then create a visually-hidden input with type `file`.
+To create a file upload button, turn the Button into a label using `component="label"` and then create a visually-hidden input with type `file`, as shown in the demo below:
 
 {{"demo": "InputFileUpload.js"}}
 
 ## Experimental APIs
 
-### Loading button
+### Loading Button
 
 ```jsx
 import LoadingButton from '@mui/lab/LoadingButton';
@@ -188,7 +197,7 @@ For more instructions on how to use it, visit the [detailed guide](/material-ui/
 The Material UI Button is composed of a single root `<button>` element:
 
 ```html
-<button class="MuiButton-root">
+<button class="MuiButtonBase-root MuiButton-root">
   <!-- Button content here -->
 </button>
 ```

From 20e3d1c889ba257cc6d4f7a4ea4eefc4b5c76d90 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Fri, 12 Jan 2024 11:22:12 -0600
Subject: [PATCH 05/12] remove CustomizedButtons demo

---
 .../components/buttons/CustomizedButtons.js   | 60 -------------------
 .../components/buttons/CustomizedButtons.tsx  | 60 -------------------
 .../buttons/CustomizedButtons.tsx.preview     |  4 --
 3 files changed, 124 deletions(-)
 delete mode 100644 docs/data/material/components/buttons/CustomizedButtons.js
 delete mode 100644 docs/data/material/components/buttons/CustomizedButtons.tsx
 delete mode 100644 docs/data/material/components/buttons/CustomizedButtons.tsx.preview

diff --git a/docs/data/material/components/buttons/CustomizedButtons.js b/docs/data/material/components/buttons/CustomizedButtons.js
deleted file mode 100644
index cf5616057f3e4e..00000000000000
--- a/docs/data/material/components/buttons/CustomizedButtons.js
+++ /dev/null
@@ -1,60 +0,0 @@
-import * as React from 'react';
-import { styled } from '@mui/material/styles';
-import Button from '@mui/material/Button';
-import Stack from '@mui/material/Stack';
-import { purple } from '@mui/material/colors';
-
-const BootstrapButton = styled(Button)({
-  boxShadow: 'none',
-  textTransform: 'none',
-  fontSize: 16,
-  padding: '6px 12px',
-  border: '1px solid',
-  lineHeight: 1.5,
-  backgroundColor: '#0063cc',
-  borderColor: '#0063cc',
-  fontFamily: [
-    '-apple-system',
-    'BlinkMacSystemFont',
-    '"Segoe UI"',
-    'Roboto',
-    '"Helvetica Neue"',
-    'Arial',
-    'sans-serif',
-    '"Apple Color Emoji"',
-    '"Segoe UI Emoji"',
-    '"Segoe UI Symbol"',
-  ].join(','),
-  '&:hover': {
-    backgroundColor: '#0069d9',
-    borderColor: '#0062cc',
-    boxShadow: 'none',
-  },
-  '&:active': {
-    boxShadow: 'none',
-    backgroundColor: '#0062cc',
-    borderColor: '#005cbf',
-  },
-  '&:focus': {
-    boxShadow: '0 0 0 0.2rem rgba(0,123,255,.5)',
-  },
-});
-
-const ColorButton = styled(Button)(({ theme }) => ({
-  color: theme.palette.getContrastText(purple[500]),
-  backgroundColor: purple[500],
-  '&:hover': {
-    backgroundColor: purple[700],
-  },
-}));
-
-export default function CustomizedButtons() {
-  return (
-    <Stack spacing={2} direction="row">
-      <ColorButton variant="contained">Custom CSS</ColorButton>
-      <BootstrapButton variant="contained" disableRipple>
-        Bootstrap
-      </BootstrapButton>
-    </Stack>
-  );
-}
diff --git a/docs/data/material/components/buttons/CustomizedButtons.tsx b/docs/data/material/components/buttons/CustomizedButtons.tsx
deleted file mode 100644
index 1be36f3f0ab3bb..00000000000000
--- a/docs/data/material/components/buttons/CustomizedButtons.tsx
+++ /dev/null
@@ -1,60 +0,0 @@
-import * as React from 'react';
-import { styled } from '@mui/material/styles';
-import Button, { ButtonProps } from '@mui/material/Button';
-import Stack from '@mui/material/Stack';
-import { purple } from '@mui/material/colors';
-
-const BootstrapButton = styled(Button)({
-  boxShadow: 'none',
-  textTransform: 'none',
-  fontSize: 16,
-  padding: '6px 12px',
-  border: '1px solid',
-  lineHeight: 1.5,
-  backgroundColor: '#0063cc',
-  borderColor: '#0063cc',
-  fontFamily: [
-    '-apple-system',
-    'BlinkMacSystemFont',
-    '"Segoe UI"',
-    'Roboto',
-    '"Helvetica Neue"',
-    'Arial',
-    'sans-serif',
-    '"Apple Color Emoji"',
-    '"Segoe UI Emoji"',
-    '"Segoe UI Symbol"',
-  ].join(','),
-  '&:hover': {
-    backgroundColor: '#0069d9',
-    borderColor: '#0062cc',
-    boxShadow: 'none',
-  },
-  '&:active': {
-    boxShadow: 'none',
-    backgroundColor: '#0062cc',
-    borderColor: '#005cbf',
-  },
-  '&:focus': {
-    boxShadow: '0 0 0 0.2rem rgba(0,123,255,.5)',
-  },
-});
-
-const ColorButton = styled(Button)<ButtonProps>(({ theme }) => ({
-  color: theme.palette.getContrastText(purple[500]),
-  backgroundColor: purple[500],
-  '&:hover': {
-    backgroundColor: purple[700],
-  },
-}));
-
-export default function CustomizedButtons() {
-  return (
-    <Stack spacing={2} direction="row">
-      <ColorButton variant="contained">Custom CSS</ColorButton>
-      <BootstrapButton variant="contained" disableRipple>
-        Bootstrap
-      </BootstrapButton>
-    </Stack>
-  );
-}
diff --git a/docs/data/material/components/buttons/CustomizedButtons.tsx.preview b/docs/data/material/components/buttons/CustomizedButtons.tsx.preview
deleted file mode 100644
index 5cf7e960f8c4eb..00000000000000
--- a/docs/data/material/components/buttons/CustomizedButtons.tsx.preview
+++ /dev/null
@@ -1,4 +0,0 @@
-<ColorButton variant="contained">Custom CSS</ColorButton>
-<BootstrapButton variant="contained" disableRipple>
-  Bootstrap
-</BootstrapButton>
\ No newline at end of file

From f3ea3dafa194a323b0bdded3f724e87be6ec9fe8 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Wed, 17 Jan 2024 15:55:37 -0600
Subject: [PATCH 06/12] restore button base header

---
 docs/data/material/components/buttons/buttons.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/data/material/components/buttons/buttons.md b/docs/data/material/components/buttons/buttons.md
index cf9a4342c559f5..462fab3e0c1fb0 100644
--- a/docs/data/material/components/buttons/buttons.md
+++ b/docs/data/material/components/buttons/buttons.md
@@ -91,6 +91,8 @@ Material UI Buttons accept an `onClick` handler that's applied to the root DOM e
 
 ## Customization
 
+### Button Base
+
 ```jsx
 import ButtonBase from '@mui/material/ButtonBase';
 ```

From 90d203a4bc2215eb96319b88deba3a4acfe59ef1 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Mon, 22 Jan 2024 07:55:35 -0600
Subject: [PATCH 07/12] anatomy

---
 .../material/components/buttons/buttons.md     | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/docs/data/material/components/buttons/buttons.md b/docs/data/material/components/buttons/buttons.md
index 462fab3e0c1fb0..e2f0d74ec58567 100644
--- a/docs/data/material/components/buttons/buttons.md
+++ b/docs/data/material/components/buttons/buttons.md
@@ -191,3 +191,21 @@ import Button from '@mui/material-next/Button';
 {{"demo": "ButtonMaterialYouPlayground.js", "hideToolbar": true, "bg": "playground"}}
 
 To learn more about Material UI's MD3 implementation, visit the [Material 3 Components documentation](/material-ui/guides/material-3-components/).
+
+## Anatomy
+
+The Material UI Button component is composed of a single root `<button>` element with a `<span>` nested inside that houses the touch ripple effect.
+Optional [start and end icons](#start-and-end-icons) are rendered inside of `<span>` elements.
+
+```html
+<button class="MuiButtonBase-root MuiButton-root">
+  <span class="MuiButton-startIcon">
+    <svg class="MuiSvgIcon-root"></svg>
+  </span>
+  <!-- Button contents here -->
+  <span class="MuiButton-endIcon">
+    <svg class="MuiSvgIcon-root"></svg>
+  </span>
+  <span class="MuiTouchRipple-root"></span>
+</button>
+```

From c485aa27a823f85361152c5ad31ce98da089e506 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Mon, 22 Jan 2024 08:18:21 -0600
Subject: [PATCH 08/12] links, ripple

---
 .../material/components/buttons/buttons.md    | 21 +++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/docs/data/material/components/buttons/buttons.md b/docs/data/material/components/buttons/buttons.md
index e2f0d74ec58567..c27cd5e4abba32 100644
--- a/docs/data/material/components/buttons/buttons.md
+++ b/docs/data/material/components/buttons/buttons.md
@@ -27,6 +27,18 @@ The Material UI Button component replaces the native HTML `<button>` element and
 import Button from '@mui/material/Button';
 ```
 
+### Links
+
+The Material UI Button accepts an `href` prop which automatically inserts an `<a>` element with the target link.
+
+```jsx
+<Button href="/home">Home</Button>
+
+// renders as
+
+<button><a href="/home">Home</a></button>
+```
+
 ### Variants
 
 The Button component supports three values for the `variant` prop: `text` (default), `contained`, and `outlined`.
@@ -62,6 +74,15 @@ Use the `startIcon` or `endIcon` prop to append an icon to the beginning or end
 
 {{"demo": "IconLabelButtons.js"}}
 
+### Ripple effect
+
+The Ripple effect provides visual feedback to the user that the Button is being clicked or focused.
+Use the `disableFocusRipple` prop to remove only the focus effect, or `disableRipple` to remove the Ripple entirely.
+
+Note that when `disableRipple` is applied, there are no default styles for the `:focus-visible` state, so you should use the `.Mui-focusVisible` class to define your own.
+
+{{"demo": "RippleButtons.js"}}
+
 ### Icon Buttons
 
 ```jsx

From 9c33cf930e4386678b2787787e5975715c912f0c Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Mon, 22 Jan 2024 08:20:06 -0600
Subject: [PATCH 09/12] full width

---
 docs/data/material/components/buttons/buttons.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/data/material/components/buttons/buttons.md b/docs/data/material/components/buttons/buttons.md
index c27cd5e4abba32..a9a4471dfa8707 100644
--- a/docs/data/material/components/buttons/buttons.md
+++ b/docs/data/material/components/buttons/buttons.md
@@ -68,6 +68,12 @@ The Button component comes in three sizes: `small`, `medium` (default), and `lar
 
 {{"demo": "ButtonSizes.js"}}
 
+### Width
+
+Use the `fullWidth` prop to stretch the Button to fill its container.
+
+{{"demo": "FullWidthButton.js"}}
+
 ### Start and end icons
 
 Use the `startIcon` or `endIcon` prop to append an icon to the beginning or end of a Button's contents.

From 83a1833e45ab61093485f931a5a249824586d86b Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Mon, 22 Jan 2024 08:23:21 -0600
Subject: [PATCH 10/12] disabled

---
 docs/data/material/components/buttons/buttons.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/docs/data/material/components/buttons/buttons.md b/docs/data/material/components/buttons/buttons.md
index a9a4471dfa8707..73bd1810243762 100644
--- a/docs/data/material/components/buttons/buttons.md
+++ b/docs/data/material/components/buttons/buttons.md
@@ -51,6 +51,12 @@ Apply the `disableElevation` prop to remove the default drop shadow from the `co
 
 {{"demo": "DisableElevation.js"}}
 
+#### Disabled
+
+Use the `disabled` prop to disable clicking on a Button.
+
+{{"demo": "DisabledButton.js"}}
+
 ### Colors
 
 Every palette included in the theme is available via the `color` prop.
@@ -68,7 +74,7 @@ The Button component comes in three sizes: `small`, `medium` (default), and `lar
 
 {{"demo": "ButtonSizes.js"}}
 
-### Width
+#### Width
 
 Use the `fullWidth` prop to stretch the Button to fill its container.
 

From 1d5bde02fd30489a6397800b238279bb7d8713b8 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Mon, 22 Jan 2024 10:57:49 -0600
Subject: [PATCH 11/12] demos

---
 .../components/buttons/DisableElevation.js    | 10 ++++---
 .../components/buttons/DisableElevation.tsx   | 10 ++++---
 .../buttons/DisableElevation.tsx.preview      |  1 +
 .../components/buttons/DisabledButton.js      | 14 ++++++++++
 .../components/buttons/DisabledButton.tsx     | 14 ++++++++++
 .../buttons/DisabledButton.tsx.preview        |  4 +++
 .../components/buttons/FullWidthButton.js     | 20 ++++++++++++++
 .../components/buttons/FullWidthButton.tsx    | 20 ++++++++++++++
 .../buttons/FullWidthButton.tsx.preview       |  3 +++
 .../components/buttons/IntroButtons.js        | 18 +++++++++++--
 .../components/buttons/IntroButtons.tsx       | 18 +++++++++++--
 .../buttons/IntroButtons.tsx.preview          |  6 -----
 .../components/buttons/RippleButtons.js       | 17 ++++++++++++
 .../components/buttons/RippleButtons.tsx      | 17 ++++++++++++
 .../buttons/RippleButtons.tsx.preview         |  7 +++++
 .../material/components/buttons/buttons.md    | 27 +++++++++++--------
 16 files changed, 179 insertions(+), 27 deletions(-)
 create mode 100644 docs/data/material/components/buttons/DisabledButton.js
 create mode 100644 docs/data/material/components/buttons/DisabledButton.tsx
 create mode 100644 docs/data/material/components/buttons/DisabledButton.tsx.preview
 create mode 100644 docs/data/material/components/buttons/FullWidthButton.js
 create mode 100644 docs/data/material/components/buttons/FullWidthButton.tsx
 create mode 100644 docs/data/material/components/buttons/FullWidthButton.tsx.preview
 delete mode 100644 docs/data/material/components/buttons/IntroButtons.tsx.preview
 create mode 100644 docs/data/material/components/buttons/RippleButtons.js
 create mode 100644 docs/data/material/components/buttons/RippleButtons.tsx
 create mode 100644 docs/data/material/components/buttons/RippleButtons.tsx.preview

diff --git a/docs/data/material/components/buttons/DisableElevation.js b/docs/data/material/components/buttons/DisableElevation.js
index e8326709da3ac5..d583f4b87da8d6 100644
--- a/docs/data/material/components/buttons/DisableElevation.js
+++ b/docs/data/material/components/buttons/DisableElevation.js
@@ -1,10 +1,14 @@
 import * as React from 'react';
+import Stack from '@mui/material/Stack';
 import Button from '@mui/material/Button';
 
 export default function DisableElevation() {
   return (
-    <Button variant="contained" disableElevation>
-      Elevation disabled
-    </Button>
+    <Stack spacing={2} direction="row">
+      <Button variant="contained">Default</Button>
+      <Button variant="contained" disableElevation>
+        Elevation disabled
+      </Button>
+    </Stack>
   );
 }
diff --git a/docs/data/material/components/buttons/DisableElevation.tsx b/docs/data/material/components/buttons/DisableElevation.tsx
index e8326709da3ac5..d583f4b87da8d6 100644
--- a/docs/data/material/components/buttons/DisableElevation.tsx
+++ b/docs/data/material/components/buttons/DisableElevation.tsx
@@ -1,10 +1,14 @@
 import * as React from 'react';
+import Stack from '@mui/material/Stack';
 import Button from '@mui/material/Button';
 
 export default function DisableElevation() {
   return (
-    <Button variant="contained" disableElevation>
-      Elevation disabled
-    </Button>
+    <Stack spacing={2} direction="row">
+      <Button variant="contained">Default</Button>
+      <Button variant="contained" disableElevation>
+        Elevation disabled
+      </Button>
+    </Stack>
   );
 }
diff --git a/docs/data/material/components/buttons/DisableElevation.tsx.preview b/docs/data/material/components/buttons/DisableElevation.tsx.preview
index 5def93ce8cc808..5c905a7864f2d6 100644
--- a/docs/data/material/components/buttons/DisableElevation.tsx.preview
+++ b/docs/data/material/components/buttons/DisableElevation.tsx.preview
@@ -1,3 +1,4 @@
+<Button variant="contained">Default</Button>
 <Button variant="contained" disableElevation>
   Elevation disabled
 </Button>
\ No newline at end of file
diff --git a/docs/data/material/components/buttons/DisabledButton.js b/docs/data/material/components/buttons/DisabledButton.js
new file mode 100644
index 00000000000000..6fe82a580e4502
--- /dev/null
+++ b/docs/data/material/components/buttons/DisabledButton.js
@@ -0,0 +1,14 @@
+import * as React from 'react';
+import Stack from '@mui/material/Stack';
+import Button from '@mui/material/Button';
+
+export default function DisabledButton() {
+  return (
+    <Stack spacing={2} direction="row">
+      <Button variant="outlined">Default</Button>
+      <Button variant="outlined" disabled>
+        Click disabled
+      </Button>
+    </Stack>
+  );
+}
diff --git a/docs/data/material/components/buttons/DisabledButton.tsx b/docs/data/material/components/buttons/DisabledButton.tsx
new file mode 100644
index 00000000000000..6fe82a580e4502
--- /dev/null
+++ b/docs/data/material/components/buttons/DisabledButton.tsx
@@ -0,0 +1,14 @@
+import * as React from 'react';
+import Stack from '@mui/material/Stack';
+import Button from '@mui/material/Button';
+
+export default function DisabledButton() {
+  return (
+    <Stack spacing={2} direction="row">
+      <Button variant="outlined">Default</Button>
+      <Button variant="outlined" disabled>
+        Click disabled
+      </Button>
+    </Stack>
+  );
+}
diff --git a/docs/data/material/components/buttons/DisabledButton.tsx.preview b/docs/data/material/components/buttons/DisabledButton.tsx.preview
new file mode 100644
index 00000000000000..de72d167ccbbc3
--- /dev/null
+++ b/docs/data/material/components/buttons/DisabledButton.tsx.preview
@@ -0,0 +1,4 @@
+<Button variant="outlined">Default</Button>
+<Button variant="outlined" disabled>
+  Click disabled
+</Button>
\ No newline at end of file
diff --git a/docs/data/material/components/buttons/FullWidthButton.js b/docs/data/material/components/buttons/FullWidthButton.js
new file mode 100644
index 00000000000000..1f084c93fb5a97
--- /dev/null
+++ b/docs/data/material/components/buttons/FullWidthButton.js
@@ -0,0 +1,20 @@
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import Button from '@mui/material/Button';
+
+export default function FullWidthButton() {
+  return (
+    <Box
+      sx={{
+        width: '300px',
+        border: '1px solid gray',
+        borderRadius: '5px',
+        padding: '5px',
+      }}
+    >
+      <Button variant="contained" fullWidth>
+        Full width button
+      </Button>
+    </Box>
+  );
+}
diff --git a/docs/data/material/components/buttons/FullWidthButton.tsx b/docs/data/material/components/buttons/FullWidthButton.tsx
new file mode 100644
index 00000000000000..1f084c93fb5a97
--- /dev/null
+++ b/docs/data/material/components/buttons/FullWidthButton.tsx
@@ -0,0 +1,20 @@
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import Button from '@mui/material/Button';
+
+export default function FullWidthButton() {
+  return (
+    <Box
+      sx={{
+        width: '300px',
+        border: '1px solid gray',
+        borderRadius: '5px',
+        padding: '5px',
+      }}
+    >
+      <Button variant="contained" fullWidth>
+        Full width button
+      </Button>
+    </Box>
+  );
+}
diff --git a/docs/data/material/components/buttons/FullWidthButton.tsx.preview b/docs/data/material/components/buttons/FullWidthButton.tsx.preview
new file mode 100644
index 00000000000000..84ffd56ae97157
--- /dev/null
+++ b/docs/data/material/components/buttons/FullWidthButton.tsx.preview
@@ -0,0 +1,3 @@
+<Button variant="contained" fullWidth>
+  Full width button
+</Button>
\ No newline at end of file
diff --git a/docs/data/material/components/buttons/IntroButtons.js b/docs/data/material/components/buttons/IntroButtons.js
index 95629a0277b57c..82116201e56d99 100644
--- a/docs/data/material/components/buttons/IntroButtons.js
+++ b/docs/data/material/components/buttons/IntroButtons.js
@@ -7,10 +7,24 @@ import Stack from '@mui/material/Stack';
 export default function IntroButtons() {
   return (
     <Stack direction="row" spacing={2}>
-      <Button variant="outlined" startIcon={<DeleteIcon />} color="error">
+      <Button disabled>Go back</Button>
+      <Button
+        variant="outlined"
+        startIcon={<DeleteIcon />}
+        color="error"
+        onClick={() => {
+          alert('Canceled.');
+        }}
+      >
         Cancel
       </Button>
-      <Button variant="contained" startIcon={<CheckIcon />} color="success">
+      <Button
+        variant="contained"
+        startIcon={<CheckIcon />}
+        onClick={() => {
+          alert('Confirmed.');
+        }}
+      >
         Confirm
       </Button>
     </Stack>
diff --git a/docs/data/material/components/buttons/IntroButtons.tsx b/docs/data/material/components/buttons/IntroButtons.tsx
index 95629a0277b57c..82116201e56d99 100644
--- a/docs/data/material/components/buttons/IntroButtons.tsx
+++ b/docs/data/material/components/buttons/IntroButtons.tsx
@@ -7,10 +7,24 @@ import Stack from '@mui/material/Stack';
 export default function IntroButtons() {
   return (
     <Stack direction="row" spacing={2}>
-      <Button variant="outlined" startIcon={<DeleteIcon />} color="error">
+      <Button disabled>Go back</Button>
+      <Button
+        variant="outlined"
+        startIcon={<DeleteIcon />}
+        color="error"
+        onClick={() => {
+          alert('Canceled.');
+        }}
+      >
         Cancel
       </Button>
-      <Button variant="contained" startIcon={<CheckIcon />} color="success">
+      <Button
+        variant="contained"
+        startIcon={<CheckIcon />}
+        onClick={() => {
+          alert('Confirmed.');
+        }}
+      >
         Confirm
       </Button>
     </Stack>
diff --git a/docs/data/material/components/buttons/IntroButtons.tsx.preview b/docs/data/material/components/buttons/IntroButtons.tsx.preview
deleted file mode 100644
index 40f25da2ed6715..00000000000000
--- a/docs/data/material/components/buttons/IntroButtons.tsx.preview
+++ /dev/null
@@ -1,6 +0,0 @@
-<Button variant="outlined" startIcon={<DeleteIcon />} color="error">
-  Cancel
-</Button>
-<Button variant="contained" startIcon={<CheckIcon />} color="success">
-  Confirm
-</Button>
\ No newline at end of file
diff --git a/docs/data/material/components/buttons/RippleButtons.js b/docs/data/material/components/buttons/RippleButtons.js
new file mode 100644
index 00000000000000..cf76532f322c28
--- /dev/null
+++ b/docs/data/material/components/buttons/RippleButtons.js
@@ -0,0 +1,17 @@
+import * as React from 'react';
+import Stack from '@mui/material/Stack';
+import Button from '@mui/material/Button';
+
+export default function RippleButtons() {
+  return (
+    <Stack spacing={2} direction="row">
+      <Button variant="contained">Default</Button>
+      <Button variant="outlined" disableFocusRipple>
+        Disable focus ripple
+      </Button>
+      <Button variant="outlined" disableRipple>
+        Disable ripple
+      </Button>
+    </Stack>
+  );
+}
diff --git a/docs/data/material/components/buttons/RippleButtons.tsx b/docs/data/material/components/buttons/RippleButtons.tsx
new file mode 100644
index 00000000000000..cf76532f322c28
--- /dev/null
+++ b/docs/data/material/components/buttons/RippleButtons.tsx
@@ -0,0 +1,17 @@
+import * as React from 'react';
+import Stack from '@mui/material/Stack';
+import Button from '@mui/material/Button';
+
+export default function RippleButtons() {
+  return (
+    <Stack spacing={2} direction="row">
+      <Button variant="contained">Default</Button>
+      <Button variant="outlined" disableFocusRipple>
+        Disable focus ripple
+      </Button>
+      <Button variant="outlined" disableRipple>
+        Disable ripple
+      </Button>
+    </Stack>
+  );
+}
diff --git a/docs/data/material/components/buttons/RippleButtons.tsx.preview b/docs/data/material/components/buttons/RippleButtons.tsx.preview
new file mode 100644
index 00000000000000..8b3af2aec91abc
--- /dev/null
+++ b/docs/data/material/components/buttons/RippleButtons.tsx.preview
@@ -0,0 +1,7 @@
+<Button variant="contained">Default</Button>
+<Button variant="outlined" disableFocusRipple>
+  Disable focus ripple
+</Button>
+<Button variant="outlined" disableRipple>
+  Disable ripple
+</Button>
\ No newline at end of file
diff --git a/docs/data/material/components/buttons/buttons.md b/docs/data/material/components/buttons/buttons.md
index 73bd1810243762..ab3f1d80e199de 100644
--- a/docs/data/material/components/buttons/buttons.md
+++ b/docs/data/material/components/buttons/buttons.md
@@ -29,14 +29,14 @@ import Button from '@mui/material/Button';
 
 ### Links
 
-The Material UI Button accepts an `href` prop which automatically inserts an `<a>` element with the target link.
+The Material UI Button accepts an `href` prop, which turns the HTML `<button>` element into an `<a>` with the target link.
 
 ```jsx
 <Button href="/home">Home</Button>
 
 // renders as
 
-<button><a href="/home">Home</a></button>
+<a href="/home">Home</a>
 ```
 
 ### Variants
@@ -51,12 +51,6 @@ Apply the `disableElevation` prop to remove the default drop shadow from the `co
 
 {{"demo": "DisableElevation.js"}}
 
-#### Disabled
-
-Use the `disabled` prop to disable clicking on a Button.
-
-{{"demo": "DisabledButton.js"}}
-
 ### Colors
 
 Every palette included in the theme is available via the `color` prop.
@@ -88,10 +82,15 @@ Use the `startIcon` or `endIcon` prop to append an icon to the beginning or end
 
 ### Ripple effect
 
-The Ripple effect provides visual feedback to the user that the Button is being clicked or focused.
-Use the `disableFocusRipple` prop to remove only the focus effect, or `disableRipple` to remove the Ripple entirely.
+The ripple effect provides visual feedback to the user that the Button is being clicked or focused.
+Use the `disableFocusRipple` prop to remove only the focus effect, or `disableRipple` to remove the ripple when focusing and clicking.
 
-Note that when `disableRipple` is applied, there are no default styles for the `:focus-visible` state, so you should use the `.Mui-focusVisible` class to define your own.
+:::warning
+These props remove _all_ default styles from the `:focus-visible` state, which means the user won't have any visual indication that the Button is focused.
+You can target the `.Mui-focusVisible` class to define your own styles for a better user experience.
+
+The demo below shows what happens if you don't define custom styles for the focus state.
+:::
 
 {{"demo": "RippleButtons.js"}}
 
@@ -122,6 +121,12 @@ Material UI Buttons accept an `onClick` handler that's applied to the root DOM e
 </Button>
 ```
 
+#### Disable
+
+Use the `disabled` prop to disable clicking on a Button.
+
+{{"demo": "DisabledButton.js"}}
+
 ## Customization
 
 ### Button Base

From 7a7303447994b9defa528573ebb63dcf576e9db5 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Wed, 14 Feb 2024 09:26:19 -0600
Subject: [PATCH 12/12] fix broken link

---
 docs/data/material/components/buttons/buttons.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/data/material/components/buttons/buttons.md b/docs/data/material/components/buttons/buttons.md
index 5129330b27b4b1..1927a71a74a2de 100644
--- a/docs/data/material/components/buttons/buttons.md
+++ b/docs/data/material/components/buttons/buttons.md
@@ -144,7 +144,7 @@ You can take advantage of this lower-level component to create custom interactio
 
 One frequent use case is to perform navigation on the client only, without an HTTP round-trip to the server.
 The Button Base component provides the `component` prop to handle this use case.
-For more information, see the [Routing—Button](/material-ui/guides/routing/#button) doc.
+For more information, see the [Routing—Button](/material-ui/integrations/routing/#button) doc.
 
 #### Limitations