@shopify/ui-extensions 2025.10.8 → 2025.10.9

package/src/surfaces/point-of-sale/components/ScrollBox.d.ts

@@ -22,136 +22,133 @@ import type {
 
 export type ComponentChildren = any;
 /**
- * Used when an element does not have children.
+ * The base props for elements without children, providing key, ref, and slot properties.
  */
 export interface BaseElementProps<TClass = HTMLElement> {
+  /**
+   * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation.
+   */
   key?: Key;
+  /**
+   * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations.
+   */
   ref?: Ref<TClass>;
+  /**
+   * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component.
+   */
   slot?: Lowercase<string>;
 }
 /**
- * Used when an element has children.
+ * The base props for elements with children, extending `BaseElementProps` with children support.
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
+  /**
+   * The child elements to render within this component.
+   */
   children?: ComponentChildren;
 }
 export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
 
+/**
+ * Defines the available padding size options using a semantic scale. Provides consistent spacing values that align with the POS design system.
+ */
 export type PaddingKeyword = SizeKeyword | 'none';
 declare const tagName = 's-scroll-box';
 export interface ScrollBoxJSXProps extends Pick<ScrollBoxProps, 'id'> {
   /**
-   * Adjust the block size.
+   * The block size of the scrollable container. Auto automatically sizes based on the container's content and available space.
    *
    * @default 'auto'
    */
   blockSize?: SizeUnitsOrAuto;
   /**
-   * Adjust the inline size.
+   * The inline size of the scrollable container. Auto automatically sizes based on the container's content and available space.
    *
    * @default 'auto'
    */
   inlineSize?: SizeUnitsOrAuto;
   /**
-   * Adjust the maximum block size.
+   * The maximum block size constraint for the scrollable container.
    *
    * @default 'none'
    */
   maxBlockSize?: SizeUnitsOrNone;
   /**
-   * Adjust the maximum inline size.
+   * The maximum inline size constraint for the scrollable container.
    *
    * @default 'none'
    */
   maxInlineSize?: SizeUnitsOrNone;
   /**
-   * Adjust the minimum block size.
+   * The minimum block size constraint for the scrollable container.
    *
    * @default '0'
    */
   minBlockSize?: SizeUnits;
   /**
-   * Adjust the minimum inline size.
+   * The minimum inline size constraint for the scrollable container.
    *
    * @default '0'
    */
   minInlineSize?: SizeUnits;
   /**
-   * 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 scrollable container. Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascade/Shorthand_properties#edges_of_a_box) using flow-relative values in the order:
    *
    * - 4 values: `block-start inline-end block-end inline-start`
    * - 3 values: `block-start inline block-end`
    * - 2 values: `block inline`
    *
    * For example:
+   *
    * - `large` means block-start, inline-end, block-end and inline-start paddings are `large`.
    * - `large none` means block-start and block-end paddings are `large`, inline-start and inline-end paddings are `none`.
    * - `large none large` means block-start padding is `large`, inline-end padding is `none`, block-end padding is `large` and inline-start padding is `none`.
    * - `large none large small` means block-start padding is `large`, inline-end padding is `none`, block-end padding is `large` and inline-start padding is `small`.
    *
-   * A padding value of `auto` will use the default padding for the closest container that has had its usual padding removed.
+   * An `auto` value inherits the default padding from the closest container that has removed its usual padding.
    *
    * @default 'none'
    */
   padding?: MaybeAllValuesShorthandProperty<PaddingKeyword>;
   /**
-   * Adjust the block-padding.
-   *
-   * - `large none` means block-start padding is `large`, block-end padding is `none`.
-   *
-   * This overrides the block value of `padding`.
+   * The block-axis padding for the scrollable container. Overrides the block value of the `padding` property.
    *
    * @default '' - meaning no override
    */
   paddingBlock?: MaybeTwoValuesShorthandProperty<PaddingKeyword> | '';
   /**
-   * Adjust the block-start padding.
-   *
-   * This overrides the block-start value of `paddingBlock`.
+   * The block-start padding for the scrollable container. Overrides the block-start value of the `paddingBlock` property.
    *
    * @default '' - meaning no override
    */
   paddingBlockStart?: PaddingKeyword | '';
   /**
-   * Adjust the block-end padding.
-   *
-   * This overrides the block-end value of `paddingBlock`.
+   * The block-end padding for the scrollable container. Overrides the block-end value of the `paddingBlock` property.
    *
    * @default '' - meaning no override
    */
   paddingBlockEnd?: PaddingKeyword | '';
   /**
-   * Adjust the inline padding.
-   *
-   * - `large none` means inline-start padding is `large`, inline-end padding is `none`.
-   *
-   * This overrides the inline value of `padding`.
+   * The inline-axis padding for the scrollable container. Supports two-value syntax where `large none` sets inline-start to `large` and inline-end to `none`. Overrides the inline value of the `padding` property.
    *
    * @default '' - meaning no override
    */
   paddingInline?: MaybeTwoValuesShorthandProperty<PaddingKeyword> | '';
   /**
-   * Adjust the inline-start padding.
-   *
-   * This overrides the inline-start value of `paddingInline`.
+   * The inline-start padding for the scrollable container. Overrides the inline-start value of the `paddingInline` property.
    *
    * @default '' - meaning no override
    */
   paddingInlineStart?: PaddingKeyword | '';
   /**
-   * Adjust the inline-end padding.
-   *
-   * This overrides the inline-end value of `paddingInline`.
+   * The inline-end padding for the scrollable container. Overrides the inline-end value of the `paddingInline` property.
    *
    * @default '' - meaning no override
    */
   paddingInlineEnd?: PaddingKeyword | '';
   /**
-   * The content of the ScrollBox.
+   * The child elements to render within this component.
    */
   children?: ComponentChildren;
 }

package/src/surfaces/point-of-sale/components/SearchField.d.ts

@@ -12,28 +12,64 @@ import type {SearchFieldProps, Key, Ref} from './components-shared.d.ts';
 
 export type ComponentChildren = any;
 /**
- * Used when an element does not have children.
+ * The base props for elements without children, providing key, ref, and slot properties.
  */
 export interface BaseElementProps<TClass = HTMLElement> {
+  /**
+   * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation.
+   */
   key?: Key;
+  /**
+   * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations.
+   */
   ref?: Ref<TClass>;
+  /**
+   * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component.
+   */
   slot?: Lowercase<string>;
 }
 /**
- * Used when an element has children.
+ * The base props for elements with children, extending `BaseElementProps` with children support.
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
+  /**
+   * The child elements to render within this component.
+   */
   children?: ComponentChildren;
 }
 export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
+/**
+ * Represents the event object passed to callback functions when interactive events occur. Contains metadata about the event, including the target element, event phase, and propagation behavior.
+ */
 export interface CallbackEvent<T extends keyof HTMLElementTagNameMap> {
+  /**
+   * The element that the event listener is attached to.
+   */
   currentTarget: HTMLElementTagNameMap[T];
+  /**
+   * Whether the event bubbles up through the DOM tree.
+   */
   bubbles?: boolean;
+  /**
+   * Whether the event can be canceled.
+   */
   cancelable?: boolean;
+  /**
+   * Whether the event will trigger listeners outside of a shadow root.
+   */
   composed?: boolean;
+  /**
+   * The additional data associated with the event.
+   */
   detail?: any;
+  /**
+   * The current phase of the event flow.
+   */
   eventPhase: number;
+  /**
+   * The element that triggered the event.
+   */
   target: HTMLElementTagNameMap[T] | null;
 }
 
@@ -41,19 +77,19 @@ declare const tagName = 's-search-field';
 export interface SearchFieldJSXProps
   extends Pick<SearchFieldProps, 'id' | 'disabled' | 'placeholder' | 'value'> {
   /**
-   * Callback when the user changes the value in the field.
+   * Called when the user changes the value in the field.
    */
   onInput?: ((event: CallbackEvent<typeof tagName>) => void) | null;
   /**
-   * Callback when the field loses focus after the user changes the value in the field.
+   * Called when the field loses focus after the user changes the value in the field.
    */
   onChange?: ((event: CallbackEvent<typeof tagName>) => void) | null;
   /**
-   * Callback when the field loses focus.
+   * Called when the field loses focus.
    */
   onBlur?: ((event: CallbackEvent<typeof tagName>) => void) | null;
   /**
-   * Callback when the field is focused.
+   * Called when the field is focused.
    */
   onFocus?: ((event: CallbackEvent<typeof tagName>) => void) | null;
 }

package/src/surfaces/point-of-sale/components/Section.d.ts

@@ -17,18 +17,30 @@ import type {
 
 export type ComponentChildren = any;
 /**
- * Used when an element does not have children.
+ * The base props for elements without children, providing key, ref, and slot properties.
  */
 export interface BaseElementProps<TClass = HTMLElement> {
+  /**
+   * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation.
+   */
   key?: Key;
+  /**
+   * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations.
+   */
   ref?: Ref<TClass>;
+  /**
+   * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component.
+   */
   slot?: Lowercase<string>;
 }
 /**
- * Used when an element has children.
+ * The base props for elements with children, extending `BaseElementProps` with children support.
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
+  /**
+   * The child elements to render within this component.
+   */
   children?: ComponentChildren;
 }
 export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
@@ -36,17 +48,15 @@ export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
 declare const tagName = 's-section';
 export interface SectionJSXProps extends Pick<SectionProps, 'id'> {
   /**
-   * A title that describes the content of the section.
-   *
-   * If omitted, and no secondaryActions are provided, the section will be rendered without a header.
+   * A title that describes the content of the section. If omitted and no secondary actions are provided, the section will be rendered without a header.
    */
   heading?: string;
   /**
-   * Button element to display in the section heading. A single button is supported.
+   * A button element to display in the section heading. Only a single button is supported. Use the `slot="secondary-actions"` attribute to place action elements that relate to the entire section's content.
    */
   secondaryActions?: ComponentChild;
   /**
-   * The content of the Section.
+   * The child elements to render within this component.
    */
   children?: ComponentChildren;
 }

package/src/surfaces/point-of-sale/components/Stack.d.ts

@@ -26,23 +26,38 @@ import type {
 
 export type ComponentChildren = any;
 /**
- * Used when an element does not have children.
+ * The base props for elements without children, providing key, ref, and slot properties.
  */
 export interface BaseElementProps<TClass = HTMLElement> {
+  /**
+   * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation.
+   */
   key?: Key;
+  /**
+   * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations.
+   */
   ref?: Ref<TClass>;
+  /**
+   * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component.
+   */
   slot?: Lowercase<string>;
 }
 /**
- * Used when an element has children.
+ * The base props for elements with children, extending `BaseElementProps` with children support.
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
+  /**
+   * The child elements to render within this component.
+   */
   children?: ComponentChildren;
 }
 export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
 
 declare const tagName = 's-stack';
+/**
+ * Defines the available padding size options using a semantic scale. Provides consistent spacing values that align with the POS design system.
+ */
 export type PaddingKeyword = SizeKeyword | 'none';
 export type PickedProps = Pick<
   StackProps,
@@ -63,173 +78,144 @@ export type PickedProps = Pick<
 >;
 export interface StackJSXProps extends PickedProps {
   /**
-   * 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 container. Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascade/Shorthand_properties#edges_of_a_box) using flow-relative values in the order:
    *
    * - 4 values: `block-start inline-end block-end inline-start`
    * - 3 values: `block-start inline block-end`
    * - 2 values: `block inline`
    *
    * For example:
+   *
    * - `large` means block-start, inline-end, block-end and inline-start paddings are `large`.
    * - `large none` means block-start and block-end paddings are `large`, inline-start and inline-end paddings are `none`.
    * - `large none large` means block-start padding is `large`, inline-end padding is `none`, block-end padding is `large` and inline-start padding is `none`.
    * - `large none large small` means block-start padding is `large`, inline-end padding is `none`, block-end padding is `large` and inline-start padding is `small`.
    *
-   * A padding value of `auto` will use the default padding for the closest container that has had its usual padding removed.
+   * An `auto` value inherits the default padding from the closest container that has removed its usual padding.
    *
    * @default 'none'
    */
   padding?: MaybeAllValuesShorthandProperty<PaddingKeyword>;
   /**
-   * Adjust the block-padding.
-   *
-   * - `large none` means block-start padding is `large`, block-end padding is `none`.
-   *
-   * This overrides the block value of `padding`.
+   * The block-axis padding for the container. Overrides the block value of the `padding` property.
    *
    * @default '' - meaning no override
    */
   paddingBlock?: MaybeTwoValuesShorthandProperty<PaddingKeyword | ''>;
   /**
-   * Adjust the block-start padding.
-   *
-   * This overrides the block-start value of `paddingBlock`.
+   * The block-start padding for the container. Overrides the block-start value of the `paddingBlock` property.
    *
    * @default '' - meaning no override
    */
   paddingBlockStart?: PaddingKeyword | '';
   /**
-   * Adjust the block-end padding.
-   *
-   * This overrides the block-end value of `paddingBlock`.
+   * The block-end padding for the container. Overrides the block-end value of the `paddingBlock` property.
    *
    * @default '' - meaning no override
    */
   paddingBlockEnd?: PaddingKeyword | '';
   /**
-   * Adjust the inline padding.
-   *
-   * - `large none` means inline-start padding is `large`, inline-end padding is `none`.
-   *
-   * This overrides the inline value of `padding`.
+   * The inline-axis padding for the container. Supports two-value syntax where `large none` sets inline-start to `large` and inline-end to `none`. Overrides the inline value of the `padding` property.
    *
    * @default '' - meaning no override
    */
   paddingInline?: MaybeTwoValuesShorthandProperty<PaddingKeyword | ''>;
   /**
-   * Adjust the inline-start padding.
-   *
-   * This overrides the inline-start value of `paddingInline`.
+   * The inline-start padding for the container. Overrides the inline-start value of the `paddingInline` property.
    *
    * @default '' - meaning no override
    */
   paddingInlineStart?: PaddingKeyword | '';
   /**
-   * Adjust the inline-end padding.
-   *
+   * The inline-end padding for the container.
    * This overrides the inline-end value of `paddingInline`.
    *
    * @default '' - meaning no override
    */
   paddingInlineEnd?: PaddingKeyword | '';
   /**
-   * Adjust the block size.
-   * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/block-size
+   * The block size of the `Stack` component. On mobile surfaces, avoid using percentage-based sizes as they don't behave as expected when placed within a scrollable container.
    *
+   * Learn more about [block-size on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/block-size).
    * @default 'auto'
    */
   blockSize?: SizeUnitsOrAuto;
   /**
-   * Adjust the maximum block size.
-   * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size
+   * The maximum block size constraint for the `Stack` component. On mobile surfaces, avoid using percentage-based sizes as they don't behave as expected when placed within a scrollable container.
    *
+   * Learn more about [max-block-size on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size).
    * @default 'none'
    */
   maxBlockSize?: SizeUnitsOrNone;
   /**
-   * Adjust the maximum inline size.
-   * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size
+   * The maximum inline size constraint for the `Stack` component. On mobile surfaces, avoid using percentage-based sizes as they don't behave as expected when placed within a scrollable container.
    *
+   * Learn more about [max-inline-size on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size).
    * @default 'none'
    */
   maxInlineSize?: SizeUnitsOrNone;
   /**
-   * Adjust the minimum block size.
-   * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size
+   * The minimum block size constraint for the `Stack` component. On mobile surfaces, avoid using percentage-based sizes as they don't behave as expected when placed within a scrollable container.
    *
+   * Learn more about [min-block-size on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size).
    * @default '0'
    */
   minBlockSize?: SizeUnits;
   /**
-   * Adjust the minimum inline size.
-   * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size
+   * The minimum inline size constraint for the `Stack` component. On mobile surfaces, avoid using percentage-based sizes as they don't behave as expected when placed within a scrollable container.
    *
+   * Learn more about [min-inline-size on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size).
    * @default '0'
    */
   minInlineSize?: SizeUnits;
   /**
-   * Aligns the Stack's children along the cross axis.
+   * The alignment of the `Stack` component's children along the cross axis.
    */
   alignItems?: AlignItemsKeyword;
   /**
-   * Aligns the Stack along the cross axis.
+   * The alignment of the `Stack` component along the cross axis.
    */
   alignContent?: AlignContentKeyword;
   /**
-   * Adjust spacing between elements.
-   * A single value applies to both axes. A pair of values (eg large-100 large-500) can be used to set the inline and block axes respectively.
+   * The spacing between 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.
    *
    * @default 'none'
    */
   gap?: MaybeTwoValuesShorthandProperty<SpacingKeyword>;
   /**
-   * Adjust spacing between elements in the inline axis. This overrides the column value of gap.
+   * The spacing between elements in the inline axis. This overrides the column value of gap.
    *
    * @default '' - meaning no override
    */
   columnGap?: SpacingKeyword | '';
   /**
-   * Sets how the children are placed within the Stack. This uses logical properties.
+   * The direction in which children are placed within the `Stack` component using logical properties. Use `'block'` for vertical arrangement where children are placed along the block axis (typically top to bottom) without wrapping. Use `'inline'` for horizontal arrangement where children are placed along the inline axis (typically left to right) with automatic wrapping when space is insufficient.
    *
    * @default 'block'
-   * @implementation - the content will wrap if the direction is 'inline', and not wrap if the direction is 'block'
    */
   direction?: 'block' | 'inline';
   /**
-   * Adjust the inline size.
-   * @see — https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size
+   * The inline size of the `Stack` component.
    *
+   * Learn more about [inline-size on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size).
    * @default 'auto'
    */
   inlineSize?: SizeUnitsOrAuto;
   /**
-   * Aligns the Stack along the main axis.
-   * @see — https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content
+   * The alignment of the `Stack` component along the main axis.
    *
+   * Learn more about [justify-content on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content).
    * @default 'normal'
    */
   justifyContent?: JustifyContentKeyword;
   /**
-   * Adjust spacing between elements in the block axis. This overrides the row value of gap.
+   * The spacing between elements in the block axis. This overrides the row value of gap.
    *
    * @default '' - meaning no override
    */
   rowGap?: SpacingKeyword | '';
   /**
-   * The content of the Stack.
+   * The child elements to render within this component.
    */
   children?: ComponentChildren;
 }

package/src/surfaces/point-of-sale/components/Text.d.ts

@@ -12,18 +12,30 @@ import type {TextProps, Key, Ref} from './components-shared.d.ts';
 
 export type ComponentChildren = any;
 /**
- * Used when an element does not have children.
+ * The base props for elements without children, providing key, ref, and slot properties.
  */
 export interface BaseElementProps<TClass = HTMLElement> {
+  /**
+   * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation.
+   */
   key?: Key;
+  /**
+   * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations.
+   */
   ref?: Ref<TClass>;
+  /**
+   * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component.
+   */
   slot?: Lowercase<string>;
 }
 /**
- * Used when an element has children.
+ * The base props for elements with children, extending `BaseElementProps` with children support.
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
+  /**
+   * The child elements to render within this component.
+   */
   children?: ComponentChildren;
 }
 export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
@@ -31,21 +43,31 @@ export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
 declare const tagName = 's-text';
 export interface TextJSXProps extends Pick<TextProps, 'id'> {
   /**
-   * Modify the color to be more or less intense.
+   * The color intensity of the text. Controls how prominent or subtle the text appears within the interface.
    *
    * @default 'base'
    */
   color?: Extract<TextProps['color'], 'base' | 'strong' | 'subdued'>;
   /**
-   * Provide semantic meaning and default styling to the text.
+   * The semantic meaning and default styling of the text. Other presentation properties override the default styling provided by the type. Available options:
    *
-   * Other presentation properties on Text override the default styling.
+   * - `'generic'` - The default text type for general content without specific semantic meaning or emphasis.
+   * - `'strong'` - A text type that provides emphasis and importance, typically rendered with increased font weight or visual prominence.
+   * - `'small'` - A text type for secondary or supplementary content, typically rendered with reduced size for captions, fine print, or less important information.
    *
    * @default 'generic'
    */
   type?: Extract<TextProps['type'], 'generic' | 'strong' | 'small'>;
   /**
-   * Sets the tone of the component, based on the intention of the information being conveyed.
+   * Determines the visual appearance and semantic meaning of the text. Available options:
+   *
+   * - `'auto'` - Lets the system automatically choose the appropriate tone based on context. Use when you want the system to determine the most appropriate styling.
+   * - `'neutral'` - Gray styling for general status information that doesn't require emphasis. Use for general status updates and standard information.
+   * - `'info'` - Blue styling for informational content and neutral updates. Use for informational content that provides helpful context.
+   * - `'success'` - Green styling for positive states, completed actions, and successful operations. Use for positive outcomes and successful processes.
+   * - `'caution'` - Yellow styling for situations that need attention but aren't urgent. Use for potential issues that require awareness.
+   * - `'warning'` - Orange styling for important notices that require merchant awareness. Use for situations that need attention but aren't critical.
+   * - `'critical'` - Red styling for errors, failures, and urgent issues requiring immediate action. Use for urgent issues that need immediate merchant attention.
    *
    * @default 'auto'
    */