@utilitywarehouse/hearth-react 0.31.9 → 0.32.1

package/public/llms/components/list.md

@@ -1,8 +1,11 @@
 # List
 
-The `List` component is a flexible and customizable component for displaying a
-list of items. It supports various visual variants, color schemes, and
-additional features like helper text and links.
+Use List to display a list of items, with support for visual variants,
+colour schemes, a heading, and helper text. Use ListItem for simple text
+content, or as a container for more complex or interactive content such as
+ListItemContent, ListItemButton, or ListItemLink. `variant` and
+`colorScheme` must be used together — if either is left `undefined`, the
+list falls back to its default appearance.
 
 ```tsx
 <Box width="400px">
@@ -542,13 +545,13 @@ This component is based on the `ul` element and supports the following common pr
 | Prop               | Type                                    | Default     | Description                                                                                       |
 | ------------------ | --------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------- |
 | `heading`          | `string`                                | —           | Actual string to display as section header                                                        |
-| `headingElement`   | `"div" \| "h1" \| "h2" \| "h3" \| "h4"` | `h2`        |                                                                                                   |
+| `headingElement`   | `"div" \| "h1" \| "h2" \| "h3" \| "h4"` | `h2`        | The element type to render the heading as.                                                        |
 | `helperText`       | `string`                                | —           | Optional helper text to provide additional context or instructions.                               |
 | `trailingContent`  | `ReactNode`                             | —           | Optional trailing content element                                                                 |
 | `validationStatus` | `"invalid"`                             | —           | Indicates the validation state                                                                    |
 | `validationText`   | `string`                                | —           | Text to display when the `validationStatus` is set.                                               |
 | `direction`        | `Responsive<"row" \| "column">`         | —           | Responsive direction of the section header content. By default, the content is laid out in a row. |
-| `variant`          | `"emphasis" \| "subtle"`                | `undefined` | Sets the visual variant of the list.                                                              |
+| `variant`          | `"emphasis" \| "subtle"`                | `undefined` | Sets the visual variant of the list. Must be used together with `colorScheme`.                    |
 | `colorScheme`      | `"neutralStrong" \| "neutralSubtle"`    | —           | Sets the color scheme of the list.                                                                |
 | `as`               | `"ol" \| "ul"`                          | `ul`        | Shorthand for changing the default rendered element into a semantically appropriate alternative.  |
 | `paddingNone`      | `boolean`                               | —           | Remove the inline padding for better alignment with other elements.                               |
@@ -613,14 +616,14 @@ The `ListItemContent` component is used to render more advanced text content.
 
 This component is base on the `div` element.
 
-| Prop              | Type                | Default  | Description                                                         |
-| ----------------- | ------------------- | -------- | ------------------------------------------------------------------- |
-| `heading`         | `string`            | —        |                                                                     |
-| `helperText`      | `ReactNode`         | —        | Optional helper text to provide additional context or instructions. |
-| `leadingContent`  | `ReactNode`         | —        |                                                                     |
-| `trailingContent` | `ReactNode`         | —        |                                                                     |
-| `badge`           | `ReactNode`         | —        |                                                                     |
-| `badgePlacement`  | `"top" \| "bottom"` | `bottom` | Placement of the badge element                                      |
+| Prop              | Type                | Default  | Description                                                              |
+| ----------------- | ------------------- | -------- | ------------------------------------------------------------------------ |
+| `heading`         | `string`            | —        | The list item's main heading text.                                       |
+| `helperText`      | `ReactNode`         | —        | Optional helper text to provide additional context or instructions.      |
+| `leadingContent`  | `ReactNode`         | —        | Optional content rendered before the heading, such as an icon or avatar. |
+| `trailingContent` | `ReactNode`         | —        | Optional content rendered after the heading, such as an icon or chevron. |
+| `badge`           | `ReactNode`         | —        | Optional badge rendered alongside the heading.                           |
+| `badgePlacement`  | `"top" \| "bottom"` | `bottom` | Placement of the badge element                                           |
 
 ## ListItemButton
 

package/public/llms/components/menu.md

@@ -1,9 +1,11 @@
 # Menu
 
-Use the `Menu` component to present a short list of actions or options in
-response to a user’s interaction. Menus are ideal for actions like sorting,
-filtering, or providing additional options without navigating away from the
-current screen.
+Use Menu to present a short list of actions or options in response to a
+user's interaction, such as sorting, filtering, or additional options,
+without navigating away from the current screen. Compose the root Menu
+with MenuTrigger and MenuContent, which wraps any number of MenuItem
+components. Set `modal={false}` when multiple Menu components are used
+together, such as in a navigation bar.
 
 - [Usage](#usage)
 - [MenuTrigger](#menutrigger)
@@ -101,8 +103,8 @@ You must render either a `Button` or `IconButton` component as a child of the `M
 ### Detached trigger
 
 By default the `MenuTrigger` lives inside `Menu`. When the trigger needs to exist in a
-different part of the component tree — for example in a toolbar while the menu state is
-managed elsewhere — use `Menu.createHandle()` to connect them.
+different part of the component tree (for example in a toolbar while the menu state is
+managed elsewhere), use `Menu.createHandle()` to connect them.
 
 Create the handle once at module level (outside any component), then pass it to both
 `MenuTrigger` and `Menu` via the `handle` prop. `Menu` no longer needs a `MenuTrigger`
@@ -206,7 +208,7 @@ You can adjust the vertical and horizontal placement of the `MenuContent`.
 The `MenuItem` can be either `functional` or `destructive`, and can also contain icons.
 
 If a `MenuItem` is navigating to another page, use the `asChild` prop to render a
-semantic `<a>` element — all accessible attributes are merged onto the child.
+semantic `<a>` element: all accessible attributes are merged onto the child.
 
 ```tsx
 <MenuContent>
@@ -288,7 +290,7 @@ to manage focus movement among menu items.
 
 By default, `MenuContent` is removed from the DOM when the menu is closed, which
 means search engines may not index its content. If the menu items are important
-for SEO — for example, primary navigation links — use the `keepMounted` prop on
+for SEO (for example, primary navigation links), use the `keepMounted` prop on
 `MenuContent` to keep them in the DOM at all times.
 
 ```tsx
@@ -301,8 +303,8 @@ for SEO — for example, primary navigation links — use the `keepMounted` prop
 
 **`MenuItem` deprecations:**
 
-- `onSelect` is deprecated. Use `onClick` instead — it fires for both mouse and keyboard activation.
-- `textValue` is deprecated. Use `label` instead — it is used for accessibility and keyboard navigation.
+- `onSelect` is deprecated. Use `onClick` instead: it fires for both mouse and keyboard activation.
+- `textValue` is deprecated. Use `label` instead: it is used for accessibility and keyboard navigation.
 
 **`MenuContent` deprecation:**
 
@@ -362,8 +364,8 @@ run TypeScript to confirm no type errors remain.
 
 | Prop          | Type                                                          | Default | Description                                                                                                                     |
 | ------------- | ------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `style`       | `CSSProperties`                                               | —       |                                                                                                                                 |
-| `className`   | `string`                                                      | —       |                                                                                                                                 |
+| `style`       | `CSSProperties`                                               | —       | The style applied to the element                                                                                                |
+| `className`   | `string`                                                      | —       | CSS class applied to the element                                                                                                |
 | `disabled`    | `boolean`                                                     | `false` | Whether the component should ignore user interaction.                                                                           |
 | `children`    | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | —       | The content of the MenuTrigger. Should contain a single `Button` or `IconButton` that will be used as the trigger for the Menu. |
 | `closeDelay`  | `number`                                                      | `0`     | How long to wait before closing the menu that was opened on hover. Specified in milliseconds. Requires the `openOnHover` prop.  |
@@ -375,8 +377,8 @@ run TypeScript to confirm no type errors remain.
 
 | Prop          | Type                                                       | Default      | Description                                                                          |
 | ------------- | ---------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------ |
-| `className`   | `string`                                                   | —            |                                                                                      |
-| `style`       | `CSSProperties`                                            | —            |                                                                                      |
+| `className`   | `string`                                                   | —            | CSS class applied to the element                                                     |
+| `style`       | `CSSProperties`                                            | —            | The style applied to the element                                                     |
 | `placement`   | `"bottomLeft" \| "bottomRight" \| "topLeft" \| "topRight"` | `bottomLeft` | The placement of the menu relative to the trigger element. Defaults to 'bottomLeft'. |
 | `keepMounted` | `boolean`                                                  | `false`      | Whether the menu should be kept mounted in the DOM when closed. Defaults to false.   |
 | `forceMount`  | `true`                                                     | —            | @deprecated Use `keepMounted` instead. Will be removed in next major.                |
@@ -388,11 +390,11 @@ This component is based on the `div` element.
 | Prop           | Type                                                                     | Default      | Description                                                                                                                                    |
 | -------------- | ------------------------------------------------------------------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
 | `label`        | `string`                                                                 | —            | Overrides the text label to use when the item is matched during keyboard text navigation.                                                      |
-| `className`    | `string`                                                                 | —            |                                                                                                                                                |
+| `className`    | `string`                                                                 | —            | CSS class applied to the element                                                                                                               |
 | `id`           | `string`                                                                 | —            | @ignore                                                                                                                                        |
 | `onClick`      | `((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void)` | —            | The click handler for the menu item.                                                                                                           |
 | `disabled`     | `boolean`                                                                | `false`      | Whether the component should ignore user interaction.                                                                                          |
 | `closeOnClick` | `boolean`                                                                | `true`       | Whether to close the menu when the item is clicked.                                                                                            |
-| `colorScheme`  | `"functional" \| "destructive"`                                          | `functional` |                                                                                                                                                |
+| `colorScheme`  | `"functional" \| "destructive"`                                          | `functional` | Sets the visual colour scheme of the item. Use `destructive` for actions like delete.                                                          |
 | `asChild`      | `boolean`                                                                | —            | Change the default rendered element for the one passed as a child, merging their props and behaviour. Useful for rendering MenuItem as a link. |
 | `textValue`    | `string`                                                                 | —            | Deprecated override of the text label to use when the item is matched during keyboard text navigation. @deprecated Use `label` instead.        |

package/public/llms/components/modal.md

@@ -1,9 +1,11 @@
 # Modal
 
-A `Modal` overlays content to request a decision or inform users of important information. When
-users need to interact with the application without navigating to a new page or disrupting their
-workflow, a `Modal` creates a floating layer over the current page to gather feedback or display
-information.
+Use Modal to overlay content that requests a decision from the user or
+informs them of important information, without navigating to a new page.
+Modal must be wrapped in a ModalRoot, and is typically composed with
+ModalTrigger, ModalContent, ModalFooter, and ModalClose. Pass `heading` and
+`description` for standard content, or custom children alongside
+ModalFooter for more control over layout.
 
 - [Usage Guidelines](#usage-guidelines)
 - [Content](#content)
@@ -363,20 +365,20 @@ This component is based on Radix UI's Dialog primitive and supports the followin
 
 | Prop                   | Type                                                              | Default | Description                                                                                                                                                                               |
 | ---------------------- | ----------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `image`                | `ReactNode`                                                       | —       |                                                                                                                                                                                           |
+| `image`                | `ReactNode`                                                       | —       | An image, such as an SVG illustration, rendered at the top of the modal. The layout automatically adjusts to accommodate it.                                                              |
 | `container`            | `Element \| DocumentFragment \| null`                             | —       | Specify a container element to portal the content into.                                                                                                                                   |
 | `forceMount`           | `true`                                                            | —       | Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.                                                                     |
-| `heading`              | `string`                                                          | —       |                                                                                                                                                                                           |
+| `heading`              | `string`                                                          | —       | The heading shown in the modal's main content. Required unless `loading` is `true`. The heading shown in the modal's main content. Optional while `loading` is `true`.                    |
 | `onEscapeKeyDown`      | `((event: KeyboardEvent) => void)`                                | —       | Event handler called when the escape key is down. Can be prevented.                                                                                                                       |
 | `onPointerDownOutside` | `((event: PointerDownOutsideEvent) => void)`                      | —       | Event handler called when the a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented.                                                                          |
 | `onFocusOutside`       | `((event: FocusOutsideEvent) => void)`                            | —       | Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented.                                                                                            |
 | `onInteractOutside`    | `((event: PointerDownOutsideEvent \| FocusOutsideEvent) => void)` | —       | Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. |
 | `onOpenAutoFocus`      | `((event: Event) => void)`                                        | —       | Event handler called when auto-focusing on open. Can be prevented.                                                                                                                        |
 | `onCloseAutoFocus`     | `((event: Event) => void)`                                        | —       | Event handler called when auto-focusing on close. Can be prevented.                                                                                                                       |
-| `description`          | `string`                                                          | —       |                                                                                                                                                                                           |
-| `hideCloseButton`      | `boolean`                                                         | —       |                                                                                                                                                                                           |
-| `fullScreen`           | `boolean`                                                         | —       |                                                                                                                                                                                           |
+| `description`          | `string`                                                          | —       | Additional descriptive text shown below the heading.                                                                                                                                      |
+| `hideCloseButton`      | `boolean`                                                         | `false` | Hides the visible close icon button. Only use this when providing a visible alternative way to close the modal, such as a Cancel button.                                                  |
+| `fullScreen`           | `boolean`                                                         | `false` | Makes the modal take up the full screen on mobile, ensuring long content scrolls correctly.                                                                                               |
 | `loadingText`          | `string`                                                          | —       | @deprecated Please use loadingHeading and loadingDescription instead                                                                                                                      |
-| `loadingHeading`       | `string`                                                          | —       |                                                                                                                                                                                           |
-| `loadingDescription`   | `string`                                                          | —       |                                                                                                                                                                                           |
-| `loading`              | `boolean`                                                         | —       |                                                                                                                                                                                           |
+| `loadingHeading`       | `string`                                                          | —       | The heading shown while `loading` is `true`.                                                                                                                                              |
+| `loadingDescription`   | `string`                                                          | —       | The description shown while `loading` is `true`.                                                                                                                                          |
+| `loading`              | `boolean`                                                         | `false` | Whether the modal is in a loading state. When `true`, a loading heading (via `loadingHeading`) is required for accessibility purposes.                                                    |

package/public/llms/components/pagination.md

@@ -1,6 +1,11 @@
 # Pagination
 
-Use the `Pagination` component to help users navigate through multiple pages of content.
+Use Pagination to let users navigate through multiple pages of content, such
+as search results or a paginated table. It automatically condenses to a
+maximum of 7 visible page numbers (using ellipses) for large page counts.
+Render `as="nav"` when it acts as a standalone navigation landmark — in that
+case also provide an `id` for accessibility. Use the `condensed` prop for
+compact spaces where only a page count needs to be shown.
 
 ## Table of Contents
 

package/public/llms/components/password-input.md

@@ -1,6 +1,9 @@
 # PasswordInput
 
-`PasswordInput` is an interactive field that is used to securely collect users passwords.
+Use PasswordInput to securely collect a user's password, with a built-in
+control for toggling visibility of the entered value. It automatically
+resets to hidden when its parent form is submitted. For general text entry
+use TextInput instead, and for search input use SearchInput.
 
 ```tsx
 <PasswordInput {...args} />
@@ -72,15 +75,15 @@ This component is based on the `TextInput` component and supports the following
 
 - Margin
 
-| Prop               | Type                   | Default | Description                                                                 |
-| ------------------ | ---------------------- | ------- | --------------------------------------------------------------------------- |
-| `label`            | `string`               | —       | The label for the form field, describing its purpose.                       |
-| `defaultValue`     | `string \| number`     | —       | The initial value of the input when rendered.                               |
-| `value`            | `string \| number`     | —       | The controlled value of the input. Must be used with an `onChange` handler. |
-| `labelId`          | `string`               | —       |                                                                             |
-| `helperTextId`     | `string`               | —       |                                                                             |
-| `validationTextId` | `string`               | —       |                                                                             |
-| `labelVariant`     | `"body" \| "heading"`  | —       | Change the label variant                                                    |
-| `helperText`       | `string`               | —       | Optional helper text to provide additional context or instructions.         |
-| `validationText`   | `string`               | —       | Text to display when the `validationStatus` is set.                         |
-| `validationStatus` | `"valid" \| "invalid"` | —       | Indicates the validation status.                                            |
+| Prop               | Type                   | Default | Description                                                                                        |
+| ------------------ | ---------------------- | ------- | -------------------------------------------------------------------------------------------------- |
+| `label`            | `string`               | —       | The label for the form field, describing its purpose.                                              |
+| `defaultValue`     | `string \| number`     | —       | The initial value of the input when rendered.                                                      |
+| `value`            | `string \| number`     | —       | The controlled value of the input. Must be used with an `onChange` handler.                        |
+| `labelId`          | `string`               | —       | The `id` of the element rendering the field's label, for `aria-labelledby` association.            |
+| `helperTextId`     | `string`               | —       | The `id` of the element rendering the field's helper text, for `aria-describedby` association.     |
+| `validationTextId` | `string`               | —       | The `id` of the element rendering the field's validation text, for `aria-describedby` association. |
+| `labelVariant`     | `"body" \| "heading"`  | —       | Change the label variant                                                                           |
+| `helperText`       | `string`               | —       | Optional helper text to provide additional context or instructions.                                |
+| `validationText`   | `string`               | —       | Text to display when the `validationStatus` is set.                                                |
+| `validationStatus` | `"valid" \| "invalid"` | —       | Indicates the validation status.                                                                   |

package/public/llms/components/progress-bar.md

@@ -1,6 +1,10 @@
 # ProgressBar
 
-`ProgressBar` displays the progress of a task or process in a linear bar format, with support for different visual states.
+Use ProgressBar to show the progress of a task or process as a linear or
+circular bar. Use the `colorScheme` prop to indicate success or danger
+states, and always provide a `label` describing what is progressing (this
+can be visually hidden with `hideLabel`). For a multi-step process where
+each step is discrete, use ProgressStepper instead.
 
 ```tsx
 <Flex direction="column" gap="400" width="600px">
@@ -121,7 +125,7 @@ This component is based on the `div` element and supports the following common p
 | Prop              | Type                                 | Default     | Description                                                                           |
 | ----------------- | ------------------------------------ | ----------- | ------------------------------------------------------------------------------------- |
 | `label`           | `string`                             | —           | The required text label. Can be visually hidden with the `hideLabel` prop.            |
-| `variant`         | `"linear" \| "circular"`             | —           |                                                                                       |
+| `variant`         | `"linear" \| "circular"`             | `'linear'`  | Sets the visual style of the progress indicator.                                      |
 | `colorScheme`     | `"default" \| "success" \| "danger"` | `'default'` | Set the visual apearance.                                                             |
 | `size`            | `Responsive<"sm" \| "md">`           | `md`        | Sets the circular variant size. Does not affect the appearance of the linear variant. |
 | `value`           | `number`                             | —           | The current progress value.                                                           |

package/public/llms/components/progress-stepper.md

@@ -1,6 +1,11 @@
 # ProgressStepper
 
-Use the `ProgressStepper` component to show users their progress through a multi-step process.
+Use ProgressStepper to show a user's progress through a multi-step process,
+such as a checkout or application flow. Wrap ProgressStep, ProgressStepButton,
+or ProgressStepLink children depending on whether each step is static,
+triggers an action, or navigates — don't mix step types within the same
+stepper. Render `as="nav"` when the stepper represents site or app
+navigation. For a single continuous task's completion, use ProgressBar instead.
 
 - [Usage](#usage)
 - [Step states](#step-states)
@@ -108,10 +113,10 @@ This component is based on the `div` element and supports the following common p
 
 - Margin
 
-| Prop         | Type             | Default | Description                 |
-| ------------ | ---------------- | ------- | --------------------------- |
-| `hideLabels` | `boolean`        | `false` | Whether to hide step labels |
-| `as`         | `"div" \| "nav"` | —       |                             |
+| Prop         | Type             | Default | Description                                                                                      |
+| ------------ | ---------------- | ------- | ------------------------------------------------------------------------------------------------ |
+| `hideLabels` | `boolean`        | `false` | Whether to hide step labels                                                                      |
+| `as`         | `"div" \| "nav"` | `div`   | Shorthand for changing the default rendered element into a semantically appropriate alternative. |
 
 ### ProgressStep API
 

package/public/llms/components/radio-group.md

@@ -1,6 +1,10 @@
 # RadioGroup
 
-`RadioGroup` provides an accessible way to group and control a set of `Radio`, `RadioTile` or `RadioCard` components, allowing the user to select one option from a set. The `RadioGroup` is responsible for handling the value, helper text, validation status and text, as well as determining the presentation and selection of the items in the list. Follows the [WAI-ARIA Radio Group Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/) for radio groups not contained in a toolbar.
+Use RadioGroup to group a set of Radio, RadioTile, or RadioCard components
+so a user can select a single option from a set. It manages the shared
+value, label, helper text, and validation state for its children, and
+follows the WAI-ARIA Radio Group pattern for groups not contained in a
+toolbar. For multi-select options, use CheckboxGroup instead.
 
 ```tsx
 <Flex direction="column" gap="400">
@@ -401,7 +405,7 @@ This component is based on the `fieldset` element and supports the following com
 | --------------------- | -------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `label`               | `ReactNode`                                                          | —        | The label for the formfield group. This should contain the question being answered by the formfield group. If you don't include a label you need to ensure you use the `aria-label` or `aria-labelledby` prop to properly associate a label with the formfield group. |
 | `defaultValue`        | `string`                                                             | —        |                                                                                                                                                                                                                                                                       |
-| `asChild`             | `boolean`                                                            | —        |                                                                                                                                                                                                                                                                       |
+| `asChild`             | `boolean`                                                            | `false`  | Merges the component's props onto its immediate child instead of rendering its own DOM element, so the child determines the rendered tag.                                                                                                                             |
 | `name`                | `string`                                                             | —        |                                                                                                                                                                                                                                                                       |
 | `required`            | `boolean`                                                            | —        |                                                                                                                                                                                                                                                                       |
 | `disabled`            | `boolean`                                                            | —        |                                                                                                                                                                                                                                                                       |
@@ -410,10 +414,10 @@ This component is based on the `fieldset` element and supports the following com
 | `onValueChange`       | `((value: string) => void)`                                          | —        |                                                                                                                                                                                                                                                                       |
 | `labelVariant`        | `"body" \| "heading"`                                                | —        | Set the label variant                                                                                                                                                                                                                                                 |
 | `helperText`          | `ReactNode`                                                          | —        | Helper text for the formfield group. Provides a hint such as specific requirements for what to choose. When displayed, child components should not display their own `helperText`.                                                                                    |
-| `validationText`      | `ReactNode`                                                          | —        |                                                                                                                                                                                                                                                                       |
-| `validationStatus`    | `"valid" \| "invalid"`                                               | —        |                                                                                                                                                                                                                                                                       |
-| `validationPlacement` | `"top" \| "bottom"`                                                  | —        |                                                                                                                                                                                                                                                                       |
-| `direction`           | `Responsive<"row" \| "column" \| "row-reverse" \| "column-reverse">` | `column` |                                                                                                                                                                                                                                                                       |
+| `validationText`      | `ReactNode`                                                          | —        | Text to display when the `validationStatus` is set.                                                                                                                                                                                                                   |
+| `validationStatus`    | `"valid" \| "invalid"`                                               | —        | Indicates the validation status of the formfield group.                                                                                                                                                                                                               |
+| `validationPlacement` | `"top" \| "bottom"`                                                  | —        | Sets where the validation text is displayed relative to the group's children.                                                                                                                                                                                         |
+| `direction`           | `Responsive<"row" \| "column" \| "row-reverse" \| "column-reverse">` | `column` | The layout direction of the radio items within the group.                                                                                                                                                                                                             |
 | `contentWidth`        | `Responsive<string>`                                                 | —        | Set the container width of the RadioGroup children, independent to the width of the parent RadioGroup.                                                                                                                                                                |
 
 ### Radio API
@@ -427,10 +431,10 @@ This component is based on the `button` element and supports the following commo
 | `label`           | `ReactNode`               | —       | The label for the Radio. If not using please properly associate the Radio with a label using the `aria-label` or `aria-labelledby` props. |
 | `image`           | `ReactNode`               | —       | Optional image to show between the radio indicator and label.                                                                             |
 | `value`           | `string`                  | —       |                                                                                                                                           |
-| `asChild`         | `boolean`                 | —       |                                                                                                                                           |
+| `asChild`         | `boolean`                 | `false` | Merges the component's props onto its immediate child instead of rendering its own DOM element, so the child determines the rendered tag. |
 | `checked`         | `boolean`                 | —       |                                                                                                                                           |
 | `required`        | `boolean`                 | —       |                                                                                                                                           |
-| `labelFontWeight` | `"regular" \| "semibold"` | —       |                                                                                                                                           |
+| `labelFontWeight` | `"regular" \| "semibold"` | —       | Overrides the font weight of the label.                                                                                                   |
 | `helperText`      | `ReactNode`               | —       | Helper text for the Radio. Will not display if the radio group has `helperText` set.                                                      |
 
 ### RadioTile API
@@ -440,17 +444,17 @@ This component is based on the `button` element and supports the following commo
 - Margin
 - Flex item
 
-| Prop              | Type                      | Default | Description                                                                          |
-| ----------------- | ------------------------- | ------- | ------------------------------------------------------------------------------------ |
-| `label`           | `ReactNode`               | —       |                                                                                      |
-| `image`           | `ReactNode`               | —       | Optional image to show between the radio indicator and label.                        |
-| `value`           | `string`                  | —       |                                                                                      |
-| `asChild`         | `boolean`                 | —       |                                                                                      |
-| `checked`         | `boolean`                 | —       |                                                                                      |
-| `required`        | `boolean`                 | —       |                                                                                      |
-| `labelFontWeight` | `"regular" \| "semibold"` | —       |                                                                                      |
-| `helperText`      | `ReactNode`               | —       | Helper text for the Radio. Will not display if the radio group has `helperText` set. |
-| `badge`           | `ReactNode`               | —       |                                                                                      |
+| Prop              | Type                      | Default | Description                                                                                                                                       |
+| ----------------- | ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`           | `ReactNode`               | —       | The label for the RadioTile. If not using please properly associate the RadioTile with a label using the `aria-label` or `aria-labelledby` props. |
+| `image`           | `ReactNode`               | —       | Optional image to show between the radio indicator and label.                                                                                     |
+| `value`           | `string`                  | —       |                                                                                                                                                   |
+| `asChild`         | `boolean`                 | `false` | Merges the component's props onto its immediate child instead of rendering its own DOM element, so the child determines the rendered tag.         |
+| `checked`         | `boolean`                 | —       |                                                                                                                                                   |
+| `required`        | `boolean`                 | —       |                                                                                                                                                   |
+| `labelFontWeight` | `"regular" \| "semibold"` | —       | Overrides the font weight of the label.                                                                                                           |
+| `helperText`      | `ReactNode`               | —       | Helper text for the Radio. Will not display if the radio group has `helperText` set.                                                              |
+| `badge`           | `ReactNode`               | —       | Optional badge content, displayed below the label and helper text.                                                                                |
 
 ### RadioCard API
 
@@ -463,7 +467,7 @@ This component is based on the `button` element and supports the following commo
 | `label`           | `ReactNode`               | —       | The label for the Radio. If not using please properly associate the Radio with a label using the `aria-label` or `aria-labelledby` props. |
 | `image`           | `ReactNode`               | —       | Optional image to show between the radio indicator and label.                                                                             |
 | `value`           | `string`                  | —       |                                                                                                                                           |
-| `asChild`         | `boolean`                 | —       |                                                                                                                                           |
+| `asChild`         | `boolean`                 | `false` | Merges the component's props onto its immediate child instead of rendering its own DOM element, so the child determines the rendered tag. |
 | `checked`         | `boolean`                 | —       |                                                                                                                                           |
 | `required`        | `boolean`                 | —       |                                                                                                                                           |
-| `labelFontWeight` | `"regular" \| "semibold"` | —       |                                                                                                                                           |
+| `labelFontWeight` | `"regular" \| "semibold"` | —       | Overrides the font weight of the label.                                                                                                   |

package/public/llms/components/search-input.md

@@ -1,6 +1,11 @@
 # SearchInput
 
-`SearchInput` allows users to enter a specific keyword or phrase and obtain results related to the context in which it is placed.
+Use SearchInput to let users enter a keyword or phrase to search content
+related to the context it's placed in. Pass an `onClear` handler to show a
+clear button, and set `loading` to display a spinner while results are
+fetched. On desktop and tablet it must be paired with a button to trigger
+the search; on mobile the keyboard's search action can trigger it instead.
+For general text entry use TextInput instead.
 
 - [Alternatives](#alternatives)
 - [Accessibility](#accessibility)
@@ -110,16 +115,16 @@ This component is based on the `TextInput` component and supports the following
 
 - Margin
 
-| Prop               | Type                  | Default | Description                                                                 |
-| ------------------ | --------------------- | ------- | --------------------------------------------------------------------------- |
-| `label`            | `string`              | —       | The label for the form field, describing its purpose.                       |
-| `defaultValue`     | `string \| number`    | —       | The initial value of the input when rendered.                               |
-| `value`            | `string \| number`    | —       | The controlled value of the input. Must be used with an `onChange` handler. |
-| `labelId`          | `string`              | —       |                                                                             |
-| `helperTextId`     | `string`              | —       |                                                                             |
-| `validationTextId` | `string`              | —       |                                                                             |
-| `hideLabel`        | `boolean`             | `true`  | Visually hide the label.                                                    |
-| `labelVariant`     | `"body" \| "heading"` | —       | Change the label variant                                                    |
-| `helperText`       | `string`              | —       | Optional helper text to provide additional context or instructions.         |
-| `onClear`          | `(() => void)`        | —       |                                                                             |
-| `loading`          | `boolean`             | —       |                                                                             |
+| Prop               | Type                  | Default | Description                                                                                                            |
+| ------------------ | --------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `label`            | `string`              | —       | The label for the form field, describing its purpose.                                                                  |
+| `defaultValue`     | `string \| number`    | —       | The initial value of the input when rendered.                                                                          |
+| `value`            | `string \| number`    | —       | The controlled value of the input. Must be used with an `onChange` handler.                                            |
+| `labelId`          | `string`              | —       | The `id` of the element rendering the field's label, for `aria-labelledby` association.                                |
+| `helperTextId`     | `string`              | —       | The `id` of the element rendering the field's helper text, for `aria-describedby` association.                         |
+| `validationTextId` | `string`              | —       | The `id` of the element rendering the field's validation text, for `aria-describedby` association.                     |
+| `hideLabel`        | `boolean`             | `true`  | Visually hide the label.                                                                                               |
+| `labelVariant`     | `"body" \| "heading"` | —       | Change the label variant                                                                                               |
+| `helperText`       | `string`              | —       | Optional helper text to provide additional context or instructions.                                                    |
+| `onClear`          | `(() => void)`        | —       | Callback invoked when the clear button is clicked. When provided, a clear button is shown while the input has a value. |
+| `loading`          | `boolean`             | —       | Displays a loading spinner and disables input interaction.                                                             |

package/public/llms/components/section-header.md

@@ -1,8 +1,8 @@
 # SectionHeader
 
-Use the `SectionHeader` component to help define and separate content within a
-screen. It provides structure, clarity, and improves page scannability for
-users.
+Use SectionHeader to introduce and visually separate a section of content
+within a screen. Pass `trailingContent` to add a Link, Button, or Badge
+alongside the heading.
 
 ```tsx
 <Flex width="600px">
@@ -67,7 +67,7 @@ This component is based on the `div` element and supports the following common p
 | Prop               | Type                                    | Default | Description                                                                                       |
 | ------------------ | --------------------------------------- | ------- | ------------------------------------------------------------------------------------------------- |
 | `heading`          | `string`                                | —       | Actual string to display as section header                                                        |
-| `headingElement`   | `"div" \| "h1" \| "h2" \| "h3" \| "h4"` | `div`   |                                                                                                   |
+| `headingElement`   | `"div" \| "h1" \| "h2" \| "h3" \| "h4"` | `div`   | The element type to render the heading as.                                                        |
 | `helperText`       | `string`                                | —       | Optional helper text to provide additional context or instructions.                               |
 | `trailingContent`  | `ReactNode`                             | —       | Optional trailing content element                                                                 |
 | `validationStatus` | `"invalid"`                             | —       | Indicates the validation state                                                                    |

package/public/llms/components/segmented-control.md

@@ -1,6 +1,11 @@
 # SegmentedControl
 
-Use a Segmented Control to switch between alternative views of closely related content.
+Use SegmentedControl to switch between alternative views of closely related content.
+Always provide a `defaultValue` or controlled `value` — a SegmentedControl cannot
+be used without a default selected option.
+
+For navigation between pages or sections, use Tabs instead.
+For binary on/off settings, use Switch instead.
 
 - [Usage](#usage)
 - [Sizes](#sizes)
@@ -83,7 +88,7 @@ Use a Segmented Control to switch between alternative views of closely related c
 
 ## Usage
 
-Wrap `SegmentedControlOption` components in a `SegmentedControl`. Each option requires a unique `value`. Always provide a `defaultValue` — a Segmented Control cannot be used without a selected option.
+Wrap `SegmentedControlOption` components in a `SegmentedControl`. Each option requires a unique `value`. Always provide a `defaultValue`: a Segmented Control cannot be used without a selected option.
 
 ```tsx
 <SegmentedControl defaultValue={['gas']}>
@@ -113,7 +118,7 @@ Two sizes are available: `sm` (32px, default) and `md` (48px). The `size` prop i
 
 ## Icons
 
-Use the `icon` prop to display an icon before the label. Use the Small icon variant with `size="sm"` and the Medium icon variant with `size="md"`. Either add icons to all options or none — do not mix.
+Use the `icon` prop to display an icon before the label. Use the Small icon variant with `size="sm"` and the Medium icon variant with `size="md"`. Either add icons to all options or none; do not mix.
 
 ```tsx
 <SegmentedControl defaultValue={['gas']} size="sm">

package/public/llms/components/select.md

@@ -1,6 +1,9 @@
 # Select
 
-`Select` enables users to select an option from a list of choices, and generally requires a final submit action to confirm the selection.
+Use Select to let users choose a single option from a list, when the choice
+requires a final submit action to confirm — for a choice that applies
+immediately, consider SegmentedControl instead. Wrap SelectItem children to
+define the options, and always provide a `label`.
 
 ```tsx
 <Select {...args}>
@@ -115,26 +118,25 @@ This component is based on the `button` element and supports the following commo
 
 - Margin
 
-| Prop               | Type                        | Default | Description                                                         |
-| ------------------ | --------------------------- | ------- | ------------------------------------------------------------------- |
-| `label`            | `string`                    | —       | The label for the form field, describing its purpose.               |
-| `value`            | `string`                    | —       |                                                                     |
-| `defaultValue`     | `string`                    | —       |                                                                     |
-| `asChild`          | `boolean`                   | —       |                                                                     |
-| `open`             | `boolean`                   | —       |                                                                     |
-| `defaultOpen`      | `boolean`                   | —       |                                                                     |
-| `onOpenChange`     | `((open: boolean) => void)` | —       |                                                                     |
-| `autoComplete`     | `string`                    | —       |                                                                     |
-| `required`         | `boolean`                   | —       |                                                                     |
-| `onValueChange`    | `((value: string) => void)` | —       |                                                                     |
-| `labelId`          | `string`                    | —       |                                                                     |
-| `helperTextId`     | `string`                    | —       |                                                                     |
-| `validationTextId` | `string`                    | —       |                                                                     |
-| `labelVariant`     | `"body" \| "heading"`       | —       | Change the label variant                                            |
-| `helperText`       | `string`                    | —       | Optional helper text to provide additional context or instructions. |
-| `validationText`   | `string`                    | —       | Text to display when the `validationStatus` is set.                 |
-| `validationStatus` | `"valid" \| "invalid"`      | —       | Indicates the validation status.                                    |
-| `placeholder`      | `string`                    | —       |                                                                     |
+| Prop               | Type                        | Default | Description                                                                                        |
+| ------------------ | --------------------------- | ------- | -------------------------------------------------------------------------------------------------- |
+| `label`            | `string`                    | —       | The label for the form field, describing its purpose.                                              |
+| `value`            | `string`                    | —       | The controlled value of the selected option. Must be used with an `onValueChange` handler.         |
+| `defaultValue`     | `string`                    | —       | The initial value of the selected option when rendered, for uncontrolled usage.                    |
+| `open`             | `boolean`                   | —       |                                                                                                    |
+| `defaultOpen`      | `boolean`                   | —       |                                                                                                    |
+| `onOpenChange`     | `((open: boolean) => void)` | —       |                                                                                                    |
+| `autoComplete`     | `string`                    | —       |                                                                                                    |
+| `required`         | `boolean`                   | —       | Marks the field as required.                                                                       |
+| `onValueChange`    | `((value: string) => void)` | —       | Callback fired when the selected value changes.                                                    |
+| `labelId`          | `string`                    | —       | The `id` of the element rendering the field's label, for `aria-labelledby` association.            |
+| `helperTextId`     | `string`                    | —       | The `id` of the element rendering the field's helper text, for `aria-describedby` association.     |
+| `validationTextId` | `string`                    | —       | The `id` of the element rendering the field's validation text, for `aria-describedby` association. |
+| `labelVariant`     | `"body" \| "heading"`       | —       | Change the label variant                                                                           |
+| `helperText`       | `string`                    | —       | Optional helper text to provide additional context or instructions.                                |
+| `validationText`   | `string`                    | —       | Text to display when the `validationStatus` is set.                                                |
+| `validationStatus` | `"valid" \| "invalid"`      | —       | Indicates the validation status.                                                                   |
+| `placeholder`      | `string`                    | —       | Placeholder text shown when no value is selected.                                                  |
 
 ### SelectItem API