Merge pull request #4287 from Shopify/typography-web-components-2025-07

sordaz00 · web-flow · commit 2c9a6e741685 · 2026-04-14T18:58:49.000-05:00
Update Typography and Content component descriptions (2025-07)
diff --git a/packages/ui-extensions/src/surfaces/checkout/components/Badge/Badge.ts b/packages/ui-extensions/src/surfaces/checkout/components/Badge/Badge.ts
@@ -7,8 +7,8 @@ import type {IconSource} from '../Icon/Icon';
  * The available tone values for the badge.
  *
  * - `default`: General information without specific intent.
- * - `subdued`: Reduced visual emphasis for less prominent badges.
  * - `critical`: Urgent problems or destructive actions requiring immediate attention.
+ * - `subdued`: Reduced visual emphasis for less prominent badges.
  */
 type Tone = 'default' | 'critical' | 'subdued';
 
diff --git a/packages/ui-extensions/src/surfaces/checkout/components/Chat/AppBridge.ts b/packages/ui-extensions/src/surfaces/checkout/components/Chat/AppBridge.ts
@@ -25,10 +25,7 @@ interface AppBridge {
   /**
    * The ID token providing a set of claims as a signed [JSON Web Token (JWT)](https://openid.net/specs/openid-connect-core-1_0.html#IDToken%5C)
    * with a TTL of 5 minutes. It can be used to ensure that requests came from a Shopify authenticated user.
-   * See the [ID Token documentation](https://shopify.dev/docs/apps/build/authentication-authorization/session-tokens) for more information.
-   *
-   * @see https://shopify.dev/docs/api/checkout-ui-extensions/latest/apis/session-token
-   * @see https://shopify.dev/docs/apps/build/authentication-authorization/session-tokens
+   * See the [ID Token documentation](https://shopify.dev/docs/apps/build/authentication-authorization/session-tokens) and the [session token API](https://shopify.dev/docs/api/checkout-ui-extensions/latest/apis/session-token) for more information.
    */
   idToken?: () => Promise<string>;
 
diff --git a/packages/ui-extensions/src/surfaces/checkout/components/Disclosure/Disclosure.ts b/packages/ui-extensions/src/surfaces/checkout/components/Disclosure/Disclosure.ts
@@ -4,9 +4,7 @@ import type {MaybeResponsiveConditionalStyle} from '../../style/types';
 import type {DisclosureOpen} from '../shared';
 
 /**
- * Disclosure is an optionally controlled component used to put long sections of information under content blocks that users can expand or collapse by pressing an activator. The activator can be specified as children using an action component (`Button`, `Link` or `Pressable`) or a form control (`Checkbox` or `Switch`) component. The content blocks can be specified as children inside a structure component (`View`, `InlineLayout`, `BlockStack`, `Grid`, etc.).
-
-The library automatically applies the [WAI-ARIA Accordion pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/) to both the activator and the toggled content.
+ * Configure the following properties on the disclosure component.
  * @publicDocs
  */
 export interface DisclosureProps {
@@ -27,7 +25,7 @@ export interface DisclosureProps {
    */
   open?: DisclosureOpen;
   /**
-   * Callback fired when the open state of the disclosure changes.
+   * A callback fired when the open state of the disclosure changes.
    */
   onToggle?(open: string[]): void;
   /**
diff --git a/packages/ui-extensions/src/surfaces/checkout/components/DropZone/DropZone.ts b/packages/ui-extensions/src/surfaces/checkout/components/DropZone/DropZone.ts
@@ -44,7 +44,7 @@ export interface DropZoneProps extends IdProps {
    *
    * If left empty, the dropzone will accept all files.
    *
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept
+   * Learn more about the [`accept`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept) attribute.
    */
   accept?: string;
 
@@ -64,7 +64,8 @@ export interface DropZoneProps extends IdProps {
 
   /**
    * A callback fired when files are dropped or selected.
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/drop_event
+   *
+   * Learn more about the [`drop`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/drop_event) event.
    */
   onInput?(files: File[]): void;
 
diff --git a/packages/ui-extensions/src/surfaces/checkout/components/Heading/Heading.ts b/packages/ui-extensions/src/surfaces/checkout/components/Heading/Heading.ts
@@ -5,34 +5,32 @@ import type {InlineAlignment, AccessibilityRole} from '../shared';
 type Level = 1 | 2 | 3 | 4;
 
 /**
- * Headings control the visual style of headings. Use headings to introduce major sections, like Contact information, Shipping address, or Shipping method.
-
-Unlike HTML headings, you don’t explicitly specify the position of the heading in the document outline. Nest headings within the heading group component to control the document outline structure used by assistive technologies.
+ * Configure the following properties on the heading component.
  * @publicDocs
  */
 export interface HeadingProps {
   /**
-   * Unique identifier.
+   * A unique identifier for the component.
    * Typically used to make the heading a target that another component
    * can refer to in order to provide an alternative accessibility label.
    */
   id?: string;
   /**
    * The visual level of the heading. When not set, the heading will use
-   * its “automatic” heading level, which is determined by the level of nesting
+   * its "automatic" heading level, which is determined by the level of nesting
    * within ancestor `HeadingGroup`s. No matter what value you provide here,
    * the semantic level (e.g., how the heading contributes to the document outline)
-   * is determined exclusively by the “automatic” heading level.
+   * is determined exclusively by the "automatic" heading level.
    */
   level?: Level;
   /**
-   * Sets the semantic meaning of the component’s content. When set,
-   * the role will be used by assistive technologies to help buyers
-   * navigate the page.
+   * Sets the semantic meaning of the heading for assistive technologies. When set, the role overrides the default heading semantics.
+   *
+   * - `presentation`: Strips the heading level, preventing the element's implicit ARIA semantics from being exposed to the accessibility tree.
    */
   accessibilityRole?: Extract<AccessibilityRole, 'presentation'>;
   /**
-   * Align text along the main axis.
+   * Aligns the heading text along the inline axis (horizontal in standard writing modes).
    */
   inlineAlignment?: InlineAlignment;
 }
@@ -41,7 +39,7 @@ export interface HeadingProps {
  * Headings control the visual style of headings. Use headings to introduce major
  * sections, like Contact information, Shipping address, or Shipping method.
  *
- * Unlike HTML headings, you don’t explicitly specify the position of the heading in the
+ * Unlike HTML headings, you don't explicitly specify the position of the heading in the
  * document outline. Nest headings within the heading group component to control
  * the document outline structure used by assistive technologies.
  */
diff --git a/packages/ui-extensions/src/surfaces/checkout/components/HeadingGroup/HeadingGroup.ts b/packages/ui-extensions/src/surfaces/checkout/components/HeadingGroup/HeadingGroup.ts
@@ -1,9 +1,7 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
 /**
- * Heading group controls the heading level of headings nested within it, like H1, H2, H3.
-
-Use a heading group whenever you use a heading to ensure the experience is the same for screen reader users. When using a heading, any children related to that heading should be nested within the same heading group.
+ * Configure the following properties on the heading group component.
  * @publicDocs
  */
 export interface HeadingGroupProps {}
diff --git a/packages/ui-extensions/src/surfaces/checkout/components/Icon/Icon.ts b/packages/ui-extensions/src/surfaces/checkout/components/Icon/Icon.ts
@@ -102,8 +102,8 @@ export interface IconProps extends IdProps {
    *
    * - `extraSmall`: The smallest available icon size.
    * - `small`: A compact icon size, smaller than the default.
-   * - `large`: A larger icon for increased visual prominence.
    * - `base`: Renders the icon at its standard size.
+   * - `large`: A larger icon for increased visual prominence.
    * - `fill`: Stretches the icon to fill the available space in its
    *   container while preserving its aspect ratio.
    *
diff --git a/packages/ui-extensions/src/surfaces/checkout/components/List/List.ts b/packages/ui-extensions/src/surfaces/checkout/components/List/List.ts
@@ -6,26 +6,28 @@ import type {MaybeResponsiveConditionalStyle} from '../../style/types';
 export type Marker = 'none' | 'bullet' | 'number';
 
 /**
- * Lists display a set of related content. Each list item usually begins with a bullet or a number.
+ * Configure the following properties on the list component.
  * @publicDocs
  */
 export interface ListProps extends IdProps {
   /**
-   * Adjust spacing between list items
+   * Adjusts the vertical spacing between list items. Use a design system spacing keyword to control the density of the list.
    *
    * @defaultValue 'base'
    */
   spacing?: MaybeResponsiveConditionalStyle<Spacing>;
   /**
-   * Type of marker to display
+   * The type of marker displayed before each list item.
+   *
+   * - `none`: No marker is displayed.
+   * - `bullet`: A bullet point marker for unordered lists.
+   * - `number`: A number marker for ordered lists.
    *
    * @defaultValue 'bullet'
    */
   marker?: Marker;
   /**
-   * A label that describes the purpose or contents of the list. When set,
-   * it will be announced to buyers using assistive technologies and will
-   * provide them with more context.
+   * A label that describes the purpose or contents of the list. When set, it will be announced to users of assistive technologies such as screen readers to provide additional context.
    */
   accessibilityLabel?: string;
 }
diff --git a/packages/ui-extensions/src/surfaces/checkout/components/ListItem/ListItem.ts b/packages/ui-extensions/src/surfaces/checkout/components/ListItem/ListItem.ts
@@ -3,17 +3,15 @@ import {createRemoteComponent} from '@remote-ui/core';
 import type {IdProps} from '../shared';
 
 /**
- * List items are used as children of the `List` component.
-
-They usually begins with a bullet or a number.
+ * Configure the following properties on the list item component.
  * @publicDocs
  */
 export interface ListItemProps extends IdProps {}
 
 /**
  * List items are used as children of the `List` component.
  *
- * They usually begins with a bullet or a number.
+ * They usually begin with a bullet or a number.
  */
 export const ListItem = createRemoteComponent<'ListItem', ListItemProps>(
   'ListItem',
diff --git a/packages/ui-extensions/src/surfaces/checkout/components/ProductThumbnail/ProductThumbnail.ts b/packages/ui-extensions/src/surfaces/checkout/components/ProductThumbnail/ProductThumbnail.ts
@@ -17,9 +17,7 @@ export interface ProductThumbnailProps {
    * with the HTML specification. When both are specified,
    * `accessibilityLabel` takes precedence.
    *
-   * Learn more about [writing effective alternative text](https://ux.shopify.com/considerations-when-writing-alt-text-a9c1985a8204).
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt
+   * Learn more about [writing effective alternative text](https://ux.shopify.com/considerations-when-writing-alt-text-a9c1985a8204) and the [`alt`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt) attribute.
    */
   alt?: string;
 
@@ -32,10 +30,9 @@ export interface ProductThumbnailProps {
    * HTML specification. When both are specified, `accessibilityLabel`
    * takes precedence.
    *
-   * Learn more about [writing effective alternative text](https://ux.shopify.com/considerations-when-writing-alt-text-a9c1985a8204).
+   * Learn more about [writing effective alternative text](https://ux.shopify.com/considerations-when-writing-alt-text-a9c1985a8204) and the [`alt`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt) attribute.
    *
    * @defaultValue `''`
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt
    */
   accessibilityLabel?: string;
 
@@ -45,7 +42,7 @@ export interface ProductThumbnailProps {
    * A `src` property is available as an alias for this for compatibility with the HTML
    * specification. When both are specified, `source` takes precedence.
    *
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#src
+   * Learn more about the [`src`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#src) attribute.
    */
   source?: MaybeConditionalStyle<string, ResolutionCondition>;
 
@@ -55,7 +52,7 @@ export interface ProductThumbnailProps {
    * This property is available as an alias for `source` for compatibility with the HTML
    * specification. When both are specified, `source` takes precedence.
    *
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#src
+   * Learn more about the [`src`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#src) attribute.
    */
   src?: MaybeConditionalStyle<string, ResolutionCondition>;
 
@@ -68,8 +65,8 @@ export interface ProductThumbnailProps {
   /**
    * The size of the product thumbnail image.
    *
-   * - `small`: A compact thumbnail for tighter layouts.
    * - `base`: Renders the thumbnail at its standard size.
+   * - `small`: A compact thumbnail for tighter layouts.
    *
    * @defaultValue 'base'
    */
diff --git a/packages/ui-extensions/src/surfaces/checkout/components/SkeletonText/SkeletonText.ts b/packages/ui-extensions/src/surfaces/checkout/components/SkeletonText/SkeletonText.ts
@@ -3,9 +3,7 @@ import {createRemoteComponent} from '@remote-ui/core';
 import type {IdProps, TextSize, Size} from '../shared';
 
 /**
- * SkeletonText is used to provide a low fidelity representation of text content before it appears on the page. 
-
-Optionally you can use any text content inside `SkeletonText` to be used as a base for the rendered skeleton
+ * Configure the following properties on the skeleton text component.
  * @publicDocs
  */
 export interface SkeletonTextProps extends IdProps {
@@ -15,11 +13,11 @@ export interface SkeletonTextProps extends IdProps {
    */
   emphasis?: 'bold';
   /**
-   * Adjust the length of the text when no children are passed.
+   * Adjusts the visual length of the skeleton placeholder when no children are provided. Use this to approximate the expected width of the content that will eventually load.
    */
   inlineSize?: Extract<Size, 'small' | 'base' | 'large'>;
   /**
-   * Size of the text the skeleton replaces.
+   * A keyword that sets the size of the skeleton to match the text it replaces. The size maps to the design system's type scale, ensuring the placeholder accurately represents the final content dimensions.
    */
   size?: TextSize;
 }
diff --git a/packages/ui-extensions/src/surfaces/checkout/components/SkeletonTextBlock/SkeletonTextBlock.ts b/packages/ui-extensions/src/surfaces/checkout/components/SkeletonTextBlock/SkeletonTextBlock.ts
@@ -3,9 +3,7 @@ import {createRemoteComponent} from '@remote-ui/core';
 import type {IdProps, TextSize} from '../shared';
 
 /**
- * SkeletonTextBlock is used to provide a low fidelity representation of a block of text before it appears on the page. 
-
-Optionally you can use any text content inside `SkeletonTextBlock` to be used as a base for the rendered skeleton
+ * Configure the following properties on the skeleton text block component.
  * @publicDocs
  */
 export interface SkeletonTextBlockProps extends IdProps {
@@ -15,13 +13,13 @@ export interface SkeletonTextBlockProps extends IdProps {
    */
   emphasis?: 'bold';
   /**
-   * Number of lines to display when no children are passed.
+   * The number of text lines the skeleton renders when no children are provided. Use this to match the expected paragraph length of the content being loaded.
    *
    * @defaultValue 1
    */
   lines?: number;
   /**
-   * Size of the text the skeleton replaces.
+   * A keyword that sets the size of the skeleton to match the text it replaces. The size maps to the design system's type scale, ensuring the placeholder accurately represents the final content dimensions.
    */
   size?: TextSize;
 }
diff --git a/packages/ui-extensions/src/surfaces/checkout/components/Tag/Tag.ts b/packages/ui-extensions/src/surfaces/checkout/components/Tag/Tag.ts
@@ -4,22 +4,22 @@ import type {IconSource} from '../Icon/Icon';
 import type {IdProps} from '../shared';
 
 /**
- * A Tag is used to help label, organize or categorize objects. It is commonly used in Checkout to display the discounts applied to a cart.
+ * Configure the following properties on the tag component.
  * @publicDocs
  */
 export interface TagProps extends IdProps {
   children?: string;
   /**
-   * Icon source
+   * The source of the icon displayed inside the tag. Pass a valid icon source to render a visual indicator alongside the tag label.
    */
   icon?: IconSource;
   /**
-   * A label used for buyers using assistive technologies. When set, any
+   * A label used for users using assistive technologies. When set, any
    * `children` supplied to this component will not be announced to screen reader users.
    */
   accessibilityLabel?: string;
   /**
-   * Callback when tag is removed
+   * A callback fired when the tag is removed by the user.
    */
   onRemove?(): void;
 }
diff --git a/packages/ui-extensions/src/surfaces/checkout/components/Text/Text.ts b/packages/ui-extensions/src/surfaces/checkout/components/Text/Text.ts
@@ -9,29 +9,55 @@ import type {
 } from '../shared';
 
 /**
- * Text is used to visually style and provide semantic value for a small piece of text content.
+ * Configure the following properties on the text component.
  * @publicDocs
  */
 export interface TextProps extends VisibilityProps {
   /**
-   * Size of the text
+   * A keyword that sets the size of the text. Sizes map to the design system's type scale.
+   *
+   * - `extraSmall`: The smallest text size.
+   * - `small`: A smaller text size for secondary content.
+   * - `base`: The default text size for body content.
+   * - `medium`: A slightly larger text size.
+   * - `large`: A larger text size for emphasis.
+   * - `extraLarge`: The largest text size.
    */
   size?: TextSize;
   /**
-   * Use to emphasize a word or a group of words.
+   * Use to emphasize a word or a group of words. Set to `bold` or `italic` to apply typographic emphasis that communicates visual hierarchy or stress.
+   *
+   * - `italic`: Sets the text in italic. Combine with an `accessibilityRole` of `offset` or `stress` to add more meaning to the text.
+   * - `bold`: Sets the text in bold. Combine with an `accessibilityRole` of `strong` to add more meaning to the text.
    */
   emphasis?: Emphasis;
   /**
-   * Set the semantic of the component’s content
+   * Sets the semantic meaning of the text content for assistive technologies. When set, the role conveys additional context about the text's purpose.
+   *
+   * - `address`: Indicates the text is contact information. Typically used for addresses.
+   * - `deletion`: Indicates the text has been deleted. Typically used for discounted prices.
+   * - `marking`: Indicates the text is marked or highlighted and relevant to the user's current action.
+   * - `stress`: Indicates emphatic stress. Typically for words that have a stressed emphasis compared to surrounding text.
+   * - `offset`: Indicates an offset from the normal prose of the text. Typically used for a foreign word or fictional character thoughts.
+   * - `strong`: Indicates strong importance, seriousness, or urgency.
    */
   accessibilityRole?: TextAccessibilityRole;
   /**
-   * Unique identifier. Typically used as a target for another component’s controls
+   * A unique identifier for the component.
+   * Typically used as a target for another component's controls
    * to associate an accessible label with an action.
    */
   id?: string;
   /**
-   * Changes the visual appearance
+   * Changes the visual appearance of the text, letting you convey meaning through color.
+   *
+   * - `accent`: Conveys emphasis and draws attention to the element.
+   * - `subdued`: Conveys a subdued or disabled state.
+   * - `info`: Conveys informational content.
+   * - `success`: Conveys a successful interaction.
+   * - `warning`: Conveys something needs attention or action.
+   * - `critical`: Conveys a problem has arisen.
+   * - `decorative`: Uses the `decorative` color set within the theme.
    */
   appearance?: Extract<
     Appearance,
diff --git a/packages/ui-extensions/src/surfaces/checkout/components/TextBlock/TextBlock.ts b/packages/ui-extensions/src/surfaces/checkout/components/TextBlock/TextBlock.ts
diff --git a/packages/ui-extensions/src/surfaces/checkout/components/View/View.ts b/packages/ui-extensions/src/surfaces/checkout/components/View/View.ts
diff --git a/packages/ui-extensions/src/surfaces/checkout/components/shared.ts b/packages/ui-extensions/src/surfaces/checkout/components/shared.ts
diff --git a/packages/ui-extensions/src/surfaces/customer-account/components/Heading/Heading.doc.ts b/packages/ui-extensions/src/surfaces/customer-account/components/Heading/Heading.doc.ts
diff --git a/packages/ui-extensions/src/surfaces/customer-account/components/Text/Text.doc.ts b/packages/ui-extensions/src/surfaces/customer-account/components/Text/Text.doc.ts

Original file line number	Diff line number	Diff line change
`@@ -7,8 +7,8 @@ import type {IconSource} from '../Icon/Icon';`
`7`	`7`	`* The available tone values for the badge.`
`8`	`8`	`*`
`9`	`9`	* - `default`: General information without specific intent.
`10`		- * - `subdued`: Reduced visual emphasis for less prominent badges.
`11`	`10`	* - `critical`: Urgent problems or destructive actions requiring immediate attention.
	`11`	+ * - `subdued`: Reduced visual emphasis for less prominent badges.
`12`	`12`	`*/`
`13`	`13`	`type Tone = 'default' \| 'critical' \| 'subdued';`
`14`	`14`
Original file line number	Diff line number	Diff line change
`@@ -102,8 +102,8 @@ export interface IconProps extends IdProps {`
`102`	`102`	`*`
`103`	`103`	* - `extraSmall`: The smallest available icon size.
`104`	`104`	* - `small`: A compact icon size, smaller than the default.
`105`		- * - `large`: A larger icon for increased visual prominence.
`106`	`105`	* - `base`: Renders the icon at its standard size.
	`106`	+ * - `large`: A larger icon for increased visual prominence.
`107`	`107`	* - `fill`: Stretches the icon to fill the available space in its
`108`	`108`	`* container while preserving its aspect ratio.`
`109`	`109`	`*`