[docs] Final polish on Base docs - formatting and style consistency

docs/data/base/components/badge/badge.md

@@ -1,43 +1,149 @@
 ---
 product: base
-title: Unstyled React Badge component
+title: Unstyled React Badge component and hook
 components: BadgeUnstyled
 githubLabel: 'component: badge'
 packageName: '@mui/base'
 ---
 
 # Unstyled badge
 
-<p class="description">The `BadgeUnstyled` component generates a small label that is attached to its children elements.</p>
+<p class="description">The BadgeUnstyled component generates a small label that is attached to its child element.</p>
 
-```js
+## Introduction
+
+A badge is a small descriptor for UI elements.
+It typically sits on or near an element and indicates the status of that element by displaying a number, icon, or other short set of characters.
+
+The `BadgeUnstyled` component creates a badge that is applied to its child element.
+
+{{"component": "modules/components/ComponentLinkHeader.js", "design": false}}
+
+## Component
+
+### Usage
+
+After [installation](/base/getting-started/installation/), you can start building with this component using the following basic elements:
+
+```jsx
 import BadgeUnstyled from '@mui/base/BadgeUnstyled';
+
+export default function MyApp() {
+  return (
+    <BadgeUnstyled>{/* the element that the badge is attached to */}</BadgeUnstyled>
+  );
+}
 ```
 
-{{"component": "modules/components/ComponentLinkHeader.js", "design": false}}
+### Basics
+
+`BadgeUnstyled` wraps around the UI element that it's attached to.
+For instance, if the badge indicates the number of emails in an inbox, then the component will be structured like this:
+
+```jsx
+<BadgeUnstyled>
+  <MailIcon />
+</BadgeUnstyled>
+```
+
+### Anatomy
+
+The `BadgeUnstyled` component is composed of a root `<span>` that houses the element that the badge is attached to, followed by a `<span>` slot to represent the badge itself:
+
+```html
+<span class="BaseBadge-root">
+  <!-- the element the badge is attached to is nested here -->
+  <span class="BaseBadge-badge">badge content</span>
+</span>
+```
+
+### Slot props
+
+:::info
+The following props are available on all non-utility Base components.
+See [Usage](/base/getting-started/usage/) for full details.
+:::
+
+Use the `component` prop to override the root slot with a custom element:
+
+```jsx
+<BadgeUnstyled component="div" />
+```
+
+Use the `components` prop to override any interior slots in addition to the root:
+
+```jsx
+<BadgeUnstyled components={{ Root: 'div', Badge: 'div' }} />
+```
+
+:::warning
+If the root element is customized with both the `component` and `components` props, then `component` will take precedence.
+:::
+
+Use the `componentsProps` prop to pass custom props to internal slots.
+The following code snippet applies a CSS class called `my-badge` to the badge slot:
+
+```jsx
+<BadgeUnstyled componentsProps={{ badge: { className: 'my-badge' } }} />
+```
+
+:::warning
+Note that `componentsProps` slot names are written in lowercase (`root`) while `components` slot names are capitalized (`Root`).
+:::
+
+## Hook
+
+```jsx
+import { useBadge } from '@mui/base/BadgeUnstyled';
+```
+
+The `useBadge` hook lets you apply the functionality of `BadgeUnstyled` to a fully custom component.
+It returns props to be placed on the custom component, along with fields representing the component's internal state.
+
+Hooks _do not_ support [slot props](#slot-props), but they do support [customization props](#customization).
+
+:::info
+Hooks give you the most room for customization, but require more work to implement.
+With hooks, you can take full control over how your component is rendered, and define all the custom props and CSS classes you need.
+
+You may not need to use hooks unless you find that you're limited by the customization options of their component counterparts—for instance, if your component requires significantly different [structure](#component-slots).
+:::
+
+## Customization
+
+:::info
+The following features can be used with both components and hooks.
+For the sake of simplicity, demos and code snippets primarily feature components.
+:::
+
+### Badge content
+
+The `badgeContent` prop defines the content that's displayed inside the badge.
+When this content is a number, there are additional props you can use for further customization—see the [Numerical badges section](#numerical-badges) below.
 
-## Basic usage
+The following demo shows how to create and style a typical numerical badge that's attached to a generic box element:
 
 {{"demo": "UnstyledBadge.js", "defaultCodeOpen": false}}
 
-## Badge visibility
+### Badge visibility
 
-You can control the visibility of a `BadgeUnstyled` by using the `invisible` prop.
-Setting a badge to `invisible` does not actually hide it—instead, this prop adds the `MuiBadge-invisible` class to the badge, which you can target with styles to hide however you prefer:
+You can control the visibility of a badge by using the `invisible` prop.
+Setting a badge to `invisible` does not actually hide it—instead, this prop adds the `BaseBadge-invisible` class to the badge, which you can target with styles to hide however you prefer:
 
 {{"demo": "BadgeVisibility.js"}}
 
-## Numerical badges
+### Numerical badges
 
 The following props are useful when `badgeContent` is a number.
 
-### The showZero prop
+#### The showZero prop
 
-By default, badges automatically hide when `badgeContent={0}`. You can override this behavior with the `showZero` prop:
+By default, badges automatically hide when `badgeContent={0}`.
+You can override this behavior with the `showZero` prop:
 
 {{"demo": "ShowZeroBadge.js"}}
 
-### The max prop
+#### The max prop
 
 You can use the `max` prop to set a maximum value for `badgeContent`.
 The default is 99.
@@ -47,6 +153,6 @@ The default is 99.
 ## Accessibility
 
 Screen readers may not provide users with enough information about a badge's contents.
-To make your `BadgeUnstyled` accessible, you must provide a full description with `aria-label`:
+To make your badge accessible, you must provide a full description with `aria-label`, as shown in the demo below:
 
-{{"demo": "AccessibleBadges.js", "defaultCodeOpen": false}}
+{{"demo": "AccessibleBadges.js"}}

docs/data/base/components/button/button.md

@@ -8,37 +8,131 @@ waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/button/
 
 # Unstyled button
 
-<p class="description">Buttons allow users to take actions and make choices with a single tap.</p>
+<p class="description">Buttons let users take actions and make choices with a single tap.</p>
 
-## Basic button
+## Introduction
 
-```js
+`ButtonUnstyled` replaces the native HTML `<button>` element.
+
+{{"component": "modules/components/ComponentLinkHeader.js", "design": false}}
+
+## Component
+
+### Usage
+
+After [installation](/base/getting-started/installation/), you can start building with this component using the following basic elements:
+
+```jsx
 import ButtonUnstyled from '@mui/base/ButtonUnstyled';
 
-<ButtonUnstyled>Button</ButtonUnstyled>;
+export default function MyApp() {
+  return <ButtonUnstyled>{/* button text */}</ButtonUnstyled>;
+}
 ```
 
+### Basics
+
+`ButtonUnstyled` behaves similarly to the native HTML `<button>`, so it wraps around the text that will be displayed on its surface.
+
+The following demo shows how to create and style two basic buttons.
+Notice that the second button cannot be clicked due to the `disabled` prop:
+
 {{"demo": "UnstyledButtonsSimple.js", "defaultCodeOpen": true}}
 
-## Customizing the root element
+### Anatomy
+
+The `ButtonUnstyled` component is composed of a root `<button>` slot with no interior slots:
+
+```html
+<button class="BaseButton-root">
+  <!-- button text goes here -->
+</button>
+```
 
-By default, the `ButtonUnstyled` component renders a native `button` HTML element.
-You can override this by setting the `component` or `components.Root` prop.
+### Slot props
+
+:::info
+The following props are available on all non-utility Base components.
+See [Usage](/base/getting-started/usage/) for full details.
+:::
+
+Use the `component` prop to override the root slot with a custom element:
+
+```jsx
+<ButtonUnstyled component="div" />
+```
 
 If you provide a non-interactive element such as a `<span>`, the `ButtonUnstyled` component will automatically add the necessary accessibility attributes.
 
+Use the `components` prop to override any interior slots in addition to the root:
+
+```jsx
+<ButtonUnstyled components={{ Root: 'div' }} />
+```
+
+:::warning
+If the root element is customized with both the `component` and `components` props, then `component` will take precedence.
+:::
+
+Use the `componentsProps` prop to pass custom props to internal slots.
+The following code snippet applies a CSS class called `my-button` to the root slot:
+
+```jsx
+<ButtonUnstyled componentsProps={{ root: { className: 'my-button' } }} />
+```
+
+:::warning
+Note that `componentsProps` slot names are written in lowercase (`root`) while `components` slot names are capitalized (`Root`).
+:::
+
 Compare the attributes on the `<span>` in this demo with the `ButtonUnstyled` from the previous demo:
 
 {{"demo": "UnstyledButtonsSpan.js"}}
 
-### Complex customization
+:::warning
+If a `ButtonUnstyled` is customized with a non-button element (i.e. `<ButtonUnstyled component="span" />`), it will not submit the form it's in when clicked.
+Similarly, `<ButtonUnstyled component="span" type="reset">` will not reset its parent form.
+:::
+
+## Hook
+
+```js
+import { useButton } from '@mui/base/ButtonUnstyled';
+```
+
+The `useButton` hook lets you apply the functionality of `ButtonUnstyled` to a fully custom component.
+It returns props to be placed on the custom component, along with fields representing the component's internal state.
+
+Hooks _do not_ support [slot props](#slot-props), but they do support [customization props](#customization).
+
+:::info
+Hooks give you the most room for customization, but require more work to implement.
+With hooks, you can take full control over how your component is rendered, and define all the custom props and CSS classes you need.
+
+You may not need to use hooks unless you find that you're limited by the customization options of their component counterparts—for instance, if your component requires significantly different [structure](#component-slots).
+:::
+
+The `useButton` hook requires the `ref` of the element it's used on.
+
+The following demo shows how to build the same buttons as those found in the [Basic usage section](#basic-usage), but with the `useButton` hook:
+
+{{"demo": "UseButton.js", "defaultCodeOpen": true}}
+
+## Customization
+
+:::info
+The following features can be used with both components and hooks.
+For the sake of simplicity, demos and code snippets primarily feature components.
+:::
+
+### Custom elements
 
 `ButtonUnstyled` accepts a wide range of custom elements beyond HTML elements.
 You can even use SVGs, as the following demo illustrates:
 
 {{"demo": "UnstyledButtonCustom.js", "defaultCodeOpen": false}}
 
-## Focus on disabled buttons
+### Focus on disabled buttons
 
 Similarly to the native HTML `<button>` element, the `ButtonUnstyled` component can't receive focus when it's disabled.
 This may reduce its accessibility, as screen readers won't be able to announce the existence and state of the button.
@@ -51,28 +145,11 @@ This should be used whenever the disabled button needs to be read by screen read
 
 MUI Base uses this prop internally in [menu items](/base/react-menu/), making it possible to use the keyboard to navigate to disabled items (in compliance with [ARIA guidelines](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#x6-7-focusability-of-disabled-controls)).
 
+The following demo shows how the `focusableWhenDisabled` prop works—use the <kbd class="key">Tab</kbd> key to navigate within this document to see that only the second button accepts the focus:
+
 {{"demo": "UnstyledButtonsDisabledFocus.js"}}
 
-The `focusWhenDisabled` prop works the same when the root slot is customized, except that the `aria-disabled` attribute is used no regardless of the prop's state.
+The `focusableWhenDisabled` prop works the same when the root slot is customized, except that the `aria-disabled` attribute is used no regardless of the prop's state.
 The ability to receive focus is controlled internally by the `tabindex` attribute.
 
 {{"demo": "UnstyledButtonsDisabledFocusCustom.js"}}
-
-## The useButton hook
-
-```js
-import { useButton } from '@mui/base/ButtonUnstyled';
-```
-
-The `useButton` hook lets you use the functionality of `ButtonUnstyled` in other components.
-It returns props to be placed on a custom button element, along with fields representing the internal state of the button.
-
-The `useButton` hook requires the `ref` of the element it's used on.
-Additionally, you need to provide the `component` prop (unless you intend to use the native HTML `<button>`).
-
-{{"demo": "UseButton.js", "defaultCodeOpen": true}}
-
-## Limitations
-
-If a `ButtonUnstyled` is customized with a non-button element (i.e. `<ButtonUnstyled component="span" />`), it will not submit the form it's in when clicked.
-Similarly, `<ButtonUnstyled component="span" type="reset">` will not reset its parent form.