[docs][base-ui] Structure and style revisions for Component docs (#38826

)

Signed-off-by: Sam Sycamore <[email protected]>
Co-authored-by: Marija Najdova <[email protected]>

docs/data/base/components/autocomplete/autocomplete.md

@@ -35,8 +35,6 @@ To learn more about implementing a custom Autocomplete, you can explore the [`us
 
 ## Hook
 
-### Usage
-
 ```jsx
 import { useAutocomplete } from '@mui/base/useAutocomplete';
 ```
@@ -104,7 +102,7 @@ Learn more about controlled and uncontrolled components in the [React documentat
 
 React Portals can be used to render the listbox outside of the DOM hierarchy, making it easier to allow it to "float" above adjacent elements.
 
-Base UI provides a [`<Popper />`](/base-ui/react-popper/) component built around React's `createPortal()` for exactly this purpose, and additionally helps you manage keyboard focus as it moves in and out of the portal.
+Base UI provides a [Popper](/base-ui/react-popper/) component built around React's `createPortal()` for exactly this purpose, and additionally helps you manage keyboard focus as it moves in and out of the portal.
 
 To render the listbox in Base UI's Popper, the `ref`s must be merged as follows:
 

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

@@ -25,32 +25,15 @@ The Badge component creates a badge that is applied to its child element.
 
 ## Component
 
-### Usage
-
-After [installation](/base-ui/getting-started/quickstart/#installation), you can start building with this component using the following basic elements:
-
 ```jsx
 import { Badge } from '@mui/base/Badge';
-
-export default function MyApp() {
-  return <Badge>{/* the element that the badge is attached to */}</Badge>;
-}
 ```
 
-### Basics
-
 The Badge 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
-<Badge>
-  <MailIcon />
-</Badge>
-```
 
 ### Anatomy
 
-The Badge 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:
+The Badge 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">
@@ -79,9 +62,10 @@ The following code snippet applies a CSS class called `my-badge` to the badge sl
 <Badge slotProps={{ badge: { className: 'my-badge' } }} />
 ```
 
-#### Usage with TypeScript
+### Usage with TypeScript
 
-In TypeScript, you can specify the custom component type used in the `slots.root` as a generic parameter of the unstyled component. This way, you can safely provide the custom root's props directly on the component:
+In TypeScript, you can specify the custom component type used in the `slots.root` as a generic parameter of the unstyled component.
+This way, you can safely provide the custom root's props directly on the component:
 
 ```tsx
 <Badge<typeof CustomComponent> slots={{ root: CustomComponent }} customProp />
@@ -99,10 +83,10 @@ The same applies for props specific to custom primitive elements:
 import { useBadge } from '@mui/base/useBadge';
 ```
 
-The `useBadge` hook lets you apply the functionality of a badge to a fully custom component.
+The `useBadge` hook lets you apply the functionality of a Badge 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).
+Hooks _do not_ support [slot props](#custom-structure), but they do support [customization props](#customization).
 
 :::info
 Hooks give you the most room for customization, but require more work to implement.
@@ -120,27 +104,27 @@ 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.
+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.
 
-The following demo shows how to create and style a typical numerical badge that's attached to a generic box element:
+The following demo shows how to create and style a typical numerical Badge that's attached to a generic box element:
 
 {{"demo": "UnstyledBadge", "defaultCodeOpen": false}}
 
 ### Badge visibility
 
-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:
+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
 
-By default, badges automatically hide when `badgeContent={0}`.
+By default, Badges automatically hide when `badgeContent={0}`.
 You can override this behavior with the `showZero` prop:
 
 {{"demo": "ShowZeroBadge.js"}}
@@ -154,7 +138,7 @@ The default is 99.
 
 ## Accessibility
 
-Screen readers may not provide users with enough information about a badge's contents.
+Screen readers may not provide users with enough information about a Badge's contents.
 To make your badge accessible, you must provide a full description with `aria-label`, as shown in the demo below:
 
 {{"demo": "AccessibleBadges.js"}}

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

@@ -23,20 +23,10 @@ The Button component replaces the native HTML `<button>` element, and offers exp
 
 ## Component
 
-### Usage
-
-After [installation](/base-ui/getting-started/quickstart/#installation), you can start building with this component using the following basic elements:
-
 ```jsx
 import { Button } from '@mui/base/Button';
-
-export default function MyApp() {
-  return <Button>{/* button text */}</Button>;
-}
 ```
 
-### Basics
-
 The Button behaves similar 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.
@@ -78,7 +68,7 @@ If a Button is customized with a non-button element (for instance, `<Button slot
 Similarly, `<Button slots={{ root: "span" }} type="reset">` will not reset its parent form.
 :::
 
-#### Usage with TypeScript
+### Usage with TypeScript
 
 In TypeScript, you can specify the custom component type used in the `slots.root` as a generic parameter of the unstyled component. This way, you can safely provide the custom root's props directly on the component:
 
@@ -98,10 +88,10 @@ The same applies for props specific to custom primitive elements:
 import { useButton } from '@mui/base/useButton';
 ```
 
-The `useButton` hook lets you apply the functionality of a button to a fully custom component.
+The `useButton` hook lets you apply the functionality of a Button 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).
+Hooks _do not_ support [slot props](#custom-structure), but they do support [customization props](#customization).
 
 :::info
 Hooks give you the most room for customization, but require more work to implement.
@@ -110,7 +100,7 @@ With hooks, you can take full control over how your component is rendered, and d
 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](#anatomy).
 :::
 
-The following demo shows how to build the same buttons as those found in the [Basics](#basics) section above, but with the `useButton` hook:
+The following demo shows how to build the same buttons as those found in the [Component](#component) section above, but with the `useButton` hook:
 
 {{"demo": "UseButton.js", "defaultCodeOpen": true}}
 
@@ -131,7 +121,7 @@ For the sake of simplicity, demos and code snippets primarily feature components
 ### Custom elements
 
 The Button accepts a wide range of custom elements beyond HTML elements.
-You can even use SVGs, as the following demo illustrates:
+You can even use SVGs, as shown in the demo below:
 
 {{"demo": "UnstyledButtonCustom.js", "defaultCodeOpen": false}}
 
@@ -147,14 +137,14 @@ Similarly to the native HTML `<button>` element, the Button component can't rece
 This may reduce its accessibility, as screen readers won't be able to announce the existence and state of the button.
 
 The `focusableWhenDisabled` prop lets you change this behavior.
-When this prop is set, the underlying button does not set the `disabled` prop.
-Instead, `aria-disabled` is used, which makes the button focusable.
+When this prop is set, the underlying Button does not set the `disabled` prop.
+Instead, `aria-disabled` is used, which makes the Button focusable.
 
-This should be used whenever the disabled button needs to be read by screen readers.
+This should be used whenever the disabled Button needs to be read by screen readers.
 
 Base UI uses this prop internally in [menu items](/base-ui/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:
+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"}}
 

docs/data/base/components/click-away-listener/click-away-listener.md

@@ -24,25 +24,11 @@ Click-Away Listener also supports the [Portal](/base-ui/react-portal/) component
 
 ## Component
 
-### Usage
-
-After [installation](/base-ui/getting-started/quickstart/#installation), you can start building with this component using the following basic elements:
-
 ```jsx
 import { ClickAwayListener } from '@mui/base/ClickAwayListener';
-
-export default function MyApp() {
-  return (
-    <ClickAwayListener>
-      {/* the child listening for a click outside of its container */}
-    </ClickAwayListener>
-  );
-}
 ```
 
-### Basics
-
-The following demo shows how to hide a menu dropdown when users click anywhere else on the page:
+The demo below shows how to hide a menu dropdown when users click anywhere else on the page:
 
 {{"demo": "ClickAway.js"}}
 

docs/data/base/components/focus-trap/focus-trap.md

@@ -19,20 +19,10 @@ Focus Trap is a utility component that's useful when implementing an overlay suc
 
 ## Component
 
-### Usage
-
-After [installation](/base-ui/getting-started/quickstart/#installation), you can start building with this component using the following basic elements:
-
 ```jsx
 import { FocusTrap } from '@mui/base/FocusTrap';
-
-export default function MyApp() {
-  return <FocusTrap>{/* children where the focus will be trapped */}</FocusTrap>;
-}
 ```
 
-### Basics
-
 Focus Trap wraps around the UI elements that should hold the user's focus.
 For instance, if the focus needs to stay inside of an [Menu](/base-ui/react-menu/), then the component will be structured like this:
 
@@ -67,7 +57,7 @@ By default, clicks outside of the Focus Trap component are blocked.
 
 You can disable this behavior with the `disableEnforceFocus` prop.
 
-Compare the following demo with the demo from the [Basics](#basics) section—notice how that demo prevents you from clicking outside of it, while this one allows it:
+Compare the following demo with the demo from the [Component](#component) section—notice how that demo prevents you from clicking outside of it, while this one allows it:
 
 {{"demo": "DisableEnforceFocus.js"}}
 

docs/data/base/components/form-control/form-control.md

@@ -22,22 +22,10 @@ For instance, you may want to show an additional element asking the user to ente
 
 ## Component
 
-### Usage
-
-After [installation](/base-ui/getting-started/quickstart/#installation), you can start building with this component using the following basic elements:
-
 ```jsx
 import { FormControl } from '@mui/base/FormControl';
-
-export default function MyApp() {
-  return (
-    <FormControl>{/* <input> and/or other contents of the form */}</FormControl>
-  );
-}
 ```
 
-### Basics
-
 Form Control wraps around the elements of a form that need access to the state of an `<input>`.
 For instance, if the form's **Submit** button needs to change states after the user enters information, then the component will be structured like this:
 
@@ -53,9 +41,10 @@ Note that it also uses the `useFormControlContext` hook in order to pass props t
 
 {{"demo": "BasicFormControl"}}
 
-#### Usage with TypeScript
+### Usage with TypeScript
 
-In TypeScript, you can specify the custom component type used in the `slots.root` as a generic parameter of the unstyled component. This way, you can safely provide the custom root's props directly on the component:
+In TypeScript, you can specify the custom component type used in the `slots.root` as a generic parameter of the unstyled component.
+This way, you can safely provide the custom root's props directly on the component:
 
 ```tsx
 <FormControl<typeof CustomComponent> slots={{ root: CustomComponent }} customProp />
@@ -77,7 +66,7 @@ The `useFormControlContext` hook reads the context provided by Form Control.
 This hook lets you work with custom input components inside of the Form Control.
 You can also use it to read the form control's state and react to its changes in a custom component.
 
-Hooks _do not_ support [slot props](#slot-props), but they do support [customization props](#customization).
+Hooks _do not_ support [slot props](#custom-structure), but they do support [customization props](#customization).
 
 :::info
 Hooks give you the most room for customization, but require more work to implement.
@@ -113,9 +102,9 @@ For the sake of simplicity, demos and code snippets primarily feature components
 
 ### Accessing the form control state
 
-You can access the state of the form control by providing a function as a child of the Form Control.
+You can access the state of the Form Control by providing a function as a child.
 The state will be provided as a parameter to this function.
 
-The following demo shows how to access the state of the form control in an Input component nested inside of the Form Control:
+The following demo shows how to access the state of the Form Control in an Input component nested inside:
 
 {{"demo": "FormControlFunctionChild.js"}}

docs/data/base/components/input/input.md

@@ -24,20 +24,10 @@ It can also be transformed into a `<textarea>` as needed.
 
 ## Component
 
-### Usage
-
-After [installation](/base-ui/getting-started/quickstart/#installation), you can start building with this component using the following basic elements:
-
 ```jsx
 import { Input } from '@mui/base/Input';
-
-export default function MyApp() {
-  return <Input />;
-}
 ```
 
-### Basics
-
 Input behaves similarly to the native HTML `<input>`, except that it's nested inside of a root `<div>`—see [Anatomy](#anatomy) for details.
 
 The following demo shows how to create and style an input component, including `placeholder` text:
@@ -74,9 +64,10 @@ The following code snippet applies a CSS class called `my-input` to the input sl
 <Input slotProps={{ input: { className: 'my-input' } }} />
 ```
 
-#### Usage with TypeScript
+### Usage with TypeScript
 
-In TypeScript, you can specify the custom component type used in the `slots.root` as a generic parameter of the unstyled component. This way, you can safely provide the custom root's props directly on the component:
+In TypeScript, you can specify the custom component type used in the `slots.root` as a generic parameter of the unstyled component.
+This way, you can safely provide the custom root's props directly on the component:
 
 ```tsx
 <Input<typeof CustomComponent> slots={{ root: CustomComponent }} customProp />
@@ -94,10 +85,10 @@ The same applies for props specific to custom primitive elements:
 import { useInput } from '@mui/base/useInput';
 ```
 
-The `useInput` hook lets you apply the functionality of an input to a fully custom component.
+The `useInput` hook lets you apply the functionality of an Input 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).
+Hooks _do not_ support [slot props](#custom-structure), but they do support [customization props](#customization).
 
 :::info
 Hooks give you the most room for customization, but require more work to implement.
@@ -112,12 +103,17 @@ The demo below shows how to use the `useInput` hook to create a custom input com
 
 ## 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.
+:::
+
 ### Adornments
 
-You can use the `startAdornment` and `endAdornment` props to add a prefix, suffix, or an action to an input.
+You can use the `startAdornment` and `endAdornment` props to add a prefix, suffix, or an action to an Input.
 Common use cases of adornments include:
 
-- when an input receives a specific unit of measure (like weight or currency)
+- when an Input receives a specific unit of measure (like weight or currency)
 - when an icon button toggles hiding/showing a password
 
 The following demo shows examples of both of these use cases: