@shopify/ui-extensions 2026.1.2 → 2026.1.4

package/build/ts/surfaces/admin/components/shared.d.ts

@@ -1,4 +1,4 @@
-/** VERSION: 1.38.0 **/
+/** VERSION: 1.25.0 **/
 
 /* eslint-disable @typescript-eslint/ban-types */
 
@@ -7,35 +7,48 @@
 /**
  * TODO: Update `any` type here after this is resolved
  * https://github.com/Shopify/ui-api-design/issues/139
+ * @publicDocs
  */
 export type ComponentChildren = preact.ComponentChildren;
+/**
+ * @publicDocs
+ */
 export type StringChildren = string;
+/**
+ * @publicDocs
+ */
 export interface GlobalProps {
   /**
    * A unique identifier for the element.
    */
   id?: string;
 }
+/**
+ * @publicDocs
+ */
 export interface ActionProps {
   /**
    * The text to use as the Action modal’s title. If not provided, the name of the extension will be used.
    */
   heading?: string;
 }
+/**
+ * @publicDocs
+ */
 export interface ActionSlots {
   /**
-   * The primary action to perform, provided as a button or link type element.
+   * The primary action element, typically a button or link component representing the main call-to-action.
    */
   primaryAction?: ComponentChildren;
   /**
-   * The secondary actions to perform, provided as button or link type elements.
+   * The secondary action elements, typically button or link components representing alternative or supporting actions.
    */
   secondaryActions?: ComponentChildren;
 }
 interface AdminActionProps$1 extends GlobalProps, ActionProps, ActionSlots {
   /**
-   * Whether the action is in a loading state, such as initial page load or action opening.
-   * When true, the action could be in an inert state, which prevents user interaction.
+   * Whether the action is in a loading state, such as during initial page load or when the action is being opened.
+   * When `true`, the action might be in an inert state that prevents user interaction.
    *
    * @default false
    */
@@ -43,39 +56,40 @@ interface AdminActionProps$1 extends GlobalProps, ActionProps, ActionSlots {
 }
 interface AdminBlockProps$1 extends GlobalProps {
   /**
-   * The text to use as the Block title in the block header. If not provided, the name of the
-   * extension will be used.
+   * The text displayed as the block's title in the header. If not provided, the extension name will be used.
    */
   heading?: string;
   /**
-   * The summary to display when the app block is collapsed.
-   * Summary longer than 30 characters will be truncated.
+   * The summary text displayed when the app block is collapsed. Summaries longer than 30 characters will be truncated.
    */
   collapsedSummary?: string;
 }
 interface AdminPrintActionProps$1 extends GlobalProps {
   /**
-   * Sets the src URL of the preview and the document to print.
+   * The source URL of the preview and the document to print.
    * If not provided, the preview will show an empty state and the print button will be disabled.
-   * HTML, PDFs and images are supported.
+   * HTML, PDFs, and images are supported.
    */
   src?: string;
 }
+/**
+ * @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;
 }
@@ -86,90 +100,105 @@ 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.
    *
    * @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 [ToggleEvent.newState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState) and [ToggleEvent.oldState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState).
    */
   onAfterToggle?: (event: ToggleEvent$1) => void;
   /**
-   * Callback straight after the element state changes.
+   * A callback 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
    *   `newState` will be `closed`.
    *
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/toggle_event
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState
+   * Learn more about the [toggle event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/toggle_event), [ToggleEvent.newState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState), and [ToggleEvent.oldState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState).
    */
   onToggle?: (event: ToggleEvent$1) => void;
 }
+/**
+ * @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.
+   * A method that accepts a promise signaling the duration and eventual success or failure of actions relating to the event.
    *
-   * This may be called many times, which adds promises to the event.
+   * This might be called multiple times to add promises to the event.
    *
-   * However, this may only be called synchronously during the dispatch of the event.
+   * However, this might only be called synchronously during the dispatch of the event.
    * As in, you cannot call it after a `setTimeout` or microtask.
    */
   waitUntil?: (promise: Promise<void>) => void;
 }
+/**
+ * @publicDocs
+ */
 export interface AggregateError<T extends Error> extends Error {
   errors: T[];
 }
+/**
+ * @publicDocs
+ */
 export interface AggregateErrorEvent<T extends Error> extends ErrorEvent {
   error: AggregateError<T>;
 }
+/**
+ * @publicDocs
+ */
 export type SizeKeyword =
   | 'small-500'
   | 'small-400'
@@ -184,46 +213,73 @@ export type SizeKeyword =
   | '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';
 interface AvatarProps$1 extends GlobalProps {
   /**
-   * Initials to display in the avatar.
+   * The initials to display in the avatar when no image is provided or fails to load. Typically one or two characters representing a person's first and last name initials (e.g., "JD" for John Doe).
    */
   initials?: string;
   /**
-   * The URL or path to the image.
-   *
-   * Initials will be rendered as a fallback if `src` is not provided, fails to load or does not load quickly
+   * The URL or path to the avatar image. When provided, the image takes priority over `initials`. If the image is not provided, fails to load, or loads slowly, `initials` will be rendered as a fallback.
    */
   src?: string;
   /**
-   * Invoked when load of provided image completes successfully.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onload
+   * A callback fired when the avatar image loads successfully. Learn more about the [load event](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onload).
    */
   onLoad?: (event: Event) => void;
   /**
-   * Invoked on load error of provided image.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onerror
+   * A callback fired when the avatar image fails to load. Learn more about the [error event](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onerror).
    */
   onError?: (event: Event) => void;
   /**
-   * Size of the avatar.
+   * The size of the avatar. Available sizes range from `small-500` (smallest) to `large-500` (largest), with `base` providing the default medium size that works well in most contexts.
    *
    * @default 'base'
    */
   size?: SizeKeyword;
   /**
-   * An alternative text that describes the avatar for the reader
-   * to understand what it is about or identify the user the avatar belongs to.
+   * Alternative text that describes the avatar for accessibility.
+   *
+   * Provides a text description of the avatar for users with assistive technology
+   * and serves as a fallback when the avatar fails to load. A well-written description
+   * enables people with visual impairments to understand non-text content.
+   *
+   * When a screen reader encounters an avatar, it reads this description aloud.
+   * When an avatar fails to load, this text displays on screen, helping all users
+   * understand what content was intended.
+   *
+   * Learn more about [writing effective alt text](https://www.shopify.com/ca/blog/image-alt-text#4)
+   * and the [alt attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt).
    */
   alt?: string;
 }
+/**
+ * Defines the background color intensity or emphasis level for UI elements.
+ *
+ * - `transparent`: No background, allowing the underlying surface to show through.
+ * - `ColorKeyword`: Applies color intensity levels (subdued, base, strong) to create spatial emphasis and containment.
+ *
+ * @publicDocs
+ */
 export type BackgroundColorKeyword = 'transparent' | ColorKeyword;
+/**
+ * @publicDocs
+ */
 export interface BackgroundProps {
   /**
-   * Adjust the background of the element.
+   * The background color of the element. Use `transparent` for no background, or choose from `subdued`, `base`, or `strong` to apply varying levels of color intensity based on the component's `tone`.
+   *
+   * - `transparent`: No background, allowing the underlying surface to show through.
+   * - `ColorKeyword`: Applies color intensity levels (subdued, base, strong) to create spatial emphasis and containment.
    *
    * @default 'transparent'
    */
@@ -233,11 +289,12 @@ export interface BackgroundProps {
  * Tone is a property for defining the color treatment of a component.
  *
  * A tone can apply a grouping of colors to a component. For example,
- * critical may have a specific text color and background color.
+ * critical might have a specific text color and background color.
  *
- * In some cases, like for Banner, the tone may also affect the semantic and accessibility treatment of the component.
+ * In some cases, like for Banner, the tone might also affect the semantic and accessibility treatment of the component.
  *
  * @default 'auto'
+ * @publicDocs
  */
 export type ToneKeyword =
   | 'auto'
@@ -261,7 +318,6 @@ declare const privateIconArray: readonly [
   'alert-octagon-filled',
   'alert-triangle',
   'alert-triangle-filled',
-  'align-horizontal-centers',
   'app-extension',
   'apps',
   'archive',
@@ -325,7 +381,6 @@ declare const privateIconArray: readonly [
   'catalog-product',
   'categories',
   'channels',
-  'channels-filled',
   'chart-cohort',
   'chart-donut',
   'chart-funnel',
@@ -811,17 +866,47 @@ 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.
+ * 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`.
@@ -830,6 +915,7 @@ export type MaybeResponsive<T> = T | `@container${string}`;
  * //   ^? string
  * type PropName = 'foo' | 'bar' | (string & {})
  * //   ^? 'foo' | 'bar' | (string & {})
+ * @publicDocs
  */
 export type AnyString = string & {};
 /**
@@ -837,37 +923,50 @@ 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 {
   /**
-   * The content of the Badge.
+   * The text or elements displayed inside the badge component.
    */
   children?: ComponentChildren;
   /**
-   * Sets the tone of the Badge, based on the intention of the information being conveyed.
+   * The semantic meaning and color treatment of the component.
+   *
+   * - `auto`: Automatically determined based on context.
+   * - `neutral`: General information without specific intent.
+   * - `info`: Informational content or helpful tips.
+   * - `success`: Positive outcomes or successful states.
+   * - `caution`: Advisory notices that need attention.
+   * - `warning`: Important warnings about potential issues.
+   * - `critical`: Urgent problems or destructive actions.
    *
    * @default 'auto'
    */
   tone?: ToneKeyword;
   /**
-   * Modify the color to be more or less intense.
+   * Controls the visual weight and emphasis of the badge.
+   *
+   * - `base`: Standard weight with moderate emphasis, suitable for most use cases.
+   * - `strong`: Increased visual weight for higher emphasis and prominence.
    *
    * @default 'base'
    */
   color?: ColorKeyword;
   /**
-   * The type of icon to be displayed in the badge.
+   * An icon displayed inside the badge to provide additional visual context or reinforce the badge's meaning.
+   * Accepts any icon name from the icon library or a custom string identifier.
    *
    * @default ''
    */
   icon?: IconType | AnyString;
   /**
-   * The position of the icon in relation to the text.
+   * The position of the icon relative to the badge text. Use `start` to place the icon before the text, or `end` to place it after.
    */
   iconPosition?: 'start' | 'end';
   /**
-   * Adjusts the size.
+   * The size of the badge. Available sizes range from `small-500` (smallest) to `large-500` (largest), with `base` providing the default size.
    *
    * @default 'base'
    */
@@ -875,42 +974,42 @@ interface BadgeProps$1 extends GlobalProps {
 }
 interface BannerProps$1 extends GlobalProps, ActionSlots {
   /**
-   * The title of the banner.
+   * The heading text displayed at the top of the banner to summarize the message or alert.
    *
    * @default ''
    */
   heading?: string;
   /**
-   * The content of the Banner.
+   * The main content displayed within the banner component, typically descriptive text or other elements providing details about the message or alert.
    */
   children?: ComponentChildren;
   /**
-   * Sets the tone of the Banner, based on the intention of the information being conveyed.
+   * The semantic meaning and color treatment of the component. The banner is a live region and the type of status is dictated by the tone selected.
    *
-   * The banner is a live region and the type of status will be dictated by the Tone selected.
+   * - `auto`: Automatically determined based on context.
+   * - `neutral`: General status information without emphasis.
+   * - `info`: Informational content or helpful tips.
+   * - `success`: Positive outcomes or successful states.
+   * - `caution`: Situations that need attention but aren't urgent.
+   * - `warning`: Important warnings about potential issues.
+   * - `critical`: Urgent problems or destructive actions.
    *
-   * - `critical` creates an [assertive live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) that is announced by screen readers immediately.
-   * - `neutral`, `info`, `success`, `warning` and `caution` creates an [informative live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/status_role) that is announced by screen readers after the current message.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions
-   * @see https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role
-   * @see https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/status_role
+   * The `critical` tone creates an [assertive live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role) that is announced by screen readers immediately. The `neutral`, `info`, `success`, `warning`, and `caution` tones create an [informative live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/status_role) that is announced by screen readers after the current message.
    *
    * @default 'auto'
    */
   tone?: ToneKeyword;
   /**
-   * Makes the content collapsible.
-   * A collapsible banner will conceal child elements initially, but allow the user to expand the banner to see them.
+   * Whether the banner content can be collapsed and expanded by the user. A collapsible banner conceals child elements initially, allowing the user to expand the banner to reveal them.
    *
    * @default false
    */
   collapsible?: boolean;
   /**
-   * Determines whether the close button of the banner is present.
+   * Whether the banner displays a close button that allows users to dismiss it.
    *
    * When the close button is pressed, the `dismiss` event will fire,
-   * then `hidden` will be true,
+   * then `hidden` will be set to `true`,
    * any animation will complete,
    * and the `afterhide` event will fire.
    *
@@ -918,17 +1017,17 @@ interface BannerProps$1 extends GlobalProps, ActionSlots {
    */
   dismissible?: boolean;
   /**
-   * Event handler when the banner is dismissed by the user.
+   * A callback that fires when the banner is dismissed by the user clicking the close button.
    *
-   * This does not fire when setting `hidden` manually.
+   * This doesn't fire when setting `hidden` manually.
    *
-   * The `hidden` property will be `false` when this event fires.
+   * The `hidden` property is `false` when this event fires.
    */
   onDismiss?: (event: Event) => void;
   /**
-   * Event handler when the banner has fully hidden.
+   * A callback that fires when the banner has fully hidden, including after any hide animations have completed.
    *
-   * The `hidden` property will be `true` when this event fires.
+   * The `hidden` property is `true` when this event fires.
    *
    * @implementation If implementations animate the hiding of the banner,
    * this event must fire after the banner has fully hidden.
@@ -936,18 +1035,20 @@ interface BannerProps$1 extends GlobalProps, ActionSlots {
    */
   onAfterHide?: (event: Event) => void;
   /**
-   * Determines whether the banner is hidden.
+   * Controls whether the banner is visible or hidden.
    *
-   * If this property is being set on each framework render (as in 'controlled' usage),
-   * and the banner is `dismissible`,
-   * ensure you update app state for this property when the `dismiss` event fires.
+   * When using a controlled component pattern and the banner is `dismissible`,
+   * update this property to `true` when the `dismiss` event fires.
    *
-   * If the banner is not `dismissible`, it can still be hidden by setting this property.
+   * You can hide the banner programmatically by setting this to `true` even if it's not `dismissible`.
    *
    * @default false
    */
   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).
@@ -955,11 +1056,15 @@ export interface DisplayProps {
    * - `auto`: the component’s initial value. The actual value depends on the component and context.
    * - `none`: hides the component from display and removes it from the accessibility tree, making it invisible to screen readers.
    *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/display
+   * Learn more about the [display property](https://developer.mozilla.org/en-US/docs/Web/CSS/display).
+   *
    * @default 'auto'
    */
   display?: MaybeResponsive<'auto' | 'none'>;
 }
+/**
+ * @publicDocs
+ */
 export interface AccessibilityRoleProps {
   /**
    * Sets the semantic meaning of the component’s content. When set,
@@ -973,6 +1078,37 @@ export interface AccessibilityRoleProps {
    */
   accessibilityRole?: AccessibilityRole;
 }
+/**
+ * Defines the semantic role of a component for assistive technologies like screen readers.
+ *
+ * Accessibility roles help users with disabilities understand the purpose and structure of content.
+ * These roles map to HTML elements and ARIA roles, providing semantic meaning beyond visual presentation.
+ *
+ * Use these roles to:
+ * - Improve navigation for screen reader users
+ * - Provide semantic structure to your UI
+ * - Ensure proper interpretation by assistive technologies
+ *
+ * Learn more about [ARIA roles](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) in the MDN web docs.
+ *
+ * - `main`: Indicates the primary content area of the page.
+ * - `header`: Marks a component as a header containing introductory content or navigation.
+ * - `footer`: Designates content containing information like copyright, navigation links, or privacy statements.
+ * - `section`: Defines a generic thematic grouping of content that should have a heading or accessible label.
+ * - `aside`: Marks supporting content that relates to but is separate from the main content.
+ * - `navigation`: Identifies major groups of navigation links for moving around the site or page.
+ * - `ordered-list`: Represents a list where the order of items is meaningful.
+ * - `list-item`: Identifies an individual item within a list.
+ * - `list-item-separator`: Acts as a visual and semantic divider between items in a list.
+ * - `unordered-list`: Represents a list where the order of items is not meaningful.
+ * - `separator`: Creates a divider that separates and distinguishes sections of content.
+ * - `status`: Defines a live region for advisory information that is not urgent enough to be an alert.
+ * - `alert`: Marks important, time-sensitive information that requires the user's immediate attention.
+ * - `generic`: Creates a semantically neutral container element with no inherent meaning.
+ * - `presentation`: Removes semantic meaning from an element while preserving its visual appearance.
+ * - `none`: Synonym for `presentation`, removes semantic meaning while keeping visual styling.
+ * @publicDocs
+ */
 export type AccessibilityRole =
   /**
    * Used to indicate the primary content.
@@ -997,21 +1133,13 @@ export type AccessibilityRole =
   | 'footer'
   /**
    * Used to indicate a generic section.
-   * Sections should always have a `Heading` or an accessible name provided in the `accessibilityLabel` property.
+   * 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.
    *
    */
   | 'section'
-  /**
-   * Used to identify a perceivable section containing content that is relevant to a specific, author-specified purpose and sufficiently important that users will likely want to be able to navigate to the section easily.
-   *
-   * In an HTML host `region` will render as `<div role="region">`.
-   * A region **must** have an accessible name provided via the `accessibilityLabel` property.
-   * Learn more about the [`region` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/region_role) in the MDN web docs.
-   */
-  | 'region'
   /**
    * Used to designate a supporting section that relates to the main content.
    *
@@ -1096,24 +1224,33 @@ export type AccessibilityRole =
    * Learn more about the [`none` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/none_role) in the MDN web docs.
    */
   | 'none';
+/**
+ * @publicDocs
+ */
 export interface AccessibilityVisibilityProps {
   /**
-   * Changes the visibility of the element.
+   * Controls the visibility of the element for both visual and assistive technology users.
    *
-   * - `visible`: the element is visible to all users.
-   * - `hidden`: the element is removed from the accessibility tree but remains visible.
-   * - `exclusive`: the element is visually hidden but remains in the accessibility tree.
+   * - `visible`: The element is visible to all users (both sighted users and screen readers).
+   * - `hidden`: The element is visually visible but hidden from screen readers. Use this for decorative elements that don't provide meaningful information.
+   * - `exclusive`: The element is visually hidden but announced by screen readers. Use this for screen-reader-only content like skip links or additional context.
    *
    * @default 'visible'
    */
   accessibilityVisibility?: 'visible' | 'hidden' | 'exclusive';
 }
+/**
+ * @publicDocs
+ */
 export interface LabelAccessibilityVisibilityProps {
   /**
-   * Changes the visibility of the component's label.
+   * Controls whether the label is visible to all users or only to screen readers.
+   *
+   * - `visible`: The label is shown to everyone (default).
+   * - `exclusive`: The label is visually hidden but still announced by screen readers.
    *
-   * - `visible`: the label is visible to all users.
-   * - `exclusive`: the label is visually hidden but remains in the accessibility tree.
+   * Use `exclusive` when the surrounding context makes the label redundant visually,
+   * but screen reader users still need it for clarity.
    *
    * @default 'visible'
    */
@@ -1122,35 +1259,42 @@ export interface LabelAccessibilityVisibilityProps {
     '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.
-   *
-   * [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) is
-   * supported. Note that, contrary to the CSS, it uses flow-relative values and the order is:
+   * The padding applied to all edges of the component.
    *
-   * - 4 values: `block-start inline-end block-end inline-start`
-   * - 3 values: `block-start inline block-end`
-   * - 2 values: `block inline`
+   * Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) using flow-relative values:
+   * - 1 value applies to all sides
+   * - 2 values apply to block (top/bottom) and inline (left/right)
+   * - 3 values apply to block-start (top), inline (left/right), and block-end (bottom)
+   * - 4 values apply to block-start (top), inline-end (right), block-end (bottom), and inline-start (left)
    *
-   * For example:
-   * - `large` means block-start, inline-end, block-end and inline-start paddings are `large`.
-   * - `large none` means block-start and block-end paddings are `large`, inline-start and inline-end paddings are `none`.
-   * - `large none large` means block-start padding is `large`, inline-end padding is `none`, block-end padding is `large` and inline-start padding is `none`.
-   * - `large none large small` means block-start padding is `large`, inline-end padding is `none`, block-end padding is `large` and inline-start padding is `small`.
+   * **Examples:** `base`, `large none`, `base large-100 base small`
    *
-   * A padding value of `auto` will use the default padding for the closest container that has had its usual padding removed.
+   * Use `auto` to inherit padding from the nearest container with removed padding.
    *
    * @default 'none'
    */
   padding?: MaybeResponsive<MaybeAllValuesShorthandProperty<PaddingKeyword>>;
   /**
-   * Adjust the block-padding.
+   * The block-direction padding (top and bottom in horizontal writing modes).
    *
-   * - `large none` means block-start padding is `large`, block-end padding is `none`.
+   * Accepts a single value for both sides or two space-separated values for block-start and block-end.
    *
-   * This overrides the block value of `padding`.
+   * **Example:** `large none` applies `large` to the top and `none` to the bottom.
+   *
+   * Overrides the block value from `padding`.
    *
    * @default '' - meaning no override
    */
@@ -1158,27 +1302,29 @@ export interface PaddingProps {
     MaybeTwoValuesShorthandProperty<PaddingKeyword> | ''
   >;
   /**
-   * Adjust the block-start padding.
+   * The block-start padding (top in horizontal writing modes).
    *
-   * This overrides the block-start value of `paddingBlock`.
+   * Overrides the block-start value from `paddingBlock`.
    *
    * @default '' - meaning no override
    */
   paddingBlockStart?: MaybeResponsive<PaddingKeyword | ''>;
   /**
-   * Adjust the block-end padding.
+   * The block-end padding (bottom in horizontal writing modes).
    *
-   * This overrides the block-end value of `paddingBlock`.
+   * Overrides the block-end value from `paddingBlock`.
    *
    * @default '' - meaning no override
    */
   paddingBlockEnd?: MaybeResponsive<PaddingKeyword | ''>;
   /**
-   * Adjust the inline padding.
+   * The inline-direction padding (left and right in horizontal writing modes).
+   *
+   * Accepts a single value for both sides or two space-separated values for inline-start and inline-end.
    *
-   * - `large none` means inline-start padding is `large`, inline-end padding is `none`.
+   * **Example:** `large none` applies `large` to the left and `none` to the right.
    *
-   * This overrides the inline value of `padding`.
+   * Overrides the inline value from `padding`.
    *
    * @default '' - meaning no override
    */
@@ -1186,101 +1332,134 @@ export interface PaddingProps {
     MaybeTwoValuesShorthandProperty<PaddingKeyword> | ''
   >;
   /**
-   * Adjust the inline-start padding.
+   * The inline-start padding (left in LTR writing modes, right in RTL).
    *
-   * This overrides the inline-start value of `paddingInline`.
+   * Overrides the inline-start value from `paddingInline`.
    *
    * @default '' - meaning no override
    */
   paddingInlineStart?: MaybeResponsive<PaddingKeyword | ''>;
   /**
-   * Adjust the inline-end padding.
+   * The inline-end padding (right in LTR writing modes, left in RTL).
    *
-   * This overrides the inline-end value of `paddingInline`.
+   * Overrides the inline-end value from `paddingInline`.
    *
    * @default '' - meaning no override
    */
   paddingInlineEnd?: MaybeResponsive<PaddingKeyword | ''>;
 }
+/**
+ * Represents size values in pixels, percentages, or zero.
+ *
+ * - `${number}px`: Absolute size in pixels for fixed dimensions (such as `100px`, `24px`).
+ * - `${number}%`: Relative size as a percentage of the parent container (such as `50%`, `100%`).
+ * - `0`: Zero size, equivalent to no dimension.
+ * @publicDocs
+ */
 export type SizeUnits = `${number}px` | `${number}%` | `0`;
+/**
+ * Represents size values that can also be set to `auto` for automatic sizing.
+ *
+ * - `SizeUnits`: Specific size values in pixels, percentages, or zero for precise control.
+ * - `auto`: Automatically sizes based on content and layout constraints.
+ * @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.
+ * @publicDocs
+ */
 export type SizeUnitsOrNone = SizeUnits | 'none';
+/**
+ * @publicDocs
+ */
 export interface SizingProps {
   /**
-   * Adjust the block size.
+   * The block size of the element (height in horizontal writing modes). Learn more about the [block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/block-size).
    *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/block-size
+   * - `SizeUnits`: Specific size values in pixels, percentages, or zero for precise control.
+   * - `auto`: Automatically sizes based on content and layout constraints.
    *
    * @default 'auto'
    */
   blockSize?: MaybeResponsive<SizeUnitsOrAuto>;
   /**
-   * Adjust the minimum block size.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size
+   * The minimum block size of the element (minimum height in horizontal writing modes). Learn more about the [min-block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size).
    *
    * @default '0'
    */
   minBlockSize?: MaybeResponsive<SizeUnits>;
   /**
-   * Adjust the maximum block size.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size
+   * The maximum block size of the element (maximum height in horizontal writing modes). Learn more about the [max-block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size).
    *
    * @default 'none'
    */
   maxBlockSize?: MaybeResponsive<SizeUnitsOrNone>;
   /**
-   * Adjust the inline size.
+   * The inline size of the element (width in horizontal writing modes). Learn more about the [inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size).
    *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size
+   * - `SizeUnits`: Specific size values in pixels, percentages, or zero for precise control.
+   * - `auto`: Automatically sizes based on content and layout constraints.
    *
    * @default 'auto'
    */
   inlineSize?: MaybeResponsive<SizeUnitsOrAuto>;
   /**
-   * Adjust the minimum inline size.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size
+   * The minimum inline size of the element (minimum width in horizontal writing modes). Learn more about the [min-inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size).
    *
    * @default '0'
    */
   minInlineSize?: MaybeResponsive<SizeUnits>;
   /**
-   * Adjust the maximum inline size.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size
+   * The maximum inline size of the element (maximum width in horizontal writing modes). Learn more about the [max-inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size).
    *
    * @default 'none'
    */
   maxInlineSize?: MaybeResponsive<SizeUnitsOrNone>;
 }
+/**
+ * @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';
+/**
+ * @publicDocs
+ */
 export type BorderRadiusKeyword = SizeKeyword | 'max' | 'none';
 /**
  * Represents a shorthand for defining a border. It can be a combination of size, optionally followed by color, optionally followed by style.
+ * @publicDocs
  */
 export type BorderShorthand =
   | BorderSizeKeyword
   | `${BorderSizeKeyword} ${ColorKeyword}`
   | `${BorderSizeKeyword} ${ColorKeyword} ${BorderStyleKeyword}`;
+/**
+ * @publicDocs
+ */
 export interface BorderProps {
   /**
-   * Set the border via the shorthand property.
-   *
-   * This can be a size, optionally followed by a color, optionally followed by a style.
+   * Applies a border using shorthand syntax to specify width, color, and style in a single property.
    *
-   * If the color is not specified, it will be `base`.
+   * Accepts a size value, optionally followed by a color, optionally followed by a style.
+   * Omitted values use defaults: color defaults to `base`, style defaults to `auto`.
    *
-   * If the style is not specified, it will be `auto`.
-   *
-   * Values can be overridden by `borderWidth`, `borderStyle`, and `borderColor`.
+   * Individual properties (`borderWidth`, `borderStyle`, `borderColor`) can override values set here.
    *
    * @example
    * // The following are equivalent:
@@ -1291,82 +1470,85 @@ export interface BorderProps {
    */
   border?: BorderShorthand;
   /**
-   * Set the width of the border.
-   *
-   * If set, it takes precedence over the `border` property's width.
-   *
-   * Like CSS, up to 4 values can be specified.
-   *
-   * If one value is specified, it applies to all sides.
+   * Controls the thickness of the border on all sides. When set, this overrides the width value specified in the `border` property.
    *
-   * If two values are specified, they apply to the block sides and inline sides respectively.
+   * - `small`: Thin border for subtle definition.
+   * - `small-100`: Extra thin border for minimal emphasis.
+   * - `base`: Standard border width.
+   * - `large`: Thick border for strong emphasis.
+   * - `large-100`: Extra thick border for maximum prominence.
+   * - `none`: No border.
    *
-   * If three values are specified, they apply to the block-start, both inline sides, and block-end respectively.
-   *
-   * If four values are specified, they apply to the block-start, block-end, inline-start, and inline-end sides respectively.
+   * Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) for specifying different widths per side:
+   * - One value: applies to all sides
+   * - Two values: applies to block sides (top/bottom) and inline sides (left/right) respectively
+   * - Three values: applies to block-start (top), inline sides (left/right), and block-end (bottom) respectively
+   * - Four values: applies to block-start (top), inline-end (right), block-end (bottom), and inline-start (left) respectively
    *
    * @default '' - meaning no override
    */
   borderWidth?: MaybeAllValuesShorthandProperty<BorderSizeKeyword> | '';
   /**
-   * Set the style of the border.
-   *
-   * If set, it takes precedence over the `border` property's style.
-   *
-   * Like CSS, up to 4 values can be specified.
-   *
-   * If one value is specified, it applies to all sides.
+   * Controls the visual style of the border on all sides, such as solid, dashed, or dotted.
    *
-   * If two values are specified, they apply to the block sides and inline sides respectively.
+   * When set, this overrides the style value specified in the `border` property.
    *
-   * If three values are specified, they apply to the block-start, both inline sides, and block-end respectively.
-   *
-   * If four values are specified, they apply to the block-start, block-end, inline-start, and inline-end sides respectively.
+   * Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) for specifying different styles per side:
+   * - One value: applies to all sides
+   * - Two values: applies to block sides (top/bottom) and inline sides (left/right) respectively
+   * - Three values: applies to block-start (top), inline sides (left/right), and block-end (bottom) respectively
+   * - Four values: applies to block-start (top), inline-end (right), block-end (bottom), and inline-start (left) respectively
    *
    * @default '' - meaning no override
    */
   borderStyle?: MaybeAllValuesShorthandProperty<BorderStyleKeyword> | '';
   /**
-   * Set the color of the border.
+   * Controls the color of the border using the design system's color scale.
    *
-   * If set, it takes precedence over the `border` property's color.
+   * When set, this overrides the color value specified in the `border` property.
+   * Choose from `subdued`, `base`, or `strong` to match the visual emphasis needed.
    *
    * @default '' - meaning no override
    */
   borderColor?: ColorKeyword | '';
   /**
-   * Set the radius of the border.
-   *
-   * [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) is
-   * supported. Note that, contrary to the CSS, it uses flow-relative values and the order is:
+   * Controls the roundedness of the element's corners using the design system's radius scale.
    *
-   * - 4 values: `start-start start-end end-end end-start`
-   * - 3 values: `start-start (start-end & end-start) start-end`
-   * - 2 values: `(start-start & end-end) (start-end & end-start)`
+   * Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) using flow-relative values:
+   * - One value: applies to all corners
+   * - Two values: applies to start corners (top-left & bottom-right) and end corners (top-right & bottom-left) respectively
+   * - Three values: applies to start-start (top-left), end corners (top-right & bottom-left), and end-end (bottom-right) respectively
+   * - Four values: applies to start-start (top-left), start-end (top-right), end-end (bottom-right), and end-start (bottom-left) respectively
    *
-   * For example:
-   * - `small-100` means start-start, start-end, end-end and end-start border radii are `small-100`.
-   * - `small-100 none` means start-start and end-end border radii are `small-100`, start-end and end-start border radii are `none`.
-   * - `small-100 none large-100` means start-start border radius is `small-100`, start-end border radius is `none`, end-end border radius is `large-100` and end-start border radius is `none`.
-   * - `small-100 none large-100 small-100` means start-start border radius is `small-100`, start-end border radius is `none`, end-end border radius is `large-100` and end-start border radius is `small-100`.
+   * Examples:
+   * - `small-100`: All corners have `small-100` radius
+   * - `small-100 none`: Top-left and bottom-right are `small-100`, top-right and bottom-left are `none`
+   * - `small-100 none large-100`: Top-left is `small-100`, top-right and bottom-left are `none`, bottom-right is `large-100`
+   * - `small-100 none large-100 base`: Each corner has its specified radius value
    *
    * @defaultValue 'none'
    */
   borderRadius?: MaybeAllValuesShorthandProperty<BorderRadiusKeyword>;
 }
+/**
+ * @publicDocs
+ */
 export interface OverflowProps {
   /**
    * Sets the overflow behavior of the element.
    *
+   * - `visible`: the content that extends beyond the element’s container is visible.
    * - `hidden`: clips the content when it is larger than the element’s container.
    * The element will not be scrollable and 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.
    *
    * @default 'visible'
    */
   overflow?: 'hidden' | 'visible';
 }
+/**
+ * @publicDocs
+ */
 export interface BaseBoxProps
   extends AccessibilityVisibilityProps,
     BackgroundProps,
@@ -1376,70 +1558,72 @@ export interface BaseBoxProps
     BorderProps,
     OverflowProps {
   /**
-   * The content of the Box.
+   * The content of the box.
    */
   children?: ComponentChildren;
   /**
-   * A label that describes the purpose or contents of the element.
-   * When set, it will be announced to users using assistive technologies and will provide them with more context.
-   *
-   * Only use this when the element's content is not enough context for users using assistive technologies.
+   * A label that describes the purpose or content of the component for assistive technologies like screen readers. Use this to provide additional context when the visible content alone doesn't clearly convey the component's purpose.
    */
   accessibilityLabel?: string;
 }
+/**
+ * @publicDocs
+ */
 export interface BaseBoxPropsWithRole
   extends BaseBoxProps,
     AccessibilityRoleProps {}
 interface BoxProps$1 extends BaseBoxPropsWithRole, GlobalProps {}
+/**
+ * @publicDocs
+ */
 export interface ButtonBehaviorProps extends InteractionProps, FocusEventProps {
   /**
-   * The behavior of the Button.
+   * The behavioral type of the button component, which determines what action it performs when activated.
    *
-   * - `submit`: Used to indicate the component acts as a submit button, meaning it submits the closest form.
-   * - `button`: Used to indicate the component acts as a button, meaning it has no default action.
-   * - `reset`: Used to indicate the component acts as a reset button, meaning it resets the closest form (returning fields to their default values).
+   * - `submit`: Submits the nearest containing form.
+   * - `button`: Performs no default action, relying on the `onClick` handler for behavior.
+   * - `reset`: Resets all fields in the nearest containing form to their default values.
    *
-   * This property is ignored if the component supports `href` or `commandFor`/`command` and one of them is set.
+   * This property is ignored if `href` or `commandFor`/`command` is set.
    *
    * @default 'button'
    */
   type?: 'submit' | 'button' | 'reset';
   /**
-   * Callback when the Button is activated.
-   * This will be called before the action indicated by `type`.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event
+   * A callback fired when the button is activated, before performing the action indicated by `type`. Learn more about the [click event](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event).
    */
   onClick?: (event: Event) => void;
   /**
-   * Disables the Button meaning it cannot be clicked or receive focus.
+   * Whether the button is disabled, preventing it from being clicked or receiving focus.
    *
    * @default false
    */
   disabled?: boolean;
   /**
-   * Replaces content with a loading indicator while a background action is being performed.
-   *
-   * This also disables the Button.
+   * Whether the button is in a loading state, which replaces the button content with a loading indicator and disables interactions.
    *
    * @default false
    */
   loading?: boolean;
 }
+/**
+ * @publicDocs
+ */
 export interface LinkBehaviorProps extends InteractionProps, FocusEventProps {
   /**
-   * The URL to link to.
-   *
-   * - If set, it will navigate to the location specified by `href` after executing the `click` event.
-   * - If a `commandFor` is set, the `command` will be executed instead of the navigation.
+   * The URL to navigate to when clicked. The `click` event fires first, then navigation occurs. If `commandFor` is also set, the command executes instead of navigation.
    */
   href?: string;
   /**
    * Specifies where to display the linked URL.
    *
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target
+   * Learn more about the [target attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target).
    *
-   * 'auto': The target is automatically determined based on the origin of the URL.
+   * - `auto`: The target is automatically determined based on the origin of the URL.
+   * - `_blank`: Opens the URL in a new window or tab.
+   * - `_self`: Opens the URL in the same browsing context as the current one.
+   * - `_parent`: Opens the URL in the parent browsing context of the current one. If there is no parent, behaves as `_self`.
+   * - `_top`: Opens the URL in the topmost browsing context (the highest ancestor of the current one). If there is no ancestor, behaves as `_self`.
    *
    * @implementation Surfaces can set specific rules on how they handle each URL.
    * @implementation It’s expected that the behavior of `auto` is as `_self` except in specific cases.
@@ -1449,187 +1633,186 @@ export interface LinkBehaviorProps extends InteractionProps, FocusEventProps {
    */
   target?: 'auto' | '_blank' | '_self' | '_parent' | '_top' | AnyString;
   /**
-   * Causes the browser to treat the linked URL as a download with the string being the file name.
-   * Download only works for same-origin URLs or the `blob:` and `data:` schemes.
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#download
+   * A filename that causes the browser to treat the linked URL as a download. Downloads only work for same-origin URLs or the `blob:` and `data:` schemes. Learn more about the [download attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#download).
    */
   download?: string;
   /**
-   * Callback when the link is activated.
-   * This will be called before navigating to the location specified by `href`.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event
+   * A callback fired when the link is activated, before navigating to the location specified by `href`. Learn more about the [click event](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event).
    */
   onClick?: (event: Event) => void;
 }
+/**
+ * @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.
+   * The action that the `commandFor` target should take when this component is activated. The supported actions vary by target component type.
    *
-   * See the documentation of particular components for the actions they support.
+   * - `--auto`: Performs the default action appropriate for the target component.
+   * - `--show`: Displays the target component if it's currently hidden.
+   * - `--hide`: Conceals the target component from view.
+   * - `--toggle`: Alternates the target component between visible and hidden states.
+   * - `--copy`: Copies the content of the target `ClipboardItem` to the system clipboard.
    *
-   * - `--auto`: a default action for the target component.
-   * - `--show`: shows the target component.
-   * - `--hide`: hides the target component.
-   * - `--toggle`: toggles the target component.
-   * - `--copy`: copies the target ClipboardItem.
+   * Learn more about the [command attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command).
    *
    * @default '--auto'
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command
    */
   command?: '--auto' | '--show' | '--hide' | '--toggle' | '--copy';
   /**
-   * ID of a component that should respond to interest (e.g. hover and focus) on this component.
+   * The ID of the component to show when users hover over or focus on this component. 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 component for assistive technologies like screen readers. Use this to provide additional context when the visible content alone doesn't clearly convey the component's purpose.
    */
   accessibilityLabel?: string;
   /**
-   * 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.
+   * Use icons to help users quickly identify the button's action or to improve scannability.
+   * Accepts any icon name from the icon library or a custom string identifier.
    *
    * @default ''
    */
   icon?: IconType | AnyString;
   /**
-   * The displayed inline width of the Button.
+   * The inline width (horizontal size) of the button component.
    *
-   * - `auto`: the size of the button depends on the surface and context.
-   * - `fill`: the button will takes up 100% of the available inline size.
-   * - `fit-content`: the button will take up the minimum inline-size required to fit its content.
+   * - `auto`: The button size depends on the surface and context.
+   * - `fill`: The button takes up 100% of the available inline space.
+   * - `fit-content`: The button takes up only the space needed 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 in the interface.
    *
-   * @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 component.
+   *
+   * - `critical`: Urgent problems or destructive actions.
+   * - `auto`: Automatically determined based on context.
+   * - `neutral`: General information without specific intent.
    *
    * @default 'auto'
    */
   tone?: ToneKeyword;
   /**
-   * Indicate the text language. Useful when the text is in a different language than the rest of the page.
-   * It will allow assistive technologies such as screen readers to invoke the correct pronunciation.
-   * [Reference of values](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) ("subtag" label)
+   * The language of the button's text content. Use this when the button text is in a different language than the rest of the page, allowing assistive technologies such as screen readers to invoke the correct pronunciation. See the [reference of values](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) ("subtag" label).
    */
   lang?: string;
 }
 interface ButtonGroupProps$1 extends GlobalProps, ActionSlots {
   /**
-   * The content of the ButtonGroup.
+   * The content of the button group, typically a collection of button or link components.
    */
   children?: ComponentChildren;
   /**
-   * The gap between elements.
+   * The spacing between button elements within the group.
+   *
    * @default 'base'
    */
   gap?: 'base' | 'none';
   /**
-   * Label for the button group that describes the content of the group for screen reader users to understand what's included.
+   * A label that describes the purpose or content of the component for assistive technologies like screen readers. Use this to provide additional context when the visible content alone doesn't clearly convey the component's purpose.
    *
    * @implementation Used as a hidden heading or an aria-label on the wrapping element.
    */
   accessibilityLabel?: string;
 }
+/**
+ * @publicDocs
+ */
 export interface BaseInputProps {
   /**
-   * An identifier for the field that is unique within the nearest containing form.
+   * The name attribute for the field, used to identify the field's value when the form is submitted. Must be unique within the nearest containing form.
    */
   name?: string;
   /**
-   * Disables the field, disallowing any interaction.
+   * Whether the field is disabled, preventing any user interaction.
    *
    * @default false
    */
   disabled?: boolean;
 }
+/**
+ * @publicDocs
+ */
 export interface InputProps extends BaseInputProps {
   /**
-   * Callback when the user has **finished editing** a field, e.g. once they have blurred the field.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event
+   * A callback fired when the user has finished editing the field, such as when they blur the field or press Enter. Learn more about the [change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event).
    */
   onChange?: (event: Event) => void;
   /**
-   * Callback when the user makes any changes in the field.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event
+   * A callback fired when the user makes any changes in the field, such as typing a character. Learn more about the [input event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event).
    */
   onInput?: (event: Event) => void;
   /**
-   * The current value for the field. If omitted, the field will be empty.
+   * The current value in the field. When setting this property programmatically, it updates the field's display value. When reading it, you get the user's current input.
    */
   value?: string;
   /**
-   * The default value for the field.
+   * The initial value of the field when it first loads. Unlike `placeholder`, this is a real value that the user can edit and that gets submitted with the form. After the user starts typing, their input replaces it. Changing this property after the field has loaded has no effect. To update the field value, use `value` instead.
    *
    * @implementation `defaultValue` reflects to the `value` attribute.
    */
   defaultValue?: string;
 }
+/**
+ * @publicDocs
+ */
 export interface MultipleInputProps extends BaseInputProps {
   /**
-   * Callback when the user has selected option(s).
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event
+   * A callback fired when the user has selected one or more options. Learn more about the [change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event).
    */
   onChange?: (event: Event) => void;
   /**
-   * Callback when the user has selected option(s).
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event
+   * A callback fired when the user selects or deselects options. Learn more about the [input event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event).
    */
   onInput?: (event: Event) => void;
   /**
-   * An array of the `value`s of the selected options.
+   * An array of `value` attributes for the currently selected options.
    *
-   * This is a convenience prop for setting the `selected` prop on child options.
+   * When provided, this property automatically sets the `selected` state on child Option components that have matching `value` attributes. Options with values included in this array will be marked as selected, while others will be unselected.
    */
   values?: string[];
 }
+/**
+ * @publicDocs
+ */
 export interface FileInputProps extends BaseInputProps {
   /**
-   * Callback when the user has **finished selecting** a file or files.
+   * A callback fired when the user has finished selecting one or more files.
    */
   onChange?: (event: Event) => void;
   /**
-   * Callback when the user makes any changes in the file selection.
+   * A callback fired when the user makes any changes to the file selection.
    */
   onInput?: (event: Event) => void;
   /**
    * A string that represents the path to the selected file(s). If no file is selected yet, the value is an empty string ("").
    * When the user selected multiple files, the value represents the first file in the list of files they selected.
-   * The value is always the file's name prefixed with "C:\fakepath\", which isn't the real path of the file.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/file#value
+   * The value is always the file's name prefixed with "C:\fakepath\", which isn't the real path of the file. Learn more about the [file input value](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/file#value).
    *
    * @default ''
    */
@@ -1644,81 +1827,81 @@ export interface FileInputProps extends BaseInputProps {
    */
   files?: ReadonlyArray<File>;
 }
+/**
+ * @publicDocs
+ */
 export interface FieldErrorProps {
   /**
-   * Indicate an error to the user. The field will be given a specific stylistic treatment
-   * to communicate problems that have to be resolved immediately.
+   * An error message to display to the user. When set, the field will be styled with error indicators to communicate problems that need to be resolved immediately.
    */
   error?: string;
 }
+/**
+ * @publicDocs
+ */
 export interface BasicFieldProps
   extends FieldErrorProps,
     LabelAccessibilityVisibilityProps {
   /**
-   * Whether the field needs a value. This requirement adds semantic value
-   * to the field, but it will not cause an error to appear automatically.
-   * If you want to present an error when this field is empty, you can do
-   * so with the `error` property.
+   * Whether the field requires a value before form submission. Displays a visual indicator and adds semantic meaning, but doesn't automatically validate or show errors. Use the `error` property to display validation messages.
    *
    * @default false
    */
   required?: boolean;
   /**
-   * Content to use as the field label.
+   * The text label displayed above or alongside the field to describe its purpose.
    */
   label?: string;
 }
+/**
+ * @publicDocs
+ */
 export interface FieldDetailsProps {
   /**
-   * Additional text to provide context or guidance for the field.
-   * This text is displayed along with the field and its label
-   * to offer more information or instructions to the user.
-   *
-   * This will also be exposed to screen reader users.
+   * Additional helpful text displayed alongside the field to provide context, guidance, or instructions to the user. This content is accessible to both visual and screen reader users.
    */
   details?: string;
 }
+/**
+ * @publicDocs
+ */
 export interface FieldProps
   extends BasicFieldProps,
     InputProps,
     FocusEventProps,
     FieldDetailsProps {
   /**
-   * A short hint that describes the expected value of the field.
+   * The placeholder text displayed in the field when it's empty, providing a hint about the expected input format or value. Unlike `defaultValue`, this is a temporary value that disappears after the user starts typing.
    */
   placeholder?: string;
 }
+/**
+ * @publicDocs
+ */
 export interface BaseTextFieldProps extends FieldProps {
   /**
-   * The field cannot be edited by the user. It is focusable will be announced by screen readers.
+   * Whether the field is read-only and can't be edited. Read-only fields remain focusable and their content is announced by screen readers.
    *
    * @default false
    */
   readOnly?: boolean;
 }
+/**
+ * @publicDocs
+ */
 export interface FieldDecorationProps {
   /**
-   * A value to be displayed immediately after the editable portion of the field.
-   *
-   * This is useful for displaying an implied part of the value, such as "@shopify.com", or "%".
+   * A non-editable text value displayed immediately after the editable portion of the field. This is useful for displaying an implied part of the value, such as `@shopify.com` or `%`.
    *
-   * This cannot be edited by the user, and it isn't included in the value of the field.
-   *
-   * It may not be displayed until the user has interacted with the input.
-   * For example, an inline label may take the place of the suffix until the user focuses the input.
+   * This text can't be edited by the user and is not included in the field's value. The suffix might not appear until the user interacts with the field. For example, an inline label might occupy the suffix position until the user focuses the field.
    *
    * @default ''
    */
   suffix?: string;
   /**
-   * A value to be displayed immediately before the editable portion of the field.
-   *
-   * This is useful for displaying an implied part of the value, such as "https://" or "+353".
+   * A non-editable text value displayed immediately before the editable portion of the field. This is useful for displaying an implied part of the value, such as `https://` or `+353`.
    *
-   * This cannot be edited by the user, and it isn't included in the value of the field.
-   *
-   * It may not be displayed until the user has interacted with the input.
-   * For example, an inline label may take the place of the prefix until the user focuses the input.
+   * This text can't be edited by the user and is not included in the field's value. The prefix might not appear until the user interacts with the field. For example, an inline label might occupy the prefix position until the user focuses the field.
    *
    * @default ''
    */
@@ -1730,28 +1913,28 @@ export interface FieldDecorationProps {
    */
   icon?: IconType | AnyString;
   /**
-   * Additional content to be displayed in the field.
-   * Commonly used to display an icon that activates a tooltip providing more information.
+   * Additional interactive content displayed within the field.
+   *
+   * Accepts Button and Clickable components with text content only. Commonly used for actions like clearing the field or opening additional information.
    */
   accessory?: ComponentChildren;
 }
+/**
+ * @publicDocs
+ */
 export interface NumberConstraintsProps {
   /**
-   * The highest decimal or integer to be accepted for the field.
-   * When used with `step` the value will round down to the max number.
+   * The highest decimal or integer value accepted for the field. When used with `step`, the value rounds down to the maximum number.
    *
-   * Note: a user will still be able to use the keyboard to input a number higher than
-   * the max. It is up to the developer to add appropriate validation.
+   * Users can still type values higher than the maximum using the keyboard. Implement validation to enforce this constraint.
    *
    * @default Infinity
    */
   max?: number;
   /**
-   * The lowest decimal or integer to be accepted for the field.
-   * When used with `step` the value will round up to the min number.
+   * The lowest decimal or integer value accepted for the field. When used with `step`, the value rounds up to the minimum number.
    *
-   * Note: a user will still be able to use the keyboard to input a number lower than
-   * the min. It is up to the developer to add appropriate validation.
+   * Users can still type values lower than the minimum using the keyboard. Implement validation to enforce this constraint.
    *
    * @default -Infinity
    */
@@ -1777,46 +1960,54 @@ export interface NumberConstraintsProps {
    */
   controls?: 'auto' | 'stepper' | 'none';
 }
+/**
+ * @publicDocs
+ */
 export interface MinMaxLengthProps {
   /**
-   * Specifies the maximum number of characters allowed.
+   * The maximum number of characters allowed in the field.
    *
    * @default Infinity
    */
   maxLength?: number;
   /**
-   * Specifies the min number of characters allowed.
+   * The minimum number of characters required in the field.
    *
    * @default 0
    */
   minLength?: number;
 }
+/**
+ * @publicDocs
+ */
 export interface BaseSelectableProps {
   /**
-   * A label used for users using assistive technologies like screen readers. When set, any children or `label` supplied will not be announced.
-   * This can also be used to display a control without a visual label, while still providing context to users using screen readers.
+   * A label that describes the purpose or content of the component for assistive technologies like screen readers. Use this to provide additional context when the visible content alone doesn't clearly convey the component's purpose.
    */
   accessibilityLabel?: string;
   /**
-   * Disables the control, disallowing any interaction.
+   * Whether the control is disabled, preventing any user interaction.
    *
    * @default false
    */
   disabled?: boolean;
   /**
-   * The value used in form data when the control is checked.
+   * The value submitted with form data when the control is checked or selected.
    */
   value?: string;
 }
+/**
+ * @publicDocs
+ */
 export interface BaseOptionProps extends BaseSelectableProps {
   /**
-   * Whether the control is active.
+   * Whether the option is currently selected.
    *
    * @default false
    */
   selected?: boolean;
   /**
-   * Whether the control is active by default.
+   * Whether the option is selected by default when first rendered.
    *
    * @implementation `defaultSelected` reflects to the `selected` attribute.
    *
@@ -1824,21 +2015,24 @@ export interface BaseOptionProps extends BaseSelectableProps {
    */
   defaultSelected?: boolean;
 }
+/**
+ * @publicDocs
+ */
 export interface BaseCheckableProps
   extends BaseSelectableProps,
     InteractionProps {
   /**
-   * Visual content to use as the control label.
+   * The visual text label displayed alongside the control to describe its purpose.
    */
   label?: string;
   /**
-   * Whether the control is active.
+   * Whether the control is currently checked (for checkboxes) or toggled on (for switches).
    *
    * @default false
    */
   checked?: boolean;
   /**
-   * Whether the control is active by default.
+   * Whether the control is checked by default when first rendered.
    *
    * @implementation `defaultChecked` reflects to the `checked` attribute.
    *
@@ -1846,20 +2040,15 @@ export interface BaseCheckableProps
    */
   defaultChecked?: boolean;
   /**
-   * An identifier for the control that is unique within the nearest
-   * containing `Form` component.
+   * The name attribute for the control, which must be unique within the nearest containing Form component. This name is used to identify the control's value when the form is submitted.
    */
   name?: string;
   /**
-   * A callback that is run whenever the control is changed.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event
+   * A callback fired when the control's value changes. Learn more about the [change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event).
    */
   onChange?: (event: Event) => void;
   /**
-   * A callback that is run whenever the control is changed.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event
+   * A callback fired when the control's value changes. Learn more about the [input event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event).
    */
   onInput?: (event: Event) => void;
 }
@@ -1869,22 +2058,21 @@ interface CheckboxProps$1
     FieldErrorProps,
     FieldDetailsProps {
   /**
-   * Whether to display the checkbox in an indeterminate state (neither checked or unchecked).
+   * Whether the checkbox displays in an indeterminate state (neither checked nor unchecked), typically used to indicate partial selection in hierarchical lists.
    *
-   * In terms of appearance, this takes priority over the `checked` prop.
-   * But this is purely a visual change.
-   * Whether the value is submitted along with a form is still down to the `checked` prop.
+   * This visual state takes priority over the `checked` prop in appearance only.
+   * The form submission value is still determined by the `checked` prop.
    *
-   * If `indeterminate` has not been explicitly set, and the `indeterminate` state hasn't been modified by the user (via clicking),
-   * then `indeterminate` returns the value of `defaultIndeterminate`.
+   * If `indeterminate` has not been explicitly set and hasn't been modified by user interaction,
+   * it returns the value of `defaultIndeterminate`.
    *
    * @implementation The `indeterminate` property doesn't reflect to any attribute.
    */
   indeterminate?: boolean;
   /**
-   * Whether the checkbox is in an `indeterminate` state by default.
+   * Whether the checkbox is in an indeterminate state by default when first rendered.
    *
-   * Similar to `defaultValue` and `defaultChecked`, this value applies until `indeterminate` is set, or user changes the state of the checkbox.
+   * Similar to `defaultValue` and `defaultChecked`, this value applies until `indeterminate` is explicitly set or the user changes the checkbox state.
    *
    * @implementation `defaultIndeterminate` reflects to the `indeterminate` attribute.
    *
@@ -1892,73 +2080,41 @@ interface CheckboxProps$1
    */
   defaultIndeterminate?: boolean;
   /**
-   * Whether the field needs a value. This requirement adds semantic value
-   * to the field, but it will not cause an error to appear automatically.
-   * If you want to present an error when this field is empty, you can do
-   * so with the `error` property.
+   * Whether the checkbox must be checked before form submission. This adds semantic meaning and typically displays a visual indicator, but does not automatically validate or show errors. Use the `error` property to display validation messages.
    *
    * @default false
    */
   required?: boolean;
 }
+/**
+ * @publicDocs
+ */
 export interface ChipProps$1 extends GlobalProps {
   /**
-   * The content of the chip.
+   * The text content displayed within the chip.
    */
   children?: ComponentChildren;
   /**
-   * The graphic to display inside of the chip.
+   * The graphic element (typically an icon) displayed inside the chip.
    *
    * @implementation Only `s-icon` is supported.
    */
   graphic?: ComponentChildren;
   /**
-   * A label that describes the purpose or contents of the Chip. It will be read to users using assistive technologies such as screen readers.
+   * A label that describes the purpose or content of the component for assistive technologies like screen readers. Use this to provide additional context when the visible content alone doesn't clearly convey the component's purpose.
    */
   accessibilityLabel?: string;
   /**
-   * Modify the color to be more or less intense.
+   * The color intensity of the chip. Use `subdued` for less intense, `base` for standard, or `strong` for more intense coloring.
    *
    * @default 'base'
    */
   color?: ColorKeyword;
-  /**
-   * Whether the chip is removable.
-   *
-   * @default false
-   */
-  removable?: boolean;
-  /**
-   * Callback when the chip is removed.
-   */
-  onRemove?: (event: Event) => void;
-  /**
-   * Determines whether the chip is hidden.
-   *
-   * If this property is being set on each framework render (as in 'controlled' usage),
-   * and the chip is `removable`,
-   * ensure you update app state for this property when the `remove` event fires.
-   *
-   * If the chip is not `removable`, it can still be hidden by setting this property.
-   *
-   * @default false
-   */
-  hidden?: boolean;
-  /**
-   * Event handler when the chip has fully hidden.
-   *
-   * The `hidden` property will be `true` when this event fires.
-   *
-   * @implementation If implementations animate the hiding of the chip,
-   * this event must fire after the chip has fully hidden.
-   * We can add an `onHide` event in future if we want to provide a hook for the start of the animation.
-   */
-  onAfterHide?: (event: Event) => void;
 }
 interface ChipProps$2 extends ChipProps$1, GlobalProps {}
 interface ChoiceProps$1 extends GlobalProps, BaseOptionProps {
   /**
-   * Content to use as the choice label.
+   * The content displayed as the choice label.
    *
    * @implementation (StringChildren) The label is produced by extracting and
    * concatenating the text nodes from the provided content; any markup or
@@ -1970,28 +2126,23 @@ interface ChoiceProps$1 extends GlobalProps, BaseOptionProps {
    */
   children?: ComponentChildren | StringChildren;
   /**
-   * Additional text to provide context or guidance for the input.
-   *
-   * This text is displayed along with the input and its label
-   * to offer more information or instructions to the user.
+   * Additional helpful text displayed alongside the choice to provide context, guidance, or instructions to the user.
    *
    * @implementation this content should be linked to the input with an `aria-describedby` attribute.
    */
   details?: ComponentChildren;
   /**
-   * Set to `true` to associate a choice with the error passed to `ChoiceList`
+   * Whether this choice should be associated with an error state from the parent ChoiceList.
    *
    * @default false
    */
   error?: boolean;
   /**
-   * Secondary content for a choice.
+   * Secondary descriptive content displayed beneath the choice label.
    */
   secondaryContent?: ComponentChildren;
   /**
-   * Content to display when the option is selected.
-   *
-   * This can be used to provide additional information or options related to the choice.
+   * Content displayed when the choice is selected, useful for showing additional information or nested options related to this choice.
    */
   selectedContent?: ComponentChildren;
 }
@@ -2001,36 +2152,33 @@ interface ChoiceListProps$1
     MultipleInputProps,
     FieldDetailsProps {
   /**
-   * Whether multiple choices can be selected.
+   * Whether users can select multiple choices simultaneously (checkboxes) or only one choice at a time (radio buttons).
    *
    * @default false
    */
   multiple?: boolean;
   /**
-   * The choices a user can select from.
-   *
-   * Accepts `Choice` components.
+   * The collection of Choice components that users can select from.
    */
   children?: ComponentChildren;
   /**
-   * Disables the field, disallowing any interaction.
+   * Whether the entire choice list is disabled, preventing any user interaction.
    *
-   * `disabled` on any child choices is ignored when this is true.
+   * When `true`, the `disabled` property on individual child Choice components is ignored.
    *
    * @default false
    */
   disabled?: MultipleInputProps['disabled'];
   /**
-   * The variant of the choice grid.
+   * The layout variant for displaying the choices.
    *
-   * - `auto`: The variant is determined by the context.
-   * - `list`: The choices are displayed in a list.
-   * - `inline`: The choices are displayed on the inline axis.
-   * - `block`: The choices are displayed on the block axis.
-   * - `grid`: The choices are displayed in a grid.
+   * - `auto`: The variant is automatically determined by the context.
+   * - `list`: The choices are displayed in a vertical list.
+   * - `inline`: The choices are arranged horizontally along the inline axis.
+   * - `block`: The choices are arranged vertically along the block axis.
+   * - `grid`: The choices are displayed in a grid layout.
    *
-   * @implementation The `block`, `inline` and `grid` variants are more suitable for button looking choices, but it's at the
-   * discretion of each surface.
+   * @implementation The `block`, `inline` and `grid` variants are more suitable for button-styled choices, but it's at the discretion of each surface.
    *
    * @default 'auto'
    */
@@ -2041,27 +2189,15 @@ interface ClickableProps$1
     BaseBoxProps,
     BaseClickableProps {
   /**
-   * Disables the clickable, and indicates to assistive technology that the loading is in progress.
-   *
-   * This also disables the clickable.
+   * Whether the component is in a loading state, which indicates to assistive technology that an action is in progress and prevents interaction.
    */
   loading?: BaseClickableProps['loading'];
   /**
-   * Disables the clickable, meaning it cannot be clicked or receive focus.
-   *
-   * In this state, onClick will not fire.
-   * If the click event originates from a child element, the event will immediately stop propagating from this element.
-   *
-   * However, items within the clickable can still receive focus and be interacted with.
-   *
-   * This has no impact on the visual state by default,
-   * but developers are encouraged to style the clickable accordingly.
+   * Whether the component is disabled, preventing clicks and focus. When disabled, the `click` event won't fire and click events from child elements stop propagating immediately. Interactive child elements can still receive focus and be interacted with. This doesn't apply visual styling by default. You should apply disabled styling as needed.
    */
   disabled?: BaseClickableProps['disabled'];
   /**
-   * Indicate the text language. Useful when the text is in a different language than the rest of the page.
-   * It will allow assistive technologies such as screen readers to invoke the correct pronunciation.
-   * [Reference of values](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) ("subtag" label)
+   * The language of the text content within the component. Useful when the text is in a different language than the rest of the page, allowing assistive technologies such as screen readers to invoke the correct pronunciation. See the [reference of values](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) ("subtag" label).
    *
    * @default ''
    */
@@ -2072,16 +2208,39 @@ interface ClickableChipProps$1
     GlobalProps,
     InteractionProps {
   /**
-   * Callback when the chip is clicked.
+   * A callback fired when the chip is clicked.
    */
   onClick?: (event: Event) => void;
   /**
-   * The URL to link to.
-   *
-   * - If set, it will navigate to the location specified by `href` after executing the `click` event.
-   * - If a `commandFor` is set, the `command` will be executed instead of the navigation.
+   * The URL to navigate to when clicked. The `click` event fires first, then navigation occurs. If `commandFor` is also set, the command executes instead of navigation.
    */
   href?: string;
+  /**
+   * Whether the chip displays a remove button for dismissal. When clicked, the `remove` callback fires.
+   *
+   * @default false
+   */
+  removable?: boolean;
+  /**
+   * A callback fired when the chip's remove button is clicked.
+   */
+  onRemove?: (event: Event) => void;
+  /**
+   * Whether the chip is hidden from view. When using controlled component pattern with `removable` chips, update this property when the `remove` event fires. For non-removable chips, manually toggle this property to show or hide the chip.
+   *
+   * @default false
+   */
+  hidden?: boolean;
+  /**
+   * Event handler when the chip has fully hidden.
+   *
+   * The `hidden` property will be `true` when this event fires.
+   *
+   * @implementation If implementations animate the hiding of the chip,
+   * this event must fire after the chip has fully hidden.
+   * We can add an `onHide` event in future if we want to provide a hook for the start of the animation.
+   */
+  onAfterHide?: (event: Event) => void;
   /**
    * Disables the chip, disallowing any interaction.
    *
@@ -2089,63 +2248,57 @@ interface ClickableChipProps$1
    */
   disabled?: boolean;
 }
-interface ColorPickerProps$1 extends GlobalProps, InputProps {
+interface ColorPickerProps$1
+  extends GlobalProps,
+    Omit<InputProps, 'value' | 'defaultValue'> {
   /**
-   * Allow user to select an alpha value.
+   * Whether to enable alpha (transparency) channel selection in the color picker, allowing users to choose semi-transparent colors.
    *
    * @default false
    */
   alpha?: boolean;
   /**
-   * This callback will emit the value in hex.
-   *
-   * If the `alpha` prop is `true`, `onChange` will emit an 8-value hex (#RRGGBBAA).
-   * If the `alpha` prop is `false`, `onChange` will emit a 6-value hex (#RRGGBB).
+   * A callback that fires when the user finishes selecting a color. The value is always emitted in hexadecimal format: 8-value hex (`#RRGGBBAA`) when `alpha` is `true`, or 6-value hex (`#RRGGBB`) when `alpha` is `false`.
    */
   onChange?: InputProps['onChange'];
   /**
-   * This callback will emit the value in hex.
-   *
-   * If the `alpha` prop is `true`, `onInput` will emit an 8-value hex (#RRGGBBAA).
-   * If the `alpha` prop is `false`, `onInput` will emit a 6-value hex (#RRGGBB).
+   * A callback that fires when the user makes any change to the color selection. The value is always emitted in hexadecimal format: 8-value hex (`#RRGGBBAA`) when `alpha` is `true`, or 6-value hex (`#RRGGBB`) when `alpha` is `false`.
    */
   onInput?: InputProps['onChange'];
   /**
-   * The currently selected color.
-   *
-   * Supported formats include:
-   * - HSL @see https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/hsl
-   * - HSLA @see https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/hsla
-   * - RGB @see https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/rgb
-   * - RGBA @see https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/rgb
-   * - Hex (3-value, 4-value, 6-value, 8-value) @see https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
+   * The currently selected color value. Accepts multiple input formats:
    *
-   * For RGB and RGBA, both the legacy syntax (comma-separated) and modern syntax (space-separate) are supported.
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/rgb
+   * - Hex: `#RGB`, `#RGBA`, `#RRGGBB`, `#RRGGBBAA` (three, four, six, or eight digits)
+   * - RGB/RGBA: `rgb(255, 0, 0)` or `rgb(255 0 0)` (comma or space-separated)
+   * - HSL/HSLA: `hsl(0, 100%, 50%)` or `hsl(0 100% 50%)`
    *
-   * If the value is invalid, the component will return an empty string ''.
-   *
-   * Note that the `onChange` handler will emit the value in hex.
+   * Returns an empty string if the value is invalid. The `onChange` handler always emits values in hex format.
+   */
+  value?: string;
+  /**
+   * The initial color value when the field first loads. Unlike `placeholder`, this is a real value that the user can edit and that gets submitted with the form. Once the user starts interacting, their input replaces it. Changing this property after the field has loaded has no effect. To update the field value at any time, use `value` instead.
    */
-  value?: InputProps['value'];
+  defaultValue?: string;
 }
+/**
+ * @publicDocs
+ */
 export interface AutocompleteProps<
   AutocompleteField extends AnyAutocompleteField,
 > {
   /**
-   * A hint as to the intended content of the field.
-   *
-   * When set to `on` (the default), this property indicates that the field should support
-   * autofill, but you do not have any more semantic information on the intended
-   * contents.
+   * Controls browser autofill behavior for the field.
    *
-   * When set to `off`, you are indicating that this field contains sensitive
-   * information, or contents that are never saved, like one-time codes.
+   * Basic values:
+   * - `on` - Enables autofill without specifying content type (default)
+   * - `off` - Disables autofill for sensitive data or one-time codes
    *
-   * Alternatively, you can provide value which describes the
-   * specific data you would like to be entered into this field during autofill.
+   * Specific field values describe the expected data type. You can optionally prefix these with:
+   * - `section-${string}` - Scopes autofill to a specific form section (when multiple forms exist on the same page)
+   * - `shipping` or `billing` - Indicates whether the data is for shipping or billing purposes
+   * - Both section and group (for example, `section-primary shipping email`)
    *
-   * @see Learn more about the set of {@link https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill-detail-tokens|autocomplete values} supported in browsers.
+   * Providing a specific autofill token helps browsers suggest more relevant saved data. Learn more about [autocomplete values](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill-detail-tokens).
    *
    * @default 'tel' for PhoneField
    * @default 'email' for EmailField
@@ -2166,16 +2319,22 @@ export interface AutocompleteProps<
  *
  * 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'
@@ -2241,6 +2400,43 @@ export type AnyAutocompleteField =
   | `${AutocompleteAddressGroup} tel-local-suffix`
   | `${AutocompleteAddressGroup} tel-local`
   | `${AutocompleteAddressGroup} tel-national`;
+/**
+ * Represents autocomplete values that are valid for text input fields.
+ * This is a subset of `AnyAutocompleteField` containing only fields suitable for text-based inputs.
+ *
+ * Available values:
+ * - `name` - Full name
+ * - `given-name` - First name
+ * - `additional-name` - Middle name
+ * - `family-name` - Last name
+ * - `nickname` - Nickname or handle
+ * - `username` - Username for login
+ * - `honorific-prefix` - Name prefix (Mr., Mrs., Dr.)
+ * - `honorific-suffix` - Name suffix (Jr., Sr., III)
+ * - `organization` - Company or organization name
+ * - `organization-title` - Job title or position
+ * - `address-line1` - Street address (first line)
+ * - `address-line2` - Street address (second line)
+ * - `address-line3` - Street address (third line)
+ * - `address-level1` - State or province
+ * - `address-level2` - City or town
+ * - `address-level3` - District or locality
+ * - `address-level4` - Neighborhood or suburb
+ * - `street-address` - Complete street address (multi-line)
+ * - `postal-code` - Postal or ZIP code
+ * - `country` - Country code (US, CA, GB)
+ * - `country-name` - Country name (United States, Canada)
+ * - `language` - Preferred language
+ * - `sex` - Gender or sex
+ * - `one-time-code` - One-time codes for authentication
+ * - `transaction-currency` - Currency code (USD, EUR, GBP)
+ * - `cc-name` - Name on credit card
+ * - `cc-given-name` - First name on credit card
+ * - `cc-additional-name` - Middle name on credit card
+ * - `cc-family-name` - Last name on credit card
+ * - `cc-type` - Credit card type (Visa, Mastercard)
+ * @publicDocs
+ */
 export type TextAutocompleteField = ExtractStrict<
   AnyAutocompleteField,
   | 'additional-name'
@@ -2276,8 +2472,27 @@ export type TextAutocompleteField = ExtractStrict<
 >;
 interface ColorFieldProps$1
   extends GlobalProps,
-    BaseTextFieldProps,
-    Pick<ColorPickerProps$1, 'alpha' | 'value' | 'defaultValue'> {
+    Omit<BaseTextFieldProps, 'value' | 'defaultValue'> {
+  /**
+   * Whether to enable alpha (transparency) channel selection in the color picker, allowing users to choose semi-transparent colors.
+   *
+   * @default false
+   */
+  alpha?: boolean;
+  /**
+   * The currently selected color value. Accepts multiple input formats:
+   *
+   * - Hex: `#RGB`, `#RGBA`, `#RRGGBB`, `#RRGGBBAA` (three, four, six, or eight digits)
+   * - RGB/RGBA: `rgb(255, 0, 0)` or `rgb(255 0 0)` (comma or space-separated)
+   * - HSL/HSLA: `hsl(0, 100%, 50%)` or `hsl(0 100% 50%)`
+   *
+   * Returns an empty string if the value is invalid. The `onChange` handler always emits values in hex format.
+   */
+  value?: string;
+  /**
+   * The initial color value when the field first loads. Unlike `placeholder`, this is a real value that the user can edit and that gets submitted with the form. Once the user starts interacting, their input replaces it. Changing this property after the field has loaded has no effect. To update the field value at any time, use `value` instead.
+   */
+  defaultValue?: string;
   autocomplete?: Extract<
     AutocompleteProps<never>['autocomplete'],
     'on' | 'off'
@@ -2285,23 +2500,15 @@ interface ColorFieldProps$1
 }
 interface DatePickerProps$1 extends GlobalProps, InputProps, FocusEventProps {
   /**
-   * Default month to display in `YYYY-MM` format.
-   *
-   * This value is used until `view` is set, either directly or as a result of user interaction.
-   *
-   * Defaults to the current month in the user's locale.
+   * The default month to display in `YYYY-MM` format. Used until the `view` callback is set by user interaction or programmatically. Defaults to the current month in the user's locale.
    */
   defaultView?: string;
   /**
-   * Displayed month in `YYYY-MM` format.
-   *
-   * `onViewChange` is called when this value changes.
-   *
-   * Defaults to `defaultView`.
+   * The currently displayed month in `YYYY-MM` format. When changed, the `viewchange` callback is triggered. Defaults to `defaultView`.
    */
   view?: string;
   /**
-   * Called whenever the month to display changes.
+   * A callback fired whenever the displayed month changes in the calendar.
    *
    * @param view The new month to display in `YYYY-MM` format.
    */
@@ -2317,144 +2524,91 @@ 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.
+   * Specifies which dates can be selected as a comma-separated list. An empty string (default) allows all dates.
    *
-   * The default `''` allows all dates.
+   * **Formats:**
+   * - `YYYY-MM-DD`: Single date
+   * - `YYYY-MM`: Whole month
+   * - `YYYY`: Whole year
+   * - `start--end`: Date range (inclusive, unbounded if start/end omitted)
    *
-   * - Dates in `YYYY-MM-DD` format allow a single date.
-   * - Dates in `YYYY-MM` format allow a whole month.
-   * - Dates in `YYYY` format allow a whole year.
-   * - Ranges are expressed as `start--end`.
-   *     - Ranges are inclusive.
-   *     - If either `start` or `end` is omitted, the range is unbounded in that direction.
-   *     - If parts of the date are omitted for `start`, they are assumed to be the minimum possible value.
-   *       So `2024--` is equivalent to `2024-01-01--`.
-   *     - If parts of the date are omitted for `end`, they are assumed to be the maximum possible value.
-   *       So `--2024` is equivalent to `--2024-12-31`.
-   *     - Whitespace is allowed either side of `--`.
+   * **Examples:**
+   * - `2024-02--2025`: February 2024 through end of 2025
+   * - `2024-05-09, 2024-05-11`: Only May 9th and 11th, 2024
    *
    * @default ""
-   *
-   * @example
-   * `2024-02--2025` // allow any date from February 2024 to the end of 2025
-   * `2024-02--` // allow any date from February 2024 to the end of the month
-   * `2024-05-09, 2024-05-11` // allow only the 9th and 11th of May 2024
    */
   allow?: string;
   /**
-   * Dates that cannot be selected. These subtract from `allow`.
+   * Specifies which dates can't be selected as a comma-separated list. These dates are excluded from those specified in `allow`. An empty string (default) has no effect.
    *
-   * A comma-separated list of dates, date ranges. Whitespace is allowed after commas.
+   * **Formats:**
+   * - `YYYY-MM-DD`: Single date
+   * - `YYYY-MM`: Whole month
+   * - `YYYY`: Whole year
+   * - `start--end`: Date range (inclusive, unbounded if start/end omitted)
    *
-   * The default `''` has no effect on `allow`.
-   *
-   * - Dates in `YYYY-MM-DD` format disallow a single date.
-   * - Dates in `YYYY-MM` format disallow a whole month.
-   * - Dates in `YYYY` format disallow a whole year.
-   * - Ranges are expressed as `start--end`.
-   *     - Ranges are inclusive.
-   *     - If either `start` or `end` is omitted, the range is unbounded in that direction.
-   *     - If parts of the date are omitted for `start`, they are assumed to be the minimum possible value.
-   *       So `2024--` is equivalent to `2024-01-01--`.
-   *     - If parts of the date are omitted for `end`, they are assumed to be the maximum possible value.
-   *       So `--2024` is equivalent to `--2024-12-31`.
-   *     - Whitespace is allowed either side of `--`.
+   * **Examples:**
+   * - `--2024-02`: All dates before February 2024
+   * - `2024-05-09, 2024-05-11`: May 9th and 11th, 2024
    *
    * @default ""
-   *
-   * @example
-   * `--2024-02` // disallow any date before February 2024
-   * `2024-05-09, 2024-05-11` // disallow the 9th and 11th of May 2024
    */
   disallow?: string;
   /**
-   * Days of the week that can be selected. These intersect with the result of `allow` and `disallow`.
-   *
-   * A comma-separated list of days. Whitespace is allowed after commas.
+   * Specifies which days of the week can be selected as a comma-separated list. Further restricts dates from `allow` and `disallow`. An empty string (default) has no effect.
    *
-   * The default `''` has no effect on the result of `allow` and `disallow`.
+   * **Valid days**: `sunday`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`
    *
-   * Days are `sunday`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`.
+   * **Example:** `saturday, sunday` (only weekends)
    *
    * @default ""
-   *
-   * @example
-   * 'saturday, sunday' // allow only weekends within the result of `allow` and `disallow`.
    */
   allowDays?: string;
   /**
-   * Days of the week that cannot be selected. This subtracts from `allowDays`, and intersects with the result of `allow` and `disallow`.
+   * Specifies which days of the week can't be selected as a comma-separated list. Excludes days from `allowDays` and intersects with `allow` and `disallow`. An empty string (default) has no effect.
    *
-   * A comma-separated list of days. Whitespace is allowed after commas.
+   * **Valid days**: `sunday`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`
    *
-   * The default `''` has no effect on `allowDays`.
-   *
-   * Days are `sunday`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`.
+   * **Example:** `saturday, sunday` (no weekends)
    *
    * @default ""
-   *
-   * @example
-   * 'saturday, sunday' // disallow weekends within the result of `allow` and `disallow`.
    */
   disallowDays?: string;
   /**
-   * Default selected value.
-   *
-   * The default means no date is selected.
+   * The initially selected date(s) when the component first renders. An empty string means no date is initially selected.
    *
-   * If the provided value is invalid, no date is selected.
-   *
-   * - If `type="single"`, this is a date in `YYYY-MM-DD` format.
-   * - If `type="multiple"`, this is a comma-separated list of dates in `YYYY-MM-DD` format.
-   * - If `type="range"`, this is a range in `YYYY-MM-DD--YYYY-MM-DD` format. The range is inclusive.
+   * - Single date in `YYYY-MM-DD` format when `type` is set to `"single"`
+   * - Date range in `YYYY-MM-DD--YYYY-MM-DD` format (inclusive) when `type` is set to `"range"`
    *
    * @default ""
    */
   defaultValue?: string;
   /**
-   * Current selected value.
-   *
-   * The default means no date is selected.
-   *
-   * If the provided value is invalid, no date is selected.
-   *
-   * Otherwise:
+   * The currently selected date(s). An empty string means no date is selected.
    *
-   * - If `type="single"`, this is a date in `YYYY-MM-DD` format.
-   * - If `type="multiple"`, this is a comma-separated list of dates in `YYYY-MM-DD` format.
-   * - If `type="range"`, this is a range in `YYYY-MM-DD--YYYY-MM-DD` format. The range is inclusive.
+   * - Single date in `YYYY-MM-DD` format when `type` is set to `"single"`
+   * - Date range in `YYYY-MM-DD--YYYY-MM-DD` format (inclusive) when `type` is set to `"range"`
    *
    * @default ""
    */
   value?: string;
   /**
-   * Callback when any date is selected.
-   *
-   * - If `type="single"`, fires when a date is selected and happens before `onChange`.
-   * - If `type="multiple"`, fires when a date is selected before `onChange`.
-   * - If `type="range"`, fires when a first date is selected (with the partial value formatted as `YYYY-MM-DD--`), and when the last date is selected before `onChange`.
+   * A callback fired when any date is selected, before `onChange`. When `type` is set to `"range"`, also fires when the first date is selected with a partial value formatted as `YYYY-MM-DD--`.
    */
   onInput?: (event: Event) => void;
   /**
-   * Callback when the value is committed.
-   *
-   * - If `type="single"`, fires when a date is selected after `onInput`.
-   * - If `type="multiple"`, fires when a date is selected after `onInput`.
-   * - If `type="range"`, fires when a range is completed by selecting the end date after `onInput`.
+   * A callback fired when the date selection is committed and complete, after `onInput`. When `type` is set to `"range"`, fires only when the range is completed by selecting the end date.
    */
   onChange?: (event: Event) => void;
 }
 interface DateFieldProps$1
   extends GlobalProps,
-    BaseTextFieldProps,
+    Omit<BaseTextFieldProps, 'value' | 'defaultValue'>,
     Pick<
       DatePickerProps$1,
       | 'view'
       | 'defaultView'
-      | 'value'
-      | 'defaultValue'
       | 'allow'
       | 'disallow'
       | 'allowDays'
@@ -2463,18 +2617,27 @@ interface DateFieldProps$1
     >,
     AutocompleteProps<DateAutocompleteField> {
   /**
-   * Callback when the user makes any changes in the field.
-   * Also triggered when a date is selected using the date picker popup before `onChange`.
+   * The initial date value when the field first renders, in `YYYY-MM-DD` format. An empty string means no date is initially selected.
+   *
+   * @default ""
+   */
+  defaultValue?: string;
+  /**
+   * The currently selected date in `YYYY-MM-DD` format. An empty string means no date is selected.
+   *
+   * @default ""
+   */
+  value?: string;
+  /**
+   * A callback fired when the user makes any changes in the field, including when selecting a date using the date picker popup. This fires before `onChange`.
    */
   onInput?: (event: Event) => void;
   /**
-   * Callback when the user has **finished editing** a field, e.g. once they have blurred the field.
-   * Also triggered when a date is selected using the date picker popup after `onInput`.
+   * A callback fired when the user has finished editing the field, such as when they blur the field or complete a date selection. This fires after `onInput`.
    */
   onChange?: (event: Event) => void;
   /**
-   * Callback when the field has an invalid date.
-   * This callback will be called, if the date typed is invalid or disabled.
+   * A callback fired when the field contains an invalid date, either because the typed date is malformed, doesn't exist (e.g., February 31st), or is disabled by the `allow`/`disallow` constraints.
    *
    * Dates that don’t exist or have formatting errors are considered invalid. Some examples of invalid dates are:
    * - 2021-02-31: February doesn’t have 31 days
@@ -2489,6 +2652,20 @@ interface DateFieldProps$1
    */
   onInvalid?: (event: Event) => void;
 }
+/**
+ * Represents autocomplete values that are valid for date input fields.
+ * This is a subset of `AnyAutocompleteField` containing only fields suitable for date-based inputs.
+ *
+ * Available values:
+ * - `bday` - Complete birthday date
+ * - `bday-day` - Day component of a birthday (1-31)
+ * - `bday-month` - Month component of a birthday (1-12)
+ * - `bday-year` - Year component of a birthday (1990)
+ * - `cc-expiry` - Complete credit card expiration date
+ * - `cc-expiry-month` - Month component of a credit card expiration date (1-12)
+ * - `cc-expiry-year` - Year component of a credit card expiration date (2025)
+ * @publicDocs
+ */
 export type DateAutocompleteField = ExtractStrict<
   AnyAutocompleteField,
   | 'bday'
@@ -2501,13 +2678,19 @@ export type DateAutocompleteField = ExtractStrict<
 >;
 interface DividerProps$1 extends GlobalProps {
   /**
-   * Specify the direction of the divider. This uses [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values).
+   * The orientation of the divider line, using [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values).
+   *
+   * - `inline`: Horizontal divider for separating vertically stacked content
+   * - `block`: Vertical divider for separating horizontally arranged content
    *
    * @default 'inline'
    */
   direction?: 'inline' | 'block';
   /**
-   * Modify the color to be more or less intense.
+   * The visual prominence of the divider line.
+   *
+   * - `base`: Standard divider for most separations (default)
+   * - `strong`: More prominent divider for major section breaks
    *
    * @default 'base'
    */
@@ -2549,17 +2732,29 @@ interface EmailFieldProps$1
     BaseTextFieldProps,
     MinMaxLengthProps,
     AutocompleteProps<EmailAutocompleteField> {}
+/**
+ * Represents autocomplete values that are valid for email input fields.
+ * This is a subset of `AnyAutocompleteField` containing only fields suitable for email inputs.
+ *
+ * Available values:
+ * - `email` - Primary email address
+ * - `home email` - Home email address
+ * - `mobile email` - Mobile device email address
+ * - `fax email` - Fax machine email address
+ * - `pager email` - Pager device email address
+ * @publicDocs
+ */
 export type EmailAutocompleteField = ExtractStrict<
   AnyAutocompleteField,
   'email' | `${AutocompleteAddressGroup} email`
 >;
 interface FormProps$1 extends GlobalProps {
   /**
-   * The content of the form.
+   * The form fields and content to be wrapped in the form element.
    */
   children?: ComponentChildren;
   /**
-   * Whether the form is able to be submitted.
+   * Whether the form can be submitted.
    *
    * When set to `true`, this will also disable the implicit submit behavior of the form.
    *
@@ -2570,14 +2765,14 @@ interface FormProps$1 extends GlobalProps {
    */
   disabled?: boolean;
   /**
-   * A callback that is run when the form is submitted.
+   * A callback fired when the form is submitted.
    *
-   * Use `event.waitUntil` to signal how long it takes to save the data,
-   * and whether it was successful or not.
+   * Use `event.waitUntil` to signal how long it takes to save the data
+   * and whether the operation was successful.
    */
   onSubmit?: (event: ExtendableEvent) => void;
   /**
-   * A callback that is run when the form is reset.
+   * A callback fired when the form is reset, typically via a reset button.
    */
   onReset?: (event: Event) => void;
 }
@@ -2604,30 +2799,37 @@ interface FunctionSettingsProps$1 extends GlobalProps, FormProps$1 {
    */
   onError?: (event: AggregateErrorEvent<FunctionSettingsError>) => void;
 }
+/**
+ * @publicDocs
+ */
 export interface FunctionSettingsError extends Error {
   /**
    * A unique identifier describing the “class” of error. These will match
    * the GraphQL error codes as closely as possible. For example the enums
-   * returned by the `metafieldsSet` mutation
-   *
-   * @see https://shopify.dev/docs/api/admin-graphql/latest/enums/MetafieldsSetUserErrorCode
+   * returned by the `metafieldsSet` mutation. Learn more about [MetafieldsSetUserErrorCode](https://shopify.dev/docs/api/admin-graphql/latest/enums/MetafieldsSetUserErrorCode).
    */
   code: string;
   name: 'FunctionSettingsError';
 }
+/**
+ * @publicDocs
+ */
 export type SpacingKeyword = SizeKeyword | 'none';
+/**
+ * @publicDocs
+ */
 export interface GapProps {
   /**
-   * Adjust spacing between elements.
+   * The spacing between child elements.
    *
    * A single value applies to both axes.
-   * A pair of values (eg `large-100 large-500`) can be used to set the inline and block axes respectively.
+   * A pair of values (e.g., `large-100 large-500`) can be used to set the inline and block axes respectively.
    *
    * @default 'none'
    */
   gap?: MaybeResponsive<MaybeTwoValuesShorthandProperty<SpacingKeyword>>;
   /**
-   * Adjust spacing between elements in the block axis.
+   * The spacing between elements along the block axis (vertical spacing in horizontal writing modes).
    *
    * This overrides the row value of `gap`.
    *
@@ -2635,7 +2837,7 @@ export interface GapProps {
    */
   rowGap?: MaybeResponsive<SpacingKeyword | ''>;
   /**
-   * Adjust spacing between elements in the inline axis.
+   * The spacing between elements along the inline axis (horizontal spacing in horizontal writing modes).
    *
    * This overrides the column value of `gap`.
    *
@@ -2643,20 +2845,31 @@ 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
+ * 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. Learn more about the [justify-items property](https://developer.mozilla.org/en-US/docs/Web/CSS/justify-items).
+ * @publicDocs
  */
 export type JustifyItemsKeyword =
   | 'normal'
@@ -2665,9 +2878,8 @@ export type JustifyItemsKeyword =
   | 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
+ * Align items sets the align-self value on all direct children as a group. Learn more about the [align-items property](https://developer.mozilla.org/en-US/docs/Web/CSS/align-items).
+ * @publicDocs
  */
 export type AlignItemsKeyword =
   | 'normal'
@@ -2676,9 +2888,8 @@ export type AlignItemsKeyword =
   | 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
+ * 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. Learn more about the [justify-content property](https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content).
+ * @publicDocs
  */
 export type JustifyContentKeyword =
   | 'normal'
@@ -2686,9 +2897,8 @@ export type JustifyContentKeyword =
   | 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
+ *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. Learn more about the [align-content property](https://developer.mozilla.org/en-US/docs/Web/CSS/align-content).
+ * @publicDocs
  */
 export type AlignContentKeyword =
   | 'normal'
@@ -2698,68 +2908,60 @@ export type AlignContentKeyword =
   | ContentPosition;
 interface GridProps$1 extends GlobalProps, BaseBoxPropsWithRole, GapProps {
   /**
-	  Define columns and specify their size.
+	  Define columns and specify their size. Learn more about the [grid-template-columns property](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-columns).
   
-	  @see https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-columns
 	  @default 'none'
 	*/
   gridTemplateColumns?: MaybeResponsive<string>;
   /**
-	  Define rows and specify their size.
+	  Define rows and specify their size. Learn more about the [grid-template-rows property](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-rows).
   
-	  @see https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-rows
 	  @default 'none'
 	*/
   gridTemplateRows?: MaybeResponsive<string>;
   /**
-	  Aligns the grid items along the inline (row) axis.
+	  Aligns the grid items along the inline (row) axis. Learn more about the [justify-items property](https://developer.mozilla.org/en-US/docs/Web/CSS/justify-items).
   
 	  This overrides the inline value of `placeItems`.
   
-	  @see https://developer.mozilla.org/en-US/docs/Web/CSS/justify-items
 	  @default '' - meaning no override
 	*/
   justifyItems?: MaybeResponsive<JustifyItemsKeyword | ''>;
   /**
-	  Aligns the grid items along the block (column) axis.
+	  Aligns the grid items along the block (column) axis. Learn more about the [align-items property](https://developer.mozilla.org/en-US/docs/Web/CSS/align-items).
   
 	  This overrides the block value of `placeItems`.
   
-	  @see https://developer.mozilla.org/en-US/docs/Web/CSS/align-items
 	  @default '' - meaning no override
 	*/
   alignItems?: MaybeResponsive<AlignItemsKeyword | ''>;
   /**
-	  A shorthand property for `justify-items` and `align-items`.
+	  A shorthand property for `justify-items` and `align-items`. Learn more about the [place-items property](https://developer.mozilla.org/en-US/docs/Web/CSS/place-items).
   
-	  @see https://developer.mozilla.org/en-US/docs/Web/CSS/place-items
 	  @default 'normal normal'
 	*/
   placeItems?: MaybeResponsive<
     `${AlignItemsKeyword} ${JustifyItemsKeyword}` | AlignItemsKeyword
   >;
   /**
-	  Aligns the grid along the inline (row) axis.
+	  Aligns the grid along the inline (row) axis. Learn more about the [justify-content property](https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content).
   
 	  This overrides the inline value of `placeContent`.
   
-	  @see https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content
 	  @default '' - meaning no override
 	*/
   justifyContent?: MaybeResponsive<JustifyContentKeyword | ''>;
   /**
-	  Aligns the grid along the block (column) axis.
+	  Aligns the grid along the block (column) axis. Learn more about the [align-content property](https://developer.mozilla.org/en-US/docs/Web/CSS/align-content).
   
 	  This overrides the block value of `placeContent`.
   
-	  @see https://developer.mozilla.org/en-US/docs/Web/CSS/align-content
 	  @default '' - meaning no override
 	*/
   alignContent?: MaybeResponsive<AlignContentKeyword | ''>;
   /**
-	  A shorthand property for `justify-content` and `align-content`.
+	  A shorthand property for `justify-content` and `align-content`. Learn more about the [place-content property](https://developer.mozilla.org/en-US/docs/Web/CSS/place-content).
   
-	  @see https://developer.mozilla.org/en-US/docs/Web/CSS/place-content
 	  @default 'normal normal'
 	*/
   placeContent?: MaybeResponsive<
@@ -2768,39 +2970,46 @@ interface GridProps$1 extends GlobalProps, BaseBoxPropsWithRole, GapProps {
 }
 interface GridItemProps$1 extends GlobalProps, BaseBoxPropsWithRole {
   /**
-   * Number of columns the item will span across
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column
+   * The number of grid columns this item spans across. Learn more about the [grid-column property](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column).
    *
    * @default 'auto'
    */
   gridColumn?: `span ${number}` | 'auto';
   /**
-   * Number of rows the item will span across
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/grid-row
+   * The number of grid rows this item spans across. Learn more about the [grid-row property](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-row).
    *
    * @default 'auto'
    */
   gridRow?: `span ${number}` | 'auto';
 }
+/**
+ * @publicDocs
+ */
 export interface BaseTypographyProps {
   /**
-   * Modify the color to be more or less intense.
+   * The color intensity of the text. Use `subdued` for less intense, `base` for standard, or `strong` for more intense coloring.
    *
    * @default 'base'
    */
   color?: ColorKeyword;
   /**
-   * Sets the tone of the component, based on the intention of the information being conveyed.
+   * The semantic meaning and color treatment of the component.
+   *
+   * - `auto`: Automatically determined based on context.
+   * - `neutral`: General information without specific intent.
+   * - `info`: Informational content or helpful tips.
+   * - `success`: Positive outcomes or successful states.
+   * - `caution`: Advisory notices that need attention.
+   * - `warning`: Important warnings about potential issues.
+   * - `critical`: Urgent problems or destructive actions.
+   * - `accent`: Highlighted or promotional content.
+   * - `custom`: Custom styling controlled by your theme.
    *
    * @default 'auto'
    */
   tone?: ToneKeyword;
   /**
-   * Set the numeric properties of the font.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant-numeric
+   * Set the numeric properties of the font. Learn more about the [font-variant-numeric property](https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant-numeric).
    *
    * @default 'auto' - inherit from the parent element
    */
@@ -2818,22 +3027,23 @@ export interface BaseTypographyProps {
   /**
    * Indicates the directionality of the element’s text.
    *
-   * - `ltr`: languages written from left to right (e.g. English)
-   * - `rtl`: languages written from right to left (e.g. Arabic)
-   * - `auto`: the user agent determines the direction based on the content
-   * - `''`: direction is inherited from parent elements (equivalent to not setting the attribute)
+   * - `""`: The direction is inherited from parent elements (equivalent to not setting the attribute).
+   * - `auto`: The user agent determines the direction based on the content.
+   * - `ltr`: The languages written from left to right (such as English).
+   * - `rtl`: The languages written from right to left (such as Arabic).
    *
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir
+   * Learn more about the [dir attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir).
    *
    * @default ''
    */
   dir?: 'ltr' | 'rtl' | 'auto' | '';
 }
+/**
+ * @publicDocs
+ */
 export interface BlockTypographyProps {
   /**
-   * Truncates the text content to the specified number of lines.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-line-clamp
+   * Truncates the text content to the specified number of lines. Learn more about the [-webkit-line-clamp property](https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-line-clamp).
    *
    * @default Infinity - no truncation is applied
    */
@@ -2844,7 +3054,7 @@ interface HeadingProps$1
     AccessibilityVisibilityProps,
     BlockTypographyProps {
   /**
-   * The content of the Heading.
+   * The content of the heading.
    */
   children?: ComponentChildren;
   /**
@@ -2872,67 +3082,72 @@ interface IconProps$1
   extends GlobalProps,
     Pick<InteractionProps, 'interestFor'> {
   /**
-   * Sets the tone of the icon, based on the intention of the information being conveyed.
+   * The semantic meaning and color treatment of the component.
+   *
+   * - `auto`: Automatically determined based on context.
+   * - `neutral`: General information without specific intent.
+   * - `info`: Informational content or helpful tips.
+   * - `success`: Positive outcomes or successful states.
+   * - `caution`: Advisory notices that need attention.
+   * - `warning`: Important warnings about potential issues.
+   * - `critical`: Urgent problems or destructive actions.
    *
    * @default 'auto'
    */
   tone?: ToneKeyword;
   /**
-   * Modify the color to be more or less intense.
+   * The color intensity of the icon. Use `subdued` for less intense, `base` for standard, or `strong` for more intense coloring.
    *
    * @default 'base'
    */
   color?: ColorKeyword;
   /**
-   * Adjusts the size of the icon.
+   * The size of the icon. Available sizes range from `small-500` (smallest) to `large-500` (largest), with `base` providing the default size.
    *
    * @default 'base'
    */
   size?: SizeKeyword;
+  /**
+   * The icon to display. Can be any icon name from the icon library or a custom string identifier.
+   */
   type?: IconType | AnyString;
 }
+/**
+ * @publicDocs
+ */
 export interface BaseImageProps {
   /**
-   * An alternative text description that describe the image for the reader to
-   * understand what it is about. It is extremely useful for both users using
-   * assistive technology and sighted users. A well written description
-   * provides people with visual impairments the ability to participate in
-   * consuming non-text content. When a screen readers encounters an `s-image`,
-   * the description is read and announced aloud. If an image fails to load,
-   * potentially due to a poor connection, the `alt` is displayed on
-   * screen instead. This has the benefit of letting a sighted buyer know an
-   * image was meant to load here, but as an alternative, they’re still able to
-   * consume the text content. Read
-   * [considerations when writing alternative text](https://www.shopify.com/ca/blog/image-alt-text#4)
-   * to learn more.
-   *
-   * @default `''`
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt
+   * Alternative text that describes the image for accessibility.
+   *
+   * Provides a text description of the image for users with assistive technology
+   * and serves as a fallback when the image fails to load. A well-written description
+   * enables people with visual impairments to understand non-text content.
+   *
+   * When a screen reader encounters an image, it reads this description aloud.
+   * When an image fails to load, this text displays on screen, helping all users
+   * understand what content was intended.
+   *
+   * Learn more about [writing effective alt text](https://www.shopify.com/ca/blog/image-alt-text#4)
+   * and the [alt attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt).
+   *
+   * @default ''
    */
   alt?: string;
   /**
-   * A set of media conditions and their corresponding sizes.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes
+   * A set of media conditions and their corresponding sizes. Learn more about the [sizes attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes).
    */
   sizes?: string;
   /**
    * The image source (either a remote URL or a local file resource).
    *
-   * When the image is loading or no `src` is provided, a placeholder will be rendered.
+   * When the image is loading or no `src` is provided, a placeholder is 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
+   * reserved, except in cases where the image area does not have a contextual inline or block size, which should be rare. Learn more about the [src attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#src).
    */
   src?: string;
   /**
-   * A set of image sources and their width or pixel density descriptors.
-   *
-   * This overrides the `src` property.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#srcset
+   * A set of image sources and their width or pixel density descriptors. Learn more about the [srcset attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#srcset). This overrides the `src` property.
    */
   srcSet?: string;
 }
@@ -2942,6 +3157,10 @@ interface ImageProps$1 extends GlobalProps, BaseImageProps, BorderProps {
    * the role will be used by assistive technologies to help users
    * navigate the page.
    *
+   * - `img`: Identifies the element as an image that conveys meaningful information to users.
+   * - `presentation`: Removes semantic meaning, making the image purely decorative and ignored by screen readers.
+   * - `none`: Completely hides the element and its content from assistive technologies.
+   *
    * @default 'img'
    *
    * @implementation The `img` role doesn't need to be applied if
@@ -2952,14 +3171,14 @@ interface ImageProps$1 extends GlobalProps, BaseImageProps, BorderProps {
     | 'img'
     | ExtractStrict<AccessibilityRole, 'presentation' | 'none'>;
   /**
-   * The displayed inline width of the image.
+   * The inline width (horizontal size) of the image.
    *
-   * - `fill`: the image will takes up 100% of the available inline size.
-   * - `auto`: the image will be displayed at its natural size.
+   * - `fill`: The image takes up 100% of the available inline space.
+   * - `auto`: The image is displayed at its natural size.
    *
-   * @default 'fill'
+   * Learn more about the [width attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#width).
    *
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#width
+   * @default 'fill'
    */
   inlineSize?: 'fill' | 'auto';
   /**
@@ -2973,20 +3192,18 @@ interface ImageProps$1 extends GlobalProps, BaseImageProps, BorderProps {
    * 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`.
    *
-   * @default '1/1'
+   * Learn more about the [aspect-ratio property](https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio).
    *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio
+   * @default '1/1'
    */
   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.
+   * 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'
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit
    */
   objectFit?: 'contain' | 'cover';
   /**
@@ -2994,62 +3211,57 @@ interface ImageProps$1 extends GlobalProps, BaseImageProps, BorderProps {
    * - `eager`: Immediately loads the image, irrespective of its position within the visible viewport.
    * - `lazy`: Delays loading the image until it approaches a specified distance from the viewport.
    *
+   * Learn more about the [loading attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#loading).
+   *
    * @default 'eager'
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#loading
    */
   loading?: 'eager' | 'lazy';
   /**
-   * Invoked when load completes successfully.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onload
+   * A callback fired when the image loads successfully. Learn more about the [load event](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onload).
    */
   onLoad?: (event: Event) => void;
   /**
-   * Invoked on load error.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onerror
+   * A callback fired when the image fails to load. Learn more about the [error event](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onerror).
    */
   onError?: (event: Event) => void;
 }
 interface LinkProps$1 extends GlobalProps, LinkBehaviorProps {
   /**
-   * The content of the Link.
+   * The text or elements displayed as the link's content.
    */
   children?: ComponentChildren;
   /**
-   * Sets the tone of the Link, based on the intention of the information being conveyed.
+   * The semantic meaning and color treatment of the component.
+   *
+   * - `critical`: Urgent problems or destructive actions.
+   * - `auto`: Automatically determined based on context.
+   * - `neutral`: General information without specific intent.
    *
    * @default 'auto'
    */
   tone?: ToneKeyword;
   /**
-   * A label that describes the purpose or contents of the Link. It will be read to users using assistive technologies such as screen readers.
-   *
-   * Use this when using only an icon or the content of the link is not enough context
-   * for users using assistive technologies.
+   * A label that describes the purpose or content of the component for assistive technologies like screen readers. Use this to provide additional context when the visible content alone doesn't clearly convey the component's purpose.
    */
   accessibilityLabel?: string;
   /**
-   * Indicate the text language. Useful when the text is in a different language than the rest of the page.
-   * It will allow assistive technologies such as screen readers to invoke the correct pronunciation.
-   * [Reference of values](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) ("subtag" label)
+   * The language of the link's text content. Use this when the link text is in a different language than the rest of the page, allowing assistive technologies such as screen readers to invoke the correct pronunciation. See the [reference of values](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) ("subtag" label).
    */
   lang?: string;
 }
 interface ListItemProps$1 extends GlobalProps {
   /**
-   * The content of the ListItem.
+   * The content displayed within the list item.
    */
   children?: ComponentChildren;
 }
 interface MenuProps$1 extends GlobalProps {
   /**
-   * A label that describes the purpose or contents of the element. When set,
-   * it will be announced using assistive technologies and provide additional context.
+   * A label that describes the purpose or content of the component for assistive technologies like screen readers. Use this to provide additional context when the visible content alone doesn't clearly convey the component's purpose.
    */
   accessibilityLabel?: string;
   /**
-   * The children define the actions to render inside the Menu. Only Button components are allowed as children of a Menu, and these Buttons can perform actions (using `onClick`) or link to other parts of the application (using `to`/ `href`). Any other component placed here will be ignored.
+   * The collection of Button components displayed as menu actions. Only Button components are allowed as children, which can perform actions using `onClick` or link to other parts of the application using `href`. Any other component type will be ignored.
    */
   children?: ComponentChildren;
 }
@@ -3067,32 +3279,32 @@ interface ModalProps$1
    */
   accessibilityLabel?: string;
   /**
-   * A title that describes the content of the Modal.
+   * A title that describes the content of the modal.
    *
    */
   heading?: string;
   /**
-   * Adjust the padding around the Modal content.
+   * Adjust the padding around the modal content.
    *
    * `base`: applies padding that is appropriate for the element.
    *
-   * `none`: removes all padding from the element. This can be useful when elements inside the Modal need to span
-   * to the edge of the Modal. For example, a full-width image. In this case, rely on `Box` with a padding of 'base'
+   * `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;
 }
@@ -3101,6 +3313,9 @@ interface MoneyFieldProps$1
     BaseTextFieldProps,
     NumberConstraintsProps,
     AutocompleteProps<MoneyAutocompleteField> {}
+/**
+ * @publicDocs
+ */
 export type MoneyAutocompleteField = ExtractStrict<
   AnyAutocompleteField,
   'transaction-amount'
@@ -3112,28 +3327,31 @@ interface NumberFieldProps$1
     NumberConstraintsProps,
     FieldDecorationProps {
   /**
-   * Sets the virtual keyboard.
+   * Sets the virtual keyboard. Learn more about the [inputmode attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inputmode).
    *
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inputmode
    * @default 'decimal'
    */
   inputMode?: 'decimal' | 'numeric';
   /**
-   * Callback when the user has **finished editing** a field, e.g. once they have blurred
-   * the field after changing the value.
-   * Also fired after `onInput` on every step when interacting with the controls or the keyboard up and down arrows.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event
+   * Callback when the user has **finished editing** a field, such as when they blur the field after changing the value.
+   * Also fired after `onInput` on every step when using keyboard up and down arrows. Learn more about the [change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event).
    */
   onChange?: (event: Event) => void;
   /**
-   * Callback when the user makes any changes in the field.
-   * Also fired before `onChange` on every step when interacting with the controls or the keyboard up and down arrows.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event
+   * A callback fired when the user makes any changes to the field value, including when using keyboard up/down arrows. This fires before `onChange`. Learn more about the [input event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event).
    */
   onInput?: (event: Event) => void;
 }
+/**
+ * Represents autocomplete values that are valid for number input fields.
+ * This is a subset of `AnyAutocompleteField` containing only fields suitable for numeric inputs.
+ *
+ * Available values:
+ * - `one-time-code` - One-time codes for authentication (OTP, 2FA codes)
+ * - `cc-number` - Credit card number
+ * - `cc-csc` - Credit card security code (CVV/CVC)
+ * @publicDocs
+ */
 export type NumberAutocompleteField = ExtractStrict<
   AnyAutocompleteField,
   'one-time-code' | 'cc-number' | 'cc-csc'
@@ -3152,27 +3370,18 @@ interface OptionGroupProps$1 extends GlobalProps {
    */
   disabled?: boolean;
   /**
-   * The user-facing label for this group of options.
+   * The label text displayed for this group of related options.
    */
   label?: string;
   /**
-   * The options a user can select from.
-   *
-   * Accepts `Option` components.
-   */
-  children?: ComponentChildren;
-}
-interface OrderedListProps$1 extends GlobalProps {
-  /**
-   * The content of the OrderededList.
-   *
-   * Accepts only `ListItem` components.
+   * The collection of option components that users can select from within this group.
    */
   children?: ComponentChildren;
 }
+interface OrderedListProps$1 extends GlobalProps {}
 interface PageProps$1 extends GlobalProps, ActionSlots {
   /**
-   * The content of the Page.
+   * The content of the page.
    */
   children?: ComponentChildren;
   /**
@@ -3212,34 +3421,30 @@ interface ParagraphProps$1
     BlockTypographyProps,
     AccessibilityVisibilityProps {
   /**
-   * The content of the Paragraph.
+   * The text or elements displayed within the paragraph.
    */
   children?: ComponentChildren;
   /**
-   * Provide semantic meaning and default styling to the paragraph.
+   * The semantic type of the paragraph, which provides meaning and default styling.
    *
-   * Other presentation properties on `s-paragraph` override the default styling.
+   * Other presentation properties on the paragraph can override the default styling.
    *
    * @default 'paragraph'
    */
   type?: ParagraphType;
 }
+/**
+ * @publicDocs
+ */
 export type ParagraphType =
   /**
-   * Indicate the text is a structural grouping of related content.
-   *
-   * In an HTML host, the text will be rendered in an `<p>` element.
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/p
+   * Indicates the text is a structural grouping of related content. In an HTML host, the text will be rendered in a `<p>` element. Learn more about the [p element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/p).
    */
   | 'paragraph'
   /**
-   * Indicates the text is considered less important than the main content, but is still necessary for the reader to understand.
-   * It can be used for secondary content but also for disclaimers, terms and conditions, or legal information.
-   *
-   * Surfaces should apply a smaller font size than the default size.
+   * Indicates the text is considered less important than the main content but is still necessary for understanding. This can be used for secondary content, disclaimers, terms and conditions, or legal information.
    *
-   * In an HTML host, the text will be rendered in a `<small>` element.
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/small
+   * Surfaces should apply a smaller font size than the default. In an HTML host, the text will be rendered in a `<small>` element. Learn more about the [small element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/small).
    */
   | 'small';
 interface PasswordFieldProps$1
@@ -3247,6 +3452,15 @@ interface PasswordFieldProps$1
     BaseTextFieldProps,
     MinMaxLengthProps,
     AutocompleteProps<PasswordAutocompleteField> {}
+/**
+ * Represents autocomplete values that are valid for password input fields.
+ * This is a subset of `AnyAutocompleteField` containing only fields suitable for password inputs.
+ *
+ * Available values:
+ * - `current-password` - Existing password for login or authentication
+ * - `new-password` - New password when creating an account or changing password
+ * @publicDocs
+ */
 export type PasswordAutocompleteField = ExtractStrict<
   AnyAutocompleteField,
   'new-password' | 'current-password'
@@ -3262,86 +3476,44 @@ interface PopoverProps$1
    */
   children?: ComponentChildren;
 }
-interface PressButtonProps$1
-  extends GlobalProps,
-    Pick<
-      ButtonProps$1,
-      | 'accessibilityLabel'
-      | 'children'
-      | 'icon'
-      | 'inlineSize'
-      | 'lang'
-      | 'tone'
-      | 'variant'
-      | 'disabled'
-      | 'loading'
-      | 'onClick'
-      | 'onBlur'
-      | 'onFocus'
-    > {
-  /**
-   * Whether the button is pressed.
-   *
-   * @default false
-   */
-  pressed?: boolean;
-  /**
-   * Whether the button is pressed by default.
-   *
-   * @default false
-   *
-   * @implementation `defaultPressed` reflects to the `pressed` attribute.
-   */
-  defaultPressed?: boolean;
-}
 interface QueryContainerProps$1 extends GlobalProps {
   /**
    * The content of the container.
    */
   children?: ComponentChildren;
   /**
-   * The name of the container, which can be used in your container queries to target this container specifically.
+   * An identifier for this container that you can reference in CSS container queries to apply styles based on this specific container's size.
    *
-   * We place the container name of `s-default` on every container. Because of this, it is not required to add a `containerName` identifier in your queries. For example, a `@container (inline-size <= 300px) none, auto` query is equivalent to `@container s-default (inline-size <= 300px) none, auto`.
+   * All QueryContainer components automatically receive a container name of `s-default`. You can omit the container name in your queries, so `@container (inline-size <= 300px)` is equivalent to `@container s-default (inline-size <= 300px)`.
    *
-   * Any value set in `containerName` will be set alongside alongside `s-default`. For example, `containerName="my-container-name"` will result in a value of `s-default my-container-name` set on the `container-name` CSS property of the rendered HTML.
+   * When you provide a custom `containerName`, it's added alongside `s-default`. For example, `containerName="product-card"` results in `s-default product-card` being set on the `container-name` CSS property, allowing you to target this container with `@container product-card (inline-size <= 300px)`.
    *
-   * @default ''
+   * Learn more about the [container-name property](https://developer.mozilla.org/en-US/docs/Web/CSS/container-name).
    *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/container-name
+   * @default ''
    *
    * @implementation You must always have a CSS `container-name` of `s-default` for this component.
    */
   containerName?: string;
 }
-export type OverflowKeyword = 'auto' | 'hidden';
-export type ScrollSnapType = 'none' | 'mandatory' | 'proximity';
-export type ScrollAccessibilityRole = 'generic' | 'region';
 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
-   * the right context to users.
+   * A label that describes the purpose or content of the component for assistive technologies like screen readers. Use this to provide additional context when the visible content alone doesn't clearly convey the component's purpose.
    */
   accessibilityLabel?: string;
   /**
-   * A title that describes the content of the section.
+   * The heading text displayed at the top of the section. This heading provides a title for the section's content and automatically uses the appropriate semantic heading level (h2, h3, h4) based on nesting depth to maintain proper document structure.
    */
   heading?: string;
   /**
-   * Adjust the padding of all edges.
+   * The amount of padding applied to all edges of the section.
    *
-   * - `base`: applies padding that is appropriate for the element. Note that it may result in no padding if
-   * this is the right design decision in a particular context.
-   * - `none`: removes all padding from the element. This can be useful when elements inside the Section need to span
-   * to the edge of the Section. For example, a full-width image. In this case, rely on `s-box` with a padding of 'base'
-   * to bring back the desired padding for the rest of the content.
+   * - `base`: Applies standard padding appropriate for the section. Note that this might result in no padding if that's the right design decision for the context.
+   * - `none`: Removes all padding, useful when content like images needs to extend to the section's edges. Use Box with `padding="base"` for individual content areas that need padding.
    *
    * @default 'base'
    */
@@ -3354,59 +3526,61 @@ interface SelectProps$1
     Omit<FieldProps, 'defaultValue'>,
     FocusEventProps {
   /**
-   * The options a user can select from.
+   * The selectable options displayed in the dropdown list.
    *
-   * Accepts `Option` and `OptionGroup` components.
+   * Accepts Option components for individual selectable items, and OptionGroup components to organize related options into logical groups with labels.
    */
   children?: ComponentChildren;
 }
 interface SpinnerProps$1 extends GlobalProps {
   /**
-   * Adjusts the size of the spinner icon.
+   * The size of the spinner icon. Available sizes range from `small-500` (smallest) to `large-500` (largest), with `base` providing the default size.
    *
    * @default 'base'
    */
   size?: SizeKeyword;
   /**
-   * A label that describes the purpose of the progress. When set,
-   * it will be announced to users using assistive technologies and will
-   * provide them with more context. Providing an `accessibilityLabel` is
-   * recommended if there is no accompanying text describing that something
-   * is loading.
+   * A label that describes the purpose or content of the component for assistive technologies like screen readers. Use this to provide additional context when the visible content alone doesn't clearly convey the component's purpose.
    */
   accessibilityLabel?: string;
 }
 interface StackProps$1 extends GlobalProps, BaseBoxPropsWithRole, GapProps {
   /**
-   * The content of the Stack.
+   * The elements arranged within the stack layout.
    */
   children?: ComponentChildren;
   /**
-   * Sets how the children are placed within the Stack. This uses [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values).
+   * The axis along which child elements are arranged, using [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values).
+   *
+   * - `block`: Arranges children vertically (in horizontal writing modes). Content does not wrap.
+   * - `inline`: Arranges children horizontally (in horizontal writing modes). Content wraps to the next line if needed.
    *
    * @default 'block'
    *
-   * @implementation the content will wrap if the direction is 'inline', and not wrap if the direction is 'block'
+   * @implementation The content will wrap if the direction is 'inline', and not wrap if the direction is 'block'.
    */
   direction?: MaybeResponsive<'block' | 'inline'>;
   /**
-   * Aligns the Stack along the main axis.
+   * Controls the distribution of children along the inline axis (horizontally in horizontal writing modes).
+   *
+   * Use this to position items along the primary axis of the stack - horizontally for inline stacks or vertically for block stacks when wrapped into multiple lines. Learn more about the [justify-content property](https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content).
    *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content
    * @default 'normal'
    */
   justifyContent?: MaybeResponsive<JustifyContentKeyword>;
   /**
-   * Aligns the Stack's children along the cross axis.
+   * Controls the alignment of children along the block axis (vertically in horizontal writing modes).
+   *
+   * Use this to align items perpendicular to the stack direction - vertically for inline stacks or horizontally for block stacks. Learn more about the [align-items property](https://developer.mozilla.org/en-US/docs/Web/CSS/align-items).
    *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/align-items
    * @default 'normal'
    */
   alignItems?: MaybeResponsive<AlignItemsKeyword>;
   /**
-   * Aligns the Stack along the cross axis.
+   * Controls the distribution of lines along the block axis when content wraps into multiple lines.
+   *
+   * This property only affects stacks with wrapping content. For single-line stacks, use `alignItems` instead. Learn more about the [align-content property](https://developer.mozilla.org/en-US/docs/Web/CSS/align-content).
    *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/align-content
    * @default 'normal'
    */
   alignContent?: MaybeResponsive<AlignContentKeyword>;
@@ -3417,6 +3591,9 @@ interface SwitchProps$1
     BasicFieldProps,
     FieldDetailsProps,
     FieldErrorProps {}
+/**
+ * @publicDocs
+ */
 export interface PaginationProps {
   /**
    * Whether to use pagination controls.
@@ -3425,11 +3602,11 @@ export interface PaginationProps {
    */
   paginate?: boolean;
   /**
-   * Called when the previous page button is clicked.
+   * A callback fired when the previous page button is clicked.
    */
   onPreviousPage?: (event: Event) => void;
   /**
-   * Called when the next page button is clicked.
+   * A callback fired when the next page button is clicked.
    */
   onNextPage?: (event: Event) => void;
   /**
@@ -3445,8 +3622,8 @@ export interface PaginationProps {
    */
   hasPreviousPage?: boolean;
   /**
-   * Whether the table is in a loading state, such as initial page load or loading the next page in a paginated table.
-   * When true, the table could be in an inert state, which prevents user interaction.
+   * Whether the table is in a loading state, such as during initial page load or when loading the next page in a paginated table.
+   * When `true`, the table might be in an inert state that prevents user interaction.
    *
    * @default false
    */
@@ -3454,19 +3631,23 @@ export interface PaginationProps {
 }
 interface TableProps$1 extends GlobalProps, PaginationProps {
   /**
-   * The content of the Table.
+   * The table structure defining headers and data rows.
+   *
+   * Accepts table header row (for column headers) and table body (for data rows) components. Structure your table with a table header row first, followed by table body.
    */
   children?: ComponentChildren;
   /**
-   * Input elements, such as SearchField, used to search and filter the table.
+   * Filter controls displayed above the table.
+   *
+   * Accepts input components like search field or select for filtering table data. These controls appear in a dedicated area above the table content.
    */
   filters?: ComponentChildren;
   /**
-   * Sets the layout of the Table.
+   * The layout variant of the table.
    *
-   * - `list`: The Table is always displayed as a list.
-   * - `table`: The Table is always displayed as a table.
-   * - `auto`: The Table is displayed as a table on wide devices and as a list on narrow devices.
+   * - `list`: Always displays as a list layout.
+   * - `table`: Always displays as a traditional table layout.
+   * - `auto`: Automatically displays as a table on wide screens and as a list on narrow screens.
    *
    * @default 'auto'
    */
@@ -3474,59 +3655,80 @@ interface TableProps$1 extends GlobalProps, PaginationProps {
 }
 interface TableBodyProps$1 extends GlobalProps {
   /**
-   * The body of the table. May not have any semantic meaning in the Table's `list` variant.
+   * The data rows displayed in the table body.
+   *
+   * Accepts TableRow components, with each row representing a single record or entry in the table.
    */
   children?: ComponentChildren;
 }
 interface TableCellProps$1 extends GlobalProps {
   /**
-   * The content of the table cell.
+   * The data value displayed in this cell.
+   *
+   * Accepts text content or inline components representing the cell's data value.
    */
   children?: ComponentChildren;
 }
+/**
+ * Represents the content designation for table columns when displayed in list variant on mobile devices.
+ *
+ * Available values:
+ * - `primary` - The most important content. Only one column can have this designation.
+ * - `secondary` - Supporting content displayed below primary. Only one column can have this designation.
+ * - `kicker` - Small label displayed above primary content with less visual prominence. Only one column can have this designation.
+ * - `inline` - Content displayed inline with primary content.
+ * - `labeled` - Each column displays as a heading-content pair.
+ * @publicDocs
+ */
 export type ListSlotType =
   | 'primary'
   | 'secondary'
   | 'kicker'
   | 'inline'
   | 'labeled';
+/**
+ * Represents the format options for table headers that control styling and alignment of column content.
+ *
+ * Available values:
+ * - `base`: Standard format for text columns
+ * - `currency`: Right-aligned format for monetary values
+ * - `numeric`: Right-aligned format for numeric values
+ * @publicDocs
+ */
+export type HeaderFormat = 'base' | 'currency' | 'numeric';
 interface TableHeaderProps$1 extends GlobalProps {
   /**
-   * The heading of the column in the `table` variant, and the label of its data in `list` variant.
+   * The column heading text.
+   *
+   * This text labels the column in table variant and appears as a label for data in list variant.
    */
   children?: ComponentChildren;
   /**
-   * Content designation for the table's `list` variant.
-   *
-   * - `primary`: The most important content. Only one column can have this designation.
-   * - `secondary`: The secondary content. Only one column can have this designation.
-   * - `kicker`: Content that is displayed before primary and secondary content, but with less visual prominence. Only one column can have this designation.
-   * - `inline`: Content that is displayed inline.
-   * - `labeled`: Each column with this designation displays as a heading-content pair.
+   * The content designation for this column when the table displays in list variant on mobile devices.
    *
    * @default 'labeled'
    */
   listSlot?: ListSlotType;
   /**
-   * The format of the column. Will automatically apply styling and alignment to cell content based on the value.
-   *
-   * - `base`: The base format for columns.
-   * - `currency`: Formats the column as currency.
-   * - `numeric`: Formats the column as a number.
+   * The format of the column that controls styling and alignment of cell content.
    *
    * @default 'base'
    */
-  format?: 'base' | 'currency' | 'numeric';
+  format?: HeaderFormat;
 }
 interface TableHeaderRowProps$1 extends GlobalProps {
   /**
-   * Contents of the table heading row; children should be `TableHeading` components.
+   * The column headers displayed in the table header row.
+   *
+   * Accepts TableHeader components, with each header defining a column and providing its label.
    */
   children?: ComponentChildren;
 }
 interface TableRowProps$1 extends GlobalProps {
   /**
-   * The content of a TableRow, which should be `TableCell` components.
+   * The data cells displayed in this table row.
+   *
+   * Accepts TableCell components, with each cell containing a data value for the corresponding column.
    */
   children?: ComponentChildren;
   /**
@@ -3537,7 +3739,7 @@ interface TableRowProps$1 extends GlobalProps {
    * Which is why the target element must be in the table; so that keyboard and screen reader users can interact with it normally.
    *
    * @implementation no focus or keyboard affordances are introduced by this property. No aria attributes need to be added to the table row.
-   * @implementation the row and/or delegate should have some affordance that indicates it is clickable. This may be a background color, a border, a hover effect, etc.
+   * @implementation the row and/or delegate should have some affordance that indicates it is clickable. This may be a background color, a border, or a hover effect.
    */
   clickDelegate?: string;
 }
@@ -3548,11 +3750,11 @@ interface TextProps$1
     DisplayProps,
     Pick<InteractionProps, 'interestFor'> {
   /**
-   * The content of the Text.
+   * The text content or inline elements displayed within the component.
    */
   children?: ComponentChildren;
   /**
-   * Provide semantic meaning and default styling to the text.
+   * The semantic type of the text, which provides meaning and default styling.
    *
    * Other presentation properties on Text override the default styling.
    *
@@ -3560,6 +3762,9 @@ interface TextProps$1
    */
   type?: TextType;
 }
+/**
+ * @publicDocs
+ */
 export type TextType =
   /**
    * Indicate the text is contact information. Typically used for addresses.
@@ -3568,11 +3773,9 @@ export type TextType =
    *
    * Surfaces may apply styling to this type.
    *
-   * In an HTML host, the text will be rendered in an `<address>` element.
+   * In an HTML host, the text will be rendered in an `<address>` element. Learn more about the [address element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/address).
    *
    * @implementation vertical alignment should be `baseline` (`vertical-align: baseline`)
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/address
    */
   | 'address'
   /**
@@ -3580,8 +3783,7 @@ export type TextType =
    *
    * Surfaces should apply styling to this type to suggest its content no longer applies.
    *
-   * In an HTML host, the text will be rendered in a `<s>` element.
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/s
+   * In an HTML host, the text will be rendered in a `<s>` element. Learn more about the [s element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/s).
    */
   | 'redundant'
   /**
@@ -3590,8 +3792,7 @@ export type TextType =
    *
    * Surfaces should apply styling to this type to draw attention to the content.
    *
-   * In an HTML host, the text will be rendered in a `<mark>` element.
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark
+   * In an HTML host, the text will be rendered in a `<mark>` element. Learn more about the [mark element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark).
    */
   | 'mark'
   /**
@@ -3599,8 +3800,7 @@ export type TextType =
    *
    * Surfaces should apply styling to this type to distinguish it from surrounding text. Italicization is a common choice, but not required.
    *
-   * In an HTML host, the text will be rendered in an `<em>` element.
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/em
+   * In an HTML host, the text will be rendered in an `<em>` element. Learn more about the [em element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/em).
    */
   | 'emphasis'
   /**
@@ -3610,8 +3810,7 @@ export type TextType =
    *
    * Surfaces should italicize this content by default.
    *
-   * In an HTML host, the text will be rendered in a `<i>` tag.
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/i
+   * In an HTML host, the text will be rendered in a `<i>` tag. Learn more about the [i element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/i).
    */
   | 'offset'
   /**
@@ -3619,8 +3818,7 @@ export type TextType =
    *
    * Surfaces should render this content bold by default.
    *
-   * In an HTML host, the text will be rendered in a `<strong>` tag.
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/strong
+   * In an HTML host, the text will be rendered in a `<strong>` tag. Learn more about the [strong element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/strong).
    */
   | 'strong'
   /**
@@ -3629,8 +3827,7 @@ export type TextType =
    *
    * Surfaces should apply a smaller font size than the default size.
    *
-   * In an HTML host, the text will be rendered in a `<small>` element.
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/small
+   * In an HTML host, the text will be rendered in a `<small>` element. Learn more about the [small element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/small).
    */
   | 'small'
   /**
@@ -3638,8 +3835,7 @@ export type TextType =
    *
    * Surfaces must not apply any default styling to this type.
    *
-   * In an HTML host, the text will be rendered in a `<span>` tag.
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span
+   * In an HTML host, the text will be rendered in a `<span>` tag. Learn more about the [span element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span).
    */
   | 'generic';
 interface TextAreaProps$1
@@ -3648,7 +3844,7 @@ interface TextAreaProps$1
     MinMaxLengthProps,
     AutocompleteProps<TextAutocompleteField> {
   /**
-   * A number of visible text lines.
+   * The number of visible text lines displayed in the textarea, which controls its initial height.
    *
    * @default 2
    */
@@ -3662,19 +3858,15 @@ interface TextFieldProps$1
     FieldDecorationProps {}
 interface ThumbnailProps$1 extends GlobalProps, BaseImageProps {
   /**
-   * Invoked when load of provided image completes successfully.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onload
+   * A callback fired when the thumbnail image loads successfully. Learn more about the [load event](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onload).
    */
   onLoad?: (event: Event) => void;
   /**
-   * Invoked on load error of provided image.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onerror
+   * A callback fired when the thumbnail image fails to load. Learn more about the [error event](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onerror).
    */
   onError?: (event: Event) => void;
   /**
-   * Adjusts the size the product thumbnail image.
+   * The size of the product thumbnail image. Available sizes range from `small-500` (smallest) to `large-500` (largest), with `base` providing the default size.
    *
    * @default 'base'
    */
@@ -3682,23 +3874,30 @@ interface ThumbnailProps$1 extends GlobalProps, BaseImageProps {
 }
 interface TooltipProps$1 extends GlobalProps {
   /**
-   * The content of the Tooltip.
-   */
-  children?: ComponentChildren;
-}
-interface UnorderedListProps$1 extends GlobalProps {
-  /**
-   * The content of the UnorderededList.
-   *
-   * Accepts only `ListItem` components.
+   * The text or elements displayed inside the tooltip popup.
    */
   children?: ComponentChildren;
 }
+interface UnorderedListProps$1 extends GlobalProps {}
 interface URLFieldProps$1
   extends GlobalProps,
     BaseTextFieldProps,
     MinMaxLengthProps,
     AutocompleteProps<URLAutocompleteField> {}
+/**
+ * Represents autocomplete values that are valid for URL input fields.
+ * This is a subset of `AnyAutocompleteField` containing only fields suitable for URL inputs.
+ *
+ * Available values:
+ * - `url` - General URL or web address
+ * - `photo` - URL to a photo or image
+ * - `impp` - Instant messaging protocol URL
+ * - `home impp` - Home instant messaging protocol URL
+ * - `mobile impp` - Mobile instant messaging protocol URL
+ * - `fax impp` - Fax instant messaging protocol URL
+ * - `pager impp` - Pager instant messaging protocol URL
+ * @publicDocs
+ */
 export type URLAutocompleteField = ExtractStrict<
   AnyAutocompleteField,
   'url' | 'photo' | 'impp' | `${AutocompleteAddressGroup} impp`
@@ -3706,6 +3905,9 @@ export type URLAutocompleteField = ExtractStrict<
 //
 // Preact Virtual DOM
 // -----------------------------------
+/**
+ * @publicDocs
+ */
 export interface VNode<P = {}> {
   type: ComponentType<P> | string;
   props: P & {
@@ -3713,8 +3915,7 @@ export interface VNode<P = {}> {
   };
   key: Key;
   /**
-   * ref is not guaranteed by React.ReactElement, for compatibility reasons
-   * with popular react libs we define it as optional too
+   * The ref is not guaranteed by `React.ReactElement`. For compatibility with popular React libraries, this is defined as optional.
    */
   ref?: Ref<any> | null;
   /**
@@ -3733,12 +3934,27 @@ export interface VNode<P = {}> {
 //
 // Preact Component interface
 // -----------------------------------
+/**
+ * @publicDocs
+ */
 export type Key = string | number | any;
+/**
+ * @publicDocs
+ */
 export interface RefObject<T> {
   current: T | null;
 }
+/**
+ * @publicDocs
+ */
 export type RefCallback<T> = (instance: T | null) => void;
+/**
+ * @publicDocs
+ */
 export type Ref<T> = RefObject<T> | RefCallback<T> | null;
+/**
+ * @publicDocs
+ */
 export type ComponentChild =
   | VNode<any>
   | object
@@ -3749,13 +3965,22 @@ export type ComponentChild =
   | null
   | undefined;
 type ComponentChildren$1 = ComponentChild[] | ComponentChild;
+/**
+ * @publicDocs
+ */
 export interface Attributes {
   key?: Key | undefined;
   jsx?: boolean | undefined;
 }
+/**
+ * @publicDocs
+ */
 export interface ErrorInfo {
   componentStack?: string;
 }
+/**
+ * @publicDocs
+ */
 export type RenderableProps<P, RefType = any> = P &
   Readonly<
     Attributes & {
@@ -3763,12 +3988,21 @@ export type RenderableProps<P, RefType = any> = P &
       ref?: Ref<RefType>;
     }
   >;
+/**
+ * @publicDocs
+ */
 export type ComponentType<P = {}> = ComponentClass<P> | FunctionComponent<P>;
+/**
+ * @publicDocs
+ */
 export interface FunctionComponent<P = {}> {
   (props: RenderableProps<P>, context?: any): ComponentChildren$1;
   displayName?: string;
   defaultProps?: Partial<P> | undefined;
 }
+/**
+ * @publicDocs
+ */
 export interface ComponentClass<P = {}, S = {}> {
   new (props: P, context?: any): Component<P, S>;
   displayName?: string;
@@ -3780,6 +4014,9 @@ export interface ComponentClass<P = {}, S = {}> {
   ): Partial<S> | null;
   getDerivedStateFromError?(error: any): Partial<S> | null;
 }
+/**
+ * @publicDocs
+ */
 export interface Component<P = {}, S = {}> {
   componentWillMount?(): void;
   componentDidMount?(): void;
@@ -3848,82 +4085,29 @@ declare abstract class Component<P, S> {
 //
 // Context
 // -----------------------------------
+/**
+ * @publicDocs
+ */
 export interface Consumer<T>
   extends FunctionComponent<{
     children: (value: T) => ComponentChildren$1;
   }> {}
+/**
+ * @publicDocs
+ */
 export interface Provider<T>
   extends FunctionComponent<{
     value: T;
     children?: ComponentChildren$1;
   }> {}
+/**
+ * @publicDocs
+ */
 export interface Context<T> extends Provider<T> {
   Consumer: Consumer<T>;
   Provider: Provider<T>;
   displayName?: string;
 }
-export type Styles = string;
-declare const shadowRootSymbol: unique symbol;
-export type RenderImpl = Omit<ShadowRootInit, 'mode'> & {
-  ShadowRoot: (element: any) => ComponentChildren$1;
-  styles?: Styles;
-  /**
-   * Only needed once in the root element, to inject global shadow CSS for all components.
-   */
-  globalShadowCSS?: Styles;
-};
-export interface ActivationEventEsque {
-  shiftKey: boolean;
-  metaKey: boolean;
-  ctrlKey: boolean;
-  button: number;
-}
-export interface ClickOptions {
-  /**
-   * The event you want to influence the synthetic click.
-   */
-  sourceEvent?: ActivationEventEsque;
-}
-declare const BaseClass: typeof globalThis.HTMLElement;
-export declare abstract class PreactCustomElement extends BaseClass {
-  /** @private */
-  static get observedAttributes(): string[];
-  /** @private */
-  [shadowRootSymbol]: ShadowRoot | null;
-  constructor({
-    styles,
-    ShadowRoot: renderFunction,
-    delegatesFocus,
-    globalShadowCSS,
-    ...options
-  }: RenderImpl);
-
-  /** @private */
-  setAttribute(name: string, value: string): void;
-  /** @private */
-  attributeChangedCallback(name: string): void;
-  /** @private */
-  connectedCallback(): void;
-  /** @private */
-  disconnectedCallback(): void;
-  /** @private */
-  adoptedCallback(): void;
-  /**
-   * Queue a run of the render function.
-   * You shouldn't need to call this manually - it should be handled by changes to @property values.
-   * @private
-   */
-  queueRender(): void;
-  /**
-   * Like the standard `element.click()`, but you can influence the behavior with a `sourceEvent`.
-   *
-   * For example, if the `sourceEvent` was a middle click, or has particular keys held down,
-   * components will attempt to produce the desired behavior on links, such as opening the page in the background tab.
-   * @private
-   * @param options
-   */
-  click({sourceEvent}?: ClickOptions): void;
-}
 type IconType$1 =
   | 'adjust'
   | 'affiliate'
@@ -3935,7 +4119,6 @@ type IconType$1 =
   | 'alert-octagon'
   | 'alert-octagon-filled'
   | 'alert-triangle'
-  | 'align-horizontal-centers'
   | 'app-extension'
   | 'apps'
   | 'archive'
@@ -3995,7 +4178,6 @@ type IconType$1 =
   | 'catalog-product'
   | 'categories'
   | 'channels'
-  | 'channels-filled'
   | 'chart-cohort'
   | 'chart-donut'
   | 'chart-funnel'
@@ -4360,7 +4542,6 @@ type IconType$1 =
   | 'sort-ascending'
   | 'sort-descending'
   | 'sound'
-  | 'split'
   | 'sports'
   | 'star'
   | 'star-filled'