@shopify/ui-extensions 2025.10.13 → 2025.10.15

package/build/ts/surfaces/checkout/components/components.d.ts

@@ -11,9 +11,12 @@
 /**
  * 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.
@@ -36,6 +39,7 @@ interface AbbreviationProps$1 extends GlobalProps {
 	 */
 	title?: string;
 }
+/** @publicDocs */
 export interface ActionSlots {
 	/**
 	 * The primary action to perform, provided as a button or link type element.
@@ -46,21 +50,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;
 }
@@ -71,73 +76,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 [`newState` property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState) and [`oldState` property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState).
 	 */
 	onAfterToggle?: (event: ToggleEvent$1) => void;
 	/**
-	 * Callback straight after the element state changes.
+	 * A callback 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), [`newState` property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState), and [`oldState` property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState).
 	 */
 	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.
@@ -164,9 +167,23 @@ 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.
@@ -184,6 +201,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 [
@@ -735,13 +753,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`.
@@ -750,6 +793,7 @@ export type MaybeResponsive<T> = T | `@container${string}`;
  * //   ^? string
  * type PropName = 'foo' | 'bar' | (string & {})
  * //   ^? 'foo' | 'bar' | (string & {})
+ * @publicDocs
  */
 export type AnyString = string & {};
 /**
@@ -757,6 +801,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 {
@@ -868,6 +913,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).
@@ -880,134 +926,102 @@ export interface DisplayProps {
 	 */
 	display?: MaybeResponsive<"auto" | "none">;
 }
+/** @publicDocs */
 export interface AccessibilityRoleProps {
 	/**
-	 * Sets the semantic meaning of the component’s content. When set,
-	 * the role will be used by assistive technologies to help users
-	 * navigate the page.
-	 *
-	 * @implementation Although, in HTML hosts, this property changes the element used,
-	 * changing this property must not impact the visual styling of inside or outside of the box.
+	 * The semantic meaning of the component’s content. When set, assistive technologies use this role to help users navigate the page.
 	 *
 	 * @default 'generic'
 	 */
 	accessibilityRole?: AccessibilityRole;
 }
-export type AccessibilityRole = 
 /**
- * Used to indicate the primary content.
+ * The semantic role of a component, used by assistive technologies to convey the element’s purpose to users. Each role maps to a specific HTML element or ARIA role.
  *
- * In an HTML host, `main` will render a `<main>` element.
- * Learn more about the [`<main>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/main) and its [implicit role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/main_role) in the MDN web docs.
+ * - `main`: The primary content of the page.
+ * - `header`: A page or section header.
+ * - `footer`: Information such as copyright, navigation links, and privacy statements.
+ * - `section`: A generic section that should have a heading or `accessibilityLabel`.
+ * - `aside`: Supporting content related to the main content.
+ * - `navigation`: A major group of navigation links.
+ * - `ordered-list`: A list of ordered items.
+ * - `list-item`: An item inside a list.
+ * - `list-item-separator`: A divider between list items.
+ * - `unordered-list`: A list of unordered items.
+ * - `separator`: A divider that separates sections of content.
+ * - `status`: A live region with advisory information that is not urgent.
+ * - `alert`: Important, usually time-sensitive information.
+ * - `generic`: A nameless container with no semantic meaning (renders a `<div>`).
+ * - `presentation`: Strips semantic meaning while keeping visual styling. Synonym for `none`.
+ * - `none`: Strips semantic meaning while keeping visual styling. Synonym for `presentation`.
+ * @publicDocs
+ */
+export type AccessibilityRole =
+/**
+ * The primary content of the page. Learn more about the [`<main>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/main).
  */
 "main"
 /**
- * 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.
+ * A page or section header. Learn more about the [`<header>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/header).
  */
  | "header"
 /**
- * Used to display information such as copyright information, navigation links, and privacy statements.
- *
- * In an HTML host `footer` will render a `<footer>` element.
- * Learn more about the [`<footer>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/footer) and its [implicit role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/contentinfo_role) in the MDN web docs.
+ * Information such as copyright, navigation links, and privacy statements. Learn more about the [`<footer>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/footer).
  */
  | "footer"
 /**
- * Used to indicate a generic section.
- * Sections should always have a `Heading` or an accessible name provided in the `accessibilityLabel` property.
- *
- * In an HTML host `section` will render a `<section>` element.
- * Learn more about the [`<section>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/section) and its [implicit role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/region_role) in the MDN web docs.
- *
+ * A generic section that should have a heading or `accessibilityLabel`. Learn more about the [`<section>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/section).
  */
  | "section"
 /**
- * Used to designate a supporting section that relates to the main content.
- *
- * In an HTML host `aside` will render an `<aside>` element.
- * Learn more about the [`<aside>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/aside) and its [implicit role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/complementary_role) in the MDN web docs.
+ * Supporting content related to the main content. Learn more about the [`<aside>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/aside).
  */
  | "aside"
 /**
- * Used to identify major groups of links used for navigating.
- *
- * In an HTML host `navigation` will render a `<nav>` element.
- * Learn more about the [`<nav>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/nav) and its [implicit role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/navigation_role) in the MDN web docs.
+ * A major group of navigation links. Learn more about the [`<nav>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/nav).
  */
  | "navigation"
 /**
- * Used to identify a list of ordered items.
- *
- * In an HTML host `ordered-list` will render a `<ol>` element.
- * Learn more about the [`<ol>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ol) and its [implicit role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/list_role) in the MDN web docs.
+ * A list of ordered items. Learn more about the [`<ol>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ol).
  */
  | "ordered-list"
 /**
- * Used to identify an item inside a list of items.
- *
- * In an HTML host `list-item` will render a `<li>` element.
- * Learn more about the [`<li>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/li) and its [implicit role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/listitem_role) in the MDN web docs.
+ * An item inside a list. Learn more about the [`<li>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/li).
  */
  | "list-item"
 /**
- * Used to indicates the component acts as a divider that separates and distinguishes sections of content in a list of items.
- *
- * In an HTML host `list-item-separator` will render as `<li role="separator">`.
- * Learn more about the [`<li>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/li) and the [`separator` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role) in the MDN web docs.
+ * A divider between list items. Learn more about the [`separator` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role).
  */
  | "list-item-separator"
 /**
- * Used to identify a list of unordered items.
- *
- * In an HTML host `unordered-list` will render a `<ul>` element.
- * Learn more about the [`<ul>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ul) and its [implicit role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/list_role) in the MDN web docs.
+ * A list of unordered items. Learn more about the [`<ul>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ul).
  */
  | "unordered-list"
 /**
- * Used to indicates the component acts as a divider that separates and distinguishes sections of content.
- *
- * In an HTML host `separator` will render as `<div role="separator">`.
- * Learn more about the [`separator` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role) in the MDN web docs.
+ * A divider that separates sections of content. Learn more about the [`separator` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role).
  */
  | "separator"
 /**
- * Used to define a live region containing advisory information for the user that is not important enough to be an alert.
- *
- * In an HTML host `status` will render as `<div role="status">`.
- * Learn more about the [`status` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/status_role) in the MDN web docs.
+ * A live region with advisory information that is not urgent. Learn more about the [`status` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/status_role).
  */
  | "status"
 /**
- * Used for important, and usually time-sensitive, information.
- *
- * In an HTML host `alert` will render as `<div role="alert">`.
- * Learn more about the [`alert` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) in the MDN web docs.
+ * Important, usually time-sensitive information. Learn more about the [`alert` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role).
  */
  | "alert"
 /**
- * Used to create a nameless container element which has no semantic meaning on its own.
- *
- * In an HTML host `generic'` will render a `<div>` element.
- * Learn more about the [`generic` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/generic_role) in the MDN web docs.
+ * A nameless container with no semantic meaning (renders a `<div>`). Learn more about the [`generic` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/generic_role).
  */
  | "generic"
 /**
- * Used to strip the semantic meaning of an element, but leave the visual styling intact.
- *
- * Synonym for `none`
- * Learn more about the [`presentation` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) in the MDN web docs.
+ * Strips semantic meaning while keeping visual styling. Synonym for `none`. Learn more about the [`presentation` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role).
  */
  | "presentation"
 /**
- * Used to strip the semantic meaning of an element, but leave the visual styling intact.
- *
- * Synonym for `presentation`
- * Learn more about the [`none` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/none_role) in the MDN web docs.
+ * Strips semantic meaning while keeping visual styling. Synonym for `presentation`. Learn more about the [`none` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/none_role).
  */
  | "none";
+/** @publicDocs */
 export interface AccessibilityVisibilityProps {
 	/**
 	 * Changes the visibility of the element.
@@ -1020,6 +1034,7 @@ export interface AccessibilityVisibilityProps {
 	 */
 	accessibilityVisibility?: "visible" | "hidden" | "exclusive";
 }
+/** @publicDocs */
 export interface LabelAccessibilityVisibilityProps {
 	/**
 	 * Changes the visibility of the component's label.
@@ -1031,7 +1046,15 @@ export interface LabelAccessibilityVisibilityProps {
 	 */
 	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.
@@ -1107,9 +1130,32 @@ export interface PaddingProps {
 	 */
 	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.
@@ -1160,13 +1206,39 @@ export interface SizingProps {
 	 */
 	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.
@@ -1251,19 +1323,19 @@ export interface BorderProps {
 	 */
 	borderRadius?: MaybeAllValuesShorthandProperty<BorderRadiusKeyword>;
 }
+/** @publicDocs */
 export interface OverflowProps {
 	/**
-	 * Sets the overflow behavior of the element.
+	 * The overflow behavior of the element.
 	 *
-	 * - `hidden`: clips the content when it is larger than the element’s container.
-	 * The element will not be scrollable and the users will not be able
-	 * to access the clipped content by dragging or using a scroll wheel on a mouse.
-	 * - `visible`: the content that extends beyond the element’s container is visible.
+	 * - `visible`: Content that extends beyond the container is visible.
+	 * - `hidden`: Content that extends beyond the container is clipped and not scrollable.
 	 *
 	 * @default 'visible'
 	 */
 	overflow?: "hidden" | "visible";
 }
+/** @publicDocs */
 export interface BaseBoxProps extends AccessibilityVisibilityProps, BackgroundProps, DisplayProps, SizingProps, PaddingProps, BorderProps, OverflowProps {
 	/**
 	 * The content of the Box.
@@ -1277,13 +1349,15 @@ 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.
@@ -1295,30 +1369,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.
@@ -1345,24 +1417,18 @@ 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.
-	 *
-	 * See `command` for how to control the behavior of the target.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor
+	 * The ID of the component to control when this component is activated. Pair with the `command` property to specify what action to perform on the target component. Learn more about the [`commandFor` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor).
 	 */
 	commandFor?: string;
 	/**
-	 * Sets the action the `commandFor` should take when this clickable is activated.
+	 * Sets the action the `commandFor` target should take when this component is activated. Learn more about the [`command` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command).
 	 *
 	 * See the documentation of particular components for the actions they support.
 	 *
@@ -1373,64 +1439,60 @@ export interface InteractionProps {
 	 * - `--copy`: copies the target ClipboardItem.
 	 *
 	 * @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. Use this to connect interactive components to popovers or tooltips that provide additional context or information.
 	 */
 	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.
+	 * - `fill`: the button takes up 100% of the available inline size.
 	 * - `fit-content`: the button will take 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.
 	 *
-	 * @default 'auto' - the variant is automatically determined by the Button's context
+	 * @default 'auto' - the variant is automatically determined by the button's context
 	 */
 	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.
 	 *
 	 * @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.
+	 * 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.
@@ -1443,9 +1505,10 @@ export interface BaseInputProps {
 	 */
 	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.
+	 * Callback when the user has **finished editing** a field, for example, once they have blurred the field.
 	 *
 	 * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event
 	 */
@@ -1467,6 +1530,7 @@ export interface InputProps extends BaseInputProps {
 	 */
 	defaultValue?: string;
 }
+/** @publicDocs */
 export interface MultipleInputProps extends BaseInputProps {
 	/**
 	 * Callback when the user has selected option(s).
@@ -1481,12 +1545,13 @@ export interface MultipleInputProps extends BaseInputProps {
 	 */
 	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.
 	 */
 	values?: string[];
 }
+/** @publicDocs */
 export interface FileInputProps extends BaseInputProps {
 	/**
 	 * Callback when the user has **finished selecting** a file or files.
@@ -1516,6 +1581,7 @@ 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
@@ -1523,6 +1589,7 @@ export interface FieldErrorProps {
 	 */
 	error?: string;
 }
+/** @publicDocs */
 export interface BasicFieldProps extends FieldErrorProps, LabelAccessibilityVisibilityProps {
 	/**
 	 * Whether the field needs a value. This requirement adds semantic value
@@ -1538,6 +1605,7 @@ export interface BasicFieldProps extends FieldErrorProps, LabelAccessibilityVisi
 	 */
 	label?: string;
 }
+/** @publicDocs */
 export interface FieldDetailsProps {
 	/**
 	 * Additional text to provide context or guidance for the field.
@@ -1548,12 +1616,14 @@ 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.
 	 */
 	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.
@@ -1562,6 +1632,7 @@ export interface BaseTextFieldProps extends FieldProps {
 	 */
 	readOnly?: boolean;
 }
+/** @publicDocs */
 export interface FieldDecorationProps {
 	/**
 	 * A value to be displayed immediately after the editable portion of the field.
@@ -1601,6 +1672,7 @@ export interface FieldDecorationProps {
 	 */
 	accessory?: ComponentChildren;
 }
+/** @publicDocs */
 export interface NumberConstraintsProps {
 	/**
 	 * The highest decimal or integer to be accepted for the field.
@@ -1643,6 +1715,7 @@ export interface NumberConstraintsProps {
 	 */
 	controls?: "auto" | "stepper" | "none";
 }
+/** @publicDocs */
 export interface MinMaxLengthProps {
 	/**
 	 * Specifies the maximum number of characters allowed.
@@ -1657,6 +1730,7 @@ export interface MinMaxLengthProps {
 	 */
 	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.
@@ -1674,6 +1748,7 @@ export interface BaseSelectableProps {
 	 */
 	value?: string;
 }
+/** @publicDocs */
 export interface BaseOptionProps extends BaseSelectableProps {
 	/**
 	 * Whether the control is active.
@@ -1690,6 +1765,7 @@ export interface BaseOptionProps extends BaseSelectableProps {
 	 */
 	defaultSelected?: boolean;
 }
+/** @publicDocs */
 export interface BaseCheckableProps extends BaseSelectableProps, InteractionProps {
 	/**
 	 * Visual content to use as the control label.
@@ -1761,6 +1837,7 @@ interface CheckboxProps$1 extends GlobalProps, BaseCheckableProps, FieldErrorPro
 	 */
 	required?: boolean;
 }
+/** @publicDocs */
 export interface ChipProps$1 {
 	/**
 	 * The content of the chip.
@@ -1773,7 +1850,7 @@ export interface ChipProps$1 {
 	 */
 	graphic?: ComponentChildren;
 	/**
-	 * A label that describes the purpose or contents of the Chip. It will be read to users using assistive technologies such as screen readers.
+	 * A label that describes the purpose or contents of the chip. It will be read to users using assistive technologies such as screen readers.
 	 */
 	accessibilityLabel?: string;
 	/**
@@ -1871,7 +1948,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, `click` won’t fire.
 	 * If the click event originates from a child element, the event will immediately stop propagating from this element.
 	 *
 	 * However, items within the clickable can still receive focus and be interacted with.
@@ -1881,8 +1958,7 @@ 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.
+	 * 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 ''
@@ -1895,7 +1971,7 @@ interface ClickableChipProps$1 extends ChipProps$1, GlobalProps {
 	 */
 	onClick?: (event: Event) => void;
 	/**
-	 * 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.
 	 */
@@ -1955,6 +2031,7 @@ 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.
@@ -1984,18 +2061,24 @@ 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">;
+/** @publicDocs */
 export type ConsentPolicy = "sms-marketing";
 interface ConsentCheckboxProps$1 extends GlobalProps, CheckboxProps$1 {
 	/**
@@ -2005,6 +2088,7 @@ interface ConsentCheckboxProps$1 extends GlobalProps, CheckboxProps$1 {
 	 */
 	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> {
 	/**
@@ -2058,9 +2142,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.
 	 *
@@ -2111,7 +2193,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. These intersect with the result of `allow` and `disallow`.
 	 *
 	 * A comma-separated list of days. Whitespace is allowed after commas.
 	 *
@@ -2198,6 +2280,7 @@ interface DateFieldProps$1 extends GlobalProps, BaseTextFieldProps, Pick<DatePic
 	 */
 	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 {
 	/**
@@ -2255,7 +2338,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.
@@ -2284,6 +2367,7 @@ interface DropZoneProps$1 extends GlobalProps, FileInputProps, BasicFieldProps {
 }
 interface EmailFieldProps$1 extends GlobalProps, BaseTextFieldProps, MinMaxLengthProps, AutocompleteProps<EmailAutocompleteField> {
 }
+/** @publicDocs */
 export type EmailAutocompleteField = ExtractStrict<AnyAutocompleteField, "email" | `${AutocompleteAddressGroup} email`>;
 interface FormProps$1 extends GlobalProps {
 	/**
@@ -2313,7 +2397,9 @@ interface FormProps$1 extends GlobalProps {
 	 */
 	onReset?: (event: Event) => void;
 }
+/** @publicDocs */
 export type SpacingKeyword = SizeKeyword | "none";
+/** @publicDocs */
 export interface GapProps {
 	/**
 	 * Adjust spacing between elements.
@@ -2341,32 +2427,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 {
@@ -2453,6 +2547,7 @@ interface GridItemProps$1 extends GlobalProps, BaseBoxPropsWithRole {
 	 */
 	gridRow?: `span ${number}` | "auto";
 }
+/** @publicDocs */
 export interface BaseTypographyProps {
 	/**
 	 * Modify the color to be more or less intense.
@@ -2475,8 +2570,7 @@ export interface BaseTypographyProps {
 	 */
 	fontVariantNumeric?: "auto" | "normal" | "tabular-nums";
 	/**
-	 * 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.
+	 * 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)
 	 *
 	 * It is recommended to combine it with the `dir` attribute to ensure the text is rendered correctly if the surrounding content’s direction is different.
@@ -2487,8 +2581,8 @@ export interface BaseTypographyProps {
 	/**
 	 * Indicates the directionality of the element’s text.
 	 *
-	 * - `ltr`: languages written from left to right (e.g. English)
-	 * - `rtl`: languages written from right to left (e.g. Arabic)
+	 * - `ltr`: languages written from left to right (such as English)
+	 * - `rtl`: languages written from right to left (such as Arabic)
 	 * - `auto`: the user agent determines the direction based on the content
 	 * - `''`: direction is inherited from parent elements (equivalent to not setting the attribute)
 	 *
@@ -2498,6 +2592,7 @@ export interface BaseTypographyProps {
 	 */
 	dir?: "ltr" | "rtl" | "auto" | "";
 }
+/** @publicDocs */
 export interface BlockTypographyProps {
 	/**
 	 * Truncates the text content to the specified number of lines.
@@ -2526,7 +2621,7 @@ interface HeadingProps$1 extends GlobalProps, AccessibilityVisibilityProps, Bloc
 	 *
 	 * @default 'heading'
 	 *
-	 * @implementation The `heading` role doesn't need to be applied if
+	 * @implementation The `heading` role doesn’t need to be applied if
 	 * the host applies it for you; for example, an HTML host rendering
 	 * an `<h2>` element should not apply the `heading` role.
 	 */
@@ -2536,11 +2631,22 @@ interface IconProps$1 extends GlobalProps, Pick<InteractionProps, "interestFor">
 	/**
 	 * Sets the tone of the icon, based on the intention of the information being conveyed.
 	 *
+	 * - `'auto'`: Inherits the tone from its parent context.
+	 * - `'neutral'`: Standard, non-semantic color for general-purpose icons.
+	 * - `'info'`: Informational content.
+	 * - `'success'`: Positive outcomes or confirmations.
+	 * - `'warning'`: Cautionary messages or alerts.
+	 * - `'critical'`: Errors, destructive actions, or urgent warnings.
+	 * - `'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 emphasis of the icon.
+	 *
+	 * - `'base'`: Standard color intensity.
+	 * - `'subdued'`: A lighter, less prominent appearance.
 	 *
 	 * @default 'base'
 	 */
@@ -2548,148 +2654,115 @@ interface IconProps$1 extends GlobalProps, Pick<InteractionProps, "interestFor">
 	/**
 	 * Adjusts the size of the icon.
 	 *
+	 * - `'small-200'`: Extra extra small.
+	 * - `'small-100'`: Extra small.
+	 * - `'small'`: Small.
+	 * - `'base'`: Standard size.
+	 * - `'large'`: Large.
+	 * - `'large-100'`: Extra large.
+	 *
 	 * @default 'base'
 	 */
 	size?: SizeKeyword;
+	/**
+	 * The type of icon to display. You can specify an icon name from the available icon set, or use an empty string to show no icon.
+	 */
 	type?: IconType | AnyString;
 }
+/** @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.
+	 * Alternative text that describes the image for screen readers. This text should convey the meaning or content of the image to users who can't see it.
 	 *
 	 * @default `''`
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt
 	 */
 	alt?: string;
 	/**
-	 * A set of media conditions and their corresponding sizes.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes
+	 * The sizes of the image at different viewport widths. Use this with `srcSet` to tell the browser which image to load (for example, `'(max-width: 320px) 280px, 640px'`).
 	 */
 	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
+	 * The URL of the image to display. You can provide an absolute or relative URL pointing to the image file. When the image is loading or no `src` is provided, a placeholder is rendered in its place.
 	 */
 	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 source images with different sizes for responsive loading. Use this to provide multiple image sizes for different screen resolutions (for example, `'image-320w.jpg 320w, image-640w.jpg 640w'`). This overrides the `src` property when the browser can match a suitable source.
 	 */
 	srcSet?: string;
 }
 interface ImageProps$1 extends GlobalProps, BaseImageProps, BorderProps {
 	/**
-	 * Sets the semantic meaning of the component’s content. When set,
-	 * the role will be used by assistive technologies to help users
-	 * navigate the page.
+	 * 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.
 	 *
-	 * - `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 size.
+	 * - `'auto'`: The image is displayed at its natural size.
 	 *
 	 * @default 'fill'
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#width
 	 */
 	inlineSize?: "fill" | "auto";
 	/**
-	 * The aspect ratio of the image.
-	 *
-	 * The rendering of the image will depend on the `inlineSize` value:
-	 *
-	 * - `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`.
+	 * The aspect ratio of the image as a width-to-height ratio (for example, `'16/9'` or `'1'`). This helps prevent layout shifts while the image loads.
 	 *
 	 * @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.
+	 * When the image should be loaded.
+	 *
+	 * - `'eager'`: Loads the image immediately.
+	 * - `'lazy'`: Defers loading until the image is near the viewport.
 	 *
 	 * @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 that's fired when the image has loaded successfully.
 	 */
 	onLoad?: (event: Event) => void;
 	/**
-	 * Invoked on load error.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onerror
+	 * A callback that's fired when the image fails to load.
 	 */
 	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.
 	 *
 	 * @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.
+	 * 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;
@@ -2703,170 +2776,196 @@ interface ListItemProps$1 extends GlobalProps {
 interface MapProps$1 extends GlobalProps, SizingProps {
 	/**
 	 * A valid API key for the map service provider.
-	 *
-	 * The map service provider may require an API key. Without an API key the map could be hidden or render in a limited developer mode.
 	 */
 	apiKey?: string;
 	/**
-	 * Map center’s latitude in degrees.
+	 * The latitude of the map's center point, in degrees.
 	 *
 	 * @default 0
 	 */
 	latitude?: number;
 	/**
-	 * Map center’s longitude in degrees.
+	 * The longitude of the map's center point, in degrees.
 	 *
 	 * @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. When set, it will be announced to users using assistive technologies.
 	 */
 	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 to 18.
 	 *
 	 * @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 to 18.
 	 *
 	 * @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 to 18.
 	 *
 	 * @default 0
 	 */
 	minZoom?: number;
 	/**
-	 * Callback when the viewport bounds have changed or the map is resized.
+	 * A callback that's fired when the visible map boundaries change.
 	 */
 	onBoundsChange?: (event: MapBoundsChangeEvent) => void;
 	/**
-	 * Callback when the map view changes.
+	 * A callback that's fired when the map view changes, such as when the user pans or zooms.
 	 */
 	onViewChange?: (event: MapViewChangeEvent) => void;
 	/**
-	 * Callback when the user clicks on the map.
+	 * A callback that's fired when the user clicks on the map.
 	 */
 	onClick?: (event: MapClickEvent) => void;
 	/**
-	 * Callback when the user double-clicks on the map.
+	 * A callback that's fired when the user double-clicks on the map.
 	 */
 	onDblClick?: (event: MapDblClickEvent) => void;
 }
+/**
+ * A geographic coordinate pair representing a location on the map.
+ */
 interface Location$1 {
+	/**
+	 * The latitude of the location in degrees.
+	 */
 	latitude?: number;
+	/**
+	 * The longitude of the location in degrees.
+	 */
 	longitude?: number;
 }
+/**
+ * The geographic boundaries of a visible map area.
+ * @publicDocs
+ */
 export interface Bounds {
+	/**
+	 * The north-east corner of the bounded area.
+	 */
 	northEast?: Location$1;
+	/**
+	 * The south-west corner of the bounded area.
+	 */
 	southWest?: Location$1;
 }
+/**
+ * The event data for map view changes.
+ * @publicDocs
+ */
 export interface MapViewChangeEvent extends Event {
+	/**
+	 * The geographic location of the new map center.
+	 */
 	location?: Location$1;
+	/**
+	 * The current zoom level of the map after the view change.
+	 */
 	zoom?: number;
 }
+/**
+ * The event data for map bounds changes.
+ * @publicDocs
+ */
 export interface MapBoundsChangeEvent extends Event {
+	/**
+	 * The geographic boundaries of the visible map area after the change.
+	 */
 	bounds?: Bounds;
 }
+/**
+ * The event data for map click events.
+ * @publicDocs
+ */
 export interface MapClickEvent extends Event {
+	/**
+	 * The geographic location of the click.
+	 */
 	location?: Location$1;
 }
+/**
+ * The event data for map double-click events.
+ * @publicDocs
+ */
 export interface MapDblClickEvent extends Event {
+	/**
+	 * The geographic location of the double-click.
+	 */
 	location?: Location$1;
 }
 interface MapMarkerProps$1 extends GlobalProps, InteractionProps, Pick<SizingProps, "blockSize" | "inlineSize"> {
 	/**
-	 * Marker’s location latitude in degrees.
+	 * The latitude of the marker location, in degrees.
 	 *
 	 * @default 0
 	 */
 	latitude?: number;
 	/**
-	 * Marker’s longitude latitude in degrees.
+	 * The longitude of the marker location, in degrees.
 	 *
 	 * @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 of the marker. When set, it will be announced to users using assistive technologies.
 	 */
 	accessibilityLabel?: string;
 	/**
-	 * Allows grouping the marker in clusters when zoomed out.
+	 * Whether the marker can be grouped into clusters when zoomed out.
 	 *
 	 * @default false
 	 */
 	clusterable?: boolean;
 	/**
-	 * The graphic to use as the marker.
-	 *
-	 * If unset, it will default to the provider’s default marker.
+	 * The graphic to use as the marker. If unset, the default marker from the map provider is used.
 	 */
 	graphic?: ComponentChildren;
 	/**
-	 * Callback when a marker is clicked.
-	 *
-	 * It does not trigger a click event on the map itself.
+	 * A callback that's fired when the marker is clicked. This does not trigger a click event on the map.
 	 */
 	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 {
 	/**
@@ -2877,6 +2976,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 {
 	/**
@@ -2900,6 +3000,7 @@ interface ParagraphProps$1 extends GlobalProps, BaseTypographyProps, BlockTypogr
 	 */
 	type?: ParagraphType;
 }
+/** @publicDocs */
 export type ParagraphType = 
 /**
  * Indicate the text is a structural grouping of related content.
@@ -2920,27 +3021,25 @@ export type ParagraphType =
  | "small";
 interface PasswordFieldProps$1 extends GlobalProps, BaseTextFieldProps, MinMaxLengthProps, AutocompleteProps<PasswordAutocompleteField> {
 }
+/** @publicDocs */
 export type PasswordAutocompleteField = ExtractStrict<AnyAutocompleteField, "new-password" | "current-password">;
 interface PaymentIconProps$1 extends GlobalProps {
 	/**
-	 * The icon type of the payment method
+	 * The name of the payment method icon to display.
 	 *
 	 * @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 purpose or contents of the payment icon. When set, it will be announced to users using assistive technologies.
 	 */
 	accessibilityLabel?: string;
 }
+/** @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;
 }
@@ -2962,25 +3061,28 @@ interface PressButtonProps$1 extends GlobalProps, Pick<ButtonProps$1, "accessibi
 }
 interface ProductThumbnailProps$1 extends GlobalProps, BaseImageProps {
 	/**
-	 * Decorates the product thumbnail with the quantity of the product.
+	 * The quantity badge displayed on the product thumbnail.
 	 */
 	totalItems?: number;
 	/**
-	 * Adjusts the size the product thumbnail image.
+	 * Adjusts the size of the product thumbnail image.
+	 *
+	 * - `'small-200'`: Extra extra small.
+	 * - `'small-100'`: Extra small.
+	 * - `'small'`: Small.
+	 * - `'base'`: Standard size.
+	 * - `'large'`: Large.
+	 * - `'large-100'`: Extra large.
 	 *
 	 * @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 that's fired when the thumbnail image has loaded successfully.
 	 */
 	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 that's fired when the thumbnail image fails to load.
 	 */
 	onError?: (event: Event) => void;
 }
@@ -3002,7 +3104,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.
 	 *
@@ -3016,7 +3118,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
 	 *
@@ -3026,46 +3128,39 @@ interface ProgressProps$1 extends GlobalProps {
 }
 interface QRCodeProps$1 extends GlobalProps {
 	/**
-	 * Set the border of the QR code.
+	 * The border style of the QR code.
 	 *
-	 * `base`: applies border that is appropriate for the element.
-	 * `none`: removes the border from the element.
+	 * - `'base'`: Applies a standard border.
+	 * - `'none'`: Removes the border.
 	 *
 	 * @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 data to encode in the QR code. This can be any string, such as a URL, email address, or plain text. When scanned, specific string formats can trigger device actions like opening a link, preparing an email, or launching an app.
 	 */
 	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.
+	 * - `'fill'`: The QR code takes up 100% of the available inline size and maintains a 1:1 aspect ratio.
+	 * - `'base'`: The QR code is displayed at its default size.
 	 *
 	 * @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. When set, it will be announced to users using assistive technologies.
 	 *
 	 * @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 that's fired 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.
 	 */
 	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.
+	 * URL of an image to display in the center of the QR code, typically used for branding or to indicate what scanning the code will do.
 	 */
 	logo?: string;
 }
@@ -3089,6 +3184,7 @@ interface QueryContainerProps$1 extends GlobalProps {
 	 */
 	containerName?: string;
 }
+/** @publicDocs */
 export type OverflowKeyword = "auto" | "hidden";
 interface ScrollBoxProps$1 extends GlobalProps, Omit<BaseBoxPropsWithRole, "overflow"> {
 	/**
@@ -3109,19 +3205,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;
 	/**
@@ -3129,8 +3225,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'
@@ -3147,28 +3243,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
 	 */
@@ -3180,12 +3263,8 @@ interface SheetProps$1 extends BaseOverlayProps, BaseOverlayMethods, ToggleEvent
 	/**
 	 * Adjust the padding of all edges.
 	 *
-	 * `base`: applies padding that is appropriate for the element. Note that it may result in no padding if Shopify
-	 * believes this is the right design decision in a particular context.
-	 *
-	 * `none`: removes all padding from the element. This can be useful when elements inside the Sheet need to span
-	 * to the edge of the Sheet. For example, a full-width image. In this case, rely on `Box` with a padding of 'base'
-	 * to bring back the desired padding for the rest of the content.
+	 * - `base`: Applies padding that is appropriate for the element. Note that it may result in no padding if Shopify believes this is the right design decision in a particular context.
+	 * - `none`: Removes all padding from the element. This can be useful when elements inside the sheet need to span to the edge of the sheet. For example, a full-width image. In this case, rely on box with a padding of `base` to bring back the desired padding for the rest of the content.
 	 *
 	 * @default 'base'
 	 */
@@ -3288,6 +3367,7 @@ interface TextProps$1 extends GlobalProps, AccessibilityVisibilityProps, BaseTyp
 	 */
 	type?: TextType;
 }
+/** @publicDocs */
 export type TextType = 
 /**
  * Indicate the text is contact information. Typically used for addresses.
@@ -3398,14 +3478,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`>;
 
 
@@ -3419,21 +3501,33 @@ type ReducedBorderSizeKeyword = Extract<BorderSizeKeyword, 'none' | 'base' | 'la
 type ReducedColorKeyword = Extract<ColorKeyword, 'base'>;
 type BorderShorthand = ReducedBorderSizeKeyword | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword}` | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword} ${BorderStyleKeyword}`;
 /**
- * Used when an element does not have children.
+ * The base properties for elements that don't have children, providing essential attributes like keys and refs for component management.
  */
 interface BaseElementProps<TClass = HTMLElement> {
+    /**
+     * A unique identifier for this element within its parent. Used by the rendering engine for efficient reconciliation when lists change.
+     */
     key?: preact.Key;
+    /**
+     * A reference to the underlying DOM element, typically created using `useRef()`. This allows you to access and manipulate the DOM element directly in your component logic.
+     */
     ref?: preact.Ref<TClass>;
+    /**
+     * Assigns this element to a named slot in a parent component that uses slot-based composition patterns.
+     */
     slot?: Lowercase<string>;
 }
 /**
- * Used when an element has children.
+ * The base properties for elements that have children, extending `BaseElementProps` with children support.
  */
 interface BaseElementPropsWithChildren<TClass = HTMLElement> extends BaseElementProps<TClass> {
+    /**
+     * The child elements to render within this component.
+     */
     children?: preact.ComponentChildren;
 }
 /**
- * Used as the single source of truth for checkout icon types.
+ * The complete list of [icon names](https://github.com/Shopify/ui-api-design/blob/main/packages/ui-api-design/src/components/Icon/Icon.ts#L10) available in checkout and customer account surfaces. These icons are drawn from Shopify's design system and cover common UI patterns like navigation, status indicators, actions, and commerce concepts.
  *
  * @see https://github.com/Shopify/ui-api-design/blob/main/packages/ui-api-design/src/components/Icon/Icon.ts#L10
  */
@@ -4173,7 +4267,21 @@ declare module 'preact' {
 
 declare const tagName$v = "s-map-marker";
 interface MapMarkerElementProps extends Pick<MapMarkerProps$1, 'accessibilityLabel' | 'blockSize' | 'command' | 'commandFor' | 'clusterable' | 'inlineSize' | 'latitude' | 'longitude'> {
+    /**
+     * Sets the action the `commandFor` target should take when this component is activated. Learn more about the [`command` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command).
+     *
+     * - `--auto`: a default action for the target component.
+     * - `--show`: shows the target component.
+     * - `--hide`: hides the target component.
+     * - `--toggle`: toggles the target component.
+     *
+     * @default '--auto'
+     */
     command?: Extract<MapMarkerProps$1['command'], '--auto' | '--show' | '--hide' | '--toggle'>;
+    /**
+     * The ID of the component to control when this component is activated. Pair with the `command` property to specify what action to perform on the target component. Learn more about the [`commandFor` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor).
+     */
+    commandFor?: MapMarkerProps$1['commandFor'];
 }
 interface MapMarkerEvents extends Pick<MapMarkerProps$1, 'onClick'> {
 }
@@ -4223,6 +4331,18 @@ declare module 'preact' {
 
 declare const tagName$t = "s-modal";
 interface ModalElementProps extends Pick<ModalProps$1, 'accessibilityLabel' | 'heading' | 'id' | 'padding' | 'size'> {
+    /**
+     * The size of the modal.
+     *
+     * - `'base'`: The default size, suitable for most use cases.
+     * - `'small'`: A compact modal for simple confirmations or short messages.
+     * - `'small-100'`: The smallest modal size.
+     * - `'large'`: A large modal for complex content or forms.
+     * - `'large-100'`: The largest fixed-size modal, providing maximum room for content.
+     * - `'max'`: Expands the modal to its maximum size as defined by the host application, on both the horizontal and vertical axes.
+     *
+     * @default 'base'
+     */
     size?: Extract<ModalProps$1['size'], 'small-100' | 'small' | 'base' | 'large-100' | 'large' | 'max'>;
 }
 interface ModalEvents extends Pick<ModalProps$1, 'onAfterHide' | 'onAfterShow' | 'onHide' | 'onShow'> {
@@ -4411,49 +4531,37 @@ declare module 'preact' {
 declare const tagName$l = "s-popover";
 interface PopoverElementProps extends Pick<PopoverProps$1, 'id'> {
     /**
-     * Adjust the block size.
-     *
-     * @see https://developer.mozilla.org/en-US/docs/Web/CSS/block-size
+     * The block size of the popover (height in horizontal writing modes). Learn more about the [block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/block-size).
      *
      * @default 'auto'
      */
     blockSize?: SizeUnitsOrAuto;
     /**
-     * Adjust the inline size.
-     *
-     * @see https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size
+     * The inline size of the popover (width in horizontal writing modes). Learn more about the [inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size).
      *
      * @default 'auto'
      */
     inlineSize?: SizeUnitsOrAuto;
     /**
-     * Adjust the maximum block size.
-     *
-     * @see https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size
+     * The maximum block size of the popover. Constrains the popover's height to prevent it from exceeding this value. Learn more about the [max-block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size).
      *
      * @default 'none'
      */
     maxBlockSize?: SizeUnitsOrNone;
     /**
-     * Adjust the maximum inline size.
-     *
-     * @see https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size
+     * The maximum inline size of the popover. Constrains the popover's width to prevent it from exceeding this value. Learn more about the [max-inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size).
      *
      * @default 'none'
      */
     maxInlineSize?: SizeUnitsOrNone;
     /**
-     * Adjust the minimum block size.
-     *
-     * @see https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size
+     * The minimum block size of the popover. Ensures the popover maintains at least this height. Learn more about the [min-block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size).
      *
      * @default '0'
      */
     minBlockSize?: SizeUnits;
     /**
-     * Adjust the minimum inline size.
-     *
-     * @see https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size
+     * The minimum inline size of the popover. Ensures the popover maintains at least this width. Learn more about the [min-inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size).
      *
      * @default '0'
      */
@@ -4655,11 +4763,7 @@ declare module 'preact' {
 declare const tagName$c = "s-sheet";
 interface SheetElementProps extends Pick<SheetProps$1, 'defaultOpen' | 'heading' | 'id'> {
     /**
-     * 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 sheet, announced by assistive technologies. When set, screen readers will use this label instead of the `heading` to describe the sheet.
      */
     accessibilityLabel?: string;
 }