[ButtonBase] Document how to use cursor not-allowed (#17778)

docs/src/pages/components/buttons/buttons.md

@@ -134,3 +134,36 @@ Given that many of the interactive components rely on `ButtonBase`, you should b
 able to take advantage of it everywhere.
 
 Here is an [integration example with react-router](/guides/composition/#button).
+
+## Limitations
+
+### Cursor not-allowed
+
+The ButtonBase 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:
+
+1. **CSS only**. You can remove the pointer events style on the disabled state of the `<button>` element:
+
+```css
+.MuiButtonBase-root:disabled {
+  cursor: not-allowed;
+  pointer-events: auto;
+}
+```
+
+However:
+
+- You should add `pointer-events: none;` back when you need to display [tooltips on disabled elements](/components/tooltips/#disabled-elements)
+- 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:
+
+```jsx
+<span style={{ cursor: "not-allowed" }}>
+  <Button component={Link} disabled>disabled</Button>
+</span>
+```
+
+This has the advantage of supporting any element, for instance, a link `<a>` element.

docs/src/pages/components/tooltips/tooltips.md

@@ -73,7 +73,7 @@ A tooltip can be interactive. It won't close when the user hovers over the toolt
 
 ## Disabled Elements
 
-By default disabled elements like `<button>` do not trigger user interactions so a `Tooltip` will not activate on normal events like hover. To accommodate disabled elements, add a simple wrapper element like a `span`.
+By default disabled elements like `<button>` do not trigger user interactions so a `Tooltip` will not activate on normal events like hover. To accommodate disabled elements, add a simple wrapper element, such as a `span`.
 
 {{"demo": "pages/components/tooltips/DisabledTooltips.js"}}
 

packages/material-ui/src/Tooltip/Tooltip.js

@@ -134,7 +134,7 @@ const Tooltip = React.forwardRef(function Tooltip(props, ref) {
             'A disabled element does not fire events.',
             "Tooltip needs to listen to the child element's events to display the title.",
             '',
-            'Place a `div` container on top of the element.',
+            'Add a simple wrapper element, such as a `span`.',
           ].join('\n'),
         );
       }