Update Typography and Content component descriptions (2026-04-rc)

packages/ui-extensions/src/surfaces/checkout/components/Abbreviation.d.ts

@@ -27,7 +27,7 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
 
 declare const tagName = "s-abbreviation";
 /**
- * The element props interface for the Abbreviation component.
+ * Configure the following properties on the abbreviation component.
  * @publicDocs
  */
 export interface AbbreviationElementProps extends Pick<AbbreviationProps$1, 'title' | 'id'> {

packages/ui-extensions/src/surfaces/checkout/components/Chip.d.ts

@@ -27,20 +27,18 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
 
 declare const tagName = "s-chip";
 /**
- * The element props interface for the Chip component.
+ * Configure the following properties on the chip component.
  * @publicDocs
  */
 export interface ChipElementProps extends Pick<ChipProps$1, 'accessibilityLabel' | 'id'> {
 }
 /**
- * The slots interface for the Chip component.
+ * The chip component supports slots for additional content placement within the component. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots).
  * @publicDocs
  */
 export interface ChipElementSlots {
     /**
-     * The graphic to display inside of the chip.
-     *
-     * Only `s-icon` element and its `type` attribute are supported.
+     * An optional graphic displayed at the start of the chip, such as an icon to visually reinforce the chip's label. Only the `s-icon` element and its `type` attribute are supported.
      */
     graphic?: HTMLElement;
 }

packages/ui-extensions/src/surfaces/checkout/components/ClickableChip.d.ts

@@ -67,14 +67,12 @@ export interface ClickableChipElementEvents {
     remove?: CallbackEventListener<typeof tagName>;
 }
 /**
- * The clickable chip component supports slots for additional content placement. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots).
+ * The clickable chip component supports slots for additional content placement within the component. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots).
  * @publicDocs
  */
 export interface ClickableChipElementSlots {
     /**
-     * The graphic to display inside of the chip.
-     *
-     * Only `s-icon` element and its `type` attribute are supported.
+     * An optional graphic displayed at the start of the chip, such as an icon to visually reinforce the chip's label. Only the `s-icon` element and its `type` attribute are supported.
      */
     graphic?: HTMLElement;
 }

packages/ui-extensions/src/surfaces/checkout/components/Details.d.ts

@@ -44,41 +44,38 @@ export interface ToggleArgumentsEvent {
 
 declare const tagName = "s-details";
 /**
- * The element props interface for the Details component.
+ * Configure the following properties on the details component.
  * @publicDocs
  */
 export interface DetailsElementProps extends Pick<DetailsProps$1, 'defaultOpen' | 'id' | 'open' | 'toggleTransition'> {
 }
 export interface DetailsEvents extends Pick<DetailsProps$1, 'onToggle' | 'onAfterToggle'> {
 }
 /**
- * The events interface for the Details component.
+ * The details component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events).
  * @publicDocs
  */
 export interface DetailsElementEvents {
     /**
-     * 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), the [newState property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState), and the [oldState property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState).
      */
     toggle?: CallbackEventListener<typeof tagName, ToggleArgumentsEvent>;
     /**
-     * Callback fired when the element state changes **after** any animations have finished.
+     * A callback fired when the element state changes, after any toggle animations have finished.
      *
      * - If the element transitioned from hidden to showing, the `oldState` property will be set to `closed` and the
      *   `newState` property will be set to `open`.
      * - If the element transitioned from showing to hidden, the `oldState` property will be set to `open` and the
      *   `newState` will be `closed`.
      *
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState
+     * Learn more about the [newState property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState) and [oldState property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState).
      */
     aftertoggle?: CallbackEventListener<typeof tagName, ToggleArgumentsEvent>;
 }

packages/ui-extensions/src/surfaces/checkout/components/Heading.d.ts

@@ -27,7 +27,7 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
 
 declare const tagName = "s-heading";
 /**
- * The element props interface for the Heading component.
+ * Configure the following properties on the heading component.
  * @publicDocs
  */
 export interface HeadingElementProps extends Pick<HeadingProps$1, 'accessibilityRole' | 'id'> {

packages/ui-extensions/src/surfaces/checkout/components/ListItem.d.ts

@@ -27,7 +27,7 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
 
 declare const tagName = "s-list-item";
 /**
- * The element props interface for the ListItem component.
+ * Configure the following properties on the list item component.
  * @publicDocs
  */
 export interface ListItemElementProps extends Pick<ListItemProps$1, 'id'> {

packages/ui-extensions/src/surfaces/checkout/components/OrderedList.d.ts

@@ -27,7 +27,7 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
 
 declare const tagName = "s-ordered-list";
 /**
- * The element props interface for the OrderedList component.
+ * Configure the following properties on the ordered list component.
  * @publicDocs
  */
 export interface OrderedListElementProps extends OrderedListProps$1 {

packages/ui-extensions/src/surfaces/checkout/components/Paragraph.d.ts

@@ -27,12 +27,23 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
 
 declare const tagName = "s-paragraph";
 /**
- * The element props interface for the Paragraph component.
+ * Configure the following properties on the paragraph component.
  * @publicDocs
  */
 export interface ParagraphElementProps extends Pick<ParagraphProps$1, 'accessibilityVisibility' | 'color' | 'dir' | 'id' | 'lang' | 'tone' | 'type'> {
     color?: Extract<ParagraphProps$1['color'], 'subdued' | 'base'>;
     tone?: Extract<ParagraphProps$1['tone'], 'auto' | 'info' | 'success' | 'warning' | 'critical' | 'neutral' | 'custom'>;
+    /**
+     * The semantic type and styling treatment for the paragraph content.
+     *
+     * Other presentation properties on `s-paragraph` override the default styling.
+     *
+     * - `paragraph`: A semantic type that indicates the text is a structural grouping of related content.
+     * - `small`: A semantic type that indicates the text is considered less important than the main content, but is still necessary for the reader to understand.
+     *
+     * @default 'paragraph'
+     */
+    type?: Extract<ParagraphProps$1['type'], 'paragraph' | 'small'>;
 }
 export interface ParagraphElement extends ParagraphElementProps, Omit<HTMLElement, 'id' | 'dir' | 'lang'> {
 }

packages/ui-extensions/src/surfaces/checkout/components/SkeletonParagraph.d.ts

@@ -21,7 +21,7 @@ export interface BaseElementProps<TClass = HTMLElement> {
 
 declare const tagName = "s-skeleton-paragraph";
 /**
- * The element props interface for the SkeletonParagraph component.
+ * Configure the following properties on the skeleton paragraph component.
  * @publicDocs
  */
 export interface SkeletonParagraphElementProps extends SkeletonParagraphProps$1 {

packages/ui-extensions/src/surfaces/checkout/components/Summary.d.ts

@@ -12,7 +12,7 @@ import type {SummaryProps$1} from './components-shared.d.ts';
 
 declare const tagName = "s-summary";
 /**
- * The element props interface for the Summary component.
+ * Configure the following properties on the summary component.
  * @publicDocs
  */
 export interface SummaryElementProps extends Pick<SummaryProps$1, 'id'> {

packages/ui-extensions/src/surfaces/checkout/components/Text.d.ts

@@ -27,12 +27,28 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
 
 declare const tagName = "s-text";
 /**
- * The element props interface for the Text component.
+ * Configure the following properties on the text component.
  * @publicDocs
  */
 export interface TextElementProps extends Pick<TextProps$1, 'accessibilityVisibility' | 'color' | 'dir' | 'display' | 'id' | 'lang' | 'tone' | 'type'> {
     color?: Extract<TextProps$1['color'], 'subdued' | 'base'>;
     tone?: Extract<TextProps$1['tone'], 'auto' | 'neutral' | 'info' | 'success' | 'warning' | 'critical' | 'custom'>;
+    /**
+     * The semantic type and styling treatment for the text content.
+     *
+     * Other presentation properties on text override the default styling.
+     *
+     * - `address`: A semantic type that indicates the text is contact information. Typically used for addresses.
+     * - `redundant`: A semantic type that indicates the text is no longer accurate or no longer relevant. One such use-case is discounted prices.
+     * - `mark`: A semantic type that indicates the text is marked or highlighted and relevant to the user's current action.
+     * - `emphasis`: A semantic type that indicates emphatic stress. Typically for words that have a stressed emphasis compared to surrounding text.
+     * - `offset`: A semantic type that indicates an offset from the normal prose of the text.
+     * - `small`: A semantic type that indicates the text is considered less important than the main content, but is still necessary for the reader to understand.
+     * - `strong`: A semantic type that indicates strong importance, seriousness, or urgency.
+     * - `generic`: No additional semantics or styling is applied.
+     *
+     * @default 'generic'
+     */
     type?: Extract<TextProps$1['type'], 'address' | 'redundant' | 'mark' | 'emphasis' | 'offset' | 'small' | 'strong' | 'generic'>;
 }
 export interface TextElement extends TextElementProps, Omit<HTMLElement, 'id' | 'dir' | 'lang'> {

packages/ui-extensions/src/surfaces/checkout/components/Time.d.ts

@@ -27,7 +27,7 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
 
 declare const tagName = "s-time";
 /**
- * The element props interface for the Time component.
+ * Configure the following properties on the time component.
  * @publicDocs
  */
 export interface TimeElementProps extends Pick<TimeProps$1, 'dateTime' | 'id'> {

packages/ui-extensions/src/surfaces/checkout/components/UnorderedList.d.ts

@@ -27,7 +27,7 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
 
 declare const tagName = "s-unordered-list";
 /**
- * The element props interface for the UnorderedList component.
+ * Configure the following properties on the unordered list component.
  * @publicDocs
  */
 export interface UnorderedListElementProps extends UnorderedListProps$1 {