@shopify/ui-extensions 2026.1.2 → 2026.1.4

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

@@ -9,31 +9,31 @@
 /**
  * TODO: Update `any` type here after this is resolved
  * https://github.com/Shopify/ui-api-design/issues/139
+ * @publicDocs
  */
 export type ComponentChildren = any;
+/** @publicDocs */
 export type StringChildren = string;
+/** @publicDocs */
 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;
 }
 interface AbbreviationProps$1 extends GlobalProps {
 	/**
-	 * The content of the abbreviation or acronym.
+	 * The abbreviated text content displayed within the abbreviation component. Pair with the `title` attribute to provide the full expansion for accessibility.
 	 */
 	children?: ComponentChildren;
 	/**
-	 * Defines the full expansion of the abbreviation or acronym.
-	 *
-	 * Helps user agents and users understand the meaning of the abbreviated text.
+	 * Defines the full expansion of the abbreviation or acronym, helping user agents and users understand the meaning of the abbreviated text. Learn more about the [abbreviation element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/abbr).
 	 *
 	 * @default ''
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/abbr
 	 */
 	title?: string;
 }
+/** @publicDocs */
 export interface ActionSlots {
 	/**
 	 * The primary action to perform, provided as a button or link type element.
@@ -44,21 +44,22 @@ export interface ActionSlots {
 	 */
 	secondaryActions?: ComponentChildren;
 }
+/** @publicDocs */
 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;
 }
@@ -69,73 +70,71 @@ export interface BaseOverlayProps {
  * - Components implementing this interface must provide all methods
  * - Unlike props/attributes, methods are not rendered in HTML but are JavaScript APIs
  * - Consumers expect these methods to be consistently available on all instances
+ * @publicDocs
  */
 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
 	 */
 	toggleOverlay: () => void;
 }
+/** @publicDocs */
 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;
 }
+/** @publicDocs */
 export interface ToggleEventProps {
 	/**
-	 * Callback fired when the element state changes **after** any animations have finished.
+	 * A callback fired 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 the [`newState`](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState) and [`oldState`](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState) properties.
 	 */
 	onAfterToggle?: (event: ToggleEvent$1) => void;
 	/**
-	 * Callback straight after the element state changes.
+	 * A callback fired 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
+	 * - If the element is transitioning from showing to hidden, then the `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), and the [`newState`](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState) and [`oldState`](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState) properties.
 	 */
 	onToggle?: (event: ToggleEvent$1) => void;
 }
+/** @publicDocs */
 export type ToggleState = "open" | "closed";
 interface ToggleEvent$1 extends Event {
 	readonly newState: ToggleState;
 	readonly oldState: ToggleState;
 }
+/** @publicDocs */
 export interface ExtendableEvent extends Event {
 	/**
 	 * Provide a promise that signals the length, and eventual success or failure of actions relating to the event.
@@ -162,13 +161,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.
+ * @publicDocs
+ */
 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.
+ * @publicDocs
+ */
 export type ColorKeyword = "subdued" | "base" | "strong";
+/** @publicDocs */
 export type BackgroundColorKeyword = "transparent" | ColorKeyword;
+/** @publicDocs */
 export interface BackgroundProps {
 	/**
 	 * Adjust the background of the element.
 	 *
+	 * - `'transparent'`: No visible background.
+	 * - `'subdued'`: A subtle, low-emphasis background.
+	 * - `'base'`: The standard background color.
+	 * - `'strong'`: A high-emphasis background for prominence.
+	 *
 	 * @default 'transparent'
 	 */
 	background?: BackgroundColorKeyword;
@@ -182,6 +200,7 @@ export interface BackgroundProps {
  * In some cases, like for Banner, the tone may also affect the semantic and accessibility treatment of the component.
  *
  * @default 'auto'
+ * @publicDocs
  */
 export type ToneKeyword = "auto" | "neutral" | "info" | "success" | "caution" | "warning" | "critical" | "accent" | "custom";
 declare const privateIconArray: readonly [
@@ -733,13 +752,38 @@ declare const privateIconArray: readonly [
 	"x-circle",
 	"x-circle-filled"
 ];
+/** @publicDocs */
 export type IconType = (typeof privateIconArray)[number];
 /**
  * Like `Extract`, but ensures that the extracted type is a strict subtype of the input type.
+ * @publicDocs
  */
 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).
+ * @publicDocs
+ */
 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).
+ * @publicDocs
+ */
 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.
+ * @publicDocs
+ */
 export type MaybeResponsive<T> = T | `@container${string}`;
 /**
  * Prevents widening string literal types in a union to `string`.
@@ -748,6 +792,7 @@ export type MaybeResponsive<T> = T | `@container${string}`;
  * //   ^? string
  * type PropName = 'foo' | 'bar' | (string & {})
  * //   ^? 'foo' | 'bar' | (string & {})
+ * @publicDocs
  */
 export type AnyString = string & {};
 /**
@@ -755,6 +800,7 @@ export type AnyString = string & {};
  * to have a space or not in the string literal types.
  *
  * For example in the `aspectRatio` property, `16/9` and `16 / 9` are both valid.
+ * @publicDocs
  */
 export type optionalSpace = "" | " ";
 interface BadgeProps$1 extends GlobalProps {
@@ -777,6 +823,8 @@ interface BadgeProps$1 extends GlobalProps {
 	/**
 	 * The type of icon to be displayed in the badge.
 	 *
+	 * Always positioned relative to the text content. Independent positioning isn't supported.
+	 *
 	 * @default ''
 	 */
 	icon?: IconType | AnyString;
@@ -866,6 +914,7 @@ interface BannerProps$1 extends GlobalProps, ActionSlots {
 	 */
 	hidden?: boolean;
 }
+/** @publicDocs */
 export interface DisplayProps {
 	/**
 	 * Sets the outer display type of the component. The outer type sets a component’s participation in [flow layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_flow_layout).
@@ -873,11 +922,13 @@ export interface DisplayProps {
 	 * - `auto`: the component’s initial value. The actual value depends on the component and context.
 	 * - `none`: hides the component from display and removes it from the accessibility tree, making it invisible to screen readers.
 	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/CSS/display
+	 * Learn more about the [display property](https://developer.mozilla.org/en-US/docs/Web/CSS/display).
+	 *
 	 * @default 'auto'
 	 */
 	display?: MaybeResponsive<"auto" | "none">;
 }
+/** @publicDocs */
 export interface AccessibilityRoleProps {
 	/**
 	 * Sets the semantic meaning of the component’s content. When set,
@@ -891,6 +942,7 @@ export interface AccessibilityRoleProps {
 	 */
 	accessibilityRole?: AccessibilityRole;
 }
+/** @publicDocs */
 export type AccessibilityRole = 
 /**
  * Used to indicate the primary content.
@@ -903,7 +955,7 @@ export type AccessibilityRole =
  * Used to indicate the component is a header.
  *
  * In an HTML host `header` will render a `<header>` element.
- * Learn more about the [`<header>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/header) and its [implicit role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/main_role) in the MDN web docs.
+ * Learn more about the [`<header>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/header) and its [implicit role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/banner_role) in the MDN web docs.
  */
  | "header"
 /**
@@ -1006,176 +1058,225 @@ export type AccessibilityRole =
  * Learn more about the [`none` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/none_role) in the MDN web docs.
  */
  | "none";
+/** @publicDocs */
 export interface AccessibilityVisibilityProps {
 	/**
-	 * Changes the visibility of the element.
+	 * Controls how the element is exposed to sighted users and to assistive technologies such as screen readers.
 	 *
-	 * - `visible`: the element is visible to all users.
-	 * - `hidden`: the element is removed from the accessibility tree but remains visible.
-	 * - `exclusive`: the element is visually hidden but remains in the accessibility tree.
+	 * - `visible`: The element is visible to all users (both sighted users and screen readers).
+	 * - `hidden`: The element is visually visible but hidden from screen readers. Use this for decorative elements that don't provide meaningful information.
+	 * - `exclusive`: The element is visually hidden but announced by screen readers. Use this for screen-reader-only content like skip links or additional context.
 	 *
 	 * @default 'visible'
 	 */
 	accessibilityVisibility?: "visible" | "hidden" | "exclusive";
 }
+/** @publicDocs */
 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.
+ * @publicDocs
+ */
 export type PaddingKeyword = SizeKeyword | "none";
+/** @publicDocs */
 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`
-	 *
-	 * 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`.
+	 * **Examples:** `base`, `large none`, `base large-100 base 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.
+ * @publicDocs
+ */
 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).
+ * @publicDocs
+ */
 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).
+ * @publicDocs
+ */
 export type SizeUnitsOrNone = SizeUnits | "none";
+/** @publicDocs */
 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.
+ * @publicDocs
+ */
 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).
+ * @publicDocs
+ */
 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).
+ * @publicDocs
+ */
 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.
+ * @publicDocs
  */
 export type BorderShorthand = BorderSizeKeyword | `${BorderSizeKeyword} ${ColorKeyword}` | `${BorderSizeKeyword} ${ColorKeyword} ${BorderStyleKeyword}`;
+/** @publicDocs */
 export interface BorderProps {
 	/**
-	 * Set the border via the shorthand property.
-	 *
-	 * This can be a size, optionally followed by a color, optionally followed by a style.
-	 *
-	 * If the color is not specified, it will be `base`.
+	 * Applies a border using shorthand syntax to specify width, color, and style in a single property.
 	 *
-	 * If the style is not specified, it will be `auto`.
+	 * 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`.
 	 *
-	 * 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,82 +1287,72 @@ 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.
-	 *
-	 * If one value is specified, it applies to all sides.
+	 * Controls the thickness of the border on all sides. When set, this overrides the width value specified in the `border` property.
 	 *
-	 * 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.
-	 *
-	 * Like CSS, up to 4 values can be specified.
+	 * Controls the visual style of the border on all sides, such as solid, dashed, or dotted.
 	 *
-	 * If one value is specified, it applies to all sides.
+	 * When set, this overrides the style value specified in the `border` property.
 	 *
-	 * 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'
 	 */
 	borderRadius?: MaybeAllValuesShorthandProperty<BorderRadiusKeyword>;
 }
+/** @publicDocs */
 export interface OverflowProps {
 	/**
 	 * Sets 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`: The content that extends beyond the element’s container is visible.
+	 * - `hidden`: Clips the content when it is larger than the element’s container. The element will not be scrollable and users will not be able to access the clipped content by dragging or using a scroll wheel on a mouse.
 	 *
 	 * @default 'visible'
 	 */
 	overflow?: "hidden" | "visible";
 }
+/** @publicDocs */
 export interface BaseBoxProps extends AccessibilityVisibilityProps, BackgroundProps, DisplayProps, SizingProps, PaddingProps, BorderProps, OverflowProps {
 	/**
 	 * The content of the Box.
@@ -1275,17 +1366,19 @@ export interface BaseBoxProps extends AccessibilityVisibilityProps, BackgroundPr
 	 */
 	accessibilityLabel?: string;
 }
+/** @publicDocs */
 export interface BaseBoxPropsWithRole extends BaseBoxProps, AccessibilityRoleProps {
 }
 interface BoxProps$1 extends BaseBoxPropsWithRole, GlobalProps {
 }
+/** @publicDocs */
 export interface ButtonBehaviorProps extends InteractionProps, FocusEventProps {
 	/**
-	 * The behavior of the Button.
+	 * The behavioral type of the button component, which determines what action it performs when activated.
 	 *
-	 * - `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).
+	 * - `submit`: Submits the closest form.
+	 * - `button`: Performs no default action when activated.
+	 * - `reset`: Resets the closest form (returning fields to their default values).
 	 *
 	 * This property is ignored if the component supports `href` or `commandFor`/`command` and one of them is set.
 	 *
@@ -1293,30 +1386,28 @@ export interface ButtonBehaviorProps extends InteractionProps, FocusEventProps {
 	 */
 	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.
+	 * 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.
+	 * This also disables the button.
 	 *
 	 * @default false
 	 */
 	loading?: boolean;
 }
+/** @publicDocs */
 export interface LinkBehaviorProps extends InteractionProps, FocusEventProps {
 	/**
-	 * The URL to link to.
+	 * The URL to navigate to when clicked. The `click` event fires first, then navigation occurs.
 	 *
 	 * - 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.
@@ -1327,7 +1418,8 @@ export interface LinkBehaviorProps extends InteractionProps, FocusEventProps {
 	 *
 	 * @see 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 using a target automatically determined based on the origin of the URL.
+	 * - `_blank`: Opens the URL in a new browsing context.
 	 *
 	 * @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.
@@ -1343,115 +1435,117 @@ export interface LinkBehaviorProps extends InteractionProps, FocusEventProps {
 	 */
 	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;
 }
+/** @publicDocs */
 export interface InteractionProps {
 	/**
-	 * ID of a component that should respond to activations (e.g. clicks) on this component.
+	 * 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).
 	 *
-	 * See `command` for how to control the behavior of the target.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor
+	 * When both `commandFor` and `href` are set, `commandFor` takes precedence. The command runs and the link doesn't navigate.
 	 */
 	commandFor?: string;
 	/**
-	 * Sets the action the `commandFor` should take when this clickable is activated.
+	 * Sets the action the `commandFor` target should take when this component is activated.
 	 *
-	 * See the documentation of particular components for the actions they support.
+	 * - `--auto`: Performs the default action for the target component.
+	 * - `--show`: Displays the target component.
+	 * - `--hide`: Conceals the target component.
+	 * - `--toggle`: Alternates the target component.
+	 * - `--copy`: Copies the target ClipboardItem.
 	 *
-	 * - `--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.
+	 * Learn more about the [`command` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command).
 	 *
 	 * @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;
 }
+/** @publicDocs */
 export interface BaseClickableProps extends ButtonBehaviorProps, LinkBehaviorProps {
 }
 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.
+	 * [Reference of values](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) (`Subtag` label)
 	 */
 	lang?: string;
 }
+/** @publicDocs */
 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
 	 */
 	disabled?: boolean;
 }
+/** @publicDocs */
 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,39 +1553,43 @@ 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.
 	 */
 	defaultValue?: string;
 }
+/** @publicDocs */
 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;
 	/**
-	 * An array of the `value`s of the selected options.
+	 * An array of `value` attributes for the currently selected options.
 	 *
 	 * This is a convenience prop for setting the `selected` prop on child options.
+	 *
+	 * Form data captures the selected value strings only. Complex nested content inside choices is for display purposes and isn't included in form submissions.
 	 */
 	values?: string[];
 }
+/** @publicDocs */
 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;
 	/**
@@ -1514,13 +1612,14 @@ export interface FileInputProps extends BaseInputProps {
 	 */
 	files?: readonly File[];
 }
+/** @publicDocs */
 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;
 }
+/** @publicDocs */
 export interface BasicFieldProps extends FieldErrorProps, LabelAccessibilityVisibilityProps {
 	/**
 	 * Whether the field needs a value. This requirement adds semantic value
@@ -1532,10 +1631,11 @@ 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;
 }
+/** @publicDocs */
 export interface FieldDetailsProps {
 	/**
 	 * Additional text to provide context or guidance for the field.
@@ -1546,27 +1646,30 @@ export interface FieldDetailsProps {
 	 */
 	details?: string;
 }
+/** @publicDocs */
 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;
 }
+/** @publicDocs */
 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
 	 */
 	readOnly?: boolean;
 }
+/** @publicDocs */
 export interface FieldDecorationProps {
 	/**
 	 * A value to be displayed immediately after the editable portion of the field.
 	 *
 	 * 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 +1682,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.
@@ -1599,6 +1702,7 @@ export interface FieldDecorationProps {
 	 */
 	accessory?: ComponentChildren;
 }
+/** @publicDocs */
 export interface NumberConstraintsProps {
 	/**
 	 * The highest decimal or integer to be accepted for the field.
@@ -1641,6 +1745,7 @@ export interface NumberConstraintsProps {
 	 */
 	controls?: "auto" | "stepper" | "none";
 }
+/** @publicDocs */
 export interface MinMaxLengthProps {
 	/**
 	 * Specifies the maximum number of characters allowed.
@@ -1649,12 +1754,13 @@ export interface MinMaxLengthProps {
 	 */
 	maxLength?: number;
 	/**
-	 * Specifies the min number of characters allowed.
+	 * Specifies the minimum number of characters allowed.
 	 *
 	 * @default 0
 	 */
 	minLength?: number;
 }
+/** @publicDocs */
 export interface BaseSelectableProps {
 	/**
 	 * A label used for users using assistive technologies like screen readers. When set, any children or `label` supplied will not be announced.
@@ -1662,7 +1768,7 @@ export interface BaseSelectableProps {
 	 */
 	accessibilityLabel?: string;
 	/**
-	 * Disables the control, disallowing any interaction.
+	 * Whether the control is disabled, preventing any user interaction.
 	 *
 	 * @default false
 	 */
@@ -1672,15 +1778,16 @@ export interface BaseSelectableProps {
 	 */
 	value?: string;
 }
+/** @publicDocs */
 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.
 	 *
@@ -1688,19 +1795,20 @@ export interface BaseOptionProps extends BaseSelectableProps {
 	 */
 	defaultSelected?: boolean;
 }
+/** @publicDocs */
 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 +1816,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;
 	/**
@@ -1755,27 +1862,34 @@ interface CheckboxProps$1 extends GlobalProps, BaseCheckableProps, FieldErrorPro
 	 * If you want to present an error when this field is empty, you can do
 	 * so with the `error` property.
 	 *
+	 * Adds semantic meaning for accessibility. Doesn't trigger automatic validation or display an error. Implement validation logic yourself and use the `error` prop to show results.
+	 *
 	 * @default false
 	 */
 	required?: boolean;
 }
+/** @publicDocs */
 export interface ChipProps$1 {
 	/**
-	 * The content of the chip.
+	 * The text content displayed within the chip.
 	 */
 	children?: ComponentChildren;
 	/**
-	 * The graphic to display inside of the chip.
+	 * The graphic element (typically an icon) displayed inside the chip.
 	 *
 	 * @implementation Only `s-icon` is supported.
 	 */
 	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 content of the component for assistive technologies like screen readers. Use this to provide additional context when the visible content alone doesn't clearly convey the component's purpose.
 	 */
 	accessibilityLabel?: string;
 	/**
-	 * Modify the color to be more or less intense.
+	 * The color emphasis level that controls visual intensity.
+	 *
+	 * - `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.
 	 *
 	 * @default 'base'
 	 */
@@ -1806,13 +1920,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 +1950,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.
 	 *
@@ -1852,6 +1966,8 @@ interface ChoiceListProps$1 extends GlobalProps, Pick<BasicFieldProps, "label" |
 	 * - `block`: The choices are displayed on the block axis.
 	 * - `grid`: The choices are displayed in a grid.
 	 *
+	 * The selected content slot is supported only in the default (stacked) variant. `inline` and `grid` ignore it.
+	 *
 	 * @implementation The `block`, `inline` and `grid` variants are more suitable for button looking choices, but it's at the
 	 * discretion of each surface.
 	 *
@@ -1869,7 +1985,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.
@@ -1879,9 +1995,8 @@ interface ClickableProps$1 extends GlobalProps, BaseBoxProps, BaseClickableProps
 	 */
 	disabled?: BaseClickableProps["disabled"];
 	/**
-	 * 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.
+	 * [Reference of values](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) (`Subtag` label)
 	 *
 	 * @default ''
 	 */
@@ -1889,23 +2004,21 @@ interface ClickableProps$1 extends GlobalProps, BaseBoxProps, BaseClickableProps
 }
 interface ClickableChipProps$1 extends ChipProps$1, GlobalProps {
 	/**
-	 * Callback when the chip is clicked.
+	 * A callback fired when the chip is clicked. Learn more about the [click event](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event).
 	 */
 	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;
 	/**
-	 * Whether the chip is removable.
+	 * Whether the chip displays a remove button, allowing users to dismiss it. When `true`, clicking the remove button fires the `remove` event.
 	 *
 	 * @default false
 	 */
 	removable?: boolean;
 	/**
-	 * Callback when the chip is removed.
+	 * A callback fired when the chip is removed by the user clicking the remove button.
 	 */
 	onRemove?: (event: Event) => void;
 	/**
@@ -1917,11 +2030,13 @@ interface ClickableChipProps$1 extends ChipProps$1, GlobalProps {
 	 *
 	 * If the chip is not `removable`, it can still be hidden by setting this property.
 	 *
+	 * When using the `removable` variant, keep `hidden` synced with your app state. If `hidden` isn't updated after the chip is removed, the chip can become permanently hidden.
+	 *
 	 * @default false
 	 */
 	hidden?: boolean;
 	/**
-	 * Event handler when the chip has fully hidden.
+	 * A callback fired when the chip has fully hidden after a removal animation.
 	 *
 	 * The `hidden` property will be `true` when this event fires.
 	 *
@@ -1931,7 +2046,7 @@ interface ClickableChipProps$1 extends ChipProps$1, GlobalProps {
 	 */
 	onAfterHide?: (event: Event) => void;
 	/**
-	 * Disables the chip, disallowing any interaction.
+	 * Disables the chip, preventing all user interaction including clicks and removal. Disabled chips are visually dimmed to indicate they are not interactive.
 	 *
 	 * @default false
 	 */
@@ -1941,6 +2056,8 @@ interface ClipboardItemProps$1 extends GlobalProps {
 	/**
 	 * Plain text to be written to the clipboard.
 	 *
+	 * Rich text, HTML, and binary content aren't supported.
+	 *
 	 * @default ''
 	 */
 	text?: string;
@@ -1953,9 +2070,10 @@ interface ClipboardItemProps$1 extends GlobalProps {
 	 */
 	onCopyError?: (event: Event) => void;
 }
+/** @publicDocs */
 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
@@ -1982,35 +2100,47 @@ export interface AutocompleteProps<AutocompleteField extends AnyAutocompleteFiel
  *
  * Commonly used when there are multiple fields with the same autocomplete needs
  * in the same page. For example: 2 shipping address forms in the same page.
+ * @publicDocs
  */
 export type AutocompleteSection = `section-${string}`;
 /**
  * The contact information group the autocomplete data should be sourced from.
+ * @publicDocs
  */
 export type AutocompleteGroup = "shipping" | "billing";
 /**
  * The contact information subgroup the autocomplete data should be sourced from.
+ * @publicDocs
  */
 export type AutocompleteAddressGroup = "fax" | "home" | "mobile" | "pager";
+/** @publicDocs */
 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`;
+/** @publicDocs */
 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 policy for which buyer consent is being collected. Used by the [consent checkbox](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/consent-checkbox) and [consent phone field](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/consent-phone-field) components to identify the type of marketing permission requested.
+ * @publicDocs
+ */
 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.
+	 *
+	 * Only `sms-marketing` is supported. Other consent policy types aren't available through this component.
 	 */
 	policy?: ConsentPolicy;
 }
+/** @publicDocs */
 export type PhoneAutocompleteField = ExtractStrict<AnyAutocompleteField, "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`>;
 interface PhoneFieldProps$1 extends GlobalProps, BaseTextFieldProps, Pick<FieldDecorationProps, "accessory">, AutocompleteProps<PhoneAutocompleteField> {
 	/**
-	 * The type of number to collect.
+	 * The type of phone number to collect. Specific styling may be applied to each type to provide extra guidance to users. No additional validation is performed based on the type.
 	 *
-	 * Specific style may be applied to each type to provide extra guidance to users. Note that no extra validation is performed based on the type.
+	 * Styling hint for the input keyboard. Doesn't validate the phone number format. Implement validation in your extension and use the `error` prop to show results.
 	 *
-	 * @default '' meaning no specific kind of phone number
+	 * @default ''
 	 */
 	type?: "mobile" | "";
 }
@@ -2019,6 +2149,8 @@ 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.
+	 *
+	 * Only `sms-marketing` is supported.
 	 */
 	policy?: ConsentPolicy;
 }
@@ -2056,9 +2188,7 @@ interface DatePickerProps$1 extends GlobalProps, InputProps, FocusEventProps {
 	 */
 	type?: "single" | "multiple" | "range";
 	/**
-	 * Dates that can be selected.
-	 *
-	 * A comma-separated list of dates, date ranges. Whitespace is allowed after commas.
+	 * Restricts which dates the user can select. Accepts a comma-separated list of dates and date ranges. Whitespace is allowed after commas.
 	 *
 	 * The default `''` allows all dates.
 	 *
@@ -2074,6 +2204,8 @@ interface DatePickerProps$1 extends GlobalProps, InputProps, FocusEventProps {
 	 *       So `--2024` is equivalent to `--2024-12-31`.
 	 *     - Whitespace is allowed either side of `--`.
 	 *
+	 * Comma-separated list of allowed dates in `YYYY-MM-DD` format.
+	 *
 	 * @default ""
 	 *
 	 * @example
@@ -2101,6 +2233,8 @@ interface DatePickerProps$1 extends GlobalProps, InputProps, FocusEventProps {
 	 *       So `--2024` is equivalent to `--2024-12-31`.
 	 *     - Whitespace is allowed either side of `--`.
 	 *
+	 * Comma-separated list of disallowed dates in `YYYY-MM-DD` format.
+	 *
 	 * @default ""
 	 *
 	 * @example
@@ -2109,7 +2243,7 @@ interface DatePickerProps$1 extends GlobalProps, InputProps, FocusEventProps {
 	 */
 	disallow?: string;
 	/**
-	 * Days of the week that can be selected. These intersect with the result of `allow` and `disallow`.
+	 * Restricts which days of the week the user can select. Only dates that fall on an allowed day AND pass the `allow`/`disallow` filters are selectable. For example, setting `allowedDays` to `'mon, wed, fri'` with `allow` set to `'2024-06'` restricts selection to Mondays, Wednesdays, and Fridays in June 2024.
 	 *
 	 * A comma-separated list of days. Whitespace is allowed after commas.
 	 *
@@ -2165,6 +2299,8 @@ interface DatePickerProps$1 extends GlobalProps, InputProps, FocusEventProps {
 	 * - If `type="multiple"`, this is a comma-separated list of dates in `YYYY-MM-DD` format.
 	 * - If `type="range"`, this is a range in `YYYY-MM-DD--YYYY-MM-DD` format. The range is inclusive.
 	 *
+	 * Single dates use ISO 8601 format (`YYYY-MM-DD`); ranges use `YYYY-MM-DD--YYYY-MM-DD`. Locale-specific formats aren't supported.
+	 *
 	 * @default ""
 	 */
 	value?: string;
@@ -2189,47 +2325,42 @@ interface DateFieldProps$1 extends GlobalProps, BaseTextFieldProps, Pick<DatePic
 	 *
 	 * Disallowed dates are considered invalid.
 	 *
-	 * It’s important to note that this callback will be called only when the user **finishes editing** the date,
-	 * and it’s called right after the `onChange` callback.
-	 * The field is **not** validated on every change to the input. Once the buyer has signalled that
+	 * This callback fires only when the user finishes editing the date, right after the `change` callback.
+	 * The field isn’t validated on every change to the input. Once the user has signalled that
 	 * they have finished editing the field (typically, by blurring the field), the field gets validated and the callback is run if the value is invalid.
 	 */
 	onInvalid?: (event: Event) => void;
 }
+/** @publicDocs */
 export type DateAutocompleteField = ExtractStrict<AnyAutocompleteField, "bday" | "bday-day" | "bday-month" | "bday-year" | "cc-expiry" | "cc-expiry-month" | "cc-expiry-year">;
 interface DetailsProps$1 extends GlobalProps, ToggleEventProps {
 	/**
-	 * The content of the details.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details
+	 * The content displayed within the collapsible details section. This can include any elements that should be shown or hidden when the details component is toggled. Learn more about the [details element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details).
 	 */
 	children?: ComponentChildren;
 	/**
-	 * Name of the element.
-	 *
-	 * This can be used to create multiple named disclosure boxes that where only one can be open at a time.
+	 * The `name` attribute for the element. Use this to create multiple named disclosure groups where only one can be open at a time.
 	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details#multiple_named_disclosure_boxes
+	 * Learn more about [multiple named disclosure boxes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details#multiple_named_disclosure_boxes).
 	 */
 	name?: string;
 	/**
-	 * Whether the element is open.
-	 *
-	 * This does not reflect to any attribute.
+	 * Whether the element is currently open. Use this for controlled component patterns where your application manages the open state directly. This does not reflect to any attribute.
 	 *
 	 * @default false
 	 */
 	open?: boolean;
 	/**
-	 * Indicates whether the element should be open by default.
-	 *
-	 * This reflects to the `open` attribute.
+	 * Whether the element should be open when it first renders. This reflects to the `open` attribute and only takes effect on the initial render.
 	 *
 	 * @default false
 	 */
 	defaultOpen?: boolean;
 	/**
-	 * Sets the transition between the two states.
+	 * The transition style used when toggling between open and closed states.
+	 *
+	 * - `none`: Switches states immediately without animation.
+	 * - `auto`: Uses the default animated transition.
 	 *
 	 * @default 'auto'
 	 */
@@ -2239,6 +2370,8 @@ 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).
 	 *
+	 * Vertical dividers (`'block'` direction) require a parent with a defined height to render visibly.
+	 *
 	 * @default 'inline'
 	 */
 	direction?: "inline" | "block";
@@ -2253,7 +2386,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.
@@ -2280,8 +2413,12 @@ interface DropZoneProps$1 extends GlobalProps, FileInputProps, BasicFieldProps {
 	 */
 	onDropRejected?: (event: Event) => void;
 }
+/**
+ * Doesn't perform automatic format validation. Implement validation logic yourself and use the `error` prop to display results.
+ */
 interface EmailFieldProps$1 extends GlobalProps, BaseTextFieldProps, MinMaxLengthProps, AutocompleteProps<EmailAutocompleteField> {
 }
+/** @publicDocs */
 export type EmailAutocompleteField = ExtractStrict<AnyAutocompleteField, "email" | `${AutocompleteAddressGroup} email`>;
 interface FormProps$1 extends GlobalProps {
 	/**
@@ -2311,7 +2448,9 @@ interface FormProps$1 extends GlobalProps {
 	 */
 	onReset?: (event: Event) => void;
 }
+/** @publicDocs */
 export type SpacingKeyword = SizeKeyword | "none";
+/** @publicDocs */
 export interface GapProps {
 	/**
 	 * Adjust spacing between elements.
@@ -2339,32 +2478,40 @@ export interface GapProps {
 	 */
 	columnGap?: MaybeResponsive<SpacingKeyword | "">;
 }
+/** @publicDocs */
 export type BaselinePosition = "baseline" | "first baseline" | "last baseline";
+/** @publicDocs */
 export type ContentDistribution = "space-between" | "space-around" | "space-evenly" | "stretch";
+/** @publicDocs */
 export type ContentPosition = "center" | "start" | "end";
+/** @publicDocs */
 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
+ * @publicDocs
  */
 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
+ * @publicDocs
  */
 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
+ * @publicDocs
  */
 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
+ * @publicDocs
  */
 export type AlignContentKeyword = "normal" | BaselinePosition | ContentDistribution | OverflowPosition | ContentPosition;
 interface GridProps$1 extends GlobalProps, BaseBoxPropsWithRole, GapProps {
@@ -2451,23 +2598,34 @@ interface GridItemProps$1 extends GlobalProps, BaseBoxPropsWithRole {
 	 */
 	gridRow?: `span ${number}` | "auto";
 }
+/** @publicDocs */
 export interface BaseTypographyProps {
 	/**
-	 * Modify the color to be more or less intense.
+	 * The color emphasis level that controls visual intensity.
+	 *
+	 * - `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.
 	 *
 	 * @default 'base'
 	 */
 	color?: ColorKeyword;
 	/**
-	 * Sets the tone of the component, based on the intention of the information being conveyed.
+	 * The semantic meaning and color treatment of the component.
+	 *
+	 * - `auto`: Automatically determined based on context.
+	 * - `neutral`: General information without specific intent.
+	 * - `info`: Informational content or helpful tips.
+	 * - `success`: Positive outcomes or successful states.
+	 * - `warning`: Important warnings about potential issues.
+	 * - `critical`: Urgent problems or destructive actions.
+	 * - `custom`: Custom styling controlled by your theme.
 	 *
 	 * @default 'auto'
 	 */
 	tone?: ToneKeyword;
 	/**
-	 * Set the numeric properties of the font.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant-numeric
+	 * Set the numeric properties of the font. Learn more about the [font-variant-numeric property](https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant-numeric).
 	 *
 	 * @default 'auto' - inherit from the parent element
 	 */
@@ -2485,22 +2643,21 @@ 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)
-	 * - `auto`: the user agent determines the direction based on the content
-	 * - `''`: direction is inherited from parent elements (equivalent to not setting the attribute)
+	 * - `ltr`: The languages written from left to right (such as English).
+	 * - `rtl`: The languages written from right to left (such as Arabic).
+	 * - `auto`: The user agent determines the direction based on the content.
+	 * - `""`: The direction is inherited from parent elements (equivalent to not setting the attribute).
 	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir
+	 * Learn more about the [dir attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir).
 	 *
 	 * @default ''
 	 */
 	dir?: "ltr" | "rtl" | "auto" | "";
 }
+/** @publicDocs */
 export interface BlockTypographyProps {
 	/**
-	 * Truncates the text content to the specified number of lines.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-line-clamp
+	 * Truncates the text content to the specified number of lines. Learn more about the [-webkit-line-clamp property](https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-line-clamp).
 	 *
 	 * @default Infinity - no truncation is applied
 	 */
@@ -2508,7 +2665,7 @@ export interface BlockTypographyProps {
 }
 interface HeadingProps$1 extends GlobalProps, AccessibilityVisibilityProps, BlockTypographyProps {
 	/**
-	 * The content of the Heading.
+	 * The heading text displayed within the heading component, which provides a title or section header for content.
 	 */
 	children?: ComponentChildren;
 	/**
@@ -2530,94 +2687,111 @@ 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.
+ * @publicDocs
+ */
 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,243 +2802,265 @@ 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 content of the link.
 	 */
 	children?: ComponentChildren;
 	/**
-	 * Sets the tone of the Link, based on the intention of the information being conveyed.
+	 * Sets the tone of the link, based on the intention of the information being conveyed.
+	 *
+	 * - `'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.
+	 * 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.
 	 */
 	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 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.
+	 * [Reference of values](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) (`Subtag` label)
 	 */
 	lang?: string;
 }
 interface ListItemProps$1 extends GlobalProps {
 	/**
-	 * The content of the ListItem.
+	 * The content displayed within the list item, which represents a single entry in an ordered or unordered list.
 	 */
 	children?: ComponentChildren;
 }
 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.
+ * @publicDocs
+ */
 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.
+ * @publicDocs
+ */
 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.
+ * @publicDocs
+ */
 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.
+ * @publicDocs
+ */
 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.
+ * @publicDocs
+ */
 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.
-	 *
-	 * `base`: applies padding that is appropriate for the element.
+	 * Adjust the padding around the modal content.
 	 *
-	 * `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;
 }
 interface MoneyFieldProps$1 extends GlobalProps, BaseTextFieldProps, NumberConstraintsProps, AutocompleteProps<MoneyAutocompleteField> {
 }
+/** @publicDocs */
 export type MoneyAutocompleteField = ExtractStrict<AnyAutocompleteField, "transaction-amount">;
 interface NumberFieldProps$1 extends GlobalProps, BaseTextFieldProps, AutocompleteProps<NumberAutocompleteField>, NumberConstraintsProps, FieldDecorationProps {
 	/**
@@ -2875,6 +3071,7 @@ interface NumberFieldProps$1 extends GlobalProps, BaseTextFieldProps, Autocomple
 	 */
 	inputMode?: "decimal" | "numeric";
 }
+/** @publicDocs */
 export type NumberAutocompleteField = ExtractStrict<AnyAutocompleteField, "one-time-code" | "cc-number" | "cc-csc">;
 interface OptionProps$1 extends GlobalProps, BaseOptionProps {
 	/**
@@ -2886,11 +3083,11 @@ interface OrderedListProps$1 extends GlobalProps {
 }
 interface ParagraphProps$1 extends GlobalProps, BaseTypographyProps, BlockTypographyProps, AccessibilityVisibilityProps {
 	/**
-	 * The content of the Text.
+	 * The paragraph text content displayed within the paragraph component, which presents a block of related text with appropriate styling.
 	 */
 	children?: ComponentChildren;
 	/**
-	 * Provide semantic meaning and default styling to the paragraph.
+	 * The semantic type and styling treatment for the paragraph content.
 	 *
 	 * Other presentation properties on `s-paragraph` override the default styling.
 	 *
@@ -2898,47 +3095,51 @@ interface ParagraphProps$1 extends GlobalProps, BaseTypographyProps, BlockTypogr
 	 */
 	type?: ParagraphType;
 }
+/** @publicDocs */
 export type ParagraphType = 
 /**
- * Indicate the text is a structural grouping of related content.
+ * A semantic type that indicates the text is a structural grouping of related content.
  *
- * In an HTML host, the text will be rendered in an `<p>` element.
- * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/p
+ * In an HTML host, the text will be rendered in an `<p>` element. Learn more about the [p element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/p).
  */
 "paragraph"
 /**
- * Indicates the text is considered less important than the main content, but is still necessary for the reader to understand.
+ * A semantic type that indicates the text is considered less important than the main content, but is still necessary for the reader to understand.
+ *
  * It can be used for secondary content but also for disclaimers, terms and conditions, or legal information.
  *
  * Surfaces should apply a smaller font size than the default size.
  *
- * In an HTML host, the text will be rendered in a `<small>` element.
- * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/small
+ * In an HTML host, the text will be rendered in a `<small>` element. Learn more about the [small element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/small).
  */
  | "small";
 interface PasswordFieldProps$1 extends GlobalProps, BaseTextFieldProps, MinMaxLengthProps, AutocompleteProps<PasswordAutocompleteField> {
 }
+/** @publicDocs */
 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"`.
+ * @publicDocs
+ */
 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,27 +3159,30 @@ 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;
 }
@@ -3000,7 +3204,7 @@ interface ProgressProps$1 extends GlobalProps {
 	/**
 	 * 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.
+	 * 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.
 	 *
@@ -3014,7 +3218,7 @@ interface ProgressProps$1 extends GlobalProps {
 	/**
 	 * This attribute describes how much work the task indicated by the progress element requires.
 	 *
-	 * The `max` attribute, if present, must have a value greater than 0 and be a valid floating point number.
+	 * The `max` attribute, if present, must have a value greater than `0` and be a valid floating point number.
 	 *
 	 * @default 1
 	 *
@@ -3022,48 +3226,44 @@ interface ProgressProps$1 extends GlobalProps {
 	 */
 	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;
 }
@@ -3087,6 +3287,7 @@ interface QueryContainerProps$1 extends GlobalProps {
 	 */
 	containerName?: string;
 }
+/** @publicDocs */
 export type OverflowKeyword = "auto" | "hidden";
 interface ScrollBoxProps$1 extends GlobalProps, Omit<BaseBoxPropsWithRole, "overflow"> {
 	/**
@@ -3107,19 +3308,19 @@ interface ScrollBoxProps$1 extends GlobalProps, Omit<BaseBoxPropsWithRole, "over
 }
 interface SectionProps$1 extends GlobalProps, ActionSlots {
 	/**
-	 * The content of the Section.
+	 * The content of the section.
 	 */
 	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
+	 * When no `heading` property is provided or included as a child 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.
 	 */
 	accessibilityLabel?: string;
 	/**
-	 * A title that describes the content of the section.
+	 * A title displayed at the top of the section. When provided, it serves as both a visible heading and the accessible name for the section. If omitted, you must provide an `accessibilityLabel` instead.
 	 */
 	heading?: string;
 	/**
@@ -3127,8 +3328,8 @@ interface SectionProps$1 extends GlobalProps, ActionSlots {
 	 *
 	 * - `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'
+	 * - `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.
 	 *
 	 * @default 'base'
@@ -3145,28 +3346,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 +3366,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. This might result in no padding if Shopify determines that is the right design decision for 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'
 	 */
@@ -3256,12 +3440,10 @@ interface StackProps$1 extends GlobalProps, BaseBoxPropsWithRole, GapProps {
 }
 interface SummaryProps$1 extends GlobalProps {
 	/**
-	 * The content to use as the label.
-	 *
-	 * Interactive content is disallowed. For example, you can use a `<Text>` element for extra formatting but
-	 * elements like buttons and fields are not allowed.
+	 * The text or elements displayed as the summary label for the collapsible details section.
 	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary
+	 * Interactive content is disallowed. For example, you can use an `s-text` element for extra formatting but
+	 * elements like buttons and fields are not allowed. Learn more about the [summary element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary).
 	 *
 	 * @implementation Surfaces may apply styling to this element. An icon suggesting the state (open or closed) of the
 	 * details element is recommended.
@@ -3274,21 +3456,22 @@ interface SwitchProps$1 extends GlobalProps, BaseCheckableProps, BasicFieldProps
 }
 interface TextProps$1 extends GlobalProps, AccessibilityVisibilityProps, BaseTypographyProps, DisplayProps, Pick<InteractionProps, "interestFor"> {
 	/**
-	 * The content of the Text.
+	 * The text content displayed within the text component, which applies semantic meaning and styling appropriate to the specified text type.
 	 */
 	children?: ComponentChildren;
 	/**
-	 * Provide semantic meaning and default styling to the text.
+	 * The semantic type and styling treatment for the text content.
 	 *
-	 * Other presentation properties on Text override the default styling.
+	 * Other presentation properties on `s-text` override the default styling.
 	 *
 	 * @default 'generic'
 	 */
 	type?: TextType;
 }
+/** @publicDocs */
 export type TextType = 
 /**
- * Indicate the text is contact information. Typically used for addresses.
+ * A semantic type that indicates the text is contact information. Typically used for addresses.
  *
  * This must have `inline` layout (despite the default being `block` in HTML hosts).
  *
@@ -3298,65 +3481,60 @@ export type TextType =
  *
  * @implementation vertical alignment should be `baseline` (`vertical-align: baseline`)
  *
- * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/address
+ * Learn more about the [address element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/address).
  */
 "address"
 /**
- * Indicate the text is no longer accurate or no longer relevant. One such use-case is discounted prices.
+ * A semantic type that indicates the text is no longer accurate or no longer relevant. One such use-case is discounted prices.
  *
  * Surfaces should apply styling to this type to suggest its content no longer applies.
  *
- * In an HTML host, the text will be rendered in a `<s>` element.
- * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/s
+ * In an HTML host, the text will be rendered in a `<s>` element. Learn more about the [s element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/s).
  */
  | "redundant"
 /**
- * Indicate the text is marked or highlighted and relevant to the user’s current action.
+ * A semantic type that indicates the text is marked or highlighted and relevant to the user’s current action.
  * One such use-case is to indicate the characters that matched a search query.
  *
  * Surfaces should apply styling to this type to draw attention to the content.
  *
- * In an HTML host, the text will be rendered in a `<mark>` element.
- * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark
+ * In an HTML host, the text will be rendered in a `<mark>` element. Learn more about the [mark element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark).
  */
  | "mark"
 /**
- * Indicate emphatic stress. Typically for words that have a stressed emphasis compared to surrounding text.
+ * A semantic type that indicates emphatic stress. Typically for words that have a stressed emphasis compared to surrounding text.
  *
  * Surfaces should apply styling to this type to distinguish it from surrounding text. Italicization is a common choice, but not required.
  *
- * In an HTML host, the text will be rendered in an `<em>` element.
- * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/em
+ * In an HTML host, the text will be rendered in an `<em>` element. Learn more about the [em element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/em).
  */
  | "emphasis"
 /**
- * Indicate an offset from the normal prose of the text. Typically used to indicate
- * a foreign word, fictional character thoughts, or when the text refers to the definition of a word
- * instead of representing its semantic meaning.
+ * A semantic type that indicates an offset from the normal prose of the text.
+ *
+ * Typically used to indicate a foreign word, fictional character thoughts, or when the text refers to the definition of a word instead of representing its semantic meaning.
  *
  * Surfaces should italicize this content by default.
  *
- * In an HTML host, the text will be rendered in a `<i>` tag.
- * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/i
+ * In an HTML host, the text will be rendered in a `<i>` tag. Learn more about the [i element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/i).
  */
  | "offset"
 /**
- * Indicate strong importance, seriousness, or urgency.
+ * A semantic type that indicates strong importance, seriousness, or urgency.
  *
  * Surfaces should render this content bold by default.
  *
- * In an HTML host, the text will be rendered in a `<strong>` tag.
- * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/strong
+ * In an HTML host, the text will be rendered in a `<strong>` tag. Learn more about the [strong element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/strong).
  */
  | "strong"
 /**
- * Indicates the text is considered less important than the main content, but is still necessary for the reader to understand.
+ * A semantic type that indicates the text is considered less important than the main content, but is still necessary for the reader to understand.
+ *
  * It can be used for secondary content but also for disclaimers, terms and conditions, or legal information.
  *
  * Surfaces should apply a smaller font size than the default size.
  *
- * In an HTML host, the text will be rendered in a `<small>` element.
- * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/small
+ * In an HTML host, the text will be rendered in a `<small>` element. Learn more about the [small element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/small).
  */
  | "small"
 /**
@@ -3364,8 +3542,7 @@ export type TextType =
  *
  * Surfaces must not apply any default styling to this type.
  *
- * In an HTML host, the text will be rendered in a `<span>` tag.
- * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span
+ * In an HTML host, the text will be rendered in a `<span>` tag. Learn more about the [span element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span).
  */
  | "generic";
 interface TextAreaProps$1 extends GlobalProps, BaseTextFieldProps, MinMaxLengthProps, AutocompleteProps<TextAutocompleteField> {
@@ -3380,15 +3557,13 @@ interface TextFieldProps$1 extends GlobalProps, BaseTextFieldProps, MinMaxLength
 }
 interface TimeProps$1 extends GlobalProps {
 	/**
-	 * The content of the Time.
+	 * The text content displayed within the time component, representing a human-readable date or time value.
 	 */
 	children?: ComponentChildren;
 	/**
-	 * Set the time and/or date of the element.
-	 *
-	 * It must be a [valid date string](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/time#valid_datetime_values).
+	 * The machine-readable date and/or time value for the element. Use this to provide a datetime string that browsers, search engines, and assistive technologies can parse for improved semantics and functionality.
 	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/time#valid_datetime_values
+	 * The value must be a [valid datetime string](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/time#valid_datetime_values), such as `2024-01-15`, `14:30`, or `2024-01-15T14:30:00`.
 	 *
 	 * @default ''
 	 */
@@ -3396,14 +3571,16 @@ 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;
 }
 interface UnorderedListProps$1 extends GlobalProps {
 }
+/** @publicDocs */
 export interface URLFieldProps extends GlobalProps, BaseTextFieldProps, MinMaxLengthProps, AutocompleteProps<URLAutocompleteField> {
 }
+/** @publicDocs */
 export type URLAutocompleteField = ExtractStrict<AnyAutocompleteField, "url" | "photo" | "impp" | `${AutocompleteAddressGroup} impp`>;