@shopify/ui-extensions 2026.4.0-rc.2 → 2026.4.0

package/src/surfaces/checkout/components/components-shared.d.ts

@@ -14,7 +14,7 @@ export type ComponentChildren = any;
 export type StringChildren = string;
 export interface GlobalProps {
 	/**
-	 * A unique identifier for the element.
+	 * A unique identifier for the element. Use this to reference the element in JavaScript, link labels to form controls, or target specific elements for styling or scripting.
 	 */
 	id?: string;
 }
@@ -46,19 +46,19 @@ export interface ActionSlots {
 }
 export interface BaseOverlayProps {
 	/**
-	 * Callback fired after the overlay is shown.
+	 * A callback fired immediately after the overlay is shown.
 	 */
 	onShow?: (event: Event) => void;
 	/**
-	 * Callback fired when the overlay is shown **after** any animations to show the overlay have finished.
+	 * A callback fired when the overlay is shown, after any show animations have completed.
 	 */
 	onAfterShow?: (event: Event) => void;
 	/**
-	 * Callback fired after the overlay is hidden.
+	 * A callback fired immediately after the overlay is hidden.
 	 */
 	onHide?: (event: Event) => void;
 	/**
-	 * Callback fired when the overlay is hidden **after** any animations to hide the overlay have finished.
+	 * A callback fired when the overlay is hidden, after any hide animations have completed.
 	 */
 	onAfterHide?: (event: Event) => void;
 }
@@ -72,19 +72,19 @@ export interface BaseOverlayProps {
  */
 export interface BaseOverlayMethods {
 	/**
-	 * Method to show an overlay.
+	 * A method to programmatically show the overlay.
 	 *
 	 * @implementation This is a method to be called on the element and not a callback and should hence be camelCase
 	 */
 	showOverlay: () => void;
 	/**
-	 * Method to hide an overlay.
+	 * A method to programmatically hide the overlay and run any associated hide animations.
 	 *
 	 * @implementation This is a method to be called on the element and not a callback and should hence be camelCase
 	 */
 	hideOverlay: () => void;
 	/**
-	 * Method to toggle the visiblity of an overlay.
+	 * A method to programmatically toggle the visibility of the overlay.
 	 *
 	 * @implementation This is a method to be called on the element and not a callback and should hence be camelCase
 	 */
@@ -92,48 +92,56 @@ export interface BaseOverlayMethods {
 }
 export interface FocusEventProps {
 	/**
-	 * Callback when the element loses focus.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event
+	 * A callback fired when the element loses focus. Learn more about the [blur event](https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event).
 	 */
 	onBlur?: (event: FocusEvent) => void;
 	/**
-	 * Callback when the element receives focus.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event
+	 * A callback fired when the element receives focus. Learn more about the [focus event](https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event).
 	 */
 	onFocus?: (event: FocusEvent) => void;
 }
 export interface ToggleEventProps {
 	/**
-	 * Callback fired when the element state changes **after** any animations have finished.
+	 * A callback that fires when the element state changes, after any toggle animations have finished.
 	 *
 	 * - If the element transitioned from hidden to showing, the `oldState` property will be set to `closed` and the
 	 *   `newState` property will be set to `open`.
 	 * - If the element transitioned from showing to hidden, the `oldState` property will be set to `open` and the
 	 *   `newState` will be `closed`.
 	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState
-	 * @see https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState
+	 * Learn more about [ToggleEvent.newState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState) and [ToggleEvent.oldState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState).
 	 */
 	onAfterToggle?: (event: ToggleEvent$1) => void;
 	/**
-	 * Callback straight after the element state changes.
+	 * A callback that fires immediately when the element state changes, before any animations.
 	 *
 	 * - If the element is transitioning from hidden to showing, the `oldState` property will be set to `closed` and the
 	 *   `newState` property will be set to `open`.
 	 * - If the element is transitioning from showing to hidden, then `oldState` property will be set to `open` and the
 	 *   `newState` will be `closed`.
 	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/toggle_event
-	 * @see https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState
-	 * @see https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState
+	 * Learn more about the [toggle event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/toggle_event), [ToggleEvent.newState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState), and [ToggleEvent.oldState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState).
 	 */
 	onToggle?: (event: ToggleEvent$1) => void;
 }
+/**
+ * The visibility state of a toggleable element.
+ *
+ * - `open`: The element is visible and showing its content.
+ * - `closed`: The element is hidden and its content is not visible.
+ */
 export type ToggleState = "open" | "closed";
+/**
+ * The event data provided to toggle-related callbacks. Contains the previous and next visibility states of the element.
+ */
 interface ToggleEvent$1 extends Event {
+	/**
+	 * The visibility state of the element after the toggle occurred.
+	 */
 	readonly newState: ToggleState;
+	/**
+	 * The visibility state of the element before the toggle occurred.
+	 */
 	readonly oldState: ToggleState;
 }
 export interface ExtendableEvent extends Event {
@@ -153,8 +161,7 @@ interface AnnouncementProps$1 extends GlobalProps, ToggleEventProps {
 	 */
 	children?: ComponentChildren;
 	/**
-	 * Callback fired when the announcement is dismissed by the user
-	 * (either via the built-in dismiss button or programmatically).
+	 * A callback that fires when the announcement is dismissed by the user clicking the close button or by calling the `dismiss()` method programmatically.
 	 */
 	onDismiss?: (event: Event) => void;
 	/**
@@ -162,12 +169,32 @@ interface AnnouncementProps$1 extends GlobalProps, ToggleEventProps {
 	 */
 	dismiss: () => void;
 }
+/**
+ * The design system's size scale, used to control the dimensions of components like avatars, icons, and thumbnails. Values range from `"small-500"` (smallest) through `"base"` (standard) to `"large-500"` (largest). Not all components support every size — check the component's `size` property type for its available options.
+ */
 export type SizeKeyword = "small-500" | "small-400" | "small-300" | "small-200" | "small-100" | "small" | "base" | "large" | "large-100" | "large-200" | "large-300" | "large-400" | "large-500";
+/**
+ * Defines the color intensity or emphasis level for text and UI elements.
+ *
+ * - `subdued`: Deemphasized color for secondary text, supporting labels, and less critical interface elements.
+ * - `base`: Primary color for body text, standard UI elements, and general content with good readability.
+ * - `strong`: Emphasized color for headings, key labels, and interactive elements that need prominence.
+ */
 export type ColorKeyword = "subdued" | "base" | "strong";
 export type BackgroundColorKeyword = "transparent" | ColorKeyword;
 export interface BackgroundProps {
 	/**
-	 * Adjust the background of the element.
+	 * The background color of the element.
+	 *
+	 * - `base`: The standard background color for general content areas.
+	 * - `subdued`: A muted background for secondary or supporting content.
+	 * - `transparent`: No background color (the default).
+	 * - `strong`: An emphasized background for prominent sections.
+	 *
+	 * - `'transparent'`: No visible background.
+	 * - `'subdued'`: A subtle, low-emphasis background.
+	 * - `'base'`: The standard background color.
+	 * - `'strong'`: A high-emphasis background for prominence.
 	 *
 	 * @default 'transparent'
 	 */
@@ -738,8 +765,28 @@ export type IconType = (typeof privateIconArray)[number];
  * Like `Extract`, but ensures that the extracted type is a strict subtype of the input type.
  */
 export type ExtractStrict<T, U extends T> = Extract<T, U>;
+/**
+ * Represents CSS shorthand properties that accept one to four values, following the [CSS shorthand syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box). Supports specifying values for all four sides: top, right, bottom, and left.
+ *
+ * - `T`: Single value that applies to all four sides.
+ * - `${T} ${T}`: Two values for block axis (top/bottom) and inline axis (left/right).
+ * - `${T} ${T} ${T}`: Three values for block-start (top), inline axis (left/right), and block-end (bottom).
+ * - `${T} ${T} ${T} ${T}`: Four values for block-start (top), inline-end (right), block-end (bottom), and inline-start (left).
+ */
 export type MaybeAllValuesShorthandProperty<T extends string> = T | `${T} ${T}` | `${T} ${T} ${T}` | `${T} ${T} ${T} ${T}`;
+/**
+ * Represents CSS shorthand properties that accept one or two values. Supports specifying the same value for both dimensions or different values.
+ *
+ * - `T`: Single value that applies to both dimensions.
+ * - `${T} ${T}`: Two values for block axis (vertical) and inline axis (horizontal).
+ */
 export type MaybeTwoValuesShorthandProperty<T extends string> = T | `${T} ${T}`;
+/**
+ * Makes a property responsive by allowing it to be set conditionally based on container query conditions. The value can be either a base value or a container query string.
+ *
+ * - `T`: Base value that applies in all conditions.
+ * - `@container${string}`: Container query string for conditional responsive styling based on container size.
+ */
 export type MaybeResponsive<T> = T | `@container${string}`;
 /**
  * Prevents widening string literal types in a union to `string`.
@@ -763,29 +810,32 @@ interface BadgeProps$1 extends GlobalProps {
 	 */
 	children?: ComponentChildren;
 	/**
-	 * Sets the tone of the Badge, based on the intention of the information being conveyed.
+	 * The semantic meaning and color treatment of the badge.
 	 *
 	 * @default 'auto'
 	 */
 	tone?: ToneKeyword;
 	/**
-	 * Modify the color to be more or less intense.
+	 * Controls the visual weight and emphasis of the badge.
 	 *
 	 * @default 'base'
 	 */
 	color?: ColorKeyword;
 	/**
-	 * The type of icon to be displayed in the badge.
+	 * An icon displayed inside the badge to provide additional visual context or reinforce the badge's meaning. Set to an empty string to display no icon.
 	 *
 	 * @default ''
 	 */
 	icon?: IconType | AnyString;
 	/**
-	 * The position of the icon in relation to the text.
+	 * The position of the icon relative to the badge text.
+	 *
+	 * - `start`: Places the icon before the text.
+	 * - `end`: Places the icon after the text.
 	 */
 	iconPosition?: "start" | "end";
 	/**
-	 * Adjusts the size.
+	 * The size of the badge.
 	 *
 	 * @default 'base'
 	 */
@@ -793,42 +843,34 @@ interface BadgeProps$1 extends GlobalProps {
 }
 interface BannerProps$1 extends GlobalProps, ActionSlots {
 	/**
-	 * The title of the banner.
+	 * The heading text displayed at the top of the banner to summarize the message or alert.
 	 *
 	 * @default ''
 	 */
 	heading?: string;
 	/**
-	 * The content of the Banner.
+	 * The main content displayed within the banner component, typically descriptive text or other elements providing details about the message or alert.
 	 */
 	children?: ComponentChildren;
 	/**
-	 * Sets the tone of the Banner, based on the intention of the information being conveyed.
+	 * The semantic meaning and color treatment of the component. The banner is a live region and the type of status is dictated by the tone selected.
 	 *
-	 * The banner is a live region and the type of status will be dictated by the Tone selected.
-	 *
-	 * - `critical` creates an [assertive live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) that is announced by screen readers immediately.
-	 * - `neutral`, `info`, `success`, `warning` and `caution` creates an [informative live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/status_role) that is announced by screen readers after the current message.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions
-	 * @see https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role
-	 * @see https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/status_role
+	 * The `critical` tone creates an [assertive live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) that is announced by screen readers immediately. The `neutral`, `info`, `success`, `warning`, and `caution` tones create an [informative live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/status_role) that is announced by screen readers after the current message.
 	 *
 	 * @default 'auto'
 	 */
 	tone?: ToneKeyword;
 	/**
-	 * Makes the content collapsible.
-	 * A collapsible banner will conceal child elements initially, but allow the user to expand the banner to see them.
+	 * Whether the banner content can be collapsed and expanded by the user. A collapsible banner conceals child elements initially, allowing the user to expand the banner to reveal them.
 	 *
 	 * @default false
 	 */
 	collapsible?: boolean;
 	/**
-	 * Determines whether the close button of the banner is present.
+	 * Whether the banner displays a close button that allows users to dismiss it.
 	 *
 	 * When the close button is pressed, the `dismiss` event will fire,
-	 * then `hidden` will be true,
+	 * then `hidden` will be set to `true`,
 	 * any animation will complete,
 	 * and the `afterhide` event will fire.
 	 *
@@ -836,31 +878,26 @@ interface BannerProps$1 extends GlobalProps, ActionSlots {
 	 */
 	dismissible?: boolean;
 	/**
-	 * Event handler when the banner is dismissed by the user.
+	 * A callback that fires when the banner is dismissed by the user clicking the close button.
 	 *
-	 * This does not fire when setting `hidden` manually.
+	 * This doesn't fire when setting `hidden` manually.
 	 *
-	 * The `hidden` property will be `false` when this event fires.
+	 * The `hidden` property is `false` when this event fires.
 	 */
 	onDismiss?: (event: Event) => void;
 	/**
-	 * Event handler when the banner has fully hidden.
-	 *
-	 * The `hidden` property will be `true` when this event fires.
+	 * A callback that fires when the banner has fully hidden, including after any hide animations have completed.
 	 *
-	 * @implementation If implementations animate the hiding of the banner,
-	 * this event must fire after the banner has fully hidden.
-	 * We can add an `onHide` event in future if we want to provide a hook for the start of the animation.
+	 * The `hidden` property is `true` when this event fires.
 	 */
 	onAfterHide?: (event: Event) => void;
 	/**
-	 * Determines whether the banner is hidden.
+	 * Controls whether the banner is visible or hidden.
 	 *
-	 * If this property is being set on each framework render (as in 'controlled' usage),
-	 * and the banner is `dismissible`,
-	 * ensure you update app state for this property when the `dismiss` event fires.
+	 * When using a controlled component pattern and the banner is `dismissible`,
+	 * update this property to `true` when the `dismiss` event fires.
 	 *
-	 * If the banner is not `dismissible`, it can still be hidden by setting this property.
+	 * You can hide the banner programmatically by setting this to `true` even if it's not `dismissible`.
 	 *
 	 * @default false
 	 */
@@ -880,17 +917,32 @@ export interface DisplayProps {
 }
 export interface AccessibilityRoleProps {
 	/**
-	 * Sets the semantic meaning of the component’s content. When set,
-	 * the role will be used by assistive technologies to help users
-	 * navigate the page.
-	 *
-	 * @implementation Although, in HTML hosts, this property changes the element used,
-	 * changing this property must not impact the visual styling of inside or outside of the box.
+	 * The semantic meaning of the component's content. When set, assistive technologies use this role to help users navigate the page.
 	 *
 	 * @default 'generic'
 	 */
 	accessibilityRole?: AccessibilityRole;
 }
+/**
+ * The semantic role of a component, used by assistive technologies to convey the element's purpose to users. Each role maps to a specific HTML element or ARIA role.
+ *
+ * - `main`: The primary content of the page.
+ * - `header`: A page or section header.
+ * - `footer`: Information such as copyright, navigation links, and privacy statements.
+ * - `section`: A generic section that should have a heading or `accessibilityLabel`.
+ * - `aside`: Supporting content related to the main content.
+ * - `navigation`: A major group of navigation links.
+ * - `ordered-list`: A list of ordered items.
+ * - `list-item`: An item inside a list.
+ * - `list-item-separator`: A divider between list items.
+ * - `unordered-list`: A list of unordered items.
+ * - `separator`: A divider that separates sections of content.
+ * - `status`: A live region with advisory information that is not urgent.
+ * - `alert`: Important, usually time-sensitive information.
+ * - `generic`: A nameless container with no semantic meaning (renders a `<div>`).
+ * - `presentation`: Strips semantic meaning while keeping visual styling. Synonym for `none`.
+ * - `none`: Strips semantic meaning while keeping visual styling. Synonym for `presentation`.
+ */
 export type AccessibilityRole = 
 /**
  * Used to indicate the primary content.
@@ -1020,162 +1072,198 @@ export interface AccessibilityVisibilityProps {
 }
 export interface LabelAccessibilityVisibilityProps {
 	/**
-	 * Changes the visibility of the component's label.
+	 * Controls whether the label is visible to all users or only to screen readers.
 	 *
-	 * - `visible`: the label is visible to all users.
-	 * - `exclusive`: the label is visually hidden but remains in the accessibility tree.
+	 * - `visible`: The label is shown to everyone.
+	 * - `exclusive`: The label is visually hidden but still announced by screen readers.
 	 *
 	 * @default 'visible'
 	 */
 	labelAccessibilityVisibility?: ExtractStrict<AccessibilityVisibilityProps["accessibilityVisibility"], "visible" | "exclusive">;
 }
+/**
+ * Defines the padding size for elements, using the standard size scale or `none` for no padding.
+ *
+ * - `SizeKeyword`: Standard padding sizes from the size scale for consistent spacing.
+ * - `none`: No padding.
+ */
 export type PaddingKeyword = SizeKeyword | "none";
 export interface PaddingProps {
 	/**
-	 * Adjust the padding of all edges.
+	 * The padding applied to all edges of the component.
 	 *
-	 * [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) is
-	 * supported. Note that, contrary to the CSS, it uses flow-relative values and the order is:
+	 * Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) using flow-relative values:
+	 * - 1 value applies to all sides
+	 * - 2 values apply to block (top/bottom) and inline (left/right)
+	 * - 3 values apply to block-start (top), inline (left/right), and block-end (bottom)
+	 * - 4 values apply to block-start (top), inline-end (right), block-end (bottom), and inline-start (left)
 	 *
-	 * - 4 values: `block-start inline-end block-end inline-start`
-	 * - 3 values: `block-start inline block-end`
-	 * - 2 values: `block inline`
+	 * **Examples:** `base`, `large none`, `base large-100 base small`
 	 *
-	 * For example:
-	 * - `large` means block-start, inline-end, block-end and inline-start paddings are `large`.
-	 * - `large none` means block-start and block-end paddings are `large`, inline-start and inline-end paddings are `none`.
-	 * - `large none large` means block-start padding is `large`, inline-end padding is `none`, block-end padding is `large` and inline-start padding is `none`.
-	 * - `large none large small` means block-start padding is `large`, inline-end padding is `none`, block-end padding is `large` and inline-start padding is `small`.
-	 *
-	 * A padding value of `auto` will use the default padding for the closest container that has had its usual padding removed.
+	 * Use `auto` to inherit padding from the nearest container with removed padding.
 	 *
 	 * @default 'none'
 	 */
 	padding?: MaybeResponsive<MaybeAllValuesShorthandProperty<PaddingKeyword>>;
 	/**
-	 * Adjust the block-padding.
+	 * The block-direction padding (top and bottom in horizontal writing modes).
+	 *
+	 * Accepts a single value for both sides or two space-separated values for block-start and block-end.
 	 *
-	 * - `large none` means block-start padding is `large`, block-end padding is `none`.
+	 * **Example:** `large none` applies `large` to the top and `none` to the bottom.
 	 *
-	 * This overrides the block value of `padding`.
+	 * Overrides the block value from `padding`.
 	 *
 	 * @default '' - meaning no override
 	 */
 	paddingBlock?: MaybeResponsive<MaybeTwoValuesShorthandProperty<PaddingKeyword> | "">;
 	/**
-	 * Adjust the block-start padding.
+	 * The block-start padding (top in horizontal writing modes).
 	 *
-	 * This overrides the block-start value of `paddingBlock`.
+	 * Overrides the block-start value from `paddingBlock`.
 	 *
 	 * @default '' - meaning no override
 	 */
 	paddingBlockStart?: MaybeResponsive<PaddingKeyword | "">;
 	/**
-	 * Adjust the block-end padding.
+	 * The block-end padding (bottom in horizontal writing modes).
 	 *
-	 * This overrides the block-end value of `paddingBlock`.
+	 * Overrides the block-end value from `paddingBlock`.
 	 *
 	 * @default '' - meaning no override
 	 */
 	paddingBlockEnd?: MaybeResponsive<PaddingKeyword | "">;
 	/**
-	 * Adjust the inline padding.
+	 * The inline-direction padding (left and right in horizontal writing modes).
 	 *
-	 * - `large none` means inline-start padding is `large`, inline-end padding is `none`.
+	 * Accepts a single value for both sides or two space-separated values for inline-start and inline-end.
 	 *
-	 * This overrides the inline value of `padding`.
+	 * **Example:** `large none` applies `large` to the left and `none` to the right.
+	 *
+	 * Overrides the inline value from `padding`.
 	 *
 	 * @default '' - meaning no override
 	 */
 	paddingInline?: MaybeResponsive<MaybeTwoValuesShorthandProperty<PaddingKeyword> | "">;
 	/**
-	 * Adjust the inline-start padding.
+	 * The inline-start padding (left in LTR writing modes, right in RTL).
 	 *
-	 * This overrides the inline-start value of `paddingInline`.
+	 * Overrides the inline-start value from `paddingInline`.
 	 *
 	 * @default '' - meaning no override
 	 */
 	paddingInlineStart?: MaybeResponsive<PaddingKeyword | "">;
 	/**
-	 * Adjust the inline-end padding.
+	 * The inline-end padding (right in LTR writing modes, left in RTL).
 	 *
-	 * This overrides the inline-end value of `paddingInline`.
+	 * Overrides the inline-end value from `paddingInline`.
 	 *
 	 * @default '' - meaning no override
 	 */
 	paddingInlineEnd?: MaybeResponsive<PaddingKeyword | "">;
 }
+/**
+ * Represents size values in pixels, percentages, or zero.
+ *
+ * - `` `${number}px` ``: Absolute size in pixels for fixed dimensions (such as `100px`, `24px`).
+ * - `` `${number}%` ``: Relative size as a percentage of the parent container (such as `50%`, `100%`).
+ * - `0`: Zero size, equivalent to no dimension.
+ */
 export type SizeUnits = `${number}px` | `${number}%` | `0`;
+/**
+ * Represents size values that can also be set to `auto` for automatic sizing.
+ *
+ * - `SizeUnits`: Specific size values in pixels, percentages, or zero for precise control.
+ * - `auto`: Automatically sizes based on content and layout constraints. Learn more about the [auto value](https://developer.mozilla.org/en-US/docs/Web/CSS/width#auto).
+ */
 export type SizeUnitsOrAuto = SizeUnits | "auto";
+/**
+ * Represents size values that can also be set to `none` to remove the size constraint.
+ *
+ * - `SizeUnits`: Specific size values in pixels, percentages, or zero for precise control.
+ * - `none`: No size constraint, allowing unlimited growth. Learn more about the [none value](https://developer.mozilla.org/en-US/docs/Web/CSS/max-width#none).
+ */
 export type SizeUnitsOrNone = SizeUnits | "none";
 export interface SizingProps {
 	/**
-	 * Adjust the block size.
+	 * The block size of the element (height in horizontal writing modes). Learn more about the [block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/block-size).
 	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/CSS/block-size
+	 * - `SizeUnits`: Specific size values in pixels, percentages, or zero for precise control.
+	 * - `auto`: Automatically sizes based on content and layout constraints.
 	 *
 	 * @default 'auto'
 	 */
 	blockSize?: MaybeResponsive<SizeUnitsOrAuto>;
 	/**
-	 * Adjust the minimum block size.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size
+	 * The minimum block size of the element (minimum height in horizontal writing modes). Learn more about the [min-block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size).
 	 *
 	 * @default '0'
 	 */
 	minBlockSize?: MaybeResponsive<SizeUnits>;
 	/**
-	 * Adjust the maximum block size.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size
+	 * The maximum block size of the element (maximum height in horizontal writing modes). Learn more about the [max-block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size).
 	 *
 	 * @default 'none'
 	 */
 	maxBlockSize?: MaybeResponsive<SizeUnitsOrNone>;
 	/**
-	 * Adjust the inline size.
+	 * The inline size of the element (width in horizontal writing modes). Learn more about the [inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size).
 	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size
+	 * - `SizeUnits`: Specific size values in pixels, percentages, or zero for precise control.
+	 * - `auto`: Automatically sizes based on content and layout constraints.
 	 *
 	 * @default 'auto'
 	 */
 	inlineSize?: MaybeResponsive<SizeUnitsOrAuto>;
 	/**
-	 * Adjust the minimum inline size.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size
+	 * The minimum inline size of the element (minimum width in horizontal writing modes). Learn more about the [min-inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size).
 	 *
 	 * @default '0'
 	 */
 	minInlineSize?: MaybeResponsive<SizeUnits>;
 	/**
-	 * Adjust the maximum inline size.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size
+	 * The maximum inline size of the element (maximum width in horizontal writing modes). Learn more about the [max-inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size).
 	 *
 	 * @default 'none'
 	 */
 	maxInlineSize?: MaybeResponsive<SizeUnitsOrNone>;
 }
+/**
+ * The visual style of a border. Learn more about [border-style](https://developer.mozilla.org/en-US/docs/Web/CSS/border-style).
+ *
+ * - `"none"`: No border is rendered.
+ * - `"solid"`: A single continuous line.
+ * - `"dashed"`: A series of short dashes.
+ * - `"dotted"`: A series of round dots.
+ * - `"auto"`: The border style is determined automatically based on the surface's design system.
+ */
 export type BorderStyleKeyword = "none" | "solid" | "dashed" | "dotted" | "auto";
+/**
+ * Defines the width of borders, using the standard size scale or `none` for no border.
+ *
+ * - `SizeKeyword`: Standard border widths from the size scale for consistent thickness.
+ * - `none`: No border width (removes the border).
+ */
 export type BorderSizeKeyword = SizeKeyword | "none";
+/**
+ * The corner radius of a border, using the design system's `SizeKeyword` scale with additional options:
+ *
+ * - `"max"`: The maximum possible radius, creating a pill or circular shape.
+ * - `"none"`: No rounding — corners are sharp (0 radius).
+ */
 export type BorderRadiusKeyword = SizeKeyword | "max" | "none";
 /**
- * Represents a shorthand for defining a border. It can be a combination of size, optionally followed by color, optionally followed by style.
+ * A shorthand string for specifying border properties. Accepts a size alone (`'base'`), size with color (`'base strong'`), or size with color and style (`'base strong dashed'`). Omitted values use their defaults.
  */
 export type BorderShorthand = BorderSizeKeyword | `${BorderSizeKeyword} ${ColorKeyword}` | `${BorderSizeKeyword} ${ColorKeyword} ${BorderStyleKeyword}`;
 export interface BorderProps {
 	/**
-	 * Set the border via the shorthand property.
+	 * Applies a border using shorthand syntax to specify width, color, and style in a single property.
 	 *
-	 * This can be a size, optionally followed by a color, optionally followed by a style.
+	 * Accepts a size value, optionally followed by a color, optionally followed by a style.
+	 * Omitted values use defaults: color defaults to `base`, style defaults to `auto`.
 	 *
-	 * If the color is not specified, it will be `base`.
-	 *
-	 * If the style is not specified, it will be `auto`.
-	 *
-	 * Values can be overridden by `borderWidth`, `borderStyle`, and `borderColor`.
+	 * Individual properties (`borderWidth`, `borderStyle`, `borderColor`) can override values set here.
 	 *
 	 * @example
 	 * // The following are equivalent:
@@ -1186,64 +1274,54 @@ export interface BorderProps {
 	 */
 	border?: BorderShorthand;
 	/**
-	 * Set the width of the border.
-	 *
-	 * If set, it takes precedence over the `border` property's width.
-	 *
-	 * Like CSS, up to 4 values can be specified.
+	 * Controls the thickness of the border on all sides. When set, this overrides the width value specified in the `border` property.
 	 *
-	 * If one value is specified, it applies to all sides.
-	 *
-	 * If two values are specified, they apply to the block sides and inline sides respectively.
-	 *
-	 * If three values are specified, they apply to the block-start, both inline sides, and block-end respectively.
-	 *
-	 * If four values are specified, they apply to the block-start, block-end, inline-start, and inline-end sides respectively.
+	 * Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) for specifying different widths per side:
+	 * - One value: applies to all sides
+	 * - Two values: applies to block sides (top/bottom) and inline sides (left/right) respectively
+	 * - Three values: applies to block-start (top), inline sides (left/right), and block-end (bottom) respectively
+	 * - Four values: applies to block-start (top), inline-end (right), block-end (bottom), and inline-start (left) respectively
 	 *
 	 * @default '' - meaning no override
 	 */
 	borderWidth?: MaybeAllValuesShorthandProperty<BorderSizeKeyword> | "";
 	/**
-	 * Set the style of the border.
-	 *
-	 * If set, it takes precedence over the `border` property's style.
+	 * Controls the visual style of the border on all sides, such as solid, dashed, or dotted.
 	 *
-	 * Like CSS, up to 4 values can be specified.
+	 * When set, this overrides the style value specified in the `border` property.
 	 *
-	 * If one value is specified, it applies to all sides.
-	 *
-	 * If two values are specified, they apply to the block sides and inline sides respectively.
-	 *
-	 * If three values are specified, they apply to the block-start, both inline sides, and block-end respectively.
-	 *
-	 * If four values are specified, they apply to the block-start, block-end, inline-start, and inline-end sides respectively.
+	 * Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) for specifying different styles per side:
+	 * - One value: applies to all sides
+	 * - Two values: applies to block sides (top/bottom) and inline sides (left/right) respectively
+	 * - Three values: applies to block-start (top), inline sides (left/right), and block-end (bottom) respectively
+	 * - Four values: applies to block-start (top), inline-end (right), block-end (bottom), and inline-start (left) respectively
 	 *
 	 * @default '' - meaning no override
 	 */
 	borderStyle?: MaybeAllValuesShorthandProperty<BorderStyleKeyword> | "";
 	/**
-	 * Set the color of the border.
+	 * Controls the color of the border using the design system's color scale.
 	 *
-	 * If set, it takes precedence over the `border` property's color.
+	 * When set, this overrides the color value specified in the `border` property.
+	 * Choose from `subdued`, `base`, or `strong` to match the visual emphasis needed.
 	 *
 	 * @default '' - meaning no override
 	 */
 	borderColor?: ColorKeyword | "";
 	/**
-	 * Set the radius of the border.
-	 *
-	 * [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) is
-	 * supported. Note that, contrary to the CSS, it uses flow-relative values and the order is:
+	 * Controls the roundedness of the element's corners using the design system's radius scale.
 	 *
-	 * - 4 values: `start-start start-end end-end end-start`
-	 * - 3 values: `start-start (start-end & end-start) start-end`
-	 * - 2 values: `(start-start & end-end) (start-end & end-start)`
+	 * Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) using flow-relative values:
+	 * - One value: applies to all corners
+	 * - Two values: applies to start corners (top-left & bottom-right) and end corners (top-right & bottom-left) respectively
+	 * - Three values: applies to start-start (top-left), end corners (top-right & bottom-left), and end-end (bottom-right) respectively
+	 * - Four values: applies to start-start (top-left), start-end (top-right), end-end (bottom-right), and end-start (bottom-left) respectively
 	 *
-	 * For example:
-	 * - `small-100` means start-start, start-end, end-end and end-start border radii are `small-100`.
-	 * - `small-100 none` means start-start and end-end border radii are `small-100`, start-end and end-start border radii are `none`.
-	 * - `small-100 none large-100` means start-start border radius is `small-100`, start-end border radius is `none`, end-end border radius is `large-100` and end-start border radius is `none`.
-	 * - `small-100 none large-100 small-100` means start-start border radius is `small-100`, start-end border radius is `none`, end-end border radius is `large-100` and end-start border radius is `small-100`.
+	 * Examples:
+	 * - `small-100`: All corners have `small-100` radius
+	 * - `small-100 none`: Top-left and bottom-right are `small-100`, top-right and bottom-left are `none`
+	 * - `small-100 none large-100`: Top-left is `small-100`, top-right and bottom-left are `none`, bottom-right is `large-100`
+	 * - `small-100 none large-100 base`: Each corner has its specified radius value
 	 *
 	 * @defaultValue 'none'
 	 */
@@ -1251,12 +1329,10 @@ export interface BorderProps {
 }
 export interface OverflowProps {
 	/**
-	 * Sets the overflow behavior of the element.
+	 * The overflow behavior of the element.
 	 *
-	 * - `hidden`: clips the content when it is larger than the element’s container.
-	 * The element will not be scrollable and the users will not be able
-	 * to access the clipped content by dragging or using a scroll wheel on a mouse.
-	 * - `visible`: the content that extends beyond the element’s container is visible.
+	 * - `visible`: Content that extends beyond the container is visible.
+	 * - `hidden`: Content that extends beyond the container is clipped and not scrollable.
 	 *
 	 * @default 'visible'
 	 */
@@ -1264,14 +1340,11 @@ export interface OverflowProps {
 }
 export interface BaseBoxProps extends AccessibilityVisibilityProps, BackgroundProps, DisplayProps, SizingProps, PaddingProps, BorderProps, OverflowProps {
 	/**
-	 * The content of the Box.
+	 * The child elements to render inside the container.
 	 */
 	children?: ComponentChildren;
 	/**
-	 * A label that describes the purpose or contents of the element.
-	 * When set, it will be announced to users using assistive technologies and will provide them with more context.
-	 *
-	 * Only use this when the element's content is not enough context for users using assistive technologies.
+	 * A label announced by assistive technologies that describes the purpose or contents of the element. Only set this when the element's visible content doesn't provide enough context on its own.
 	 */
 	accessibilityLabel?: string;
 }
@@ -1281,34 +1354,28 @@ interface BoxProps$1 extends BaseBoxPropsWithRole, GlobalProps {
 }
 export interface ButtonBehaviorProps extends InteractionProps, FocusEventProps {
 	/**
-	 * The behavior of the Button.
-	 *
-	 * - `submit`: Used to indicate the component acts as a submit button, meaning it submits the closest form.
-	 * - `button`: Used to indicate the component acts as a button, meaning it has no default action.
-	 * - `reset`: Used to indicate the component acts as a reset button, meaning it resets the closest form (returning fields to their default values).
+	 * The behavioral type of the button component, which determines what action it performs when activated.
+	 * - `'submit'`: Submits the nearest containing form.
+	 * - `'button'`: Performs no default action, relying on the `click` event handler for behavior.
+	 * - `'reset'`: Resets all fields in the nearest containing form to their default values.
 	 *
-	 * This property is ignored if the component supports `href` or `commandFor`/`command` and one of them is set.
+	 * This property is ignored if `href` or `commandFor`/`command` is set.
 	 *
 	 * @default 'button'
 	 */
 	type?: "submit" | "button" | "reset";
 	/**
-	 * Callback when the Button is activated.
-	 * This will be called before the action indicated by `type`.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event
+	 * A callback fired when the button is activated, before performing the action indicated by `type`. Learn more about the [click event](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event).
 	 */
 	onClick?: (event: Event) => void;
 	/**
-	 * Disables the Button meaning it cannot be clicked or receive focus.
+	 * Whether the button is disabled, preventing it from being clicked or receiving focus.
 	 *
 	 * @default false
 	 */
 	disabled?: boolean;
 	/**
-	 * Replaces content with a loading indicator while a background action is being performed.
-	 *
-	 * This also disables the Button.
+	 * Whether the button is in a loading state, which replaces the button content with a loading indicator while a background action is being performed. This also disables the button.
 	 *
 	 * @default false
 	 */
@@ -1316,18 +1383,14 @@ export interface ButtonBehaviorProps extends InteractionProps, FocusEventProps {
 }
 export interface LinkBehaviorProps extends InteractionProps, FocusEventProps {
 	/**
-	 * The URL to link to.
-	 *
-	 * - If set, it will navigate to the location specified by `href` after executing the `click` event.
-	 * - If a `commandFor` is set, the `command` will be executed instead of the navigation.
+	 * The URL to navigate to when clicked. The `click` event fires first, then navigation occurs. If `commandFor` is also set, the command executes instead of navigation.
 	 */
 	href?: string;
 	/**
-	 * Specifies where to display the linked URL.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target
+	 * Specifies where to display the linked URL. Learn more about the [target attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target).
 	 *
-	 * 'auto': The target is automatically determined based on the origin of the URL.
+	 * - `'auto'`: Opens the URL in the current frame or a new tab, depending on the context.
+	 * - `'_blank'`: Opens the URL in a new tab or window.
 	 *
 	 * @implementation Surfaces can set specific rules on how they handle each URL.
 	 * @implementation It’s expected that the behavior of `auto` is as `_self` except in specific cases.
@@ -1337,46 +1400,35 @@ export interface LinkBehaviorProps extends InteractionProps, FocusEventProps {
 	 */
 	target?: "auto" | "_blank" | "_self" | "_parent" | "_top" | AnyString;
 	/**
-	 * Causes the browser to treat the linked URL as a download with the string being the file name.
-	 * Download only works for same-origin URLs or the `blob:` and `data:` schemes.
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#download
+	 * A filename that causes the browser to treat the linked URL as a download. Download is only supported for same-origin URLs, or `blob:` and `data:` schemes. Learn more about the [download attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#download).
 	 */
 	download?: string;
 	/**
-	 * Callback when the link is activated.
-	 * This will be called before navigating to the location specified by `href`.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event
+	 * A callback fired when the link is activated, before navigating to the location specified by `href`. Learn more about the [click event](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event).
 	 */
 	onClick?: (event: Event) => void;
 }
 export interface InteractionProps {
 	/**
-	 * ID of a component that should respond to activations (e.g. clicks) on this component.
-	 *
-	 * See `command` for how to control the behavior of the target.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor
+	 * The ID of the component to control when this component is activated. Pair with the `command` property to specify what action to perform on the target component. Learn more about the [`commandFor` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor).
 	 */
 	commandFor?: string;
 	/**
-	 * Sets the action the `commandFor` should take when this clickable is activated.
+	 * Sets the action the [`command`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command) should take when this component is activated. Available options:
 	 *
-	 * See the documentation of particular components for the actions they support.
+	 * - `'--auto'`: Performs the default action appropriate for the target component.
+	 * - `'--show'`: Displays the target component if it's currently hidden.
+	 * - `'--hide'`: Conceals the target component from view.
+	 * - `'--toggle'`: Alternates the target component between visible and hidden states.
+	 * - `'--copy'`: Copies the target clipboard item.
 	 *
-	 * - `--auto`: a default action for the target component.
-	 * - `--show`: shows the target component.
-	 * - `--hide`: hides the target component.
-	 * - `--toggle`: toggles the target component.
-	 * - `--copy`: copies the target ClipboardItem.
+	 * The supported actions vary by target component type.
 	 *
 	 * @default '--auto'
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command
 	 */
 	command?: "--auto" | "--show" | "--hide" | "--toggle" | "--copy";
 	/**
-	 * ID of a component that should respond to interest (e.g. hover and focus) on this component.
+	 * The ID of the component to show when users hover over or focus on this component. Pair with a target component that supports interest-based interactions. Learn more about the [interestFor attribute](https://open-ui.org/components/interest-invokers.explainer/#the-pitch-in-code).
 	 */
 	interestFor?: string;
 }
@@ -1384,58 +1436,62 @@ export interface BaseClickableProps extends ButtonBehaviorProps, LinkBehaviorPro
 }
 interface ButtonProps$1 extends GlobalProps, BaseClickableProps {
 	/**
-	 * A label that describes the purpose or contents of the Button. It will be read to users using assistive technologies such as screen readers.
-	 *
-	 * Use this when using only an icon or the Button text is not enough context
-	 * for users using assistive technologies.
+	 * A label that describes the purpose or content of the button for users of assistive technologies such as screen readers. Use this when the visible content alone doesn't provide enough context.
 	 */
 	accessibilityLabel?: string;
 	/**
-	 * The content of the Button.
+	 * The content displayed within the button component.
 	 */
 	children?: ComponentChildren;
 	/**
-	 * The type of icon to be displayed in the Button.
+	 * An icon displayed inside the button, typically positioned before the button text.
 	 *
 	 * @default ''
 	 */
 	icon?: IconType | AnyString;
 	/**
-	 * The displayed inline width of the Button.
+	 * The inline width of the button component.
 	 *
-	 * - `auto`: the size of the button depends on the surface and context.
-	 * - `fill`: the button will takes up 100% of the available inline size.
-	 * - `fit-content`: the button will take up the minimum inline-size required to fit its content.
+	 * - `'auto'`: The size depends on the surface and context.
+	 * - `'fill'`: The button takes up 100% of the available inline size.
+	 * - `'fit-content'`: The button takes up the minimum inline size required to fit its content.
 	 *
 	 * @default 'auto'
 	 */
 	inlineSize?: "auto" | "fill" | "fit-content";
 	/**
-	 * Changes the visual appearance of the Button.
+	 * The visual style variant of the button component, which controls its prominence and emphasis.
+	 *
+	 * - `'auto'`: Automatically determined by the button's context.
+	 * - `'primary'`: High-emphasis style for the main action.
+	 * - `'secondary'`: Medium-emphasis style for supporting actions.
+	 * - `'tertiary'`: Low-emphasis style for less prominent actions.
 	 *
-	 * @default 'auto' - the variant is automatically determined by the Button's context
+	 * @default 'auto'
 	 */
 	variant?: "auto" | "primary" | "secondary" | "tertiary";
 	/**
-	 * Sets the tone of the Button based on the intention of the information being conveyed.
+	 * The semantic meaning and color treatment of the button.
+	 *
+	 * - `'auto'`: Automatically determined based on context.
+	 * - `'neutral'`: General information without specific intent.
+	 * - `'critical'`: Urgent problems or destructive actions.
 	 *
 	 * @default 'auto'
 	 */
 	tone?: ToneKeyword;
 	/**
-	 * Indicate the text language. Useful when the text is in a different language than the rest of the page.
-	 * It will allow assistive technologies such as screen readers to invoke the correct pronunciation.
-	 * [Reference of values](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) ("subtag" label)
+	 * The language of the button's text content. Use this when the button text is in a different language than the rest of the page, so assistive technologies can invoke the correct pronunciation. See the [reference of values](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) (`Subtag` label).
 	 */
 	lang?: string;
 }
 export interface BaseInputProps {
 	/**
-	 * An identifier for the field that is unique within the nearest containing form.
+	 * The name attribute for the field, used to identify the field's value when the form is submitted. Must be unique within the nearest containing form.
 	 */
 	name?: string;
 	/**
-	 * Disables the field, disallowing any interaction.
+	 * Whether the field is disabled, preventing any user interaction.
 	 *
 	 * @default false
 	 */
@@ -1443,15 +1499,15 @@ export interface BaseInputProps {
 }
 export interface InputProps extends BaseInputProps {
 	/**
-	 * Callback when the user has **finished editing** a field, e.g. once they have blurred the field.
+	 * A callback fired when the user has **finished editing** a field, such as when they blur the field or press Enter.
 	 *
 	 * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event
 	 */
 	onChange?: (event: Event) => void;
 	/**
-	 * Callback when the user makes any changes in the field.
+	 * A callback fired when the user makes any changes in the field, such as typing a character.
 	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event
+	 * Learn more about the [input event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event).
 	 */
 	onInput?: (event: Event) => void;
 	/**
@@ -1459,7 +1515,7 @@ export interface InputProps extends BaseInputProps {
 	 */
 	value?: string;
 	/**
-	 * The default value for the field.
+	 * The initial value of the field when it first loads. Unlike `placeholder`, this is a real value that the user can edit and that gets submitted with the form. Once the user starts typing, their input replaces this value.
 	 *
 	 * @implementation `defaultValue` reflects to the `value` attribute.
 	 */
@@ -1467,15 +1523,15 @@ export interface InputProps extends BaseInputProps {
 }
 export interface MultipleInputProps extends BaseInputProps {
 	/**
-	 * Callback when the user has selected option(s).
+	 * A callback fired when the user has selected one or more options.
 	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event
+	 * Learn more about the [change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event).
 	 */
 	onChange?: (event: Event) => void;
 	/**
-	 * Callback when the user has selected option(s).
+	 * A callback fired when the user selects or deselects options.
 	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event
+	 * Learn more about the [input event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event).
 	 */
 	onInput?: (event: Event) => void;
 	/**
@@ -1487,11 +1543,11 @@ export interface MultipleInputProps extends BaseInputProps {
 }
 export interface FileInputProps extends BaseInputProps {
 	/**
-	 * Callback when the user has **finished selecting** a file or files.
+	 * A callback fired when the user has finished selecting one or more files.
 	 */
 	onChange?: (event: Event) => void;
 	/**
-	 * Callback when the user makes any changes in the file selection.
+	 * A callback fired when the user makes any changes to the file selection.
 	 */
 	onInput?: (event: Event) => void;
 	/**
@@ -1516,8 +1572,7 @@ export interface FileInputProps extends BaseInputProps {
 }
 export interface FieldErrorProps {
 	/**
-	 * Indicate an error to the user. The field will be given a specific stylistic treatment
-	 * to communicate problems that have to be resolved immediately.
+	 * An error message displayed below the field to indicate validation problems. When set, the field is styled with error indicators and the message is announced to screen readers.
 	 */
 	error?: string;
 }
@@ -1532,7 +1587,7 @@ export interface BasicFieldProps extends FieldErrorProps, LabelAccessibilityVisi
 	 */
 	required?: boolean;
 	/**
-	 * Content to use as the field label.
+	 * The text displayed as the field label, which identifies the purpose of the field to users. This label is associated with the field for accessibility and helps users understand what information to provide.
 	 */
 	label?: string;
 }
@@ -1548,13 +1603,13 @@ export interface FieldDetailsProps {
 }
 export interface FieldProps extends BasicFieldProps, InputProps, FocusEventProps, FieldDetailsProps {
 	/**
-	 * A short hint that describes the expected value of the field.
+	 * The placeholder text displayed in the field when it's empty, providing a hint about the expected input format or value.
 	 */
 	placeholder?: string;
 }
 export interface BaseTextFieldProps extends FieldProps {
 	/**
-	 * The field cannot be edited by the user. It is focusable will be announced by screen readers.
+	 * Whether the field is read-only and can't be edited. Read-only fields remain focusable and their content is announced by screen readers.
 	 *
 	 * @default false
 	 */
@@ -1566,7 +1621,7 @@ export interface FieldDecorationProps {
 	 *
 	 * This is useful for displaying an implied part of the value, such as "@shopify.com", or "%".
 	 *
-	 * This cannot be edited by the user, and it isn't included in the value of the field.
+	 * This can't be edited by the user, and it isn't included in the value of the field.
 	 *
 	 * It may not be displayed until the user has interacted with the input.
 	 * For example, an inline label may take the place of the suffix until the user focuses the input.
@@ -1579,7 +1634,7 @@ export interface FieldDecorationProps {
 	 *
 	 * This is useful for displaying an implied part of the value, such as "https://" or "+353".
 	 *
-	 * This cannot be edited by the user, and it isn't included in the value of the field.
+	 * This can't be edited by the user, and it isn't included in the value of the field.
 	 *
 	 * It may not be displayed until the user has interacted with the input.
 	 * For example, an inline label may take the place of the prefix until the user focuses the input.
@@ -1604,8 +1659,7 @@ export interface NumberConstraintsProps {
 	 * The highest decimal or integer to be accepted for the field.
 	 * When used with `step` the value will round down to the max number.
 	 *
-	 * Note: a user will still be able to use the keyboard to input a number higher than
-	 * the max. It is up to the developer to add appropriate validation.
+	 * Note: a user can still use the keyboard to input a number higher than the max. It's up to the developer to add appropriate validation.
 	 *
 	 * @default Infinity
 	 */
@@ -1614,8 +1668,7 @@ export interface NumberConstraintsProps {
 	 * The lowest decimal or integer to be accepted for the field.
 	 * When used with `step` the value will round up to the min number.
 	 *
-	 * Note: a user will still be able to use the keyboard to input a number lower than
-	 * the min. It is up to the developer to add appropriate validation.
+	 * Note: a user can still use the keyboard to input a number lower than the min. It's up to the developer to add appropriate validation.
 	 *
 	 * @default -Infinity
 	 */
@@ -1632,10 +1685,9 @@ export interface NumberConstraintsProps {
 	/**
 	 * Sets the type of controls displayed in the field.
 	 *
-	 * - `stepper`: displays buttons to increase or decrease the value of the field by the stepping interval defined in the `step` property.
-	 * Appropriate mouse and [keyboard interactions](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role#keyboard_interactions) to control the value of the field are enabled.
-	 * - `none`: no controls are displayed and users must input the value manually. Arrow keys and scroll wheels can’t be used either to avoid accidental changes.
-	 * - `auto`: the presence of the controls depends on the surface and context.
+	 * - `'auto'`: The presence of the controls depends on the surface and context.
+	 * - `'stepper'`: Displays buttons to increase or decrease the value by the stepping interval defined in the `step` property. Appropriate mouse and [keyboard interactions](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role#keyboard_interactions) to control the value are enabled.
+	 * - `'none'`: No controls are displayed and users must input the value manually. Arrow keys and scroll wheels can’t be used either to avoid accidental changes.
 	 *
 	 * @default 'auto'
 	 */
@@ -1649,7 +1701,7 @@ export interface MinMaxLengthProps {
 	 */
 	maxLength?: number;
 	/**
-	 * Specifies the min number of characters allowed.
+	 * Specifies the minimum number of characters allowed.
 	 *
 	 * @default 0
 	 */
@@ -1662,7 +1714,7 @@ export interface BaseSelectableProps {
 	 */
 	accessibilityLabel?: string;
 	/**
-	 * Disables the control, disallowing any interaction.
+	 * Whether the control is disabled, preventing any user interaction.
 	 *
 	 * @default false
 	 */
@@ -1674,13 +1726,13 @@ export interface BaseSelectableProps {
 }
 export interface BaseOptionProps extends BaseSelectableProps {
 	/**
-	 * Whether the control is active.
+	 * Whether the control is currently selected.
 	 *
 	 * @default false
 	 */
 	selected?: boolean;
 	/**
-	 * Whether the control is active by default.
+	 * Whether the control is selected by default.
 	 *
 	 * @implementation `defaultSelected` reflects to the `selected` attribute.
 	 *
@@ -1690,17 +1742,17 @@ export interface BaseOptionProps extends BaseSelectableProps {
 }
 export interface BaseCheckableProps extends BaseSelectableProps, InteractionProps {
 	/**
-	 * Visual content to use as the control label.
+	 * The text displayed as the control label, which identifies the purpose of the control to users. This label is associated with the control for accessibility.
 	 */
 	label?: string;
 	/**
-	 * Whether the control is active.
+	 * Whether the control is currently checked.
 	 *
 	 * @default false
 	 */
 	checked?: boolean;
 	/**
-	 * Whether the control is active by default.
+	 * Whether the control is checked by default.
 	 *
 	 * @implementation `defaultChecked` reflects to the `checked` attribute.
 	 *
@@ -1708,8 +1760,7 @@ export interface BaseCheckableProps extends BaseSelectableProps, InteractionProp
 	 */
 	defaultChecked?: boolean;
 	/**
-	 * An identifier for the control that is unique within the nearest
-	 * containing `Form` component.
+	 * The name attribute for the control, used to identify its value when the form is submitted. Must be unique within the nearest containing form.
 	 */
 	name?: string;
 	/**
@@ -1771,7 +1822,7 @@ export interface ChipProps$1 {
 	 */
 	graphic?: ComponentChildren;
 	/**
-	 * A label that describes the purpose or contents of the Chip. It will be read to users using assistive technologies such as screen readers.
+	 * A label that describes the purpose or contents of the chip. It will be read to users using assistive technologies such as screen readers.
 	 */
 	accessibilityLabel?: string;
 	/**
@@ -1806,13 +1857,13 @@ interface ChoiceProps$1 extends GlobalProps, BaseOptionProps {
 	 */
 	details?: ComponentChildren;
 	/**
-	 * Set to `true` to associate a choice with the error passed to `ChoiceList`
+	 * Whether this choice is associated with the error state of the parent choice list. When `true`, the choice is visually marked as having an error.
 	 *
 	 * @default false
 	 */
 	error?: boolean;
 	/**
-	 * Secondary content for a choice.
+	 * Additional text or elements displayed below the choice label, providing extra context or detail to help users make a selection.
 	 */
 	secondaryContent?: ComponentChildren;
 	/**
@@ -1836,7 +1887,7 @@ interface ChoiceListProps$1 extends GlobalProps, Pick<BasicFieldProps, "label" |
 	 */
 	children?: ComponentChildren;
 	/**
-	 * Disables the field, disallowing any interaction.
+	 * Whether the field is disabled, preventing any user interaction.
 	 *
 	 * `disabled` on any child choices is ignored when this is true.
 	 *
@@ -1869,7 +1920,7 @@ interface ClickableProps$1 extends GlobalProps, BaseBoxProps, BaseClickableProps
 	/**
 	 * Disables the clickable, meaning it cannot be clicked or receive focus.
 	 *
-	 * In this state, onClick will not fire.
+	 * In this state, the `click` event will not fire.
 	 * If the click event originates from a child element, the event will immediately stop propagating from this element.
 	 *
 	 * However, items within the clickable can still receive focus and be interacted with.
@@ -1881,7 +1932,7 @@ interface ClickableProps$1 extends GlobalProps, BaseBoxProps, BaseClickableProps
 	/**
 	 * Indicate the text language. Useful when the text is in a different language than the rest of the page.
 	 * It will allow assistive technologies such as screen readers to invoke the correct pronunciation.
-	 * [Reference of values](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) ("subtag" label)
+	 * [Reference of values](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) (`Subtag` label)
 	 *
 	 * @default ''
 	 */
@@ -1893,9 +1944,7 @@ interface ClickableChipProps$1 extends ChipProps$1, GlobalProps {
 	 */
 	onClick?: (event: Event) => void;
 	/**
-	 * The URL to link to.
-	 *
-	 * - If set, it will navigate to the location specified by `href` after executing the `click` event.
+	 * The URL to link to. When set, the chip navigates to the specified location after the `click` event fires.
 	 */
 	href?: string;
 	/**
@@ -1955,7 +2004,7 @@ interface ClipboardItemProps$1 extends GlobalProps {
 }
 export interface AutocompleteProps<AutocompleteField extends AnyAutocompleteField> {
 	/**
-	 * A hint as to the intended content of the field.
+	 * A hint about the intended content of the field for browser autofill.
 	 *
 	 * When set to `on` (the default), this property indicates that the field should support
 	 * autofill, but you do not have any more semantic information on the intended
@@ -1967,12 +2016,9 @@ export interface AutocompleteProps<AutocompleteField extends AnyAutocompleteFiel
 	 * Alternatively, you can provide value which describes the
 	 * specific data you would like to be entered into this field during autofill.
 	 *
-	 * @see Learn more about the set of {@link https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill-detail-tokens|autocomplete values} supported in browsers.
+	 * Learn more about the set of [autocomplete values](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill-detail-tokens) supported in browsers.
 	 *
-	 * @default 'tel' for PhoneField
-	 * @default 'email' for EmailField
-	 * @default 'url' for URLField
-	 * @default 'on' for everything else
+	 * @default 'on'
 	 */
 	autocomplete?: AutocompleteField | `${AutocompleteSection} ${AutocompleteField}` | `${AutocompleteGroup} ${AutocompleteField}` | `${AutocompleteSection} ${AutocompleteGroup} ${AutocompleteField}` | "on" | "off";
 }
@@ -1994,12 +2040,15 @@ export type AutocompleteGroup = "shipping" | "billing";
 export type AutocompleteAddressGroup = "fax" | "home" | "mobile" | "pager";
 export type AnyAutocompleteField = "additional-name" | "address-level1" | "address-level2" | "address-level3" | "address-level4" | "address-line1" | "address-line2" | "address-line3" | "country-name" | "country" | "current-password" | "email" | "family-name" | "given-name" | "honorific-prefix" | "honorific-suffix" | "language" | "name" | "new-password" | "nickname" | "one-time-code" | "organization-title" | "organization" | "photo" | "postal-code" | "sex" | "street-address" | "transaction-amount" | "transaction-currency" | "url" | "username" | "bday-day" | "bday-month" | "bday-year" | "bday" | "cc-additional-name" | "cc-expiry-month" | "cc-expiry-year" | "cc-expiry" | "cc-family-name" | "cc-given-name" | "cc-name" | "cc-number" | "cc-csc" | "cc-type" | `${AutocompleteAddressGroup} email` | "impp" | `${AutocompleteAddressGroup} impp` | "tel" | "tel-area-code" | "tel-country-code" | "tel-extension" | "tel-local-prefix" | "tel-local-suffix" | "tel-local" | "tel-national" | `${AutocompleteAddressGroup} tel` | `${AutocompleteAddressGroup} tel-area-code` | `${AutocompleteAddressGroup} tel-country-code` | `${AutocompleteAddressGroup} tel-extension` | `${AutocompleteAddressGroup} tel-local-prefix` | `${AutocompleteAddressGroup} tel-local-suffix` | `${AutocompleteAddressGroup} tel-local` | `${AutocompleteAddressGroup} tel-national`;
 export type TextAutocompleteField = ExtractStrict<AnyAutocompleteField, "additional-name" | "address-level1" | "address-level2" | "address-level3" | "address-level4" | "address-line1" | "address-line2" | "address-line3" | "country-name" | "country" | "family-name" | "given-name" | "honorific-prefix" | "honorific-suffix" | "language" | "name" | "nickname" | "one-time-code" | "organization-title" | "organization" | "postal-code" | "sex" | "street-address" | "transaction-currency" | "username" | "cc-name" | "cc-given-name" | "cc-additional-name" | "cc-family-name" | "cc-type">;
+/**
+ * The type of consent policy being collected.
+ *
+ * - `'sms-marketing'`: Represents the policy for SMS marketing consent.
+ */
 export type ConsentPolicy = "sms-marketing";
 interface ConsentCheckboxProps$1 extends GlobalProps, CheckboxProps$1 {
 	/**
-	 * The policy for which user consent is being collected for.
-	 *
-	 * `sms-marketing`: Represents the policy for SMS marketing consent.
+	 * The policy for which user consent is being collected.
 	 */
 	policy?: ConsentPolicy;
 }
@@ -2016,9 +2065,7 @@ interface PhoneFieldProps$1 extends GlobalProps, BaseTextFieldProps, Pick<FieldD
 }
 interface ConsentPhoneFieldProps$1 extends GlobalProps, PhoneFieldProps$1 {
 	/**
-	 * The policy for which user consent is being collected for.
-	 *
-	 * `sms-marketing`: Represents the policy for SMS marketing consent.
+	 * The policy for which user consent is being collected.
 	 */
 	policy?: ConsentPolicy;
 }
@@ -2237,13 +2284,20 @@ interface DetailsProps$1 extends GlobalProps, ToggleEventProps {
 }
 interface DividerProps$1 extends GlobalProps {
 	/**
-	 * Specify the direction of the divider. This uses [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values).
+	 * The orientation of the divider, using [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values).
+	 *
+	 * - `inline`: A horizontal divider that separates content stacked vertically.
+	 * - `block`: A vertical divider that separates content arranged horizontally.
 	 *
 	 * @default 'inline'
 	 */
 	direction?: "inline" | "block";
 	/**
-	 * Modify the color to be more or less intense.
+	 * The visual emphasis of the divider's color.
+	 *
+	 * - `subdued`: A lighter divider for subtle separation.
+	 * - `base`: The standard divider color for most contexts.
+	 * - `strong`: A darker divider for stronger visual separation.
 	 *
 	 * @default 'base'
 	 */
@@ -2253,7 +2307,7 @@ interface DropZoneProps$1 extends GlobalProps, FileInputProps, BasicFieldProps {
 	/**
 	 * A string representing the types of files that are accepted by the drop zone.
 	 * This string is a comma-separated list of unique file type specifiers which can be one of the following:
-	 * - A file extension starting with a period (".") character (e.g. .jpg, .pdf, .doc)
+	 * - A file extension starting with a period (".") character (such as .jpg, .pdf, .doc)
 	 * - A valid MIME type string with no extensions
 	 *
 	 * If omitted, all file types are accepted.
@@ -2311,29 +2365,31 @@ interface FormProps$1 extends GlobalProps {
 	 */
 	onReset?: (event: Event) => void;
 }
+/**
+ * The amount of space between child elements.
+ *
+ * - `none`: No spacing.
+ * - `small-500`: The smallest spacing.
+ * - `small-400` / `small-300` / `small-200` / `small-100` / `small`: Progressively larger small spacings.
+ * - `base`: The standard spacing for most use cases.
+ * - `large` / `large-100` / `large-200` / `large-300` / `large-400` / `large-500`: Progressively larger spacings.
+ */
 export type SpacingKeyword = SizeKeyword | "none";
 export interface GapProps {
 	/**
-	 * Adjust spacing between elements.
-	 *
-	 * A single value applies to both axes.
-	 * A pair of values (eg `large-100 large-500`) can be used to set the inline and block axes respectively.
+	 * The spacing between child elements. A single value applies to both the inline and block axes. A pair of space-separated values (for example, `large-100 large-500`) sets the inline and block axes independently.
 	 *
 	 * @default 'none'
 	 */
 	gap?: MaybeResponsive<MaybeTwoValuesShorthandProperty<SpacingKeyword>>;
 	/**
-	 * Adjust spacing between elements in the block axis.
-	 *
-	 * This overrides the row value of `gap`.
+	 * The spacing between child elements along the block axis (vertical in horizontal writing modes). Overrides the block-axis value set by `gap`.
 	 *
 	 * @default '' - meaning no override
 	 */
 	rowGap?: MaybeResponsive<SpacingKeyword | "">;
 	/**
-	 * Adjust spacing between elements in the inline axis.
-	 *
-	 * This overrides the column value of `gap`.
+	 * The spacing between child elements along the inline axis (horizontal in horizontal writing modes). Overrides the inline-axis value set by `gap`.
 	 *
 	 * @default '' - meaning no override
 	 */
@@ -2344,108 +2400,80 @@ export type ContentDistribution = "space-between" | "space-around" | "space-even
 export type ContentPosition = "center" | "start" | "end";
 export type OverflowPosition = `unsafe ${ContentPosition}` | `safe ${ContentPosition}`;
 /**
- * Justify items defines the default justify-self for all items of the box, giving them all a default way of justifying each box along the appropriate axis.
- *
- * @see https://developer.mozilla.org/en-US/docs/Web/CSS/justify-items
+ * Controls the default inline-axis alignment for all items within a container. Learn more about [`justify-items`](https://developer.mozilla.org/en-US/docs/Web/CSS/justify-items).
  */
 export type JustifyItemsKeyword = "normal" | "stretch" | BaselinePosition | OverflowPosition | ContentPosition;
 /**
- * Align items sets the align-self value on all direct children as a group.
- *
- * @see https://developer.mozilla.org/en-US/docs/Web/CSS/align-items
+ * Controls how all direct children are aligned along the cross axis. Learn more about [`align-items`](https://developer.mozilla.org/en-US/docs/Web/CSS/align-items).
  */
 export type AlignItemsKeyword = "normal" | "stretch" | BaselinePosition | OverflowPosition | ContentPosition;
 /**
- * Justify content defines how the browser distributes space between and around content items along the main-axis of a flex container, and the inline axis of a grid container.
- *
- * @see https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content
+ * Controls how space is distributed between and around content items along the main axis of a flex container or the inline axis of a grid container. Learn more about [`justify-content`](https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content).
  */
 export type JustifyContentKeyword = "normal" | ContentDistribution | OverflowPosition | ContentPosition;
 /**
- *Align content sets the distribution of space between and around content items along a flexbox's cross axis, or a grid or block-level element's block axis.
- *
- * @see https://developer.mozilla.org/en-US/docs/Web/CSS/align-content
+ * Controls the distribution of space between and around content items along the cross axis of a flex container or the block axis of a grid container. Learn more about [`align-content`](https://developer.mozilla.org/en-US/docs/Web/CSS/align-content).
  */
 export type AlignContentKeyword = "normal" | BaselinePosition | ContentDistribution | OverflowPosition | ContentPosition;
 interface GridProps$1 extends GlobalProps, BaseBoxPropsWithRole, GapProps {
 	/**
-	  Define columns and specify their size.
-  
-	  @see https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-columns
-	  @default 'none'
-	*/
+	 * Defines the number and size of columns in the grid. Accepts any valid CSS [`grid-template-columns`](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-columns) value, such as `"1fr 2fr"` or `"repeat(3, 1fr)"`.
+	 *
+	 * @default 'none'
+	 */
 	gridTemplateColumns?: MaybeResponsive<string>;
 	/**
-	  Define rows and specify their size.
-  
-	  @see https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-rows
-	  @default 'none'
-	*/
+	 * Defines the number and size of rows in the grid. Accepts any valid CSS [`grid-template-rows`](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-rows) value, such as `"auto 1fr"` or `"repeat(2, 100px)"`.
+	 *
+	 * @default 'none'
+	 */
 	gridTemplateRows?: MaybeResponsive<string>;
 	/**
-	  Aligns the grid items along the inline (row) axis.
-  
-	  This overrides the inline value of `placeItems`.
-  
-	  @see https://developer.mozilla.org/en-US/docs/Web/CSS/justify-items
-	  @default '' - meaning no override
-	*/
+	 * Aligns grid items along the inline (row) axis. Overrides the inline value of `placeItems`. Learn more about [`justify-items`](https://developer.mozilla.org/en-US/docs/Web/CSS/justify-items).
+	 *
+	 * @default '' - meaning no override
+	 */
 	justifyItems?: MaybeResponsive<JustifyItemsKeyword | "">;
 	/**
-	  Aligns the grid items along the block (column) axis.
-  
-	  This overrides the block value of `placeItems`.
-  
-	  @see https://developer.mozilla.org/en-US/docs/Web/CSS/align-items
-	  @default '' - meaning no override
-	*/
+	 * Aligns grid items along the block (column) axis. Overrides the block value of `placeItems`. Learn more about [`align-items`](https://developer.mozilla.org/en-US/docs/Web/CSS/align-items).
+	 *
+	 * @default '' - meaning no override
+	 */
 	alignItems?: MaybeResponsive<AlignItemsKeyword | "">;
 	/**
-	  A shorthand property for `justify-items` and `align-items`.
-  
-	  @see https://developer.mozilla.org/en-US/docs/Web/CSS/place-items
-	  @default 'normal normal'
-	*/
+	 * A shorthand for `justifyItems` and `alignItems` that sets both alignment axes at once. Learn more about [`place-items`](https://developer.mozilla.org/en-US/docs/Web/CSS/place-items).
+	 *
+	 * @default 'normal normal'
+	 */
 	placeItems?: MaybeResponsive<`${AlignItemsKeyword} ${JustifyItemsKeyword}` | AlignItemsKeyword>;
 	/**
-	  Aligns the grid along the inline (row) axis.
-  
-	  This overrides the inline value of `placeContent`.
-  
-	  @see https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content
-	  @default '' - meaning no override
-	*/
+	 * Controls how the grid's columns are distributed along the inline (row) axis when there is extra space. Overrides the inline value of `placeContent`. Learn more about [`justify-content`](https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content).
+	 *
+	 * @default '' - meaning no override
+	 */
 	justifyContent?: MaybeResponsive<JustifyContentKeyword | "">;
 	/**
-	  Aligns the grid along the block (column) axis.
-  
-	  This overrides the block value of `placeContent`.
-  
-	  @see https://developer.mozilla.org/en-US/docs/Web/CSS/align-content
-	  @default '' - meaning no override
-	*/
+	 * Controls how the grid's rows are distributed along the block (column) axis when there is extra space. Overrides the block value of `placeContent`. Learn more about [`align-content`](https://developer.mozilla.org/en-US/docs/Web/CSS/align-content).
+	 *
+	 * @default '' - meaning no override
+	 */
 	alignContent?: MaybeResponsive<AlignContentKeyword | "">;
 	/**
-	  A shorthand property for `justify-content` and `align-content`.
-  
-	  @see https://developer.mozilla.org/en-US/docs/Web/CSS/place-content
-	  @default 'normal normal'
-	*/
+	 * A shorthand for `justifyContent` and `alignContent` that sets both distribution axes at once. Learn more about [`place-content`](https://developer.mozilla.org/en-US/docs/Web/CSS/place-content).
+	 *
+	 * @default 'normal normal'
+	 */
 	placeContent?: MaybeResponsive<`${AlignContentKeyword} ${JustifyContentKeyword}` | AlignContentKeyword>;
 }
 interface GridItemProps$1 extends GlobalProps, BaseBoxPropsWithRole {
 	/**
-	 * Number of columns the item will span across
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column
+	 * The number of columns this item spans within the grid. Set to `auto` to let the grid determine placement automatically, or use `span {number}` to span a specific number of columns. Learn more about [`grid-column`](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column).
 	 *
 	 * @default 'auto'
 	 */
 	gridColumn?: `span ${number}` | "auto";
 	/**
-	 * Number of rows the item will span across
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/CSS/grid-row
+	 * The number of rows this item spans within the grid. Set to `auto` to let the grid determine placement automatically, or use `span {number}` to span a specific number of rows. Learn more about [`grid-row`](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-row).
 	 *
 	 * @default 'auto'
 	 */
@@ -2475,7 +2503,7 @@ export interface BaseTypographyProps {
 	/**
 	 * Indicate the text language. Useful when the text is in a different language than the rest of the page.
 	 * It will allow assistive technologies such as screen readers to invoke the correct pronunciation.
-	 * [Reference of values](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) ("subtag" label)
+	 * [Reference of values](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) (`Subtag` label)
 	 *
 	 * It is recommended to combine it with the `dir` attribute to ensure the text is rendered correctly if the surrounding content’s direction is different.
 	 *
@@ -2485,8 +2513,8 @@ export interface BaseTypographyProps {
 	/**
 	 * Indicates the directionality of the element’s text.
 	 *
-	 * - `ltr`: languages written from left to right (e.g. English)
-	 * - `rtl`: languages written from right to left (e.g. Arabic)
+	 * - `ltr`: languages written from left to right (such as English)
+	 * - `rtl`: languages written from right to left (such as Arabic)
 	 * - `auto`: the user agent determines the direction based on the content
 	 * - `''`: direction is inherited from parent elements (equivalent to not setting the attribute)
 	 *
@@ -2530,94 +2558,110 @@ interface HeadingProps$1 extends GlobalProps, AccessibilityVisibilityProps, Bloc
 	 */
 	accessibilityRole?: "heading" | ExtractStrict<AccessibilityRole, "presentation" | "none">;
 }
+/**
+ * The shared properties for the icon component. An icon displays a graphical symbol with configurable appearance, color, and semantic meaning.
+ */
 interface IconProps$1 extends GlobalProps, Pick<InteractionProps, "interestFor"> {
 	/**
-	 * Sets the tone of the icon, based on the intention of the information being conveyed.
+	 * The semantic meaning and color treatment of the icon.
+	 *
+	 * - `'info'`: Informational content or helpful tips.
+	 * - `'auto'`: Automatically determined based on context.
+	 * - `'neutral'`: General information without specific intent.
+	 * - `'success'`: Positive outcomes or successful states.
+	 * - `'warning'`: Important warnings about potential issues.
+	 * - `'critical'`: Urgent problems or destructive actions.
+	 * - `'custom'`: Inherits a custom color from its parent element's CSS.
 	 *
 	 * @default 'auto'
 	 */
 	tone?: ToneKeyword;
 	/**
-	 * Modify the color to be more or less intense.
+	 * The color intensity of the icon. Use `'subdued'` for less intense, or `'base'` for standard coloring.
 	 *
 	 * @default 'base'
 	 */
 	color?: ColorKeyword;
 	/**
-	 * Adjusts the size of the icon.
+	 * The size of the icon.
+	 *
+	 * - `'base'`: Default size that works well for most use cases.
+	 * - `'small'`: Small icon for inline use within text or compact UI elements.
+	 * - `'small-200'`: Extra small icon for the most compact contexts.
+	 * - `'small-100'`: Small icon suitable for tight or dense layouts.
+	 * - `'large'`: Large icon for emphasis or prominent display.
+	 * - `'large-100'`: Extra large icon for maximum visual impact.
 	 *
 	 * @default 'base'
 	 */
 	size?: SizeKeyword;
+	/**
+	 * The icon to display. Can be any icon name from the icon library or a custom string identifier.
+	 */
 	type?: IconType | AnyString;
 }
+/**
+ * The shared base properties for image-based components. These properties are common to all components that display images, including the image and product thumbnail components. Properties include `alt` for accessibility text, `src` for the image URL, `sizes` for responsive sizing hints, and `srcSet` for multiple image sources.
+ */
 export interface BaseImageProps {
 	/**
-	 * An alternative text description that describe the image for the reader to
-	 * understand what it is about. It is extremely useful for both users using
-	 * assistive technology and sighted users. A well written description
-	 * provides people with visual impairments the ability to participate in
-	 * consuming non-text content. When a screen readers encounters an `s-image`,
-	 * the description is read and announced aloud. If an image fails to load,
-	 * potentially due to a poor connection, the `alt` is displayed on
-	 * screen instead. This has the benefit of letting a sighted buyer know an
-	 * image was meant to load here, but as an alternative, they’re still able to
-	 * consume the text content. Read
-	 * [considerations when writing alternative text](https://www.shopify.com/ca/blog/image-alt-text#4)
-	 * to learn more.
-	 *
-	 * @default `''`
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt
+	 * Alternative text that describes the image for accessibility.
+	 *
+	 * Provides a text description of the image for users with assistive technology
+	 * and serves as a fallback when the image fails to load. A well-written description
+	 * enables people with visual impairments to understand non-text content.
+	 *
+	 * When a screen reader encounters an image, it reads this description aloud.
+	 * When an image fails to load, this text displays on screen, helping all users
+	 * understand what content was intended.
+	 *
+	 * Learn more about [writing effective alt text](https://www.shopify.com/ca/blog/image-alt-text#4)
+	 * and the [alt attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt).
+	 *
+	 * @default ''
 	 */
 	alt?: string;
 	/**
-	 * A set of media conditions and their corresponding sizes.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes
+	 * A set of media conditions and their corresponding sizes. Learn more about the [sizes attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes).
 	 */
 	sizes?: string;
 	/**
 	 * The image source (either a remote URL or a local file resource).
 	 *
-	 * When the image is loading or no `src` is provided, a placeholder will be rendered.
-	 *
-	 * @implementation Surfaces may choose the style of the placeholder, but the space the image occupies should be
-	 * reserved, except in cases where the image area does not have a contextual inline or block size, which should be rare.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#src
+	 * When the image is loading or no `src` is provided, a placeholder is rendered.
+	 * Learn more about the [src attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#src).
 	 */
 	src?: string;
 	/**
-	 * A set of image sources and their width or pixel density descriptors.
-	 *
-	 * This overrides the `src` property.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#srcset
+	 * A set of image sources and their width or pixel density descriptors. Learn more about the [srcset attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#srcset). This overrides the `src` property.
 	 */
 	srcSet?: string;
 }
+/**
+ * The shared properties for the image component. An image displays pictures with configurable sizing, loading behavior, and borders.
+ */
 interface ImageProps$1 extends GlobalProps, BaseImageProps, BorderProps {
 	/**
-	 * Sets the semantic meaning of the component’s content. When set,
+	 * Sets the semantic meaning of the image content. When set,
 	 * the role will be used by assistive technologies to help users
 	 * navigate the page.
 	 *
-	 * @default 'img'
+	 * - `'img'`: Identifies the element as an image that conveys meaningful information to users.
+	 * - `'none'`: Completely hides the element and its content from assistive technologies.
+	 * - `'presentation'`: Removes semantic meaning, making the image purely decorative and ignored by screen readers.
 	 *
-	 * @implementation The `img` role doesn't need to be applied if
-	 * the host applies it for you; for example, an HTML host rendering
-	 * an `<img>` element should not apply the `img` role.
+	 * @default 'img'
 	 */
 	accessibilityRole?: "img" | ExtractStrict<AccessibilityRole, "presentation" | "none">;
 	/**
-	 * The displayed inline width of the image.
+	 * The inline width (horizontal size) of the image.
 	 *
-	 * - `fill`: the image will takes up 100% of the available inline size.
-	 * - `auto`: the image will be displayed at its natural size.
+	 * - `'fill'`: The image takes up 100% of the available inline space.
+	 * - `'auto'`: The image is displayed at its natural size.
 	 *
-	 * @default 'fill'
+	 * Learn more about the [width attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#width).
 	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#width
+	 * @default 'fill'
 	 */
 	inlineSize?: "fill" | "auto";
 	/**
@@ -2628,67 +2672,59 @@ interface ImageProps$1 extends GlobalProps, BaseImageProps, BorderProps {
 	 * - `inlineSize="fill"`: the aspect ratio will be respected and the image will take the necessary space.
 	 * - `inlineSize="auto"`: the image will not render until it has loaded and the aspect ratio will be ignored.
 	 *
-	 * For example, if the value is set as `50 / 100`, the getter returns `50 / 100`.
-	 * If the value is set as `0.5`, the getter returns `0.5 / 1`.
+	 * Learn more about the [aspect-ratio property](https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio).
 	 *
 	 * @default '1/1'
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio
 	 */
 	aspectRatio?: `${number}${optionalSpace}/${optionalSpace}${number}` | `${number}`;
 	/**
-	 * Determines how the content of the image is resized to fit its container.
-	 * The image is positioned in the center of the container.
+	 * How the image should be resized to fit its container. The image is positioned in the center of the container. Learn more about the [object-fit property](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit).
 	 *
-	 * @default 'contain'
+	 * - `'contain'`: Fits the entire image within the container, preserving aspect ratio. May leave empty space.
+	 * - `'cover'`: Fills the container while preserving aspect ratio, cropping the image if needed.
 	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit
+	 * @default 'contain'
 	 */
 	objectFit?: "contain" | "cover";
 	/**
 	 * Determines the loading behavior of the image:
-	 * - `eager`: Immediately loads the image, irrespective of its position within the visible viewport.
-	 * - `lazy`: Delays loading the image until it approaches a specified distance from the viewport.
+	 * - `'eager'`: Immediately loads the image, irrespective of its position within the visible viewport.
+	 * - `'lazy'`: Delays loading the image until it approaches a specified distance from the viewport.
+	 *
+	 * Learn more about the [loading attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#loading).
 	 *
 	 * @default 'eager'
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#loading
 	 */
 	loading?: "eager" | "lazy";
 	/**
-	 * Invoked when load completes successfully.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onload
+	 * A callback fired when the image loads successfully. Learn more about the [load event](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onload).
 	 */
 	onLoad?: (event: Event) => void;
 	/**
-	 * Invoked on load error.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onerror
+	 * A callback fired when the image fails to load. Learn more about the [error event](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onerror).
 	 */
 	onError?: (event: Event) => void;
 }
 interface LinkProps$1 extends GlobalProps, LinkBehaviorProps {
 	/**
-	 * The content of the Link.
+	 * The text or elements displayed as the link's content.
 	 */
 	children?: ComponentChildren;
 	/**
-	 * Sets the tone of the Link, based on the intention of the information being conveyed.
+	 * The semantic meaning and color treatment of the link.
+	 *
+	 * - `'auto'`: Automatically determined based on context.
+	 * - `'neutral'`: Removes the default link color, inheriting the surrounding text style.
 	 *
 	 * @default 'auto'
 	 */
 	tone?: ToneKeyword;
 	/**
-	 * A label that describes the purpose or contents of the Link. It will be read to users using assistive technologies such as screen readers.
-	 *
-	 * Use this when using only an icon or the content of the link is not enough context
-	 * for users using assistive technologies.
+	 * A label that describes the purpose or content of the link for users of assistive technologies such as screen readers.
 	 */
 	accessibilityLabel?: string;
 	/**
-	 * Indicate the text language. Useful when the text is in a different language than the rest of the page.
-	 * It will allow assistive technologies such as screen readers to invoke the correct pronunciation.
-	 * [Reference of values](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) ("subtag" label)
+	 * The language of the link's text content. Use this when the link text is in a different language than the rest of the page.
 	 */
 	lang?: string;
 }
@@ -2700,166 +2736,186 @@ interface ListItemProps$1 extends GlobalProps {
 }
 interface MapProps$1 extends GlobalProps, SizingProps {
 	/**
-	 * A valid API key for the map service provider.
-	 *
-	 * The map service provider may require an API key. Without an API key the map could be hidden or render in a limited developer mode.
+	 * A valid API key for the map service provider. This key is required to load and render the map tiles. Obtain a key from a supported provider such as [Google Maps Platform](https://developers.google.com/maps/documentation/javascript/get-api-key).
 	 */
 	apiKey?: string;
 	/**
-	 * Map center’s latitude in degrees.
+	 * The latitude of the map's center point, in degrees. Valid values range from -90 (South Pole) to 90 (North Pole).
 	 *
 	 * @default 0
 	 */
 	latitude?: number;
 	/**
-	 * Map center’s longitude in degrees.
+	 * The longitude of the map's center point, in degrees. Valid values range from -180 (west) to 180 (east).
 	 *
 	 * @default 0
 	 */
 	longitude?: number;
 	/**
-	 * A label that describes the purpose or contents of the map.
-	 *
-	 * When set, it will be announced to users using assistive technologies and will provide them with more context.
+	 * A label that describes the purpose or contents of the map for accessibility. When set, it will be announced to users using assistive technologies such as screen readers, providing context about what the map displays.
 	 */
 	accessibilityLabel?: string;
 	/**
-	 * The initial Map zoom level.
-	 *
-	 * Valid zoom values are numbers from zero up to 18.
-	 * Larger zoom values correspond to a higher resolution.
+	 * The initial zoom level of the map. Valid values are numbers from 0 (fully zoomed out, world view) to 18 (fully zoomed in, street level).
 	 *
 	 * @default 4
 	 */
 	zoom?: number;
 	/**
-	 * The maximum zoom level which will be displayed on the map.
-	 *
-	 * Valid zoom values are numbers from zero up to 18.
+	 * The maximum zoom level the user can reach on the map. Valid values are numbers from 0 (world view) to 18 (street level). Use this to prevent users from zooming in beyond a useful level of detail.
 	 *
 	 * @default 18
 	 */
 	maxZoom?: number;
 	/**
-	 * The minimum zoom level which will be displayed on the map.
-	 *
-	 * Valid zoom values are numbers from zero up to 18.
+	 * The minimum zoom level the user can reach on the map. Valid values are numbers from 0 (world view) to 18 (street level). Use this to prevent users from zooming out beyond a useful level of context.
 	 *
 	 * @default 0
 	 */
 	minZoom?: number;
 	/**
-	 * Callback when the viewport bounds have changed or the map is resized.
+	 * A callback fired when the visible map boundaries change, such as after a pan or zoom completes.
 	 */
 	onBoundsChange?: (event: MapBoundsChangeEvent) => void;
 	/**
-	 * Callback when the map view changes.
+	 * A callback fired when the map view changes, such as when the user pans or zooms. Provides the new center location and zoom level.
 	 */
 	onViewChange?: (event: MapViewChangeEvent) => void;
 	/**
-	 * Callback when the user clicks on the map.
+	 * A callback fired when the user clicks on the map. Provides the geographic location of the click.
 	 */
 	onClick?: (event: MapClickEvent) => void;
 	/**
-	 * Callback when the user double-clicks on the map.
+	 * A callback fired when the user double-clicks on the map. Provides the geographic location of the double-click.
 	 */
 	onDblClick?: (event: MapDblClickEvent) => void;
 }
+/**
+ * A geographic coordinate pair representing a location on the map, defined by latitude and longitude values.
+ */
 interface Location$1 {
+	/**
+	 * The latitude of the location in degrees. Valid values range from -90 (South Pole) to 90 (North Pole).
+	 */
 	latitude?: number;
+	/**
+	 * The longitude of the location in degrees. Valid values range from -180 (west) to 180 (east).
+	 */
 	longitude?: number;
 }
+/**
+ * The geographic boundaries of a visible map area, defined by its north-east and south-west corners. Used by `MapBoundsChangeEvent` to report the currently visible map region.
+ */
 export interface Bounds {
+	/**
+	 * The north-east corner of the bounded area, representing the top-right of the visible map region.
+	 */
 	northEast?: Location$1;
+	/**
+	 * The south-west corner of the bounded area, representing the bottom-left of the visible map region.
+	 */
 	southWest?: Location$1;
 }
+/**
+ * The event data provided when the map view changes, such as after the user pans or zooms. Contains the new center location and zoom level.
+ */
 export interface MapViewChangeEvent extends Event {
+	/**
+	 * The geographic location of the new map center after the view change.
+	 */
 	location?: Location$1;
+	/**
+	 * The current zoom level of the map after the view change, as a number from 0 (world view) to 18 (street level).
+	 */
 	zoom?: number;
 }
+/**
+ * The event data provided when the visible map boundaries change, such as after a pan or zoom completes. Contains the new geographic bounds of the visible area.
+ */
 export interface MapBoundsChangeEvent extends Event {
+	/**
+	 * The geographic boundaries of the currently visible map area, defined by its north-east and south-west corners.
+	 */
 	bounds?: Bounds;
 }
+/**
+ * The event data provided when the user clicks on the map. Contains the geographic location of the click.
+ */
 export interface MapClickEvent extends Event {
+	/**
+	 * The geographic location on the map where the click occurred, as a latitude/longitude coordinate pair.
+	 */
 	location?: Location$1;
 }
+/**
+ * The event data provided when the user double-clicks on the map. Contains the geographic location of the double-click.
+ */
 export interface MapDblClickEvent extends Event {
+	/**
+	 * The geographic location on the map where the double-click occurred, as a latitude/longitude coordinate pair.
+	 */
 	location?: Location$1;
 }
 interface MapMarkerProps$1 extends GlobalProps, InteractionProps, Pick<SizingProps, "blockSize" | "inlineSize"> {
 	/**
-	 * Marker’s location latitude in degrees.
+	 * The latitude of the marker’s position in degrees. Valid values range from -90 (South Pole) to 90 (North Pole).
 	 *
 	 * @default 0
 	 */
 	latitude?: number;
 	/**
-	 * Marker’s longitude latitude in degrees.
+	 * The longitude of the marker’s position in degrees. Valid values range from -180 (west) to 180 (east).
 	 *
 	 * @default 0
 	 */
 	longitude?: number;
 	/**
-	 * A label that describes the purpose of the marker. When set,
-	 * it will be announced to users using assistive technologies and will
-	 * provide them with more context.
+	 * A label that describes the purpose or location of the marker for accessibility. When set, it will be announced to users using assistive technologies such as screen readers, providing context about what the marker represents.
 	 */
 	accessibilityLabel?: string;
 	/**
-	 * Allows grouping the marker in clusters when zoomed out.
+	 * Whether the marker can be grouped into clusters when the map is zoomed out. Clustering helps reduce visual clutter when many markers are close together at low zoom levels.
 	 *
 	 * @default false
 	 */
 	clusterable?: boolean;
 	/**
-	 * The graphic to use as the marker.
-	 *
-	 * If unset, it will default to the provider’s default marker.
+	 * A custom graphic element to use as the marker. If not provided, the map provider’s default marker pin is displayed.
 	 */
 	graphic?: ComponentChildren;
 	/**
-	 * Callback when a marker is clicked.
-	 *
-	 * It does not trigger a click event on the map itself.
+	 * A callback fired when the user clicks on the marker. This event does not propagate to the parent map — only the marker receives the click.
 	 */
 	onClick?: (event: Event) => void;
 }
 interface ModalProps$1 extends GlobalProps, BaseOverlayProps, BaseOverlayMethods, ActionSlots {
 	/**
-	 * A label that describes the purpose of the modal. When set,
-	 * it will be announced to users using assistive technologies and will
-	 * provide them with more context.
-	 *
-	 * This overrides the `heading` prop for screen readers.
+	 * A label that describes the purpose of the modal, announced by assistive technologies. When set, screen readers will use this label instead of the `heading` to describe the modal.
 	 */
 	accessibilityLabel?: string;
 	/**
-	 * A title that describes the content of the Modal.
-	 *
+	 * A title that describes the content of the modal.
 	 */
 	heading?: string;
 	/**
-	 * Adjust the padding around the Modal content.
+	 * Adjust the padding around the modal content.
 	 *
-	 * `base`: applies padding that is appropriate for the element.
-	 *
-	 * `none`: removes all padding from the element. This can be useful when elements inside the Modal need to span
-	 * to the edge of the Modal. For example, a full-width image. In this case, rely on `Box` with a padding of 'base'
-	 * to bring back the desired padding for the rest of the content.
+	 * - `base`: Applies padding that is appropriate for the element.
+	 * - `none`: Removes all padding from the element. This can be useful when elements inside the modal need to span to the edge of the modal. For example, a full-width image. In this case, rely on box with a padding of `base` to bring back the desired padding for the rest of the content.
 	 *
 	 * @default 'base'
 	 */
 	padding?: "base" | "none";
 	/**
-	 * Adjust the size of the Modal.
+	 * Adjust the size of the modal.
 	 *
-	 * `max`: expands the Modal to its maximum size as defined by the host application, on both the horizontal and vertical axes.
+	 * `max`: Expands the modal to its maximum size as defined by the host application, on both the horizontal and vertical axes.
 	 *
 	 * @default 'base'
 	 */
 	size?: SizeKeyword | "max";
 	/**
-	 * The content of the Modal.
+	 * The content of the modal.
 	 */
 	children?: ComponentChildren;
 }
@@ -2868,9 +2924,13 @@ interface MoneyFieldProps$1 extends GlobalProps, BaseTextFieldProps, NumberConst
 export type MoneyAutocompleteField = ExtractStrict<AnyAutocompleteField, "transaction-amount">;
 interface NumberFieldProps$1 extends GlobalProps, BaseTextFieldProps, AutocompleteProps<NumberAutocompleteField>, NumberConstraintsProps, FieldDecorationProps {
 	/**
-	 * Sets the virtual keyboard.
+	 * Sets the virtual keyboard layout for the field.
+	 *
+	 * - `'decimal'`: A numeric keyboard with a decimal point, suitable for decimal numbers.
+	 * - `'numeric'`: A numeric keyboard without a decimal point, suitable for integers.
+	 *
+	 * Learn more about the [inputMode attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inputmode).
 	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inputmode
 	 * @default 'decimal'
 	 */
 	inputMode?: "decimal" | "numeric";
@@ -2919,26 +2979,28 @@ export type ParagraphType =
 interface PasswordFieldProps$1 extends GlobalProps, BaseTextFieldProps, MinMaxLengthProps, AutocompleteProps<PasswordAutocompleteField> {
 }
 export type PasswordAutocompleteField = ExtractStrict<AnyAutocompleteField, "new-password" | "current-password">;
+/**
+ * The shared properties for the payment icon component. A payment icon displays a recognizable icon for a payment method, such as Visa, Mastercard, or PayPal.
+ */
 interface PaymentIconProps$1 extends GlobalProps {
 	/**
-	 * The icon type of the payment method
+	 * The payment method to display. Specify a payment method name from the available set (for example, `'visa'`, `'mastercard'`, or `'paypal'`), or use an empty string to show no icon.
 	 *
 	 * @default ''
 	 */
 	type?: PaymentIconName | AnyString;
 	/**
-	 * A label that describes the purpose or contents of the icon.
-	 *
-	 * When set, it will be announced to users using assistive technologies and will provide them with more context.
-	 * This should only be used if the icon requires an alternative internationalised label
-	 * or if it is otherwise inappropriate to make use of the default label included with the icon.
+	 * A label that describes the payment icon for accessibility. When set, it will be announced to users using assistive technologies such as screen readers, providing context about which payment method the icon represents.
 	 */
 	accessibilityLabel?: string;
 }
+/**
+ * The recognized payment method identifiers used by the `PaymentIcon` component. Each value maps to a branded icon for a specific payment provider, card network, digital wallet, or buy-now-pay-later service. Pass one of these names as the `type` property of `PaymentIcon` to display the corresponding icon — for example, `"visa"`, `"apple-pay"`, or `"afterpay"`.
+ */
 export type PaymentIconName = "abn" | "acima-leasing" | "acuotaz" | "ada" | "addi" | "adyen" | "aeropay" | "affin-bank" | "affirm" | "aftee" | "afterpay-paynl-version" | "afterpay" | "airtel-money" | "airteltigo-mobile-money" | "aktia" | "akulaku-paylater" | "akulaku" | "alandsbanken" | "alfamart" | "alfamidi" | "alipay-hk" | "alipay-paynl-version" | "alipay" | "alliance-bank" | "alma" | "aman" | "amazon" | "ambank" | "american-express" | "amex" | "ansa-stored-value" | "ansa" | "anyday" | "apecoin" | "aplazo" | "apple-pay" | "aqsat" | "arbitrum" | "arhaus" | "arvato" | "ashley-plcc" | "ask" | "astrapay" | "atm-bersama" | "atobaraidotcom" | "atome" | "atone" | "atrato" | "au-kantan-kessai" | "au-pay" | "authorize-net" | "avalanche" | "axs" | "bancnet" | "banco-azteca" | "bancomat" | "bancontact" | "bangkok-bank" | "bank-islam" | "bank-muamalat" | "bank-rakyat" | "barclays" | "base" | "bbva-cie" | "bc-card" | "bca-klikpay" | "bca" | "bdo" | "belfius" | "benefit" | "best-buy-card" | "biercheque-paynl-version" | "bigc" | "billease" | "biller-paynl-version" | "billie" | "billink-method" | "billink" | "bitcoin-cash" | "bitcoin" | "bizum" | "blik" | "bnbchain" | "bni" | "bnp" | "bogus-app-coin" | "bogus" | "boleto" | "boodil" | "boost" | "bpi" | "braintree" | "bread-pay" | "bread" | "bri-direct-debit" | "bri" | "brimo" | "bsi" | "bsn" | "bss" | "busd" | "careem-pay" | "cartes-bancaires" | "cash-app-pay" | "cash" | "cashew" | "cashinvoice-latin-america" | "catch-payments" | "cebuana" | "cembrapay" | "centi" | "cetelem" | "checkout-finance" | "chinabank" | "cimb-clicks" | "cimb" | "circle-k" | "citadele" | "citi-pay" | "clave-telered" | "clearpay" | "clerq" | "cleverpay" | "clip" | "cliq" | "codensa" | "coinsph" | "collector-bank" | "coop" | "coppel-pay" | "credit-agricole" | "credit-key" | "creditclick-paynl-version" | "credix" | "cuotas" | "d-barai" | "dai" | "daily-yamazaki" | "dan-dan" | "dana" | "danamon-online" | "dankort" | "danske-bank" | "dappmx" | "dash" | "daviplata" | "de-cadeaukaart" | "depay" | "deutsche-bank" | "dinacard" | "diners-club" | "direct-bank-transfer-latin-america" | "directa24" | "directpay" | "discover" | "divido" | "dnb" | "docomo-barai" | "dogecoin" | "dropp" | "duitnow" | "duologi" | "dwolla" | "easywallet" | "ebucks" | "echelon-financing" | "ecpay" | "edenred" | "efecty" | "eft-secure" | "eftpos-au" | "eghl" | "elo" | "elv" | "empty" | "enets" | "eos" | "epayments" | "epospay" | "eps" | "erste" | "escrowcom" | "esr-paymentslip-switzerland" | "ethereum" | "etihad-guest-pay" | "etika" | "ewallet-indonesia" | "ewallet-philippines" | "ewallet-southkorea" | "facebook-pay" | "fairstone-payments" | "fam" | "familymart" | "fantom" | "farmlands" | "fashion-giftcard-paynlversion" | "fashioncheque" | "favepay" | "fawry" | "finloup" | "fintecture" | "fintoc" | "flexiti" | "float-payments" | "flying-blue-plus" | "forbrugsforeningen" | "forsa" | "fortiva" | "fps" | "fpx" | "freecharge" | "freedompay" | "futurepay-mytab" | "gcash" | "generalfinancing" | "generic" | "genoapay" | "gezondheidsbon-paynl-version" | "giftcard" | "giropay" | "givacard" | "glbe-paypal" | "glbe-plus" | "gmo-atokara" | "gmo-bank-transfer" | "gmo-postpay" | "gmo-virtualaccount" | "gnosis" | "google-pay" | "google-wallet" | "gopay" | "grabpay" | "grailpay" | "gusd" | "hana-card" | "handelsbanken" | "happy-pay" | "hello-clever" | "heylight" | "hitrustpay-transfer" | "home-credit" | "hong-leong-bank" | "hong-leong-connect" | "hsbc" | "huis-tuin-cadeau" | "humm" | "hyper" | "hypercard" | "hypercash" | "hyundai-card" | "ibexpay" | "ideal" | "in3-via-ideal" | "in3" | "inbank" | "indomaret" | "ing-homepay" | "interac" | "ivy" | "iwocapay-pay-later" | "jcb" | "jenius" | "jko" | "jousto" | "kakao-pay" | "kakebaraidotcom" | "kasikornbank" | "kasssh" | "katapult" | "kb-card" | "kbc-cbc" | "kcp-credit-card" | "kfast" | "khqr" | "klarna-pay-later" | "klarna-pay-now" | "klarna-slice-it" | "klarna" | "knaken-settle" | "knet" | "koalafi" | "koin" | "krediidipank" | "kredivo" | "krungsri" | "krungthai-bank" | "kueski-pay" | "kunst-en-cultuur-cadeaukaart" | "kuwait-finance-house" | "land-bank" | "laser" | "latitude-creditline-au" | "latitude-gem-au" | "latitude-gem-nz" | "latitude-go-au" | "latitudepay" | "lawson" | "laybuy-heart" | "laybuy" | "lbc" | "lhv" | "line-pay" | "linkaja" | "linkpay" | "litecoin" | "lku" | "lloyds" | "lotte-card" | "lpb" | "luminor" | "lunch-check" | "lydia" | "mach" | "mada" | "maestro" | "mandiri" | "mash" | "master" | "mastercard" | "masterpass" | "maxima" | "maya-bank" | "maya" | "maybank-qrpay" | "maybank" | "maybankm2u" | "mb-way" | "mb" | "mcash" | "medicinos-bankas" | "meeza" | "mercado-credito" | "mercado-pago" | "merpay" | "meta-pay" | "metro-bank" | "military-starcard" | "minicuotas" | "ministop" | "mobicred" | "mobikwik" | "mobilepay" | "mode" | "mokka" | "momopay" | "mondido" | "monero" | "monzo" | "mpesa" | "mtn-mobile-money" | "multisafepay" | "mybank" | "myfatoorah" | "n26" | "naps" | "nationale-bioscoopbon" | "nationale-entertainmentcard" | "natwest" | "naver-pay" | "nelo" | "nequi" | "netbanking" | "neteller" | "nh-card" | "nordea" | "notyd" | "novuna" | "npatobarai" | "npkakebarai" | "oca" | "ocbc-bank" | "octo-clicks" | "octopus" | "offline-bank-transfer-latin-america" | "ola-money" | "omannet" | "omasp" | "oney" | "online-banking" | "online-banktransfer" | "op" | "opay" | "openpay" | "optimism" | "orange-mobile-money" | "overstock-citicobrand" | "overstock-citiplcc" | "ovo" | "oxxo" | "ozow" | "pagoefectivo" | "paid" | "paidy" | "palawa" | "palawan" | "pastpay" | "pay-after-delivery-instalments" | "pay-by-bank-us" | "pay-by-bank" | "pay-easy" | "pay-pay" | "paybylink" | "paycash" | "payco" | "payconiq" | "payd" | "payfast-instant-eft" | "payflex" | "payid" | "payitmonthly" | "payjustnow" | "paymark-online-eftpos" | "paymaya" | "payme" | "paynow-mbank" | "paynow" | "payoo-qr" | "payoo" | "paypal" | "payplan" | "paypo" | "payrexx-bank-transfer" | "payright" | "paysafecard-paynl-version" | "paysafecard" | "paysafecash" | "paysera" | "paysquad" | "paytm" | "payto" | "paytomorrow" | "payu" | "payzapp" | "pei" | "perlasfinance" | "permata" | "pf-pay" | "pivo" | "pix" | "podium-cadeaukaart" | "pointspay" | "poli" | "polygon" | "poppankki" | "postfinance-card" | "postfinance-efinance" | "postpay" | "powered-by-ansa-stored-value" | "powered-by-ansa" | "powerpay" | "pps" | "prepaysolutions" | "progressive-leasing" | "przelew24" | "przelewy24-paynl-version" | "przelewy24" | "pse" | "public-bank" | "publicbank-pbe" | "qasitli" | "qliro" | "qr-promptpay" | "qris" | "qrph" | "rabbit-line-pay" | "rabobank" | "rakuten-pay" | "rapid-transfer" | "ratepay" | "raty-pekao" | "rcbc" | "rcs" | "reka" | "resolve-pay" | "revolut" | "rhb-bank" | "rhb-now" | "rietumu" | "riverty-paynl-version" | "riverty" | "rupay" | "saastopankki" | "sadad" | "sam" | "samsung-card" | "samsung-pay" | "santander" | "satisfi" | "satispay" | "sbpl" | "scalapay" | "scream-truck-wallet" | "scream-truck" | "seb" | "seicomart" | "sepa-bank-transfer" | "sepa-direct-debit" | "sequra" | "seven-eleven" | "sezzle" | "shib" | "shinhan-card" | "shop-pay" | "shopeepay" | "shopify-pay" | "siam-commercial" | "siauliu-bankas" | "siirto" | "sika-fsa" | "sika-hsa" | "sika" | "simpl" | "simple-pay" | "sinpe-movil" | "sistecredito" | "skeps" | "skrill-digital-wallet" | "slice-fnbo" | "smartpay" | "snap-checkout" | "snapmint" | "societe-generale" | "sofort" | "softbank" | "solana-pay-helio" | "solana-pay" | "solana" | "souhoola" | "spankki" | "sparkasse" | "spei" | "splitit" | "spotii" | "spraypay" | "standard-chartered" | "stc-pay" | "stoov" | "store-credit" | "stripe" | "sunkus" | "super-payments" | "svea-b2b-faktura" | "svea-b2b-invoice" | "svea-checkout" | "svea-credit-account" | "svea-delbetalning" | "svea-faktura" | "svea-invoice" | "svea-lasku" | "svea-ostukonto" | "svea-part-payment" | "svea-yrityslasku" | "sveaeramaksu" | "swedbank" | "swiftpay" | "swish" | "swissbilling" | "sympl" | "synchrony-pay" | "synchrony" | "tabby" | "tabit" | "taly" | "tamara" | "tandympayment" | "tasa-cero" | "tbi-bank" | "tcf" | "tendopay" | "tensile" | "tesco-lotus" | "thanachart-bank" | "timepayment" | "tiptop" | "todopay" | "toss" | "touch-n-go" | "tpay" | "trevipay" | "truelayer" | "truemoney-pay" | "trustly" | "twig-pay" | "twint" | "twoinvoice" | "uae-visa" | "uangme" | "ubp" | "underpay" | "unionpay" | "unipay" | "uob-ez-pay" | "uob-thai" | "uob" | "upi" | "urbo" | "urpay" | "usdc" | "usdp" | "v-pay" | "valu" | "venmo" | "ventipay" | "venus-plcc" | "viabill" | "vipps" | "visa-electron" | "visa" | "volksbank" | "volt" | "vvv-cadeaukaart-paynl-version" | "vvv-giftcard" | "waave-pay-by-bank" | "wallet" | "walley" | "wbtc" | "webshop-giftcard" | "wechat-pay" | "wechat-paynl-version" | "wegetfinancing" | "whish-checkout" | "whish-pay" | "wise" | "wissel" | "world-chain" | "xrp" | "yape" | "yappy" | "ymobile" | "younited-pay" | "zalopay" | "zapper" | "zingala" | "zinia" | "zip" | "zoodpay" | "zulily-credit-card" | "zustaina";
 interface PopoverProps$1 extends GlobalProps, BaseOverlayProps, BaseOverlayMethods, ToggleEventProps, SizingProps {
 	/**
-	 * The content of the popover.
+	 * The content displayed within the popover, which appears in an overlay positioned relative to its trigger element.
 	 */
 	children?: ComponentChildren;
 }
@@ -2958,178 +3020,150 @@ interface PressButtonProps$1 extends GlobalProps, Pick<ButtonProps$1, "accessibi
 	 */
 	defaultPressed?: boolean;
 }
+/**
+ * The shared properties for the product thumbnail component. A product thumbnail displays a small preview image representing a product. Properties include `src` for the image URL, `alt` for accessibility text, `size` for controlling the thumbnail dimensions, and `totalItems` for displaying a quantity badge.
+ */
 interface ProductThumbnailProps$1 extends GlobalProps, BaseImageProps {
 	/**
-	 * Decorates the product thumbnail with the quantity of the product.
+	 * The total number of items that the product thumbnail represents. When this value exceeds 1, the component displays a badge showing the count, useful for representing bundled products or quantities.
 	 */
 	totalItems?: number;
 	/**
-	 * Adjusts the size the product thumbnail image.
+	 * The size of the product thumbnail image.
+	 *
+	 * - `'base'`: Default size that works well in most contexts.
+	 * - `'small'`: Small thumbnail, good for secondary contexts or tight layouts.
+	 * - `'small-100'`: Extra small thumbnail for compact displays or dense lists.
 	 *
 	 * @default 'base'
 	 */
 	size?: SizeKeyword;
 	/**
-	 * Invoked when load of provided image completes successfully.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onload
+	 * A callback fired when the product thumbnail image loads successfully. Learn more about the [load event](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onload).
 	 */
 	onLoad?: (event: Event) => void;
 	/**
-	 * Invoked on load error of provided image.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onerror
+	 * A callback fired when the product thumbnail image fails to load. Learn more about the [error event](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onerror).
 	 */
 	onError?: (event: Event) => void;
 }
 interface ProgressProps$1 extends GlobalProps {
 	/**
-	 * A label that describes the purpose of the progress. When set,
-	 * it will be announced to users using assistive technologies and will
-	 * provide them with more context.
-	 *
-	 * Use it to provide context of what is progressing.
+	 * A label announced by assistive technologies that describes what is progressing. Use this to provide context about the ongoing task, such as "Loading order details" or "Uploading file".
 	 */
 	accessibilityLabel?: string;
 	/**
-	 * Sets the tone of the progress, based on the intention of the information being conveyed.
+	 * The semantic meaning and color treatment of the progress indicator.
 	 *
 	 * @default 'auto'
 	 */
 	tone?: ToneKeyword;
 	/**
-	 * Specifies how much of the task has been completed.
-	 *
-	 * It must be a valid floating point number between 0 and `max`, or between 0 and 1 if `max` is omitted.
-	 * If there is no value attribute, the progress bar is indeterminate;
-	 * this indicates that an activity is ongoing with no indication of how long it is expected to take.
+	 * How much of the task has been completed. Must be a valid floating point number between 0 and `max`, or between 0 and 1 if `max` is omitted. When no value is set, the progress bar is indeterminate, indicating an ongoing activity with no estimated completion time.
 	 *
-	 * @implementation Surfaces should apply styling to cover that indeterminate state.
-	 * @implementation In a HTML host, you can customize the progress animation via the :indeterminate pseudo-class.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/progress#value
-	 * @see https://developer.mozilla.org/en-US/docs/Web/CSS/:indeterminate#progress_bar
+	 * Learn more about the [value attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/progress#value).
 	 */
 	value?: number;
 	/**
-	 * This attribute describes how much work the task indicated by the progress element requires.
+	 * The total amount of work the task requires. Must be a value greater than 0 and a valid floating point number.
 	 *
-	 * The `max` attribute, if present, must have a value greater than 0 and be a valid floating point number.
+	 * Learn more about the [max attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/progress#max).
 	 *
 	 * @default 1
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/progress#max
 	 */
 	max?: number;
 }
+/**
+ * The shared properties for the QR code component. A QR code generates and displays a scannable matrix barcode from a given string. Properties include `content` for the data to encode, `size` for display dimensions, `border` for visual framing, and `logo` for branding.
+ */
 interface QRCodeProps$1 extends GlobalProps {
 	/**
-	 * Set the border of the QR code.
+	 * Whether to display a border around the QR code.
 	 *
-	 * `base`: applies border that is appropriate for the element.
-	 * `none`: removes the border from the element.
+	 * - `'base'`: Applies a standard border to frame the QR code.
+	 * - `'none'`: Removes the border for seamless integration with the surrounding layout.
 	 *
 	 * @default 'base'
 	 */
 	border?: "base" | "none";
 	/**
-	 * The content to be encoded in the QR code, which can be any string such as a URL, email address, plain text, etc.
-	 * Specific string formatting can trigger actions on the user's device when scanned, like opening geolocation
-	 * coordinates on a map, opening a preferred app or app store entry, preparing an email, text message, and more.
+	 * The content to be encoded in the QR code, such as a URL, email address, or plain text. When scanned, the user's device will process this content — typically by opening a URL in a browser or prompting an action based on the content type.
 	 */
 	content?: string;
 	/**
 	 * The displayed size of the QR code.
 	 *
-	 * `fill`: the QR code will takes up 100% of the available inline-size and maintain a 1:1 aspect ratio.
-	 * `base`: the QR code will be displayed at its default size.
+	 * - `'base'`: The QR code is displayed at its default fixed size.
+	 * - `'fill'`: The QR code takes up 100% of the available inline size, useful for responsive layouts.
 	 *
 	 * @default 'base'
 	 */
 	size?: "base" | "fill";
 	/**
-	 * A label that describes the purpose or contents of the QR code. When set,
-	 * it will be announced to users using assistive technologies and will
-	 * provide more context about what the QR code may do when scanned.
+	 * A label that describes the purpose or contents of the QR code for accessibility. When set, it will be announced to users using assistive technologies such as screen readers.
 	 *
 	 * @default 'QR code' (translated to the user's locale)
 	 */
 	accessibilityLabel?: string;
 	/**
-	 * Invoked when the conversion of `content` to a QR code fails.
-	 * If an error occurs, the QR code and its child elements will not be displayed.
+	 * A callback fired when the conversion of `content` to a QR code fails. This can happen when the content is too long or contains unsupported characters.
 	 */
 	onError?: (event: Event) => void;
 	/**
-	 * URL of an image to be displayed in the center of the QR code.
-	 * This is useful for branding or to indicate to the user what scanning the QR code will do.
-	 * By default, no image is displayed.
+	 * The URL of an image to display in the center of the QR code, typically used for branding. The image should be small enough not to interfere with the QR code's scannability.
 	 */
 	logo?: string;
 }
 interface QueryContainerProps$1 extends GlobalProps {
 	/**
-	 * The content of the container.
+	 * The child elements to render inside the query container.
 	 */
 	children?: ComponentChildren;
 	/**
-	 * The name of the container, which can be used in your container queries to target this container specifically.
-	 *
-	 * We place the container name of `s-default` on every container. Because of this, it is not required to add a `containerName` identifier in your queries. For example, a `@container (inline-size <= 300px) none, auto` query is equivalent to `@container s-default (inline-size <= 300px) none, auto`.
-	 *
-	 * Any value set in `containerName` will be set alongside alongside `s-default`. For example, `containerName="my-container-name"` will result in a value of `s-default my-container-name` set on the `container-name` CSS property of the rendered HTML.
+	 * A custom name for the container, used in [container queries](https://developer.mozilla.org/en-US/docs/Web/CSS/container-name) to target this container specifically. The value is added alongside the default name `s-default`.
 	 *
 	 * @default ''
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/CSS/container-name
-	 *
-	 * @implementation You must always have a CSS `container-name` of `s-default` for this component.
 	 */
 	containerName?: string;
 }
+/**
+ * The overflow behavior for a scrollable container axis.
+ *
+ * - `auto`: Content that exceeds the container is clipped and becomes scrollable.
+ * - `hidden`: Content that exceeds the container is clipped and not scrollable.
+ */
 export type OverflowKeyword = "auto" | "hidden";
 interface ScrollBoxProps$1 extends GlobalProps, Omit<BaseBoxPropsWithRole, "overflow"> {
 	/**
-	 * Sets the overflow behavior of the element.
-	 *
-	 * - `hidden`: clips the content when it is larger than the element’s container and the element will not be scrollable in that axis.
-	 * - `auto`: clips the content when it is larger than the element’s container and make it scrollable in that axis.
+	 * The overflow behavior of the scroll box, controlling whether content that exceeds the container is scrollable or clipped. Learn more about [`overflow`](https://developer.mozilla.org/en-US/docs/Web/CSS/overflow).
 	 *
-	 * 1-to-2-value syntax is supported but note that, contrary to the CSS, it uses flow-relative values and the order is:
+	 * - `hidden`: Content is clipped and the element is not scrollable in that axis.
+	 * - `auto`: Content is clipped and becomes scrollable in that axis.
 	 *
-	 * - 2 values: `block inline`
+	 * Supports 1-to-2-value syntax using flow-relative axes. Two values are ordered as `block inline` (for example, `hidden auto` clips vertically and scrolls horizontally).
 	 *
 	 * @default 'auto'
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/CSS/overflow
 	 */
 	overflow?: OverflowKeyword | `${OverflowKeyword} ${OverflowKeyword}`;
 }
 interface SectionProps$1 extends GlobalProps, ActionSlots {
 	/**
-	 * The content of the Section.
+	 * The child elements to render inside the section, typically the main content area below the heading.
 	 */
 	children?: ComponentChildren;
 	/**
-	 * A label used to describe the section that will be announced by assistive technologies.
-	 *
-	 * When no `heading` property is provided or included as a children of the Section, you **must** provide an
-	 * `accessibilityLabel` to describe the Section. This is important as it allows assistive technologies to provide
-	 * the right context to users.
+	 * A label announced by assistive technologies that describes the purpose of the section. When no `heading` property is provided, you **must** set `accessibilityLabel` so screen readers can identify the section.
 	 */
 	accessibilityLabel?: string;
 	/**
-	 * A title that describes the content of the section.
+	 * The heading text displayed at the top of the section to summarize its content.
 	 */
 	heading?: string;
 	/**
-	 * Adjust the padding of all edges.
+	 * The padding applied to all edges of the section.
 	 *
-	 * - `base`: applies padding that is appropriate for the element. Note that it may result in no padding if
-	 * this is the right design decision in a particular context.
-	 * - `none`: removes all padding from the element. This can be useful when elements inside the Section need to span
-	 * to the edge of the Section. For example, a full-width image. In this case, rely on `s-box` with a padding of 'base'
-	 * to bring back the desired padding for the rest of the content.
+	 * - `base`: Applies context-appropriate padding. In some contexts this may result in no visible padding.
+	 * - `none`: Removes all padding, allowing child elements to span the full width of the section. Use a Box with `base` padding to restore spacing for individual content areas.
 	 *
 	 * @default 'base'
 	 */
@@ -3145,28 +3179,15 @@ interface SelectProps$1 extends GlobalProps, AutocompleteProps<AnyAutocompleteFi
 }
 interface SheetProps$1 extends BaseOverlayProps, BaseOverlayMethods, ToggleEventProps, GlobalProps, ActionSlots {
 	/**
-	 * A label that describes the purpose of the sheet. When set,
-	 * it will be announced to users using assistive technologies and will
-	 * provide them with more context.
-	 *
-	 * This overrides the `heading` prop for screen readers.
+	 * A label that describes the purpose of the sheet, announced by assistive technologies. When set, screen readers will use this label instead of the `heading` to describe the sheet.
 	 */
 	accessibilityLabel?: string;
 	/**
-	 * The content of the Sheet.
+	 * The content of the sheet.
 	 */
 	children?: ComponentChildren;
 	/**
-	 * Indicates whether the Sheet should be open by default.
-	 * This property is necessary in some cases, but its usage is generally discouraged due to potential negative impacts on user experience.
-	 *
-	 * Developers should:
-	 * - Only set this property to true when there are vitally important behaviors of the application that depend on the user interacting with the sheet.
-	 * - Make every effort to conditionally hide the sheet based on the state of checkout. An explicit example is custom privacy consent, where the sheet should only be displayed when consent is necessary and has not yet been explicitly given by the user.
-	 *
-	 * This property is useful for when the Sheet needs to be rendered on the page load and not triggered by a user action.
-	 * The property should only take effect when the `Sheet` is rendered for the first time.
-	 * To toggle the Sheet after it has been rendered, use the `ui.showOverlay()` method instead.
+	 * Whether the sheet should be open when it first renders. Use sparingly — only when the user must interact with the sheet before proceeding (for example, a privacy consent prompt). Only takes effect on the initial render.
 	 *
 	 * @default false
 	 */
@@ -3178,12 +3199,8 @@ interface SheetProps$1 extends BaseOverlayProps, BaseOverlayMethods, ToggleEvent
 	/**
 	 * Adjust the padding of all edges.
 	 *
-	 * `base`: applies padding that is appropriate for the element. Note that it may result in no padding if Shopify
-	 * believes this is the right design decision in a particular context.
-	 *
-	 * `none`: removes all padding from the element. This can be useful when elements inside the Sheet need to span
-	 * to the edge of the Sheet. For example, a full-width image. In this case, rely on `Box` with a padding of 'base'
-	 * to bring back the desired padding for the rest of the content.
+	 * - `base`: Applies padding that is appropriate for the element. Note that it may result in no padding if Shopify believes this is the right design decision in a particular context.
+	 * - `none`: Removes all padding from the element. This can be useful when elements inside the sheet need to span to the edge of the sheet. For example, a full-width image. In this case, rely on box with a padding of `base` to bring back the desired padding for the rest of the content.
 	 *
 	 * @default 'base'
 	 */
@@ -3205,51 +3222,45 @@ interface SkeletonParagraphProps$1 extends GlobalProps {
 }
 interface SpinnerProps$1 extends GlobalProps {
 	/**
-	 * Adjusts the size of the spinner icon.
+	 * The size of the spinner icon.
 	 *
 	 * @default 'base'
 	 */
 	size?: SizeKeyword;
 	/**
-	 * A label that describes the purpose of the progress. When set,
-	 * it will be announced to users using assistive technologies and will
-	 * provide them with more context. Providing an `accessibilityLabel` is
-	 * recommended if there is no accompanying text describing that something
-	 * is loading.
+	 * A label that describes the purpose of the spinner for assistive technologies like screen readers. Provide an `accessibilityLabel` when there is no visible text that conveys a loading state.
 	 */
 	accessibilityLabel?: string;
 }
 interface StackProps$1 extends GlobalProps, BaseBoxPropsWithRole, GapProps {
 	/**
-	 * The content of the Stack.
+	 * The child elements to render inside the stack.
 	 */
 	children?: ComponentChildren;
 	/**
-	 * Sets how the children are placed within the Stack. This uses [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values).
+	 * The axis along which child elements are arranged, using [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values).
 	 *
-	 * @default 'block'
+	 * - `block`: Children are stacked vertically (in horizontal writing modes). Content does not wrap.
+	 * - `inline`: Children are arranged horizontally (in horizontal writing modes). Content wraps when it overflows.
 	 *
-	 * @implementation the content will wrap if the direction is 'inline', and not wrap if the direction is 'block'
+	 * @default 'block'
 	 */
 	direction?: MaybeResponsive<"block" | "inline">;
 	/**
-	 * Aligns the Stack along the main axis.
+	 * Controls how child elements are distributed along the main axis. Learn more about [`justify-content`](https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content).
 	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content
 	 * @default 'normal'
 	 */
 	justifyContent?: MaybeResponsive<JustifyContentKeyword>;
 	/**
-	 * Aligns the Stack's children along the cross axis.
+	 * Controls how child elements are aligned along the cross axis. Learn more about [`align-items`](https://developer.mozilla.org/en-US/docs/Web/CSS/align-items).
 	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/CSS/align-items
 	 * @default 'normal'
 	 */
 	alignItems?: MaybeResponsive<AlignItemsKeyword>;
 	/**
-	 * Aligns the Stack along the cross axis.
+	 * Controls how lines of content are distributed along the cross axis when there is extra space. Learn more about [`align-content`](https://developer.mozilla.org/en-US/docs/Web/CSS/align-content).
 	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/CSS/align-content
 	 * @default 'normal'
 	 */
 	alignContent?: MaybeResponsive<AlignContentKeyword>;
@@ -3396,7 +3407,7 @@ interface TimeProps$1 extends GlobalProps {
 }
 interface TooltipProps$1 extends GlobalProps {
 	/**
-	 * The content of the Tooltip.
+	 * The text or elements displayed inside the tooltip popup.
 	 */
 	children?: ComponentChildren;
 }